@remcp/runtime 0.2.148 → 0.2.150

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.150 — 2026-10-15
+
+- Read-only browser tab discovery and semantic snapshots no longer auto-launch a separate Chromium browser when CDP is unavailable.
+- Give a clear Accessibility fallback (`ui_snapshot` / `ui_find`) without changing existing typed `structuredContent` for empty and non-empty lists.
+- Keep explicit navigation as the sole browser auto-launch entry point, with existing CDP loopback and target safety controls.
+- Add five regression tests. No new MCP tools or schemas; the 83-operation runtime catalog is preserved.
+
+
+## 0.2.149 — 2026-10-14
+
+- Automatically snapshot raw, local-only Chromium session files on crashed ReMCP CDP profiles before browser auto-launch; preserve orphaned tabs and prior snapshots without leaking URLs.
+- Fail closed if session evidence cannot be backed up safely, and cap file sizes, total data and snapshot count.
+- Add seven unit tests and document restoration limitations. No new runtime operations or MCP schema changes.
+
 ## 0.2.148 — 2026-10-14
 
 - Request Chromium-native `--restore-last-session` only when the dedicated ReMCP browser profile has a crashed exit marker and persisted tab session files.

package/README.md

@@ -64,7 +64,7 @@ discovery for new clients.
 
 For browser typing, `browser_text` is the visible DOM locator while `text` is the Unicode payload. `browser_action(action="scroll")` accepts page/element deltas or direction/wheel steps and scrolls the page or nearest scrollable ancestor; `scroll_into_view` remains the separate semantic reveal operation.
 
-When ReMCP auto-launches Chrome/Edge for local CDP, it uses a dedicated ReMCP browser profile. If that browser was interrupted (for example during an agent upgrade), and Chromium has saved tabs in that profile, the next launch requests Chromium's own last-session restoration instead of opening a new `about:blank` tab. A clean browser shutdown never triggers automatic reopening. This inspects only local session metadata, never reads or transmits tab URLs to ReMCP's relay. The browser itself controls which tabs can actually be recovered.
+When ReMCP auto-launches Chrome/Edge for local CDP, it uses a dedicated ReMCP browser profile. If that browser was interrupted (for example during an agent upgrade), and Chromium has saved tabs in that profile, the next launch requests Chromium's own last-session restoration instead of opening a new `about:blank` tab. A clean browser shutdown never triggers automatic reopening. This inspects only local session metadata, never reads or transmits tab URLs to ReMCP's relay. The browser itself controls which tabs can actually be recovered. On an interrupted profile, ReMCP now saves a private, local-only snapshot of `Session_*` and `Tabs_*` files before Chromium can rotate them on startup, even when only tab files remain. Recovery snapshots are adjacent to the dedicated browser profile in a `browser-cdp-recovery/` directory (owner-only on Unix); existing snapshots are never deleted automatically. Copy limits are 16 regular files, 32 MiB per file, 64 MiB per snapshot and 12 distinct snapshots. If evidence cannot be protected safely (for example due to symlinks, storage exhaustion or the snapshot limit), browser auto-launch fails rather than silently overwriting its only recoverable copy. No session URLs are parsed, returned through tools, or uploaded. You can review and manage those local snapshots yourself.
 
 For frontend QA, use semantic data to operate the page and rendered pixels to verify it: `browser_action(action="set_viewport")` sets an exact responsive-test viewport, `browser_wait` waits for the real application state, and `browser_snapshot(include_screenshot=true, selector=...)` recenters the component, returns its bounds, and attaches the real CDP-rendered viewport PNG. This intentionally treats screenshots as the visual oracle without making screenshot-driven coordinate guessing the primary control path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.148",
+  "version": "0.2.150",
   "description": "First-party ReMCP local device runtime: filesystem, terminal, computer-use, browser, diagnostics and document tools over MCP.",
   "type": "module",
   "license": "MIT",

package/src/extended/browser-session-backup.mjs

@@ -0,0 +1,135 @@
+import path from 'node:path';
+import process from 'node:process';
+import { closeSync, fchmodSync, constants, fstatSync, fsyncSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, writeFileSync, writeSync } from 'node:fs';
+
+const MAX_FILE_BYTES = 32 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024;
+const MAX_FILES = 16;
+const MAX_SNAPSHOTS = 12;
+const NOFOLLOW = constants.O_NOFOLLOW || 0;
+const DIRECTORY = constants.O_DIRECTORY || 0;
+
+function ownedRegularFile(file, maxBytes) {
+  let fd;
+  try {
+    if (process.platform === 'win32' && lstatSync(file).isSymbolicLink()) return null;
+    fd = openSync(file, constants.O_RDONLY | NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size <= 0 || stat.size > maxBytes) return null;
+    return { size: stat.size, mtimeMs: stat.mtimeMs };
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function sessionMetadata(profile) {
+  const file = path.join(profile, 'Default', 'Preferences');
+  let fd;
+  try {
+    if (process.platform === 'win32' && lstatSync(file).isSymbolicLink()) return null;
+    fd = openSync(file, constants.O_RDONLY | NOFOLLOW);
+    const stat = fstatSync(fd);
+    if (!stat.isFile() || stat.size > 4 * 1024 * 1024) return null;
+    return JSON.parse(readFileSync(fd, 'utf8'))?.profile?.exit_type || null;
+  } catch { return null; }
+  finally { if (fd !== undefined) closeSync(fd); }
+}
+
+function safeDirectory(dir) {
+  try { mkdirSync(dir, { recursive: false, mode: 0o700 }); }
+  catch (error) { if (error?.code !== 'EEXIST') throw error; }
+  // Open first and validate the handle, not the path: an lstat-then-open
+  // check would leave a filesystem race at the recovery destination.
+  if (process.platform === 'win32' && lstatSync(dir).isSymbolicLink()) throw new Error('Unsafe recovery directory');
+  const fd = openSync(dir, constants.O_RDONLY | DIRECTORY | NOFOLLOW);
+  try {
+    if (!fstatSync(fd).isDirectory()) throw new Error('Unsafe recovery directory');
+    if (process.platform !== 'win32') fchmodSync(fd, 0o700);
+  } finally { closeSync(fd); }
+}
+
+function rawCopy(from, to, expected) {
+  let source;
+  let destination;
+  try {
+    source = openSync(from, constants.O_RDONLY | NOFOLLOW);
+    const before = fstatSync(source);
+    if (!before.isFile() || before.size !== expected.size || before.mtimeMs !== expected.mtimeMs) {
+      throw new Error('Browser session changed while preparing the snapshot');
+    }
+    destination = openSync(to, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | NOFOLLOW, 0o600);
+    const buffer = Buffer.alloc(128 * 1024);
+    let total = 0;
+    while (total < expected.size) {
+      const count = readSync(source, buffer, 0, Math.min(buffer.length, expected.size - total), null);
+      if (count === 0) throw new Error('Browser session was truncated during snapshot');
+      let written = 0;
+      while (written < count) {
+        const next = writeSync(destination, buffer, written, count - written);
+        if (!next) throw new Error('Could not finish session backup write');
+        written += next;
+      }
+      total += count;
+    }
+    const after = fstatSync(source);
+    if (after.size !== before.size || after.mtimeMs !== before.mtimeMs) {
+      throw new Error('Browser session changed during snapshot');
+    }
+    fsyncSync(destination);
+  } finally {
+    if (source !== undefined) closeSync(source);
+    if (destination !== undefined) closeSync(destination);
+  }
+}
+
+// Called only before auto-launch of a *crashed* dedicated ReMCP CDP profile.
+// The source data stays on the user's computer; no tab URLs are parsed or sent
+// across the MCP connection. Never delete prior snapshots automatically.
+export function preserveInterruptedBrowserSession(profile) {
+  if (sessionMetadata(profile) !== 'Crashed') return { saved: false, reason: 'clean-or-missing' };
+  const sessionDir = path.join(profile, 'Default', 'Sessions');
+  let dirFd;
+  try {
+    if (process.platform !== 'win32') {
+      try { dirFd = openSync(sessionDir, constants.O_RDONLY | DIRECTORY | NOFOLLOW); }
+      catch (error) { if (error?.code === 'ENOENT') return { saved: false, reason: 'no-sessions' }; throw error; }
+      if (!fstatSync(dirFd).isDirectory()) throw new Error('Session directory is unsafe');
+    }
+    const readableDir = dirFd === undefined ? sessionDir : `${process.platform === 'darwin' ? '/dev/fd' : '/proc/self/fd'}/${dirFd}`;
+    const files = [];
+    let total = 0;
+    for (const name of readdirSync(readableDir).sort()) {
+      if (!/^(?:Session|Tabs)_\d+$/.test(name)) continue;
+      const details = ownedRegularFile(path.join(readableDir, name), MAX_FILE_BYTES);
+      if (!details) throw new Error('Session file is unsafe, empty or oversized');
+      total += details.size;
+      files.push({ name, ...details });
+      if (files.length > MAX_FILES || total > MAX_TOTAL_BYTES) throw new Error('Session data exceeds safe snapshot limits');
+    }
+    if (!files.some(file => file.name.startsWith('Tabs_'))) return { saved: false, reason: 'no-tabs' };
+
+    const recoveryDir = path.join(path.dirname(profile), `${path.basename(profile)}-recovery`);
+    safeDirectory(recoveryDir);
+    const fingerprint = JSON.stringify(files);
+    const snapshots = readdirSync(recoveryDir).filter(name => /^snapshot-[A-Za-z0-9]+$/.test(name));
+    for (const name of snapshots) {
+      const manifest = path.join(recoveryDir, name, 'manifest.json');
+      try {
+        const fd = openSync(manifest, constants.O_RDONLY | NOFOLLOW);
+        let content;
+        try { if (fstatSync(fd).size > 8192) continue; content = JSON.parse(readFileSync(fd, 'utf8')); }
+        finally { closeSync(fd); }
+        if (content?.fingerprint === fingerprint) return { saved: false, reason: 'already-saved' };
+      } catch { /* Ignore incomplete previous attempts; never overwrite them. */ }
+    }
+    if (snapshots.length >= MAX_SNAPSHOTS) throw new Error('Session recovery snapshot limit reached');
+    const snapshotDir = mkdtempSync(path.join(recoveryDir, 'snapshot-'));
+    try {
+      for (const file of files) rawCopy(path.join(readableDir, file.name), path.join(snapshotDir, file.name), file);
+      writeFileSync(path.join(snapshotDir, 'manifest.json'), JSON.stringify({ fingerprint, count: files.length, hasWindowSession: files.some(f => f.name.startsWith('Session_')) }), { flag: 'wx', mode: 0o600 });
+      return { saved: true, reason: 'saved', count: files.length, bytes: total };
+    } catch (error) {
+      rmSync(snapshotDir, { recursive: true, force: true });
+      throw error;
+    }
+  } finally { if (dirFd !== undefined) closeSync(dirFd); }
+}

package/src/extended/browser.mjs

@@ -5,6 +5,7 @@ import { isIP } from 'node:net';
 import { lookup } from 'node:dns/promises';
 import { closeSync, constants as fsConstants, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readdirSync } from 'node:fs';
 import { resolveSafePath } from '../util.mjs';
+import { preserveInterruptedBrowserSession } from './browser-session-backup.mjs';
 import { clamp, commandExists, jsonResult, optionalString, requireEnum, spawnDetached, unavailable } from './common.mjs';
 
 const DEFAULT_ENDPOINT = 'http://127.0.0.1:9222';
@@ -148,6 +149,9 @@ async function ensureBrowserEndpoint(endpoint) {
       if (!executable) throw new Error('Browser control is unavailable: no supported Chrome, Edge, or Chromium executable was found');
       const profile = browserDataDir();
       mkdirSync(profile, { recursive:true, mode:0o700 });
+      // Chrome rotates its Sessions/ files on startup. Protect existing local
+      // evidence before a restart, including profiles with only Tabs_* left.
+      preserveInterruptedBrowserSession(profile);
       spawnDetached(executable, browserAutoLaunchArgs(profile));
       if (!await waitForBrowserEndpoint(5000)) throw new Error('ReMCP launched a browser but its local CDP endpoint did not become ready');
     })().finally(() => { browserLaunchPromise = null; });
@@ -410,8 +414,22 @@ export async function filterBrowserTargets(list, { validate = assertResolvedPage
 
 export async function listBrowserTargets(endpoint) {
   assertBrowserRemoteEnabled();
-  await ensureBrowserEndpoint(endpoint);
-  return filterBrowserTargets(await requestJson('/json/list', endpoint));
+  // Reading tabs and page semantics must not launch a separate Chromium/profile.
+  // Only an explicit browser_navigate(action=new_tab) can bootstrap an isolated browser.
+  const base = endpointUrl(endpoint); // keeps the CDP address loopback-only
+  let list;
+  try {
+    list = await requestJson('/json/list', endpoint, { timeout_ms: 1500 });
+  } catch (error) {
+    const message = String(error?.message || '');
+    // Keep HTTP/policy/oversize/malformed-response errors distinct from an unavailable CDP.
+    if (!/fetch failed|ECONNREFUSED|ECONNRESET|ETIMEDOUT|abort|timed out|network error/i.test(message)) throw error;
+    const configured = Boolean(endpoint || process.env.REMCP_CDP_URL);
+    const label = configured ? 'The configured CDP endpoint' : 'Browser CDP endpoint';
+    throw new Error(`${label} is unavailable at ${base.origin}. Read-only browser_tabs and browser_snapshot do not launch a browser. Use ui_snapshot and ui_find for the existing browser window; do not retry this CDP endpoint unchanged. Only browser_navigate(action=new_tab), when explicitly requested, may start a local isolated browser.`);
+  }
+  // Retain the current bounded concurrent DNS/security checks for up to 1000 tabs.
+  return filterBrowserTargets(list);
 }
 
 function validatedTargetWebSocketUrl(target, endpoint) {
@@ -851,12 +869,18 @@ async function callPageFunction(session, functionDeclaration, args = [], awaitPr
 
 export async function browserTabs(args = {}) {
   const targets = await listBrowserTargets(args.endpoint);
-  return jsonResult(targets.filter(item => item.type === 'page').slice(0, 500).map(item => ({
+  const pages = targets.filter(item => item.type === 'page').slice(0, 500).map(item => ({
     id: boundedText(item.id, 256),
     title: boundedText(item.title, 1000),
     url: boundedText(item.url, 4096),
     description: boundedText(item.description, 1000),
-  })));
+  }));
+  const result = jsonResult(pages);
+  // Keep the typed empty-array contract while providing a native fallback hint.
+  if (!pages.length) {
+    result.content = [{ type: 'text', text: 'CDP is connected, but no debuggable Chromium tabs are available. Use ui_snapshot and ui_find to inspect existing browser windows without CDP; only open a new tab when explicitly requested.' }];
+  }
+  return result;
 }
 
 async function waitForHistoryReady(session, expectedUrl, timeoutMs) {