@remcp/runtime 0.2.107 → 0.2.109

package/src/extended/catalog.mjs

@@ -4,7 +4,7 @@ const JSON_OUTPUT_SCHEMA = {
   additionalProperties: true,
   description: 'Structured tool result. Array/scalar payloads are exposed under data for compatibility with MCP clients that require object-root output schemas.',
 };
-import { browserControlAvailable, browserHandlers } from './browser.mjs';
+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';
@@ -557,7 +557,7 @@ export const extendedToolDefinitions = [
   define('browser_find', 'Find browser element', 'Find visible DOM elements by CSS selector, text, or ARIA role and return reusable selectors plus text, value, and bounding boxes.', o({ ...browserTarget, selector:s('CSS selector.'), text:s('Visible text substring.'), role:s('ARIA role.'), limit:n() }), readOnlyLive, browserHandlers.browser_find, ['browser_cdp']),
   define('browser_action', 'Browser element action', 'Click, focus, type/set a value, select, scroll to, upload files, press a key, or set an exact responsive-test viewport in a debuggable browser page using DOM/CDP semantics.', o({ ...browserTarget, action:e(['click','focus','type','set_value','select','scroll_into_view','upload','press','set_viewport']), selector:s('CSS selector for the target element; prefer the reusable selector returned by browser_find.'), text:s('For action=type, Unicode text to insert. For element actions without selector, visible text may identify the target.'), value:s('Value for action=set_value; also accepted as a compatibility fallback for action=type.'), text_value:s('Compatibility alias for the type/set_value text value.'), option:s(), path:s(), paths:{type:'array',items:{type:'string'}}, key:s(), width:n('CSS viewport width for set_viewport.'), height:n('CSS viewport height for set_viewport.'), device_scale_factor:n('Device scale factor for set_viewport; default 1.'), mobile:b('Enable mobile emulation for set_viewport.') }, ['action']), openMutating, browserHandlers.browser_action, ['browser_cdp']),
   define('browser_wait', 'Wait for browser', 'Wait for DOM state, page text, URL, completed loading, a navigation away from the current URL, or a short network-idle period in a debuggable browser page. Use browser_evaluate separately for JavaScript predicates or page-specific inspection.', o({ ...browserTarget, condition:e(['selector','text','url_contains','load','navigation','network_idle']), selector:s(), text:s(), value:s(), poll_ms:n(), idle_ms:n('Required zero-in-flight network quiet window for network_idle; default 500 ms.') }), readOnlyLive, browserHandlers.browser_wait, ['browser_cdp']),
-  define('browser_evaluate', 'Evaluate browser JavaScript', 'Evaluate JavaScript in a selected debuggable browser page and return its serializable value. This is a powerful escape hatch for page-specific automation.', o({ ...browserTarget, expression:s('JavaScript expression.'), await_promise:b('Await a returned Promise; default true.') }, ['expression']), openMutating, browserHandlers.browser_evaluate, ['browser_cdp']),
+  define('browser_evaluate', 'Evaluate browser JavaScript', 'Evaluate JavaScript in a selected debuggable browser page and return its serializable value. This is a powerful escape hatch for page-specific automation.', o({ ...browserTarget, expression:s('JavaScript expression.'), await_promise:b('Await a returned Promise; default true.') }, ['expression']), openMutating, browserHandlers.browser_evaluate, ['browser_evaluate']),
 
   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']),
@@ -568,10 +568,10 @@ export const extendedToolDefinitions = [
   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('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),
-  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, ['ooxml']),
-  define('edit_document', 'Edit DOCX document', 'Create a new DOCX document or edit DOCX paragraph structure directly in OOXML: replace text, append/prepend paragraphs, insert before/after matching paragraphs, or delete matching paragraphs. For creation set create=true and use path as a new destination; existing files are never overwritten by create mode.', o({ path:s('Existing .docx path, or the new document destination when create=true.'), create:b('Create a new DOCX at path. Fails if path already exists; do not combine with output.'), output:s('Optional output .docx path when editing an existing document.'), operations:{ type:'array', maxItems:100, items:o({ action:e(['replace','append_paragraph','prepend_paragraph','insert_paragraph_before','insert_paragraph_after','delete_paragraph']), search:s('Paragraph text substring for replace/insert/delete operations.'), replacement:s(), all:b('Apply to all matching paragraphs; default true.'), text:s('Paragraph text to append/prepend/insert.') }, ['action']) } }, ['path','operations']), mutating, documentHandlers.edit_document, ['ooxml']),
-  define('pdf_action', 'PDF action', 'Inspect PDF annotations or metadata, merge PDFs, split a PDF into pages, or extract selected page ranges. Structural writes use qpdf/poppler/pdftk when installed.', o({ action:e(['merge','split','extract_pages','annotations','info']), path:s(), paths:{type:'array',items:{type:'string'}}, output:s(), output_dir:s(), pattern:s(), pages:s('Page list/ranges such as 1-3,5.') }, ['action']), mutating, documentHandlers.pdf_action),
+  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']),
+  define('edit_document', 'Edit DOCX document', 'Create a new DOCX document or edit DOCX paragraph structure directly in OOXML: replace text, append/prepend paragraphs, insert before/after matching paragraphs, or delete matching paragraphs. For creation set create=true and use path as a new destination; existing files are never overwritten by create mode.', o({ path:s('Existing .docx path, or the new document destination when create=true.'), create:b('Create a new DOCX at path. Fails if path already exists; do not combine with output.'), output:s('Optional output .docx path when editing an existing document.'), operations:{ type:'array', maxItems:100, items:o({ action:e(['replace','append_paragraph','prepend_paragraph','insert_paragraph_before','insert_paragraph_after','delete_paragraph']), search:s('Paragraph text substring for replace/insert/delete operations.'), replacement:s(), all:b('Apply to all matching paragraphs; default true.'), text:s('Paragraph text to append/prepend/insert.') }, ['action']) } }, ['path','operations']), mutating, documentHandlers.edit_document, ['documents']),
+  define('pdf_action', 'PDF action', 'Inspect PDF annotations or metadata, merge PDFs, split a PDF into pages, or extract selected page ranges. Structural writes use qpdf/poppler/pdftk when installed.', o({ action:e(['merge','split','extract_pages','annotations','info']), path:s(), paths:{type:'array',items:{type:'string'}}, output:s(), output_dir:s(), pattern:s(), pages:s('Page list/ranges such as 1-3,5.') }, ['action']), mutating, documentHandlers.pdf_action, ['documents']),
 ];
 
 export const extendedToolHandlers = new Map(extendedToolDefinitions.map(definition => [definition.name, definition]));
@@ -606,7 +606,7 @@ export async function capabilitySnapshot() {
   const wayland = linux && isWaylandSession();
   const portalInput = wayland && waylandPortalCandidate();
   const x11Input = linux && !wayland && (commandExists('wdotool') || commandExists('xdotool'));
-  const browserCdp = await browserControlAvailable(undefined, 500);
+  const browserCdp = browserRemoteEnabled() && await browserControlAvailable(undefined, 500);
   return {
     windows: win || mac || commandExists('wdotool') || commandExists('wmctrl') || (wayland && pyAtSpi),
     ui: win || mac || pyAtSpi,
@@ -618,13 +618,16 @@ export async function capabilitySnapshot() {
     screen_region: win || mac || commandExists('grim') || commandExists('import') || (isWaylandSession() && commandExists('ffmpeg')),
     notifications: win || mac || 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())),
+    documents: linux,
     services: win || mac || commandExists('systemctl'),
+
     logs: win || mac || commandExists('journalctl'),
     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 }),
-    ooxml: win || (commandExists('zip') && commandExists('unzip')),
+    ooxml: linux && (commandExists('zip') && commandExists('unzip')),
   };
 }
 

package/src/extended/desktop.mjs

@@ -334,16 +334,20 @@ export async function uiSnapshot(args = {}) {
   let raw = await adapter.uiSnapshot(effective);
   let value = resultValue(raw);
   const requestedDepth = Number(effective.max_depth);
-  const emptySnapshot = Array.isArray(value)
-    ? value.length === 0
-    : Array.isArray(value?.nodes) && value.nodes.length === 0;
-  if (process.platform === 'linux' && Number.isFinite(requestedDepth) && requestedDepth > 15 && emptySnapshot) {
-    // Some GNOME/AT-SPI providers collapse otherwise valid trees to an empty result
-    // when traversed too deeply. Preserve the caller's deep request first, but recover
-    // from that provider failure with the deepest stable fallback observed on Wayland.
-    effective = { ...effective, max_depth:15 };
+  const isEmptySnapshot = payload => Array.isArray(payload)
+    ? payload.length === 0
+    : Array.isArray(payload?.nodes) && payload.nodes.length === 0;
+  if (process.platform === 'linux' && isEmptySnapshot(value)) {
+    // GNOME/AT-SPI can transiently report an empty tree. Retry once at the requested
+    // depth before reducing traversal depth, so valid deep trees are not discarded.
+    await sleep(40);
     raw = await adapter.uiSnapshot(effective);
     value = resultValue(raw);
+    if (isEmptySnapshot(value) && Number.isFinite(requestedDepth) && requestedDepth > 12) {
+      effective = { ...effective, max_depth:12 };
+      raw = await adapter.uiSnapshot(effective);
+      value = resultValue(raw);
+    }
   }
   return jsonResult(enrichUiPayload(value, effective));
 }
@@ -429,7 +433,7 @@ export async function scroll(args = {}) {
   }
   const semanticTarget = args.label != null || args.id || args.name || args.role || args.automation_id || args.automationId;
   if (semanticTarget) {
-    const nodes = await uiMatches({ ...args, limit:1 });
+    const nodes = await uiMatches({ ...args, limit:1, refresh:true });
     const node = nodes[0];
     if (!node) throw new Error('Scroll target UI element was not found');
     const x = Number(node.center_x ?? (Number(node.x) + Number(node.width) / 2));
@@ -746,7 +750,7 @@ export async function typeText(args = {}) {
 }
 
 async function uiElementCenter(id, field) {
-  const matches = await uiMatches({ id, limit: 1, max_nodes: 5000, max_depth: 32 });
+  const matches = await uiMatches({ id, limit: 1, max_nodes: 5000, max_depth: 32, refresh:true });
   const node = matches[0];
   if (!node) throw new Error(`${field} UI element was not found: ${id}`);
   const x = Number(node.x), y = Number(node.y), width = Number(node.width), height = Number(node.height);

package/src/extended/diagnostics.mjs

@@ -3,10 +3,12 @@ import net from 'node:net';
 import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
-import { existsSync } from 'node:fs';
-import { stat } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { constants, existsSync } from 'node:fs';
+import { lstat, mkdtemp, open, rename, rm, stat, unlink } from 'node:fs/promises';
 import { assertAllowedCommand } from '../policy.mjs';
 import { isWaylandSession } from '../screenshot-portal.mjs';
+import { openDirectoryPath } from '../tools/files.mjs';
 import { resolveSafePath, text } from '../util.mjs';
 import {
   clamp,
@@ -297,38 +299,97 @@ export function recordScreenAvailable({
   return false;
 }
 
+async function openRecordingParent(destination) {
+  return openDirectoryPath(path.dirname(destination));
+}
+
+async function copyRecordingFile(source, destination) {
+  let input;
+  let output;
+  let parent;
+  let temporary;
+  try {
+    input = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const sourceInfo = await input.stat();
+    if (!sourceInfo.isFile()) throw new Error('Screen recording staging path is not a regular file');
+    parent = await openRecordingParent(destination);
+    const anchoredDestination = path.join(parent.anchor, path.basename(destination));
+    const existing = await lstat(anchoredDestination).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');
+    temporary = path.join(parent.anchor, `.${path.basename(destination)}.${randomUUID()}.tmp`);
+    output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let offset = 0;
+    for (;;) {
+      const { bytesRead } = await input.read(buffer, 0, buffer.length, offset);
+      if (!bytesRead) break;
+      let written = 0;
+      while (written < bytesRead) {
+        const result = await output.write(buffer, written, bytesRead - written, offset + written);
+        if (!result.bytesWritten) throw new Error('Could not finish writing the screen recording');
+        written += result.bytesWritten;
+      }
+      offset += bytesRead;
+    }
+    await output.sync();
+    await output.close();
+    output = null;
+    await rename(temporary, anchoredDestination);
+    temporary = null;
+  } finally {
+    if (output) await output.close().catch(() => {});
+    if (temporary) await unlink(temporary).catch(() => {});
+    if (input) await input.close().catch(() => {});
+    if (parent) await parent.close().catch(() => {});
+  }
+}
+
 export async function recordScreen(args) {
   const seconds = clamp(args.duration_seconds, 5, 1, 120);
   const fps = clamp(args.fps, 15, 1, 60);
-  const destination = args.destination ? await resolveSafePath(args.destination, 'destination') : path.join(os.tmpdir(), `remcp-screen-${Date.now()}.mp4`);
+  const requestedDestination = args.destination ? await resolveSafePath(args.destination, 'destination') : '';
+  if (requestedDestination) {
+    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();
-  if (wayland && commandExists('wf-recorder') && commandExists('timeout')) {
-    const result = await runFile('timeout', ['--signal=INT', `${seconds}s`, 'wf-recorder', '-f',destination,'-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');
-      unavailable('Screen recording', 'ffmpeg is required on X11');
+  let keepStaging = false;
+  try {
+    if (wayland && commandExists('wf-recorder') && commandExists('timeout')) {
+      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');
+        unavailable('Screen recording', 'ffmpeg is required on X11');
+      }
+      let argv;
+      if (process.platform === 'win32') argv=['-y','-f','gdigrab','-framerate',String(fps),'-i','desktop','-t',String(seconds),'-pix_fmt','yuv420p',staged];
+      else if (process.platform === 'darwin') {
+        const input = await avfoundationScreenInput(ffmpeg);
+        argv=['-y','-f','avfoundation','-framerate',String(fps),'-i',`${input}:none`,'-t',String(seconds),'-pix_fmt','yuv420p',staged];
+      } else argv=['-y','-f','x11grab','-framerate',String(fps),'-i',process.env.DISPLAY,'-t',String(seconds),'-pix_fmt','yuv420p',staged];
+      await runFile(ffmpeg, argv, { label:'screen recording', timeout:(seconds+20)*1000, maxBuffer:8*1024*1024 });
     }
-    let argv;
-    if (process.platform === 'win32') argv=['-y','-f','gdigrab','-framerate',String(fps),'-i','desktop','-t',String(seconds),'-pix_fmt','yuv420p',destination];
-    else if (process.platform === 'darwin') {
-      const input = await avfoundationScreenInput(ffmpeg);
-      argv=['-y','-f','avfoundation','-framerate',String(fps),'-i',`${input}:none`,'-t',String(seconds),'-pix_fmt','yuv420p',destination];
+    if (requestedDestination) {
+      await copyRecordingFile(staged, requestedDestination);
+      await rm(stagingDirectory, { recursive:true, force:true });
     }
-    else argv=['-y','-f','x11grab','-framerate',String(fps),'-i',process.env.DISPLAY,'-t',String(seconds),'-pix_fmt','yuv420p',destination];
-    await runFile(ffmpeg, argv, { label:'screen recording', timeout:(seconds+20)*1000, maxBuffer:8*1024*1024 });
+    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' });
+  } finally {
+    if (!keepStaging) await rm(stagingDirectory, { recursive:true, force:true }).catch(() => {});
   }
-  const info = await stat(destination);
-  return jsonResult({ path:destination, bytes:info.size, duration_seconds:seconds, format:path.extname(destination).slice(1) || 'mp4' });
 }
 
 export const diagnosticHandlers = {