@ricsam/r5d-browser 0.0.51 → 0.0.54

package/README.md

@@ -1,14 +1,27 @@
 # r5d-browser
 
-`r5d-browser` starts a dedicated, persistent Chromium profile on a Mac and connects it to r5d.dev. Sign in to sites in the opened browser normally; agents use Chromium's automation protocol without moving the real system pointer or taking keyboard focus.
+`r5d-browser` starts stable Google Chrome with a dedicated, persistent profile on a Mac and connects it to r5d.dev. Sign in to sites in the opened browser normally; agents control Chrome over a loopback-only debugging connection without moving the real system pointer or taking keyboard focus.
 
 ```sh
 npm install -g @ricsam/r5d-browser
 r5d-browser start
 ```
 
-The profile is stored under `~/.r5d/browser/profile`. Completed downloads are retained under `~/.r5d/browser/downloads`; agents can list them and copy a selected file into the active session's artifacts. That artifact is then synchronized to every connected worker. Browser screenshots are session artifacts in r5d.dev and are not retained by the browser process.
+Install stable [Google Chrome](https://www.google.com/chrome/) before starting the browser. `r5d-browser` resolves the executable in this order:
 
-Agents can also create loopback-only TCP port forwards from this Mac to the worker bound to a chat. For example, a forward can map Chromium's `localhost:4323` to `127.0.0.1:3232` on that worker. The relay preserves raw TCP traffic, including HTTP, HTTPS, WebSockets, HMR, and SSE; it never exposes a public listener or permits an arbitrary target host.
+1. `--chrome-path <path>`
+2. `R5D_BROWSER_CHROME_PATH`
+3. `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
+4. `~/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`
+
+For example:
+
+```sh
+r5d-browser start --chrome-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+```
+
+The profile is stored under `~/.r5d/browser/chrome-profile`. The previous Chrome for Testing profile at `~/.r5d/browser/profile` is preserved but is not migrated automatically, so sign in again the first time you use the new profile. Browser binaries previously installed under `~/.r5d/browser/browsers` are also left untouched, but new versions of `r5d-browser` do not use them. Completed downloads are retained under `~/.r5d/browser/downloads`; agents can list them and copy a selected file into the active session's artifacts. That artifact is then synchronized to every connected worker. Browser screenshots are session artifacts in r5d.dev and are not retained by the browser process.
+
+Agents can also create loopback-only TCP port forwards from this Mac to the worker bound to a chat. For example, a forward can map Chrome's `localhost:4323` to `127.0.0.1:3232` on that worker. The relay preserves raw TCP traffic, including HTTP, HTTPS, WebSockets, HMR, and SSE; it never exposes a public listener or permits an arbitrary target host.
 
 Port forwards remain active across agent turns and r5d.dev control-connection reconnects. They are owned by the running `r5d-browser` process, so restarting that process ends them. Agents can list and stop forwards, and the user can inspect or stop them from Settings.

package/dist/cjs/browser-runtime.cjs

@@ -0,0 +1,295 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var browser_runtime_exports = {};
+__export(browser_runtime_exports, {
+  BrowserRuntime: () => BrowserRuntime
+});
+module.exports = __toCommonJS(browser_runtime_exports);
+var import_node_fs = __toESM(require("node:fs"), 1);
+var import_node_path = __toESM(require("node:path"), 1);
+const MAX_DOWNLOAD_CHUNK_BYTES = 1024 * 1024;
+class BrowserRuntime {
+  constructor(context, downloadsPath) {
+    this.context = context;
+    this.downloadsPath = downloadsPath;
+    import_node_fs.default.mkdirSync(downloadsPath, { recursive: true });
+    for (const page of context.pages()) this.track(page);
+    context.on("page", (page) => this.track(page));
+  }
+  context;
+  downloadsPath;
+  ids = /* @__PURE__ */ new WeakMap();
+  pages = /* @__PURE__ */ new Map();
+  cursor = /* @__PURE__ */ new Map();
+  downloadSaveQueue = Promise.resolve();
+  track(page) {
+    const existing = this.ids.get(page);
+    if (existing) return existing;
+    const id = crypto.randomUUID();
+    this.ids.set(page, id);
+    this.pages.set(id, page);
+    page.on("download", (download) => {
+      this.downloadSaveQueue = this.downloadSaveQueue.then(() => this.persistDownload(download)).catch((error) => {
+        process.stderr.write(`[r5d-browser] failed to save download: ${error instanceof Error ? error.message : String(error)}
+`);
+      });
+    });
+    page.once("close", () => {
+      this.pages.delete(id);
+      this.cursor.delete(id);
+    });
+    return id;
+  }
+  safeDownloadFilename(suggestedFilename) {
+    const basename = import_node_path.default.basename(suggestedFilename).replace(/[\\/\0]/g, "-").trim();
+    if (!basename || basename === "." || basename === "..") return "download";
+    const extension = import_node_path.default.extname(basename).slice(0, 30);
+    let stem = basename.slice(0, basename.length - import_node_path.default.extname(basename).length) || "download";
+    while (Buffer.byteLength(`${stem}${extension}`) > 200) stem = stem.slice(0, -1);
+    return `${stem || "download"}${extension}`;
+  }
+  availableDownloadPath(suggestedFilename) {
+    const filename = this.safeDownloadFilename(suggestedFilename);
+    const extension = import_node_path.default.extname(filename);
+    const stem = filename.slice(0, filename.length - extension.length) || "download";
+    for (let suffix = 1; ; suffix += 1) {
+      const candidate = suffix === 1 ? filename : `${stem}-${suffix}${extension}`;
+      const candidatePath = import_node_path.default.join(this.downloadsPath, candidate);
+      if (!import_node_fs.default.existsSync(candidatePath)) return candidatePath;
+    }
+  }
+  async persistDownload(download) {
+    const failure = await download.failure();
+    if (failure) throw new Error(failure);
+    const targetPath = this.availableDownloadPath(download.suggestedFilename());
+    await download.saveAs(targetPath);
+    process.stdout.write(`[r5d-browser] downloaded ${import_node_path.default.basename(targetPath)}
+`);
+  }
+  downloadId(filename) {
+    return Buffer.from(filename, "utf8").toString("base64url");
+  }
+  resolveDownload(downloadId) {
+    if (typeof downloadId !== "string" || !downloadId) throw new Error("downloadId is required.");
+    const filename = Buffer.from(downloadId, "base64url").toString("utf8");
+    if (this.downloadId(filename) !== downloadId || filename !== import_node_path.default.basename(filename) || filename.includes("\0")) {
+      throw new Error("Invalid downloadId.");
+    }
+    const filePath = import_node_path.default.join(this.downloadsPath, filename);
+    let stats;
+    try {
+      stats = import_node_fs.default.lstatSync(filePath);
+    } catch {
+      throw new Error(`Browser download ${downloadId} no longer exists.`);
+    }
+    if (!stats.isFile() || stats.isSymbolicLink()) throw new Error("Browser download is not a regular file.");
+    return { filename, filePath, stats };
+  }
+  async listDownloads() {
+    await this.downloadSaveQueue;
+    return import_node_fs.default.readdirSync(this.downloadsPath, { withFileTypes: true }).flatMap((entry) => {
+      if (!entry.isFile() || entry.name.startsWith(".")) return [];
+      const { filename, stats } = this.resolveDownload(this.downloadId(entry.name));
+      return [
+        {
+          downloadId: this.downloadId(filename),
+          filename,
+          size: stats.size,
+          modifiedAt: stats.mtime.toISOString()
+        }
+      ];
+    }).sort((left, right) => right.modifiedAt.localeCompare(left.modifiedAt) || left.filename.localeCompare(right.filename));
+  }
+  async getDownloadChunk(input) {
+    await this.downloadSaveQueue;
+    const { filename, filePath, stats } = this.resolveDownload(input.downloadId);
+    const offset = input.offset === void 0 ? 0 : Number(input.offset);
+    const requestedBytes = input.maxBytes === void 0 ? MAX_DOWNLOAD_CHUNK_BYTES : Number(input.maxBytes);
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > stats.size) throw new Error("Invalid download offset.");
+    if (!Number.isSafeInteger(requestedBytes) || requestedBytes < 1) throw new Error("Invalid download chunk size.");
+    const chunkSize = Math.min(requestedBytes, MAX_DOWNLOAD_CHUNK_BYTES, stats.size - offset);
+    const bytes = Buffer.alloc(chunkSize);
+    const handle = import_node_fs.default.openSync(filePath, import_node_fs.default.constants.O_RDONLY | import_node_fs.default.constants.O_NOFOLLOW);
+    let bytesRead = 0;
+    try {
+      const openedStats = import_node_fs.default.fstatSync(handle);
+      if (!openedStats.isFile() || openedStats.dev !== stats.dev || openedStats.ino !== stats.ino) {
+        throw new Error("Browser download changed before it could be read.");
+      }
+      bytesRead = import_node_fs.default.readSync(handle, bytes, 0, chunkSize, offset);
+      const completedStats = import_node_fs.default.fstatSync(handle);
+      if (completedStats.size !== stats.size || completedStats.mtimeMs !== stats.mtimeMs) {
+        throw new Error("Browser download changed while it was being read.");
+      }
+    } finally {
+      import_node_fs.default.closeSync(handle);
+    }
+    const nextOffset = offset + bytesRead;
+    return {
+      downloadId: this.downloadId(filename),
+      filename,
+      size: stats.size,
+      modifiedAt: stats.mtime.toISOString(),
+      offset,
+      nextOffset,
+      eof: nextOffset === stats.size,
+      base64: bytes.subarray(0, bytesRead).toString("base64")
+    };
+  }
+  page(tabId) {
+    if (typeof tabId !== "string") throw new Error("tabId is required.");
+    const page = this.pages.get(tabId);
+    if (!page || page.isClosed()) throw new Error(`Browser tab ${tabId} is no longer open.`);
+    return page;
+  }
+  async tabInfo(page) {
+    const tabId = this.track(page);
+    let windowId = "unknown";
+    try {
+      const cdp = await this.context.newCDPSession(page);
+      const result = await cdp.send("Browser.getWindowForTarget");
+      windowId = String(result.windowId);
+      await cdp.detach();
+    } catch {
+    }
+    return { tabId, windowId, title: await page.title().catch(() => ""), url: page.url() };
+  }
+  async listTabs() {
+    return await Promise.all([...this.pages.values()].filter((page) => !page.isClosed()).map((page) => this.tabInfo(page)));
+  }
+  async drainDownloads() {
+    await this.downloadSaveQueue;
+  }
+  async execute(action, input) {
+    if (action === "list_tabs") return { tabs: await this.listTabs() };
+    if (action === "list_downloads") return { downloads: await this.listDownloads() };
+    if (action === "get_download") return await this.getDownloadChunk(input);
+    if (action === "open_tab") {
+      const previous = this.context.pages().findLast((candidate) => !candidate.isClosed());
+      let page2;
+      if (previous) {
+        const cdp = await this.context.newCDPSession(previous);
+        const pagePromise = this.context.waitForEvent("page");
+        await cdp.send("Target.createTarget", {
+          url: "about:blank",
+          newWindow: input.disposition === "window",
+          background: true
+        });
+        page2 = await pagePromise;
+        await cdp.detach();
+        if (input.disposition === "window") {
+          const pageCdp = await this.context.newCDPSession(page2);
+          const { windowId } = await pageCdp.send("Browser.getWindowForTarget");
+          await pageCdp.send("Browser.setWindowBounds", { windowId, bounds: { windowState: "minimized" } });
+          await pageCdp.detach();
+        }
+      } else {
+        page2 = await this.context.newPage();
+      }
+      const url = typeof input.url === "string" ? input.url : "about:blank";
+      if (url !== "about:blank") await page2.goto(url, { waitUntil: "domcontentloaded" });
+      return { tab: await this.tabInfo(page2) };
+    }
+    const page = this.page(input.tabId);
+    const tabId = input.tabId;
+    switch (action) {
+      case "close_tab":
+        await page.close();
+        return { closed: true, tabId };
+      case "navigate":
+        await page.goto(String(input.url), { waitUntil: "domcontentloaded" });
+        return { tab: await this.tabInfo(page) };
+      case "screenshot": {
+        const bytes = await page.screenshot({ type: "png" });
+        const viewport = page.viewportSize();
+        const cursor = this.cursor.get(tabId);
+        return {
+          base64: bytes.toString("base64"),
+          width: viewport?.width ?? Number(await page.evaluate(() => window.innerWidth)),
+          height: viewport?.height ?? Number(await page.evaluate(() => window.innerHeight)),
+          cursorX: cursor?.x,
+          cursorY: cursor?.y
+        };
+      }
+      case "move_mouse": {
+        const x = Number(input.x);
+        const y = Number(input.y);
+        if (!Number.isFinite(x) || !Number.isFinite(y)) throw new Error("move_mouse requires numeric x and y coordinates.");
+        await page.mouse.move(x, y);
+        this.cursor.set(tabId, { x, y });
+        return { tabId, x, y };
+      }
+      case "mouse_click": {
+        const cursor = this.cursor.get(tabId);
+        if (!cursor) throw new Error("Move the mouse in this tab before clicking.");
+        const button = input.button === "middle" || input.button === "right" ? input.button : "left";
+        await page.mouse.click(cursor.x, cursor.y, { button, clickCount: input.clickCount === 2 ? 2 : 1 });
+        return { tabId, ...cursor, button };
+      }
+      case "keyboard": {
+        const keys = Array.isArray(input.keys) ? input.keys : [];
+        const modifiers = Array.isArray(input.modifiers) ? input.modifiers.filter((value) => typeof value === "string") : [];
+        for (const modifier of modifiers) await page.keyboard.down(modifier);
+        try {
+          for (const key of keys) {
+            if (typeof key !== "string") throw new Error("keyboard keys must all be strings.");
+            await page.keyboard.press(key);
+          }
+        } finally {
+          for (const modifier of modifiers.toReversed()) await page.keyboard.up(modifier);
+        }
+        return { tabId, keys, modifiers };
+      }
+      case "keyboard_type":
+        if (typeof input.text !== "string") throw new Error("keyboard_type requires text.");
+        await page.keyboard.insertText(input.text);
+        return { tabId, characters: input.text.length };
+      case "run_js": {
+        if (typeof input.code !== "string") throw new Error("run_js requires code.");
+        const result = await page.evaluate(async (code) => {
+          const invoke = new Function(`"use strict"; return (async () => {
+${code}
+})()`);
+          return await invoke();
+        }, input.code);
+        const serialized = JSON.stringify(result);
+        if (serialized && Buffer.byteLength(serialized) > 1024 * 1024) {
+          throw new Error("Browser JavaScript result exceeded the 1 MiB limit.");
+        }
+        return { tabId, result };
+      }
+      default:
+        throw new Error(`Unsupported browser operation: ${action}`);
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BrowserRuntime
+});