@remcp/runtime 0.2.128 → 0.2.130

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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.
+- `launch_app` requires `desktop_session`; `open_path` and `reveal_path` require `desktop_open`, which additionally checks `xdg-open` on Linux.
+- AT-SPI/Wayland portal probes are skipped entirely on headless Linux. Browser/CDP and non-desktop capability groups remain independent.
+- Tool names and MCP schemas remain unchanged.
+
 ## 0.2.128 — 2026-10-02
 
 - Linux `power_action` is advertised only when both `loginctl` and `systemctl` exist, matching the full lock/sleep/restart/shutdown schema instead of exposing a partially unusable tool.

package/README.md

@@ -77,7 +77,13 @@ system tools such as qpdf/poppler when present. PDF text reading uses the built-
 A running device can advertise a smaller capability-aware subset; the runtime declares
 `tools.listChanged`, emits `notifications/tools/list_changed` when dynamic capabilities change, and the
 agent forwards the refreshed tool names to the hosted relay. Browser/CDP tools are the primary dynamic
-example: they are enabled only while the runtime can use a supported loopback browser endpoint.
+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. 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.128",
+  "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';
 
@@ -534,7 +535,7 @@ export const extendedToolDefinitions = [
   ),
   define('list_windows', 'List windows', 'List visible top-level desktop windows with stable-enough identifiers, PID, application name, title, bounds, and the monitor containing the largest part of each window when display geometry is available.', o({ include_monitor:b('Enrich each window with monitor and monitor_index; default true.') }), readOnlyLive, desktopHandlers.list_windows, ['windows']),
   define('window_action', 'Window action', 'Focus, minimize, maximize, restore, move, resize, or close a top-level desktop window selected by id, pid, application name, or title. Native GNOME Wayland focus uses AT-SPI; compositor window-manager actions use the consent-backed XDG RemoteDesktop input path.', o({ action:e(['focus','minimize','maximize','restore','move','resize','move_resize','close']), ...windowSelector, x:n(), y:n(), width:n(), height:n(), ...inputBackendSelector }, ['action']), mutating, desktopHandlers.window_action, ['windows']),
-  define('launch_app', 'Launch application', 'Launch a desktop application or executable without invoking a shell. On Windows, executable/path launch falls back to Start Menu/UWP app discovery by friendly name. cwd is confined by the ReMCP filesystem policy and is only accepted when the platform can guarantee the child working directory. Optionally wait until a matching top-level window exists.', o({ app:s('Application name, friendly Start Menu name, or executable path.'), path:s('Alias for app.'), args:{ type:'array', items:{type:'string'} }, cwd:s('Optional permitted working directory for direct executable launch.'), wait_for_window:s('Optional application/title substring that must appear after launch.'), wait_timeout_ms:n('Maximum wait for wait_for_window; default 10000, maximum 120000.') }), openMutatingNonDestructive, desktopHandlers.launch_app),
+  define('launch_app', 'Launch application', 'Launch a desktop application or executable without invoking a shell. On Windows, executable/path launch falls back to Start Menu/UWP app discovery by friendly name. cwd is confined by the ReMCP filesystem policy and is only accepted when the platform can guarantee the child working directory. Optionally wait until a matching top-level window exists.', o({ app:s('Application name, friendly Start Menu name, or executable path.'), path:s('Alias for app.'), args:{ type:'array', items:{type:'string'} }, cwd:s('Optional permitted working directory for direct executable launch.'), wait_for_window:s('Optional application/title substring that must appear after launch.'), wait_timeout_ms:n('Maximum wait for wait_for_window; default 10000, maximum 120000.') }), openMutatingNonDestructive, desktopHandlers.launch_app, ['desktop_session']),
   define('ui_snapshot', 'UI accessibility snapshot', 'Read the active desktop accessibility/UI Automation tree with compact labels, semantic hierarchy, bounds, state and suggested actions. Default scope is the active application/window; scope=desktop requests the full desktop tree. Explicit pid/app/window_title scopes override the active default. browser_dom asks the OS accessibility provider for the web-document subtree when available.', o({ scope:e(['active','desktop'],'Default active. Use desktop only when cross-application discovery is required.'), pid:n('Optional owning process id scope.'), app:s('Optional application/process name substring scope.'), window_title:s('Optional top-level accessibility window/frame title scope.'), browser_dom:b('Prefer the native browser document accessibility subtree instead of browser chrome when supported.'), semantic_tree:b('Include compact semantic hierarchy text; default true.'), max_nodes:n('Maximum nodes; default 500, maximum 5000.'), max_depth:n('Maximum traversal depth; default 8, maximum 32.') }), readOnlyLive, desktopHandlers.ui_snapshot, ['ui']),
   define('ui_find', 'Find UI elements', 'Find native accessible desktop elements by label/id/name/role/AutomationId. Reuses the latest five-second semantic snapshot for fast repeated targeting; refresh=true forces a new OS accessibility capture.', o({ ...uiSelector, refresh:b('Force a fresh accessibility capture instead of the short-lived snapshot cache.'), limit:n('Maximum matches; default 20.'), max_nodes:n(), max_depth:n() }), readOnlyLive, desktopHandlers.ui_find, ['ui']),
   define('ui_action', 'Act on UI element', 'Act on a native accessibility/UI Automation element by id, label or semantic selector. Supports invoke/focus/value/toggle/selection, expand-collapse, range values and scroll-into-view before falling back to coordinates.', o({ action:e(['click','invoke','focus','set_value','select','toggle','expand','collapse','scroll_into_view','set_range_value','add_to_selection','remove_from_selection']), ...uiSelector, value:{description:'New text or numeric range value.'} }, ['action']), openMutating, desktopHandlers.ui_action, ['ui']),
@@ -547,8 +548,8 @@ export const extendedToolDefinitions = [
   define('clipboard', 'Clipboard', 'Read, write, or clear the system text clipboard using native operating-system clipboard facilities.', o({ action:e(['read','write','clear']), text:s('Text to write.') }, ['action']), mutating, desktopHandlers.clipboard, ['clipboard']),
   define('display_inventory', 'Display inventory', 'List connected displays/monitors and their geometry and primary-display status using native display tools.', o(), readOnlyLive, desktopHandlers.display_inventory, ['displays']),
   define('screenshot_region', 'Screenshot region', 'Capture a desktop rectangle, a selected top-level window, or a selected monitor and return it as an inline PNG. This avoids full-desktop screenshots when only one UI area matters.', o({ x:n(), y:n(), width:n(), height:n(), window_id:s('Window id returned by list_windows.'), pid:n(), app:s(), title:s(), monitor:s('Monitor name substring, or "primary".'), monitor_index:n('Zero-based monitor index from display_inventory.'), padding:n('Optional pixels added around the resolved rectangle; 0..200.') }), readOnlyLive, desktopHandlers.screenshot_region, ['screen_region']),
-  define('open_path', 'Open path', 'Open a permitted local file or directory in its system-associated desktop application. Filesystem confinement is checked before opening.', o({ path:s('File or directory to open.') }, ['path']), additive, desktopHandlers.open_path),
-  define('reveal_path', 'Reveal path', 'Reveal a permitted local file or directory in Finder, Explorer, or the Linux file manager after applying ReMCP filesystem confinement.', o({ path:s('File or directory to reveal.') }, ['path']), additive, desktopHandlers.reveal_path),
+  define('open_path', 'Open path', 'Open a permitted local file or directory in its system-associated desktop application. Filesystem confinement is checked before opening.', o({ path:s('File or directory to open.') }, ['path']), additive, desktopHandlers.open_path, ['desktop_open']),
+  define('reveal_path', 'Reveal path', 'Reveal a permitted local file or directory in Finder, Explorer, or the Linux file manager after applying ReMCP filesystem confinement.', o({ path:s('File or directory to reveal.') }, ['path']), additive, desktopHandlers.reveal_path, ['desktop_open']),
   define('notification', 'Desktop notification', 'Show a native desktop notification or user-visible popup on the paired computer.', o({ title:s(), message:s('Notification message.'), timeout_seconds:n() }, ['message']), additive, desktopHandlers.notification, ['notifications']),
 
   define('browser_tabs', 'Browser tabs', 'List debuggable Chrome, Edge, or Chromium page targets from a loopback-only Chrome DevTools Protocol endpoint.', o({ ...browserTarget }), readOnlyLive, browserHandlers.browser_tabs, ['browser_cdp']),
@@ -598,6 +599,19 @@ async function linuxHasPyAtSpi() {
   return pyAtSpiCache.value;
 }
 
+export function desktopShellCapabilitySnapshot({
+  platform = process.platform,
+  env = process.env,
+  commandExistsFn = commandExists,
+} = {}) {
+  const nativeDesktop = platform === 'win32' || platform === 'darwin';
+  const desktopSession = desktopSessionAvailable({ platform, env });
+  return {
+    desktop_session:desktopSession,
+    desktop_open:desktopSession && (nativeDesktop || commandExistsFn('xdg-open')),
+  };
+}
+
 export function powerCapabilitySnapshot({
   platform = process.platform,
   commandExistsFn = commandExists,
@@ -626,23 +640,27 @@ export async function capabilitySnapshot() {
   const win = process.platform === 'win32';
   const mac = process.platform === 'darwin';
   const linux = process.platform === 'linux';
-  const pyAtSpi = linux ? await linuxHasPyAtSpi() : false;
-  const wayland = linux && isWaylandSession();
+  const desktopShellCapabilities = desktopShellCapabilitySnapshot();
+  const desktopSession = desktopShellCapabilities.desktop_session;
+  const pyAtSpi = linux && desktopSession ? await linuxHasPyAtSpi() : false;
+  const wayland = linux && desktopSession && isWaylandSession();
   const gnomeRecord = wayland ? await gnomeScreencastSupported() : false;
-  const portalInput = wayland && waylandPortalCandidate();
-  const x11Input = linux && !wayland && (commandExists('wdotool') || commandExists('xdotool'));
+  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();
   return {
-    windows: win || mac || commandExists('wdotool') || commandExists('wmctrl') || (wayland && pyAtSpi),
-    ui: win || mac || pyAtSpi,
-    input: win || mac || portalInput || x11Input || (wayland && commandExists('wtype')),
-    pointer: win || mac || portalInput || x11Input,
-    drag: win || mac || portalInput || x11Input,
-    clipboard: win || mac || commandExists('wl-paste') || commandExists('xclip') || commandExists('xsel'),
-    displays: win || mac || (wayland && linux) || commandExists('wlr-randr') || commandExists('xrandr'),
-    screen_region: win || mac || commandExists('grim') || commandExists('import') || (isWaylandSession() && commandExists('ffmpeg')),
-    notifications: win || mac || commandExists('notify-send'),
+    ...desktopShellCapabilities,
+    windows: win || mac || (desktopSession && (commandExists('wdotool') || commandExists('wmctrl') || (wayland && pyAtSpi))),
+    ui: win || mac || (desktopSession && pyAtSpi),
+    input: win || mac || (desktopSession && (portalInput || x11Input || (wayland && commandExists('wtype')))),
+    pointer: win || mac || (desktopSession && (portalInput || x11Input)),
+    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 && 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())),
     services: win || mac || commandExists('systemctl'),

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: {