@remcp/runtime 0.2.129 → 0.2.130

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.130 — 2026-10-02
+
+- `computer_snapshot` now skips desktop-only probes on headless Linux and returns stable empty/unavailable desktop fields without false error noise. The shared `desktopSessionAvailable()` helper keeps this behavior aligned with live capability discovery.
+- Linux `screenshot_region` advertising now uses the same backend resolver as execution: `grim` is Wayland-only, portal capture requires a Wayland portal candidate plus `ffmpeg`, GNOME capture requires `gnome-screenshot` + `ffmpeg`, and X11 uses ImageMagick `import`.
+- Wayland + `ffmpeg` alone no longer exposes a screenshot tool that can only fail at runtime. Tool names and MCP schemas remain unchanged.
+
 ## 0.2.129 — 2026-10-02
 
 - Linux Desktop capability discovery now requires an active `DISPLAY` or `WAYLAND_DISPLAY`, preventing headless hosts from advertising desktop actions just because helper binaries are installed.

package/README.md

@@ -80,7 +80,10 @@ agent forwards the refreshed tool names to the hosted relay. Browser/CDP tools a
 example: they are enabled only while the runtime can use a supported loopback browser endpoint. On Linux,
 Desktop capabilities additionally require an active graphical session (`DISPLAY` or `WAYLAND_DISPLAY`):
 headless hosts do not advertise window/UI/input/clipboard/display/screenshot/launch/open/reveal/notification
-operations merely because desktop helper binaries happen to be installed.
+operations merely because desktop helper binaries happen to be installed. The universal `computer_snapshot`
+remains available on those hosts but skips unavailable desktop probes instead of reporting synthetic backend
+errors. On Linux, `screenshot_region` is advertised only when the current session has a real matching capture
+backend (Wayland grim/GNOME/portal path or X11 ImageMagick), not merely because `ffmpeg` is installed.
 
 The generated hosted reference covers the current **10 hosted production definitions**, all model-visible
 and routing to the 83 granular runtime operations described above; the optional widget-enabled surface is 15.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.129",
+  "version": "0.2.130",
   "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/catalog.mjs

@@ -7,8 +7,9 @@ const JSON_OUTPUT_SCHEMA = {
 import { browserControlAvailable, browserHandlers, browserRemoteEnabled } from './browser.mjs';
 import { isWaylandSession } from '../screenshot-portal.mjs';
 import { waylandPortalCandidate } from '../wayland-remote-desktop.mjs';
-import { commandExists, runFile } from './common.mjs';
+import { commandExists, desktopSessionAvailable, runFile } from './common.mjs';
 import { desktopHandlers } from './desktop.mjs';
+import { regionScreenshotBackends } from './desktop-linux.mjs';
 import { diagnosticHandlers, gnomeScreencastSupported, recordScreenAvailable } from './diagnostics.mjs';
 import { documentHandlers } from './documents.mjs';
 
@@ -604,9 +605,7 @@ export function desktopShellCapabilitySnapshot({
   commandExistsFn = commandExists,
 } = {}) {
   const nativeDesktop = platform === 'win32' || platform === 'darwin';
-  const linuxDesktop = platform === 'linux'
-    && Boolean(String(env?.DISPLAY || '').trim() || String(env?.WAYLAND_DISPLAY || '').trim());
-  const desktopSession = nativeDesktop || linuxDesktop;
+  const desktopSession = desktopSessionAvailable({ platform, env });
   return {
     desktop_session:desktopSession,
     desktop_open:desktopSession && (nativeDesktop || commandExistsFn('xdg-open')),
@@ -646,7 +645,8 @@ export async function capabilitySnapshot() {
   const pyAtSpi = linux && desktopSession ? await linuxHasPyAtSpi() : false;
   const wayland = linux && desktopSession && isWaylandSession();
   const gnomeRecord = wayland ? await gnomeScreencastSupported() : false;
-  const portalInput = wayland && waylandPortalCandidate();
+  const portalCandidate = wayland && waylandPortalCandidate();
+  const portalInput = portalCandidate;
   const x11Input = linux && desktopSession && !wayland && (commandExists('wdotool') || commandExists('xdotool'));
   const browserCdp = browserRemoteEnabled() && await browserControlAvailable(undefined, 500);
   const documentCapabilities = documentCapabilitySnapshot();
@@ -659,7 +659,7 @@ export async function capabilitySnapshot() {
     drag: win || mac || (desktopSession && (portalInput || x11Input)),
     clipboard: win || mac || (desktopSession && (commandExists('wl-paste') || commandExists('xclip') || commandExists('xsel'))),
     displays: win || mac || (desktopSession && ((wayland && linux) || commandExists('wlr-randr') || commandExists('xrandr'))),
-    screen_region: win || mac || (desktopSession && (commandExists('grim') || commandExists('import') || (isWaylandSession() && commandExists('ffmpeg')))),
+    screen_region: win || mac || (desktopSession && regionScreenshotBackends({ wayland, portalCandidate }).length > 0),
     notifications: win || mac || (desktopSession && commandExists('notify-send')),
     browser_cdp: browserCdp,
     browser_evaluate: browserCdp && (process.env.NODE_ENV !== 'production' || ['1', 'true', 'yes', 'on'].includes(String(process.env.REMCP_BROWSER_ALLOW_EVALUATE || '').toLowerCase())),

package/src/extended/common.mjs

@@ -21,6 +21,15 @@ export function optionalString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
+export function desktopSessionAvailable({
+  platform = process.platform,
+  env = process.env,
+} = {}) {
+  if (platform === 'win32' || platform === 'darwin') return true;
+  if (platform !== 'linux') return false;
+  return Boolean(String(env?.DISPLAY || '').trim() || String(env?.WAYLAND_DISPLAY || '').trim());
+}
+
 export function requireEnum(value, field, allowed) {
   const normalized = String(value ?? '');
   if (!allowed.includes(normalized)) fail(`${field} must be one of: ${allowed.join(', ')}`);

package/src/extended/desktop-linux.mjs

@@ -1487,12 +1487,13 @@ export function regionScreenshotBackends({
   gnomeScreenshot = commandExists('gnome-screenshot'),
   ffmpeg = commandExists('ffmpeg'),
   imagemagick = commandExists('import'),
+  portalCandidate = waylandPortalCandidate(),
 } = {}) {
   const backends = [];
-  if (grim) backends.push('grim');
+  if (wayland && grim) backends.push('grim');
   if (wayland) {
     if (gnomeScreenshot && ffmpeg) backends.push('gnome-screenshot');
-    if (ffmpeg) backends.push('portal');
+    if (ffmpeg && portalCandidate) backends.push('portal');
   } else if (imagemagick) {
     backends.push('imagemagick');
   }

package/src/extended/desktop.mjs

@@ -4,7 +4,7 @@ import { fileToolHandlers } from '../tools/files.mjs';
 import { liveConfig, runtimeConfig } from '../config.mjs';
 import { assertAllowedCommand } from '../policy.mjs';
 import { multi, resolveSafePath, text } from '../util.mjs';
-import { clamp, jsonResult, optionalString, requireEnum } from './common.mjs';
+import { clamp, desktopSessionAvailable, jsonResult, optionalString, requireEnum } from './common.mjs';
 import * as linux from './desktop-linux.mjs';
 import * as macos from './desktop-macos.mjs';
 import * as windows from './desktop-windows.mjs';
@@ -1026,12 +1026,14 @@ function computerScreenshotTask(args = {}) {
 }
 
 export async function computerSnapshot(args = {}) {
-  const captureScreenshot = args.include_screenshot !== false || args.include_ocr === true;
+  const desktopAvailable = desktopSessionAvailable();
+  const screenshotRequested = args.include_screenshot !== false || args.include_ocr === true;
+  const captureScreenshot = desktopAvailable && screenshotRequested;
   const includeUi = args.include_ui !== false;
   const [windowsResult, displaysResult, uiResult, clipboardResult, cursorResult, shotResult] = await Promise.allSettled([
-    listWindows(),
-    displayInventory(),
-    includeUi
+    desktopAvailable ? listWindows() : Promise.resolve(null),
+    desktopAvailable ? displayInventory() : Promise.resolve(null),
+    includeUi && desktopAvailable
       ? uiSnapshot({
           max_nodes:args.max_ui_nodes || 800,
           max_depth:args.max_ui_depth || 12,
@@ -1040,8 +1042,8 @@ export async function computerSnapshot(args = {}) {
           ...(args.ui_browser_dom === true ? { browser_dom:true } : {}),
         })
       : Promise.resolve(null),
-    clipboard({ action:'read' }),
-    cursorPosition(),
+    desktopAvailable ? clipboard({ action:'read' }) : Promise.resolve(null),
+    desktopAvailable ? cursorPosition() : Promise.resolve(null),
     captureScreenshot ? computerScreenshotTask(args) : Promise.resolve(null),
   ]);
   const parse = (result, fallback = null) => {
@@ -1069,7 +1071,7 @@ export async function computerSnapshot(args = {}) {
   if (includeUi && parsedUi !== ui && parsedUi != null) {
     shapeErrors.push({ source:'ui', message:'accessibility snapshot returned an invalid result shape' });
   }
-  const clipboardOk = clipboardResult.status === 'fulfilled' && clipboardResult.value?.isError !== true;
+  const clipboardOk = desktopAvailable && clipboardResult.status === 'fulfilled' && clipboardResult.value?.isError !== true && Boolean(clipboardResult.value);
   const clipText = clipboardOk ? clipboardResult.value.content?.[0]?.text || '' : '';
   const uiNodes = Array.isArray(ui?.nodes) ? ui.nodes : Array.isArray(ui) ? ui : [];
   const focusedNodes = uiNodes.filter(node => node.focused === true);
@@ -1152,8 +1154,9 @@ export async function computerSnapshot(args = {}) {
     }
   }
 
-  const shouldOcr = args.include_ocr === true
-    || (args.include_ocr !== false && captureScreenshot && uiNodes.length === 0 && !browser);
+  const ocrRequested = args.include_ocr === true
+    || (desktopAvailable && args.include_ocr !== false && screenshotRequested && uiNodes.length === 0 && !browser);
+  const shouldOcr = desktopAvailable && ocrRequested;
   let ocr = null;
   let ocrCaptureBounds = null;
   let ocrShotResult = shotResult;
@@ -1193,14 +1196,14 @@ export async function computerSnapshot(args = {}) {
     ...(browser ? { browser } : {}),
     ...(ocr ? { ocr } : {}),
     fallback_chain: {
-      accessibility: { requested:includeUi, available:includeUi && uiResult.status === 'fulfilled', nodes:uiNodes.length },
+      accessibility: { requested:includeUi, available:includeUi && desktopAvailable && uiResult.status === 'fulfilled' && Boolean(uiResult.value), nodes:uiNodes.length },
       native_browser_dom: {
         requested:includeUi && args.ui_browser_dom === true,
         available:Boolean(includeUi && ui?.browser_dom?.available),
         provider:ui?.browser_dom?.provider || null,
       },
       browser_dom: { requested:browserRequested, available:Boolean(browser) },
-      ocr: { requested:shouldOcr, available:Boolean(ocr?.available), backend:ocr?.backend || null },
+      ocr: { requested:ocrRequested, available:Boolean(ocr?.available), backend:ocr?.backend || null },
       vision_screenshot: { available:shotResult.status === 'fulfilled' && Boolean(shotResult.value?.content?.some(part => part.type === 'image')) },
     },
     visual: {