@remcp/runtime 0.2.32 → 0.2.33

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.33
+
+- Linux Wayland screenshots now use the standard XDG Desktop Portal before compositor-specific
+  command-line fallbacks. The runtime subscribes to the portal response before requesting the
+  capture, handles fast and legacy request handles without losing the signal, respects an explicit
+  cancellation, and cleans the portal-created intermediate PNG after copying it.
+
 ## 0.2.30
 
 - **Unrestricted mode.** `REMCP_RUNTIME_UNRESTRICTED=1` (or `"unrestricted": true` in `runtime.json`,

package/README.md

@@ -190,7 +190,7 @@ MCP server.
 | | Desktop Commander 0.2.50 | ReMCP runtime 0.2.0 |
 | --- | --- | --- |
 | Tools | 26, including config mutators and document tooling | 35, including binary transfer, archives, screenshots, and diffs |
-| Runtime dependencies | 34 (Supabase, Puppeteer/md-to-pdf, `sharp`, `exceljs`, Tiptap, ripgrep download) | 1 (`@modelcontextprotocol/sdk`) |
+| Runtime dependencies | 34 (Supabase, Puppeteer/md-to-pdf, `sharp`, `exceljs`, Tiptap, ripgrep download) | 2 direct (`@modelcontextprotocol/sdk`, `@jellybrick/dbus-next`) |
 | Install scripts | `postinstall` posts an install payload that ignores the telemetry setting | none |
 | Telemetry | opt-out, 51 event names, remote feature flags, A/B assignment, third-party processor | opt-out, whitelisted event schema, no endpoint, no flags |
 | Install size | 3.78 MB unpacked, 249 files | ~110 kB unpacked, 20 files |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.32",
+  "version": "0.2.33",
   "description": "First-party ReMCP local device runtime: file, search, terminal and process tools over MCP for computers paired with ReMCP.",
   "type": "module",
   "license": "MIT",
@@ -24,6 +24,7 @@
     "test": "node --test test/*.test.mjs"
   },
   "dependencies": {
+    "@jellybrick/dbus-next": "^0.11.3",
     "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "repository": {

package/src/catalog.mjs

@@ -516,7 +516,7 @@ export const toolDefinitions = [
   {
     name: 'take_screenshot',
     title: 'Take screenshot',
-    description: 'Capture the screen of the paired computer and return it as an image, for GUI work, visual checks, and demonstrating what is on screen. Uses grim, gnome-screenshot, spectacle, scrot, ImageMagick import, screencapture, or PowerShell depending on the platform.',
+    description: 'Capture the screen of the paired computer and return it as an image, for GUI work, visual checks, and demonstrating what is on screen. Uses the standard desktop screenshot portal on Wayland, with grim, gnome-screenshot, spectacle, scrot, ImageMagick import, screencapture, or PowerShell fallbacks depending on the platform.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/screenshot-portal.mjs

@@ -0,0 +1,205 @@
+import process from 'node:process';
+import { copyFile, rm } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const PORTAL_NAME = 'org.freedesktop.portal.Desktop';
+const PORTAL_PATH = '/org/freedesktop/portal/desktop';
+const SCREENSHOT_INTERFACE = 'org.freedesktop.portal.Screenshot';
+const REQUEST_INTERFACE = 'org.freedesktop.portal.Request';
+const DBUS_NAME = 'org.freedesktop.DBus';
+const DBUS_PATH = '/org/freedesktop/DBus';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const CONNECT_TIMEOUT_MS = 5_000;
+
+export function isWaylandSession(env = process.env) {
+  return /wayland/i.test(String(env.XDG_SESSION_TYPE || '')) || Boolean(env.WAYLAND_DISPLAY);
+}
+
+function cleanError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/\s+/g, ' ').trim().slice(0, 500) || 'unknown error';
+}
+
+function errorWithCode(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function withTimeout(promise, timeoutMs, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs} ms`)), timeoutMs);
+    Promise.resolve(promise).then(
+      value => { clearTimeout(timer); resolve(value); },
+      error => { clearTimeout(timer); reject(error); },
+    );
+  });
+}
+
+function waitForBusName(bus, timeoutMs) {
+  if (typeof bus.name === 'string' && bus.name.startsWith(':')) return Promise.resolve(bus.name);
+  return new Promise((resolve, reject) => {
+    let timer;
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      bus.off?.('connect', onConnect);
+      bus.off?.('error', onError);
+    };
+    const onConnect = () => {
+      if (typeof bus.name !== 'string' || !bus.name.startsWith(':')) {
+        cleanup();
+        reject(new Error('session D-Bus connected without a unique bus name'));
+        return;
+      }
+      const name = bus.name;
+      cleanup();
+      resolve(name);
+    };
+    const onError = error => {
+      cleanup();
+      reject(error instanceof Error ? error : new Error(String(error)));
+    };
+    bus.once('connect', onConnect);
+    bus.once('error', onError);
+    timer = setTimeout(() => {
+      cleanup();
+      reject(new Error(`session D-Bus did not connect within ${timeoutMs} ms`));
+    }, timeoutMs);
+  });
+}
+
+function expectedRequestPath(uniqueBusName, token) {
+  // xdg-desktop-portal 0.9+ derives the request object path from the caller's unique bus name and
+  // handle_token. Subscribing before Screenshot() closes the documented race where Response can be
+  // emitted before the method reply reaches us.
+  const sender = uniqueBusName.replace(/^:/, '').replace(/\./g, '_');
+  return `/org/freedesktop/portal/desktop/request/${sender}/${token}`;
+}
+
+function matchRule() {
+  // Deliberately omit the path. Current portals return the predictable path above, while older
+  // portals may return a different handle. A short-lived broad match lets us buffer either path and
+  // still filter the response to this request in-process.
+  return `type='signal',sender='${PORTAL_NAME}',interface='${REQUEST_INTERFACE}',member='Response'`;
+}
+
+function dbusMatchMessage(dbus, member, rule) {
+  return new dbus.Message({
+    destination: DBUS_NAME,
+    path: DBUS_PATH,
+    interface: DBUS_NAME,
+    member,
+    signature: 's',
+    body: [rule],
+  });
+}
+
+function createResponseCollector(bus, dbus, initialPath, timeoutMs) {
+  let targetPath = initialPath;
+  let settled = false;
+  const buffered = new Map();
+  let resolveResponse;
+  const promise = new Promise(resolve => { resolveResponse = resolve; });
+  const finish = value => {
+    if (settled) return;
+    settled = true;
+    clearTimeout(timer);
+    resolveResponse(value);
+  };
+  const onMessage = message => {
+    if (message?.type !== dbus.MessageType.SIGNAL) return;
+    if (message.interface !== REQUEST_INTERFACE || message.member !== 'Response') return;
+    if (typeof message.path !== 'string') return;
+    const value = {
+      response: Number(message.body?.[0]),
+      results: message.body?.[1],
+    };
+    if (message.path === targetPath) finish(value);
+    else buffered.set(message.path, value);
+  };
+  const timer = setTimeout(() => finish({ timeout: true }), timeoutMs);
+  bus.on('message', onMessage);
+  return {
+    promise,
+    setPath(path) {
+      targetPath = path;
+      const pending = buffered.get(path);
+      if (pending) finish(pending);
+    },
+    stop() {
+      clearTimeout(timer);
+      bus.off?.('message', onMessage);
+    },
+  };
+}
+
+export async function capturePortalScreenshot(destination, {
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  loadDbus = () => import('@jellybrick/dbus-next'),
+} = {}) {
+  const deadline = Date.now() + timeoutMs;
+  const remaining = () => Math.max(1, deadline - Date.now());
+  let dbus;
+  let bus;
+  let collector;
+  let rule;
+  let matchInstalled = false;
+  try {
+    dbus = await loadDbus();
+    if (typeof dbus.sessionBus !== 'function' || typeof dbus.Variant !== 'function' ||
+        typeof dbus.Message !== 'function' || typeof dbus.MessageType?.SIGNAL !== 'number') {
+      throw new Error('D-Bus client module is missing required exports');
+    }
+
+    bus = dbus.sessionBus();
+    const uniqueBusName = await waitForBusName(bus, Math.min(CONNECT_TIMEOUT_MS, remaining()));
+    const desktop = await withTimeout(bus.getProxyObject(PORTAL_NAME, PORTAL_PATH), remaining(), 'desktop portal discovery');
+    const screenshot = desktop.getInterface(SCREENSHOT_INTERFACE);
+    const token = `remcp_${process.pid}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`
+      .replace(/[^A-Za-z0-9_]/g, '_');
+    const predictedHandle = expectedRequestPath(uniqueBusName, token);
+
+    // Install the D-Bus match and listener *before* calling Screenshot. The portal can emit Response
+    // very quickly, and attaching a proxy listener only after the method returns can lose it.
+    rule = matchRule();
+    collector = createResponseCollector(bus, dbus, predictedHandle, remaining());
+    await withTimeout(bus.call(dbusMatchMessage(dbus, 'AddMatch', rule)), remaining(), 'desktop portal signal subscription');
+    matchInstalled = true;
+
+    const handle = await withTimeout(screenshot.Screenshot('', {
+      handle_token: new dbus.Variant('s', token),
+      interactive: new dbus.Variant('b', false),
+    }), remaining(), 'desktop portal screenshot request');
+    if (typeof handle !== 'string' || !handle.startsWith('/')) {
+      throw new Error('desktop portal returned an invalid request handle');
+    }
+    collector.setPath(handle);
+
+    const responseResult = await collector.promise;
+    if (responseResult.timeout) throw new Error(`desktop portal did not respond within ${timeoutMs} ms`);
+    const { response, results } = responseResult;
+    if (response === 1) throw errorWithCode('screen capture permission was cancelled', 'PORTAL_CANCELLED');
+    if (response !== 0) throw new Error(`desktop portal returned response ${response}`);
+
+    const uri = results?.uri?.value;
+    if (typeof uri !== 'string') throw new Error('desktop portal returned no screenshot URI');
+    const sourceUrl = new URL(uri);
+    if (sourceUrl.protocol !== 'file:') throw new Error(`desktop portal returned unsupported URI scheme ${sourceUrl.protocol}`);
+    const source = fileURLToPath(sourceUrl);
+    await copyFile(source, destination);
+    // GNOME commonly writes the portal result to ~/Pictures. The runtime owns this capture, so remove
+    // that portal-created intermediate after copying it to the caller-selected temporary location.
+    if (source !== destination) await rm(source, { force: true }).catch(() => {});
+    return destination;
+  } catch (error) {
+    const wrapped = new Error(`xdg-desktop-portal: ${cleanError(error)}`);
+    if (error && typeof error === 'object' && typeof error.code === 'string') wrapped.code = error.code;
+    throw wrapped;
+  } finally {
+    collector?.stop();
+    if (bus && matchInstalled && rule) {
+      try { await bus.call(dbusMatchMessage(dbus, 'RemoveMatch', rule)); } catch {}
+    }
+    try { bus?.disconnect(); } catch {}
+  }
+}

package/src/tools/files.mjs

@@ -9,6 +9,7 @@ import { liveConfig, runtimeConfig } from '../config.mjs';
 import { documentKind, readDocxText, readPdfText } from '../documents.mjs';
 import { diffStats, unifiedDiff } from '../diff.mjs';
 import { describeFilesystemFailure } from '../permissions.mjs';
+import { capturePortalScreenshot, isWaylandSession } from '../screenshot-portal.mjs';
 import { applyHunks, parseUnifiedDiff } from '../patch.mjs';
 import { countEvent, recordEvent } from '../telemetry.mjs';
 import { clampInteger, decodeText, displayPath, fail, globToRegExp, image, looksBinary, multi, pageLines, resolveSafePath, splitLines, text } from '../util.mjs';
@@ -936,15 +937,14 @@ function screenshotAdvice(attempts, { platform = process.platform, env = process
   if (!env.DISPLAY && !wayland) {
     return `This computer has no graphical session (no DISPLAY and no Wayland display), so there is nothing to capture — servers and containers usually have none.`;
   }
-  // GNOME on Wayland is its own case: Mutter does not expose wlr-screencopy, so grim cannot capture
-  // it at all, and the shell's own D-Bus method answers `Screenshot is not allowed` to anything that
-  // is not the screenshot portal. The tool that does work is gnome-screenshot (it goes through the
-  // portal and asks the person once), so the message names that instead of sending people to grim.
+  // GNOME on Wayland is its own case: Mutter does not expose wlr-screencopy, so grim cannot
+  // capture it. ReMCP tries the compositor-supported XDG Desktop Portal first; local screenshot
+  // commands remain fallbacks for environments where the portal is unavailable.
   if (wayland && /gnome/i.test(String(env.XDG_CURRENT_DESKTOP || ''))) {
-    return `Could not capture the screen on GNOME Wayland (${attempts.join('; ') || 'no capture command ran'}). Install the screenshot helper once — \`sudo apt install gnome-screenshot\` (or the equivalent for this distribution) — and approve the permission dialog it shows; GNOME blocks the shell's own screenshot API for background processes, and grim cannot read a GNOME session.`;
+    return `Could not capture the screen on GNOME Wayland (${attempts.join('; ') || 'no capture backend ran'}). ReMCP tried the XDG Desktop Portal first, which is GNOME's supported screenshot API. Make sure xdg-desktop-portal and xdg-desktop-portal-gnome are installed and the agent is running inside the signed-in user's graphical session; command-line capture helpers are only fallbacks.`;
   }
   if (wayland) {
-    return `Could not capture the screen on Wayland (${attempts.join('; ') || 'no capture command ran'}). Install \`grim\` (Wayland's capture tool) — X11 tools such as scrot or ImageMagick import cannot read a Wayland session.`;
+    return `Could not capture the screen on Wayland (${attempts.join('; ') || 'no capture backend ran'}). ReMCP tried the XDG Desktop Portal first. Verify xdg-desktop-portal is running; on wlroots compositors, \`grim\` is also supported as a fallback.`;
   }
   return `Could not capture the screen. Install one of grim, gnome-screenshot, spectacle, scrot, or ImageMagick import (tried: ${attempts.join('; ') || 'none available'}).`;
 }
@@ -969,11 +969,27 @@ export async function takeScreenshotTool(args) {
     const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', windowsScreenshotScript(file)], { encoding: 'utf8', timeout: 30000 });
     attempts.push(`powershell: ${(result.stderr || '').trim() || `exit ${result.status}`}`);
   } else {
-    for (const candidate of SCREENSHOT_COMMANDS) {
-      if (spawnSync('which', [candidate.command], { encoding: 'utf8' }).status !== 0) continue;
-      const result = spawnSync(candidate.command, candidate.args(file), { encoding: 'utf8', timeout: 30000 });
-      if (result.status === 0 && await pathExists(file)) break;
-      attempts.push(`${candidate.command}: ${(result.stderr || '').trim() || `exit ${result.status}`}`);
+    // GNOME and other modern Wayland compositors intentionally prevent X11/wlroots
+    // screenshot commands from reading the desktop. The freedesktop Screenshot portal
+    // is the compositor-supported API and must run before command-line fallbacks.
+    if (process.platform === 'linux' && isWaylandSession()) {
+      try {
+        await capturePortalScreenshot(file);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : `xdg-desktop-portal: ${String(error)}`;
+        attempts.push(message);
+        if (error && typeof error === 'object' && error.code === 'PORTAL_CANCELLED') {
+          fail(`Screen capture was cancelled in the desktop permission dialog (${message}).`);
+        }
+      }
+    }
+    if (!await pathExists(file)) {
+      for (const candidate of SCREENSHOT_COMMANDS) {
+        if (spawnSync('which', [candidate.command], { encoding: 'utf8' }).status !== 0) continue;
+        const result = spawnSync(candidate.command, candidate.args(file), { encoding: 'utf8', timeout: 30000 });
+        if (result.status === 0 && await pathExists(file)) break;
+        attempts.push(`${candidate.command}: ${(result.stderr || '').trim() || `exit ${result.status}`}`);
+      }
     }
   }
   if (!await pathExists(file)) {