@ricsam/r5d-browser 0.0.44 → 0.0.46

package/README.md

@@ -7,4 +7,4 @@ npm install -g @ricsam/r5d-browser
 r5d-browser start
 ```
 
-The profile is stored under `~/.r5d/browser/profile`. Browser screenshots are session artifacts in r5d.dev and are not retained by the browser process.
+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.

package/dist/cjs/main.cjs

@@ -33,6 +33,7 @@ const DEFAULT_BASE_URL = "https://r5d.dev";
 const PACKAGE_NAME = "@ricsam/r5d-browser";
 const RECONNECT_DELAY_MS = 2e3;
 const SERVER_HEARTBEAT_TIMEOUT_MS = 45e3;
+const MAX_DOWNLOAD_CHUNK_BYTES = 1024 * 1024;
 function browserRoot() {
   return import_node_path.default.join(import_node_os.default.homedir(), ".r5d", "browser");
 }
@@ -169,27 +170,133 @@ function loadInstanceId() {
   return id;
 }
 class BrowserRuntime {
-  constructor(context) {
+  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);
@@ -213,6 +320,8 @@ class BrowserRuntime {
   }
   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;
@@ -394,6 +503,8 @@ async function start(options) {
   const { baseUrl, token } = resolveConnection(options);
   const browsersPath = import_node_path.default.resolve(options.browsersPath ?? import_node_path.default.join(browserRoot(), "browsers"));
   const profilePath = import_node_path.default.resolve(options.profilePath ?? import_node_path.default.join(browserRoot(), "profile"));
+  const downloadsPath = import_node_path.default.join(browserRoot(), "downloads");
+  const playwrightDownloadsPath = import_node_path.default.join(downloadsPath, ".playwright");
   process.env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
   let playwright = await import("playwright");
   if (!import_node_fs.default.existsSync(playwright.chromium.executablePath())) {
@@ -401,15 +512,18 @@ async function start(options) {
     playwright = await import("playwright");
   }
   import_node_fs.default.mkdirSync(profilePath, { recursive: true });
+  import_node_fs.default.mkdirSync(playwrightDownloadsPath, { recursive: true });
   const context = await playwright.chromium.launchPersistentContext(profilePath, {
     headless: false,
     viewport: { width: 1440, height: 900 },
     acceptDownloads: true,
-    downloadsPath: import_node_path.default.join(browserRoot(), "downloads")
+    downloadsPath: playwrightDownloadsPath
   });
   if (context.pages().length === 0) await context.newPage();
-  const runtime = new BrowserRuntime(context);
+  const runtime = new BrowserRuntime(context, downloadsPath);
   process.stdout.write(`[r5d-browser] profile: ${profilePath}
+`);
+  process.stdout.write(`[r5d-browser] downloads: ${downloadsPath}
 `);
   process.stdout.write(`[r5d-browser] agents use synthetic Chromium input; your system pointer and keyboard stay untouched.
 `);

package/dist/cjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "type": "commonjs"
 }

package/dist/mjs/main.mjs

@@ -10,6 +10,7 @@ const DEFAULT_BASE_URL = "https://r5d.dev";
 const PACKAGE_NAME = "@ricsam/r5d-browser";
 const RECONNECT_DELAY_MS = 2e3;
 const SERVER_HEARTBEAT_TIMEOUT_MS = 45e3;
+const MAX_DOWNLOAD_CHUNK_BYTES = 1024 * 1024;
 function browserRoot() {
   return path.join(os.homedir(), ".r5d", "browser");
 }
@@ -146,27 +147,133 @@ function loadInstanceId() {
   return id;
 }
 class BrowserRuntime {
-  constructor(context) {
+  constructor(context, downloadsPath) {
     this.context = context;
+    this.downloadsPath = downloadsPath;
+    fs.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 = path.basename(suggestedFilename).replace(/[\\/\0]/g, "-").trim();
+    if (!basename || basename === "." || basename === "..") return "download";
+    const extension = path.extname(basename).slice(0, 30);
+    let stem = basename.slice(0, basename.length - path.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 = path.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 = path.join(this.downloadsPath, candidate);
+      if (!fs.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 ${path.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 !== path.basename(filename) || filename.includes("\0")) {
+      throw new Error("Invalid downloadId.");
+    }
+    const filePath = path.join(this.downloadsPath, filename);
+    let stats;
+    try {
+      stats = fs.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 fs.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 = fs.openSync(filePath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    let bytesRead = 0;
+    try {
+      const openedStats = fs.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 = fs.readSync(handle, bytes, 0, chunkSize, offset);
+      const completedStats = fs.fstatSync(handle);
+      if (completedStats.size !== stats.size || completedStats.mtimeMs !== stats.mtimeMs) {
+        throw new Error("Browser download changed while it was being read.");
+      }
+    } finally {
+      fs.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);
@@ -190,6 +297,8 @@ class BrowserRuntime {
   }
   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;
@@ -371,6 +480,8 @@ async function start(options) {
   const { baseUrl, token } = resolveConnection(options);
   const browsersPath = path.resolve(options.browsersPath ?? path.join(browserRoot(), "browsers"));
   const profilePath = path.resolve(options.profilePath ?? path.join(browserRoot(), "profile"));
+  const downloadsPath = path.join(browserRoot(), "downloads");
+  const playwrightDownloadsPath = path.join(downloadsPath, ".playwright");
   process.env.PLAYWRIGHT_BROWSERS_PATH = browsersPath;
   let playwright = await import("playwright");
   if (!fs.existsSync(playwright.chromium.executablePath())) {
@@ -378,15 +489,18 @@ async function start(options) {
     playwright = await import("playwright");
   }
   fs.mkdirSync(profilePath, { recursive: true });
+  fs.mkdirSync(playwrightDownloadsPath, { recursive: true });
   const context = await playwright.chromium.launchPersistentContext(profilePath, {
     headless: false,
     viewport: { width: 1440, height: 900 },
     acceptDownloads: true,
-    downloadsPath: path.join(browserRoot(), "downloads")
+    downloadsPath: playwrightDownloadsPath
   });
   if (context.pages().length === 0) await context.newPage();
-  const runtime = new BrowserRuntime(context);
+  const runtime = new BrowserRuntime(context, downloadsPath);
   process.stdout.write(`[r5d-browser] profile: ${profilePath}
+`);
+  process.stdout.write(`[r5d-browser] downloads: ${downloadsPath}
 `);
   process.stdout.write(`[r5d-browser] agents use synthetic Chromium input; your system pointer and keyboard stay untouched.
 `);

package/dist/mjs/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "type": "module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ricsam/r5d-browser",
-  "version": "0.0.44",
+  "version": "0.0.46",
   "type": "module",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/mjs/main.mjs",