@remcp/runtime 0.2.119 → 0.2.121

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.121 — 2026-09-29
+
+- record_screen gains a GNOME Shell Screencast backend for GNOME Wayland, so a native GNOME desktop no longer needs wf-recorder merely to advertise and perform bounded screen recording. The backend keeps start/stop on one D-Bus connection and produces WebM.
+- Capability discovery probes ScreencastSupported fail-closed, caches the result for 15 seconds, and coalesces concurrent probes before tools/list_changed can expose the capability. Existing wf-recorder, X11 ffmpeg, AVFoundation and gdigrab paths remain available.
+- Explicit recording destinations must use an extension matching the actual container (.webm for native GNOME Wayland, .mp4 for the other current backends).
+
 ## 0.2.116 — 2026-09-29
 
 - Linux Wayland `list_windows` stops its AT-SPI inventory traversal at top-level windows instead of walking descendant controls. On the verified ASUS desktop this kept the same 13 stable window records while cutting the call from roughly 7.2 seconds to roughly 2.1 seconds; `computer_snapshot` first-look latency fell from 7.50 seconds to 2.45 seconds in the same state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.119",
+  "version": "0.2.121",
   "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

@@ -9,7 +9,7 @@ import { isWaylandSession } from '../screenshot-portal.mjs';
 import { waylandPortalCandidate } from '../wayland-remote-desktop.mjs';
 import { commandExists, runFile } from './common.mjs';
 import { desktopHandlers } from './desktop.mjs';
-import { diagnosticHandlers, recordScreenAvailable } from './diagnostics.mjs';
+import { diagnosticHandlers, gnomeScreencastSupported, recordScreenAvailable } from './diagnostics.mjs';
 import { documentHandlers } from './documents.mjs';
 
 const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
@@ -566,7 +566,7 @@ export const extendedToolDefinitions = [
   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']),
   define('power_action', 'Power action', 'Lock, sleep, restart, or shut down the paired computer using native operating-system power facilities. The action passes through ReMCP command policy.', o({ action:e(['lock','sleep','restart','shutdown']), delay_seconds:n('Optional delay, maximum 3600 seconds.') }, ['action']), mutating, diagnosticHandlers.power_action, ['power']),
-  define('record_screen', 'Record screen', 'Record a short bounded desktop video to a permitted local file for debugging and return its path and size. Uses native/available recording helpers.', o({ duration_seconds:n('1..120 seconds.'), fps:n('1..60.'), destination:s('Permitted output path.') }), mutating, diagnosticHandlers.record_screen, ['record']),
+  define('record_screen', 'Record screen', 'Record a short bounded desktop video to a permitted local file for debugging and return its path and size. Uses native/available recording helpers.', o({ duration_seconds:n('1..120 seconds.'), fps:n('1..60.'), destination:s('Permitted output path. If an extension is supplied, use .webm for native GNOME Wayland recording and .mp4 for the other recorder backends.') }), mutating, diagnosticHandlers.record_screen, ['record']),
 
   define('read_document', 'Read document', 'Read PDF, DOCX, XLSX, TXT, Markdown, CSV, JSON, or XML. PDF/DOCX extraction is built in and XLSX is parsed from its OOXML worksheet cells.', o({ path:s('Document path.'), sheet:s('Worksheet name for XLSX.'), max_cells:n() }, ['path']), readOnly, documentHandlers.read_document, ['documents']),
   define('edit_spreadsheet', 'Edit spreadsheet', 'Create a new XLSX workbook or edit up to 500 expanded XLSX cells directly in OOXML without launching Excel. For creation set create=true and use path as a new destination; existing files are never overwritten by create mode. Each edit may target one cell or a rectangular range, with a scalar fill, a values matrix, or a formula.', o({ path:s('Existing .xlsx path, or the new workbook destination when create=true.'), create:b('Create a new XLSX at path. Fails if path already exists; do not combine with output.'), output:s('Optional output .xlsx when editing an existing workbook; defaults to replacing input.'), sheet:s('Worksheet name. For create=true, defaults to Sheet1 and becomes the new workbook sheet name.'), edits:{ type:'array', maxItems:500, items:o({ cell:s('Single A1 cell reference.'), range:s('Rectangular range such as A1:C3.'), value:{ description:'Scalar value for one cell or to fill a range.' }, values:{ type:'array', items:{ type:'array', items:{} }, description:'2D matrix matching the range dimensions.' }, formula:s('Optional formula; for a range it is written to each expanded cell.') }) } }, ['path','edits']), mutating, documentHandlers.edit_spreadsheet, ['documents']),
@@ -604,6 +604,7 @@ export async function capabilitySnapshot() {
   const linux = process.platform === 'linux';
   const pyAtSpi = linux ? await linuxHasPyAtSpi() : false;
   const wayland = linux && isWaylandSession();
+  const gnomeRecord = wayland ? await gnomeScreencastSupported() : false;
   const portalInput = wayland && waylandPortalCandidate();
   const x11Input = linux && !wayland && (commandExists('wdotool') || commandExists('xdotool'));
   const browserCdp = browserRemoteEnabled() && await browserControlAvailable(undefined, 500);
@@ -626,7 +627,7 @@ export async function capabilitySnapshot() {
     apps: win || mac || commandExists('dpkg-query') || commandExists('rpm'),
     audio: win || mac || commandExists('wpctl') || commandExists('pactl') || commandExists('amixer'),
     power: win || mac || commandExists('systemctl') || commandExists('loginctl'),
-    record: recordScreenAvailable({ platform:process.platform, wayland }),
+    record: recordScreenAvailable({ platform:process.platform, wayland, gnomeSupported:gnomeRecord }),
     ooxml: linux && (commandExists('zip') && commandExists('unzip')),
   };
 }

package/src/extended/diagnostics.mjs

@@ -5,7 +5,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { randomUUID } from 'node:crypto';
 import { constants, existsSync } from 'node:fs';
-import { lstat, mkdtemp, open, rename, rm, stat, unlink } from 'node:fs/promises';
+import { lstat, mkdtemp, open, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
 import { assertAllowedCommand } from '../policy.mjs';
 import { isWaylandSession } from '../screenshot-portal.mjs';
 import { openDirectoryPath } from '../tools/files.mjs';
@@ -282,21 +282,228 @@ async function avfoundationScreenInput(ffmpeg) {
   return index;
 }
 
-export function recordScreenAvailable({
+export function gnomeScreencastCandidate({
+  platform = process.platform,
+  wayland = platform === 'linux' ? isWaylandSession() : false,
+  desktop = process.env.XDG_CURRENT_DESKTOP || '',
+  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
+  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
+  commandExistsFn = commandExists,
+} = {}) {
+  const gnomeSession = /gnome/i.test(String(desktop)) || Boolean(String(gnomeSessionMode).trim());
+  return platform === 'linux'
+    && wayland
+    && gnomeSession
+    && Boolean(String(sessionBus).trim())
+    && commandExistsFn('gjs');
+}
+
+export function recordScreenBackend({
   platform = process.platform,
   wayland = platform === 'linux' ? isWaylandSession() : false,
   display = process.env.DISPLAY || '',
+  desktop = process.env.XDG_CURRENT_DESKTOP || '',
+  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
+  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
+  gnomeSupported = false,
   commandExistsFn = commandExists,
   existsSyncFn = existsSync,
 } = {}) {
   if (platform === 'linux') {
-    if (wayland) return commandExistsFn('wf-recorder') && commandExistsFn('timeout');
-    return Boolean(String(display).trim()) && commandExistsFn('ffmpeg');
+    if (wayland) {
+      if (gnomeSupported && gnomeScreencastCandidate({
+        platform,
+        wayland,
+        desktop,
+        gnomeSessionMode,
+        sessionBus,
+        commandExistsFn,
+      })) return 'gnome-shell';
+      if (commandExistsFn('wf-recorder') && commandExistsFn('timeout')) return 'wf-recorder';
+      return null;
+    }
+    return Boolean(String(display).trim()) && commandExistsFn('ffmpeg') ? 'ffmpeg-x11' : null;
+  }
+  if (platform === 'darwin') {
+    return resolveRecordScreenFfmpeg({ platform, commandExistsFn, existsSyncFn }) ? 'ffmpeg-avfoundation' : null;
   }
-  if (platform === 'darwin' || platform === 'win32') {
-    return Boolean(resolveRecordScreenFfmpeg({ platform, commandExistsFn, existsSyncFn }));
+  if (platform === 'win32') {
+    return resolveRecordScreenFfmpeg({ platform, commandExistsFn, existsSyncFn }) ? 'ffmpeg-gdigrab' : null;
+  }
+  return null;
+}
+
+export function recordScreenAvailable({
+  platform = process.platform,
+  wayland = platform === 'linux' ? isWaylandSession() : false,
+  display = process.env.DISPLAY || '',
+  desktop = process.env.XDG_CURRENT_DESKTOP || '',
+  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
+  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
+  gnomeSupported = false,
+  commandExistsFn = commandExists,
+  existsSyncFn = existsSync,
+} = {}) {
+  return Boolean(recordScreenBackend({
+    platform,
+    wayland,
+    display,
+    desktop,
+    gnomeSessionMode,
+    sessionBus,
+    gnomeSupported,
+    commandExistsFn,
+    existsSyncFn,
+  }));
+}
+
+const GNOME_SCREENCAST_SUPPORT_HELPER = `const {Gio, GLib} = imports.gi;
+const bus = Gio.bus_get_sync(Gio.BusType.SESSION, null);
+const value = bus.call_sync(
+  'org.gnome.Shell.Screencast',
+  '/org/gnome/Shell/Screencast',
+  'org.freedesktop.DBus.Properties',
+  'Get',
+  new GLib.Variant('(ss)', ['org.gnome.Shell.Screencast', 'ScreencastSupported']),
+  new GLib.VariantType('(v)'),
+  Gio.DBusCallFlags.NONE,
+  3000,
+  null
+).deepUnpack();
+print(value[0].deepUnpack() ? 'true' : 'false');
+`;
+
+let gnomeScreencastSupportCache = { key:'', value:false, expiresAt:0 };
+let gnomeScreencastSupportProbe = { key:'', promise:null };
+
+export async function gnomeScreencastSupported({
+  platform = process.platform,
+  wayland = platform === 'linux' ? isWaylandSession() : false,
+  desktop = process.env.XDG_CURRENT_DESKTOP || '',
+  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
+  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
+  commandExistsFn = commandExists,
+  runFileFn = runFile,
+  cacheMs = 15_000,
+  nowFn = Date.now,
+} = {}) {
+  if (!gnomeScreencastCandidate({
+    platform,
+    wayland,
+    desktop,
+    gnomeSessionMode,
+    sessionBus,
+    commandExistsFn,
+  })) return false;
+
+  const key = [platform, wayland ? 'wayland' : '', desktop, gnomeSessionMode, sessionBus].join('|');
+  const now = nowFn();
+  if (cacheMs > 0 && gnomeScreencastSupportCache.key === key && gnomeScreencastSupportCache.expiresAt > now) {
+    return gnomeScreencastSupportCache.value;
+  }
+  if (gnomeScreencastSupportProbe.key === key && gnomeScreencastSupportProbe.promise) {
+    return gnomeScreencastSupportProbe.promise;
+  }
+
+  const promise = (async () => {
+    let value = false;
+    try {
+      const result = await runFileFn('gjs', ['-c', GNOME_SCREENCAST_SUPPORT_HELPER], {
+        label:'GNOME Shell screencast capability probe',
+        timeout:5000,
+        maxBuffer:64 * 1024,
+        allowFailure:true,
+      });
+      value = Number(result.code) === 0 && String(result.stdout || '').trim() === 'true';
+    } catch {
+      value = false;
+    }
+    gnomeScreencastSupportCache = {
+      key,
+      value,
+      expiresAt:nowFn() + Math.max(0, cacheMs),
+    };
+    return value;
+  })();
+
+  gnomeScreencastSupportProbe = { key, promise };
+  try {
+    return await promise;
+  } finally {
+    if (gnomeScreencastSupportProbe.key === key && gnomeScreencastSupportProbe.promise === promise) {
+      gnomeScreencastSupportProbe = { key:'', promise:null };
+    }
+  }
+}
+
+const GNOME_SCREENCAST_HELPER = `const {Gio, GLib} = imports.gi;
+const [destination, secondsRaw, fpsRaw] = ARGV;
+const seconds = Number(secondsRaw);
+const fps = Number(fpsRaw);
+const bus = Gio.bus_get_sync(Gio.BusType.SESSION, null);
+const destinationName = 'org.gnome.Shell.Screencast';
+const objectPath = '/org/gnome/Shell/Screencast';
+const interfaceName = 'org.gnome.Shell.Screencast';
+const property = bus.call_sync(
+  destinationName,
+  objectPath,
+  'org.freedesktop.DBus.Properties',
+  'Get',
+  new GLib.Variant('(ss)', [interfaceName, 'ScreencastSupported']),
+  new GLib.VariantType('(v)'),
+  Gio.DBusCallFlags.NONE,
+  5000,
+  null
+).deepUnpack();
+if (!property[0].deepUnpack()) throw new Error('GNOME Shell reports ScreencastSupported=false');
+const options = {
+  'draw-cursor': new GLib.Variant('b', true),
+  'framerate': new GLib.Variant('i', fps),
+};
+const started = bus.call_sync(
+  destinationName,
+  objectPath,
+  interfaceName,
+  'Screencast',
+  new GLib.Variant('(sa{sv})', [destination, options]),
+  new GLib.VariantType('(bs)'),
+  Gio.DBusCallFlags.NONE,
+  10000,
+  null
+).deepUnpack();
+if (!started[0]) throw new Error('GNOME Shell refused to start screencast');
+GLib.usleep(Math.round(seconds * 1000000));
+const stopped = bus.call_sync(
+  destinationName,
+  objectPath,
+  interfaceName,
+  'StopScreencast',
+  null,
+  new GLib.VariantType('(b)'),
+  Gio.DBusCallFlags.NONE,
+  10000,
+  null
+).deepUnpack();
+if (!stopped[0]) throw new Error('GNOME Shell did not stop screencast cleanly');
+print(JSON.stringify({ destination:started[1], stopped:stopped[0] }));
+`;
+
+async function recordGnomeShellScreen({ staged, stagingDirectory, seconds, fps }) {
+  const helper = path.join(stagingDirectory, 'gnome-screencast.js');
+  await writeFile(helper, GNOME_SCREENCAST_HELPER, { mode:0o600 });
+  await runFile('gjs', [helper, staged, String(seconds), String(fps)], {
+    label:'GNOME Shell screen recording',
+    timeout:(seconds + 20) * 1000,
+    maxBuffer:2 * 1024 * 1024,
+  });
+}
+
+export function validateRecordingDestinationFormat(destination, format) {
+  if (!destination) return;
+  const extension = path.extname(destination).slice(1).toLowerCase();
+  if (extension && extension !== format) {
+    throw new Error(`Screen recording backend produces .${format}; destination must use .${format} or omit the extension`);
   }
-  return false;
 }
 
 async function openRecordingParent(destination) {
@@ -348,24 +555,37 @@ async function copyRecordingFile(source, destination) {
 export async function recordScreen(args) {
   const seconds = clamp(args.duration_seconds, 5, 1, 120);
   const fps = clamp(args.fps, 15, 1, 60);
+  const wayland = process.platform === 'linux' && isWaylandSession();
+  const gnomeSupported = wayland ? await gnomeScreencastSupported() : false;
+  const backend = recordScreenBackend({ platform:process.platform, wayland, gnomeSupported });
+  if (!backend) {
+    if (wayland) unavailable('Screen recording', 'GNOME Shell Screencast or wf-recorder with timeout is required on Wayland');
+    if (process.platform === 'linux' && !String(process.env.DISPLAY || '').trim()) unavailable('Screen recording', 'an active X11 DISPLAY is required on Linux X11');
+    if (process.platform === 'darwin') unavailable('Screen recording', 'ffmpeg is required on macOS');
+    if (process.platform === 'win32') unavailable('Screen recording', 'ffmpeg is required on Windows');
+    unavailable('Screen recording', 'ffmpeg is required on X11');
+  }
+
+  const format = backend === 'gnome-shell' ? 'webm' : 'mp4';
   const requestedDestination = args.destination ? await resolveSafePath(args.destination, 'destination') : '';
   if (requestedDestination) {
+    validateRecordingDestinationFormat(requestedDestination, format);
     const existing = await lstat(requestedDestination).catch(() => null);
     if (existing?.isSymbolicLink()) throw new Error('Screen recording destination cannot be a symbolic link');
     if (existing && !existing.isFile()) throw new Error('Screen recording destination is not a regular file');
   }
+
   const stagingDirectory = await mkdtemp(path.join(os.tmpdir(), 'remcp-screen-'));
-  const staged = path.join(stagingDirectory, `capture-${randomUUID()}.mp4`);
-  const wayland = process.platform === 'linux' && isWaylandSession();
+  const staged = path.join(stagingDirectory, `capture-${randomUUID()}.${format}`);
   let keepStaging = false;
   try {
-    if (wayland && commandExists('wf-recorder') && commandExists('timeout')) {
+    if (backend === 'gnome-shell') {
+      await recordGnomeShellScreen({ staged, stagingDirectory, seconds, fps });
+    } else if (backend === 'wf-recorder') {
       const result = await runFile('timeout', ['--signal=INT', `${seconds}s`, 'wf-recorder', '-f',staged,'-r',String(fps),'-c','libx264'], { label:'screen recording', timeout:(seconds+10)*1000, allowFailure:true });
       if (![0, 124, 130].includes(Number(result.code))) throw new Error(result.stderr.trim() || `wf-recorder exited ${result.code}`);
     } else {
       const ffmpeg = resolveRecordScreenFfmpeg();
-      if (wayland) unavailable('Screen recording', 'wf-recorder and timeout are required on Wayland');
-      if (process.platform === 'linux' && !String(process.env.DISPLAY || '').trim()) unavailable('Screen recording', 'an active X11 DISPLAY is required on Linux X11');
       if (!ffmpeg) {
         if (process.platform === 'darwin') unavailable('Screen recording', 'ffmpeg is required on macOS');
         if (process.platform === 'win32') unavailable('Screen recording', 'ffmpeg is required on Windows');
@@ -386,7 +606,7 @@ export async function recordScreen(args) {
     const output = requestedDestination || staged;
     const info = await stat(output);
     keepStaging = !requestedDestination;
-    return jsonResult({ path:output, bytes:info.size, duration_seconds:seconds, format:path.extname(output).slice(1) || 'mp4' });
+    return jsonResult({ path:output, bytes:info.size, duration_seconds:seconds, format });
   } finally {
     if (!keepStaging) await rm(stagingDirectory, { recursive:true, force:true }).catch(() => {});
   }