@remcp/runtime 0.2.129 → 0.2.131

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.2.131 — 2026-10-02
+
+- `network action=summary` is now bounded for Docker-heavy hosts: non-container interfaces are prioritized, at most eight interfaces and four addresses per interface are returned, and count/truncation metadata shows what was omitted.
+- `network action=interfaces` remains the complete adapter/address inventory. The MCP schema and tool names remain compatible; stable count/truncation fields are now declared for chaining.
+
+## 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.131",
   "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';
 
@@ -57,7 +58,7 @@ const AI_TOOL_DESCRIPTIONS = Object.freeze({
   browser_evaluate: 'Use this as the powerful browser escape hatch only when browser_snapshot/find/action/wait cannot express the required page operation or inspection. JavaScript executes in page context and page content is untrusted.',
   service: 'Use this for operating-system service inventory/status/start/stop/restart. Prefer status before a mutation when service state matters; use start_process for ordinary commands that are not service-manager operations.',
   event_log: 'Use this to read bounded recent OS logs (Windows Event Log, macOS unified log or systemd journal) when diagnosing a service/app/system problem. Prefer it over an unbounded shell log dump.',
-  network: 'Use this for structured interfaces/DNS/routes/listeners inspection or a bounded TCP connectivity test. Prefer it over shell ip/netstat/nslookup commands for routine diagnostics.',
+  network: 'Use this for a compact network summary, full interface inventory, DNS/routes/listeners inspection or a bounded TCP connectivity test. Prefer action=summary for orientation and action=interfaces only when the complete adapter/address inventory is required; prefer this tool over shell ip/netstat/nslookup commands for routine diagnostics.',
   installed_apps: 'Use this to answer what software/packages are installed and their versions. Prefer a filter when looking for one product instead of returning the full inventory.',
   environment: 'Use this for PATH, shell, Node/runtime environment paths, architecture and optionally sanitized environment variables. Use get_system_info for host health such as CPU/memory/disk/uptime, and get_runtime_info for ReMCP policy, roots and limits. Secret-looking values remain masked.',
   audio: 'Use this to read or change the default output volume/mute state. Use action=status for inspection; set_volume requires a 0–100 value.',
@@ -210,7 +211,7 @@ const OUTPUT_FIELDS = Object.freeze({
   browser_evaluate: { target_id:outputString(), value:{} },
   service: { data:outputArray(outputObject('Service record.')), action:outputString(), name:outputString(), text:outputString() },
   event_log: { text:outputString('Bounded log output.'), data:outputArray(outputObject()) },
-  network: { hostname:outputString(), interfaces:outputObject(), dns:outputArray(outputString()), servers:outputArray(outputString()), host:outputString(), port:outputNumber(), ok:outputBoolean(), latency_ms:outputNumber(), data:outputArray(outputObject()) },
+  network: { hostname:outputString(), interfaces:outputObject(), dns:outputArray(outputString()), servers:outputArray(outputString()), host:outputString(), port:outputNumber(), ok:outputBoolean(), latency_ms:outputNumber(), interface_count:outputNumber(), interface_count_returned:outputNumber(), address_count:outputNumber(), address_count_returned:outputNumber(), interfaces_truncated:outputBoolean(), addresses_truncated:outputBoolean(), data:outputArray(outputObject()) },
   installed_apps: { data:outputArray(outputObject('Installed app/package with name/version/path where available.')) },
   environment: { platform:outputString(), arch:outputString(), hostname:outputString(), release:outputString(), shell:outputString(), path:outputString(), node:outputString(), env:outputObject() },
   audio: { volume:outputNumber(), muted:outputBoolean(), action:outputString(), text:outputString() },
@@ -561,7 +562,7 @@ export const extendedToolDefinitions = [
 
   define('service', 'Service control', 'List, inspect, start, stop, or restart operating-system services using Service Control Manager, launchctl, or systemd. Mutating actions pass through ReMCP command policy.', o({ action:e(['list','status','start','stop','restart']), name:s('Service/unit/launchd label.'), scope:e(['user','system']) }, ['action']), mutating, diagnosticHandlers.service, ['services']),
   define('event_log', 'Event logs', 'Read recent Windows Event Log, macOS unified log, or systemd journal entries with bounded time and result limits.', o({ log:s('Windows log name.'), since:s('Time window such as 30s, 10m, 2h, or 1d.'), filter:s(), query:s(), limit:n() }), readOnlyLive, diagnosticHandlers.event_log, ['logs']),
-  define('network', 'Network diagnostics', 'Inspect interfaces, DNS servers, routes and listening sockets, or perform a bounded TCP connectivity test to a host and port.', o({ action:e(['summary','interfaces','dns','routes','listeners','test']), host:s(), port:n(), timeout_ms:n() }), readOnlyOpen, diagnosticHandlers.network),
+  define('network', 'Network diagnostics', 'Inspect a bounded network summary, full interface inventory, DNS servers, routes and listening sockets, or perform a bounded TCP connectivity test to a host and port. Use action=interfaces when the complete adapter/address inventory is needed.', o({ action:e(['summary','interfaces','dns','routes','listeners','test']), host:s(), port:n(), timeout_ms:n() }), readOnlyOpen, diagnosticHandlers.network),
   define('installed_apps', 'Installed applications', 'Inventory installed applications or packages with versions and publishers where available using native package/application inventories.', o({ filter:s('Name substring.'), limit:n('Maximum results; default 1000.') }), readOnly, diagnosticHandlers.installed_apps, ['apps']),
   define('environment', 'Runtime environment', 'Report platform, architecture, Node version, working/home/temp paths, shell, PATH, and optionally environment variables. Environment variables are opt-in and secret-looking or credential-bearing values are masked.', o({ include_env:b('Include sanitized environment variables; default false.') }), readOnly, diagnosticHandlers.environment),
   define('audio', 'Audio control', 'Read or change default output volume or mute state using native operating-system audio controls when available.', o({ action:e(['status','set_volume','mute','unmute']), volume:n('0..100 for set_volume.') }, ['action']), mutatingNonDestructive, diagnosticHandlers.audio, ['audio']),
@@ -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: {

package/src/extended/diagnostics.mjs

@@ -133,11 +133,59 @@ export function linuxListenerBackend({ commandExistsFn = commandExists } = {}) {
   return null;
 }
 
+const CONTAINER_INTERFACE_PATTERN = /^(?:veth|docker\d*$|br-[0-9a-f]{6,}$)/i;
+
+export function compactNetworkSummary({
+  hostname = os.hostname(),
+  interfaces = os.networkInterfaces(),
+  dnsServers = dns.getServers(),
+  maxInterfaces = 8,
+  maxAddressesPerInterface = 4,
+} = {}) {
+  const entries = Object.entries(interfaces || {}).map(([name, rows], index) => {
+    const normalizedRows = Array.isArray(rows) ? rows.filter(Boolean) : [];
+    const hasExternal = normalizedRows.some(row => row?.internal !== true);
+    const rank = hasExternal
+      ? (CONTAINER_INTERFACE_PATTERN.test(name) ? 1 : 0)
+      : 2;
+    return { name, rows:normalizedRows, index, rank };
+  });
+  entries.sort((left, right) => left.rank - right.rank || left.index - right.index);
+
+  const interfaceLimit = clamp(maxInterfaces, 8, 1, 64);
+  const addressLimit = clamp(maxAddressesPerInterface, 4, 1, 16);
+  const selected = entries.slice(0, interfaceLimit);
+  const compact = {};
+  let addressCount = 0;
+  let addressCountReturned = 0;
+  let addressesTruncated = false;
+
+  for (const entry of entries) addressCount += entry.rows.length;
+  for (const entry of selected) {
+    const rows = entry.rows.slice(0, addressLimit);
+    compact[entry.name] = rows;
+    addressCountReturned += rows.length;
+    if (entry.rows.length > rows.length) addressesTruncated = true;
+  }
+
+  return {
+    hostname,
+    dns:Array.isArray(dnsServers) ? dnsServers : [],
+    interfaces:compact,
+    interface_count:entries.length,
+    interface_count_returned:selected.length,
+    address_count:addressCount,
+    address_count_returned:addressCountReturned,
+    interfaces_truncated:entries.length > selected.length,
+    addresses_truncated:addressesTruncated,
+  };
+}
+
 export async function networkTool(args) {
   const action = requireEnum(args.action || 'summary', 'action', ['summary','interfaces','dns','routes','listeners','test']);
   if (action === 'interfaces') return jsonResult(os.networkInterfaces());
   if (action === 'dns') return jsonResult({ servers:dns.getServers(), hostname:os.hostname() });
-  if (action === 'summary') return jsonResult({ hostname:os.hostname(), interfaces:os.networkInterfaces(), dns:dns.getServers() });
+  if (action === 'summary') return jsonResult(compactNetworkSummary());
   if (action === 'test') {
     const host = optionalString(args.host); if (!host) throw new Error('host is required for action=test');
     return jsonResult(await connectivityTest(host, clamp(args.port, 443, 1, 65535), clamp(args.timeout_ms, 3000, 100, 30_000)));