@remcp/runtime 0.2.226 → 0.2.228

package/package.json

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

@@ -177,7 +177,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. Delayed actions are cancelled if the client stops waiting.', o({ action:e(['lock','sleep','restart','shutdown']), delay_seconds:{ type:'number', minimum:0, maximum:90, description:'Optional delay in seconds, maximum 90. Longer delays are rejected because hosted calls expire before they can complete safely.' } }, ['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. 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('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. Omit the extension to accept the native format. GNOME may produce .webm or .mp4; other backends produce .mp4. An explicit extension must match the recorded format.') }), 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','ooxml']),

package/src/extended/desktop-core.mjs

@@ -340,21 +340,31 @@ export async function uiSnapshot(args = {}) {
     ? args.active_only === true
     : (!explicitlyScoped && args.scope !== 'desktop');
   let effective = { ...args, active_only:activeOnly };
-  let raw = await adapter.uiSnapshot(effective);
+  // For wait_for_ui, share one deadline across native capture and Linux retries.
+  const deadline = args.timeout_ms != null && Number.isFinite(Number(args.timeout_ms))
+    ? Date.now() + clamp(args.timeout_ms, 30_000, 100, 120_000) : null;
+  const canRetry = () => deadline === null || Date.now() + 100 < deadline;
+  const capture = () => adapter.uiSnapshot({
+    ...effective,
+    ...(deadline === null ? {} : { timeout_ms:Math.max(100, deadline - Date.now()) }),
+  });
+  let raw = await capture();
   let value = resultValue(raw);
   const requestedDepth = Number(effective.max_depth);
   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) {
+  if (process.platform === 'linux' && isEmptySnapshot(value) && canRetry()) {
+    // GNOME/AT-SPI can transiently report an empty tree, but retries must
+    // never start after the caller's remaining wait budget is exhausted.
+    await sleep(deadline === null ? 40 : Math.min(40, Math.max(0, deadline - Date.now() - 100)));
+    if (canRetry()) {
+      raw = await capture();
+      value = resultValue(raw);
+    }
+    if (isEmptySnapshot(value) && Number.isFinite(requestedDepth) && requestedDepth > 12 && canRetry()) {
       effective = { ...effective, max_depth:12 };
-      raw = await adapter.uiSnapshot(effective);
+      raw = await capture();
       value = resultValue(raw);
     }
   }

package/src/extended/desktop-linux-ui.mjs

@@ -113,7 +113,9 @@ export async function windowAction(args) {
   return text(`Window action ${action} completed.`);
 }
 
-export function pyAtSpiPrelude() {
+export function pyAtSpiPrelude({ pid = 0, app = '' } = {}) {
+  const scopedPid = Number.isInteger(Number(pid)) ? Number(pid) : 0;
+  const scopedApp = JSON.stringify(optionalString(app) || '');
   return `import json,sys,math
 try:
  import pyatspi
@@ -188,10 +190,13 @@ def _proc(e):
  except: pass
  return 0
 q=[]
+scope_pid=${scopedPid};scope_app=${scopedApp}
 for app in desktop:
  try:
-  app_name=app.name or ""
   pid=_proc(app)
+  if scope_pid and pid!=scope_pid: continue
+  app_name=app.name or ""
+  if scope_app and scope_app.lower() not in app_name.lower(): continue
   active=False
   try:
    active=bool(app.getState().contains(pyatspi.STATE_ACTIVE))
@@ -216,7 +221,7 @@ export async function uiSnapshot(args = {}) {
   const wantedPid = Number.isInteger(Number(args.pid)) ? Number(args.pid) : 0;
   const wantedWindow = JSON.stringify(optionalString(args.window_title || args.windowTitle) || '');
   const activeOnly = args.active_only === true;
-  const script = pyAtSpiPrelude() + `
+  const script = pyAtSpiPrelude({ pid:wantedPid, app:args.app }) + `
 want_app=${wantedApp};want_pid=${wantedPid};want_window=${wantedWindow};want_active=${activeOnly ? 'True' : 'False'}
 roots=[]
 for root,app_name,pid,active in q:
@@ -265,7 +270,7 @@ while queue and len(out)<${maxNodes}:
    for i in range(e.childCount):queue.append((e.getChildAtIndex(i),d+1,app_name,pid,active,window_name,node_path+"."+str(i)))
   except:pass
 print(json.dumps(out))`;
-  const result = await runFile('python3', ['-c', script], { label: 'AT-SPI snapshot', timeout: 30_000, allowFailure: true });
+  const result = await runFile('python3', ['-c', script], { label: 'AT-SPI snapshot', timeout:clamp(args.timeout_ms, 30_000, 100, 30_000), allowFailure:true });
   let parsed = null;
   try { parsed = JSON.parse(result.stdout || ''); } catch {}
   if (Array.isArray(parsed)) return jsonResult({ platform: 'linux', count: parsed.length, nodes: parsed });
@@ -288,7 +293,7 @@ export async function uiAction(args = {}) {
   const wantedName = JSON.stringify(optionalString(args.name) || '');
   const wantedRole = JSON.stringify(optionalString(args.role) || '');
   const value = JSON.stringify(String(args.value ?? ''));
-  const script = pyAtSpiPrelude() + `
+  const script = pyAtSpiPrelude({ pid:wantedPid, app:args.app }) + `
 want_index=${legacyIndex};want_pid=${wantedPid};want_path=${JSON.stringify(stablePath)}
 want_app=${wantedApp};want_window=${wantedWindow};want_name=${wantedName};want_role=${wantedRole};action=${JSON.stringify(action)};value=${value}
 queue=[];seen=0;target=None;target_meta={}

package/src/extended/desktop-linux-window-actions.mjs

@@ -67,7 +67,7 @@ export async function nativeWaylandAccessibilityAction(row, actionNames) {
   if (!Number.isInteger(pid) || pid <= 0 || !Array.isArray(actionNames) || !actionNames.length) {
     return { applied:false, available:[] };
   }
-  const script = pyAtSpiPrelude() + `
+  const script = pyAtSpiPrelude({ pid }) + `
 want_pid=${pid};want_window=${JSON.stringify(String(row.title || ''))};wanted_actions=${JSON.stringify(actionNames)}
 target=None
 for root,app_name,pid,active in q:

package/src/extended/desktop-ui-actions.mjs

@@ -52,6 +52,7 @@ export async function uiMatches(args = {}) {
     ...(resolved.app ? { app: resolved.app } : {}),
     ...((resolved.window_title || resolved.windowTitle) ? { window_title: resolved.window_title || resolved.windowTitle } : {}),
     ...(resolved.browser_dom === true ? { browser_dom:true } : {}),
+    ...(resolved.timeout_ms != null ? { timeout_ms:resolved.timeout_ms } : {}),
   });
   const payload = resultValue(result) || {};
   const nodes = Array.isArray(payload) ? payload : payload.nodes || [];
@@ -108,6 +109,7 @@ export async function uiConditionMatches(args, condition) {
         ...(args.app ? { app:args.app } : {}),
         ...((args.window_title || args.windowTitle) ? { window_title:args.window_title || args.windowTitle } : {}),
         ...(args.browser_dom === true ? { browser_dom:true } : {}),
+        ...(args.timeout_ms != null ? { timeout_ms:args.timeout_ms } : {}),
       })) || {};
       nodes = Array.isArray(snapshot) ? snapshot : snapshot.nodes || [];
     }
@@ -142,8 +144,27 @@ export async function waitForUi(args = {}) {
   if (['element_exists','element_enabled'].includes(condition) && !hasSelector) throw new Error(`wait_for_ui condition=${condition} requires a semantic target`);
   if (condition === 'active_window' && !(args.text || args.name || args.window_title || args.windowTitle)) throw new Error('wait_for_ui condition=active_window requires text, name, or window_title');
   if (['present','absent'].includes(state) && !hasSelector) throw new Error(`wait_for_ui state=${state} requires a semantic target`);
-  const deadline = Date.now() + timeoutMs;
   const startedAt = Date.now();
+  const deadline = startedAt + timeoutMs;
+  const expired = Symbol('wait_for_ui deadline');
+  // Resolve snapshot labels once, before invalidation; subsequent reads use the
+  // stable semantic locator rather than a label from a discarded tree.
+  const target = args.label != null ? { ...withResolvedUiLabel(args), label:undefined } : args;
+  const probe = async read => {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return expired;
+    try {
+      const value = await read({ ...target, timeout_ms:Math.max(100, remaining) });
+      return Date.now() >= deadline ? expired : value;
+    } catch (error) {
+      if (Date.now() >= deadline) return expired;
+      throw error;
+    }
+  };
+  const pause = async () => {
+    const remaining = deadline - Date.now();
+    if (remaining > 0) await sleep(Math.min(pollMs, remaining));
+  };
   let attempts = 0;
 
   if (condition) {
@@ -152,7 +173,9 @@ export async function waitForUi(args = {}) {
       attempts += 1;
       // A wait must observe fresh state, not repeatedly query the same 5-second cache.
       invalidateUiSnapshotCache();
-      evaluation = await uiConditionMatches(args, condition);
+      const observed = await probe(options => uiConditionMatches(options, condition));
+      if (observed === expired) break;
+      evaluation = observed;
       if (evaluation.matched) {
         return jsonResult({
           condition,
@@ -164,7 +187,7 @@ export async function waitForUi(args = {}) {
           ...(evaluation.detail ? { detail:evaluation.detail } : {}),
         });
       }
-      await sleep(pollMs);
+      await pause();
     } while (Date.now() < deadline);
     return jsonResult({
       condition,
@@ -178,13 +201,20 @@ export async function waitForUi(args = {}) {
   }
 
   invalidateUiSnapshotCache();
-  const baseline = state === 'changed' ? await uiMatches(args) : [];
+  const first = state === 'changed' ? await probe(uiMatches) : [];
+  const baseline = first === expired ? [] : first;
+  if (first === expired) {
+    return jsonResult({ state:'timeout', wanted:state, matched:0, attempts,
+      elapsed_ms:Date.now() - startedAt, nodes:[], before:[] });
+  }
   const baselineFingerprint = state === 'changed' ? uiFingerprint(baseline) : null;
   let nodes = baseline;
   do {
     attempts += 1;
     invalidateUiSnapshotCache();
-    nodes = await uiMatches(args);
+    const observed = await probe(uiMatches);
+    if (observed === expired) break;
+    nodes = observed;
     const changed = state === 'changed' && uiFingerprint(nodes) !== baselineFingerprint;
     if ((state === 'present' && nodes.length) || (state === 'absent' && !nodes.length) || changed) {
       return jsonResult({
@@ -196,7 +226,7 @@ export async function waitForUi(args = {}) {
         ...(state === 'changed' ? { before: baseline } : {}),
       });
     }
-    await sleep(pollMs);
+    await pause();
   } while (Date.now() < deadline);
   return jsonResult({ state:'timeout', wanted:state, matched:nodes.length, attempts, elapsed_ms:Date.now() - startedAt, nodes, ...(state === 'changed' ? { before:baseline } : {}) });
 }

package/src/extended/diagnostics-recording.mjs

@@ -253,11 +253,26 @@ 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)], {
+  const result = await runFile('gjs', [helper, staged, String(seconds), String(fps)], {
     label:'GNOME Shell screen recording',
     timeout:(seconds + 20) * 1000,
     maxBuffer:2 * 1024 * 1024,
   });
+  let report;
+  try { report = JSON.parse(result.stdout.trim()); } catch {}
+  const output = report?.destination;
+  // GNOME selects the container and may replace the template extension. Accept
+  // only the exact recording stem in our private staging directory, never an
+  // arbitrary path returned by the desktop service.
+  if (report?.stopped !== true || typeof output !== 'string' || !path.isAbsolute(output)
+    || path.dirname(output) !== stagingDirectory
+    || path.parse(output).name !== path.parse(staged).name
+    || !['.mp4','.webm'].includes(path.extname(output))) {
+    throw new Error('GNOME returned an invalid screen recording staging path or format');
+  }
+  const info = await lstat(output);
+  if (!info.isFile() || !info.size) throw new Error('GNOME screen recording is not a non-empty regular file');
+  return { path:output, format:path.extname(output).slice(1) };
 }
 
 export function validateRecordingDestinationFormat(destination, format) {
@@ -328,21 +343,27 @@ export async function recordScreen(args) {
     unavailable('Screen recording', 'ffmpeg is required on X11');
   }
 
-  const format = backend === 'gnome-shell' ? 'webm' : 'mp4';
+  let format = backend === 'gnome-shell' ? 'webm' : 'mp4';
   const requestedDestination = args.destination ? await resolveSafePath(args.destination, 'destination') : '';
   if (requestedDestination) {
-    validateRecordingDestinationFormat(requestedDestination, format);
+    if (backend !== 'gnome-shell') validateRecordingDestinationFormat(requestedDestination, format);
+    else if (path.extname(requestedDestination) && !['.mp4','.webm'].includes(path.extname(requestedDestination).toLowerCase())) {
+      throw new Error('GNOME screen recording destination must use .mp4, .webm or omit the extension');
+    }
     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()}.${format}`);
+  let staged = path.join(stagingDirectory, `capture-${randomUUID()}.${format}`);
   let keepStaging = false;
   try {
     if (backend === 'gnome-shell') {
-      await recordGnomeShellScreen({ staged, stagingDirectory, seconds, fps });
+      const recorded = await recordGnomeShellScreen({ staged, stagingDirectory, seconds, fps });
+      staged = recorded.path;
+      format = recorded.format;
+      validateRecordingDestinationFormat(requestedDestination, format);
     } 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}`);