@remcp/runtime 0.2.93 → 0.2.94

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.2.94 — 2026-09-22
+
+- Replaced DOCX/PDF regex-heavy extraction with bounded scanners and added adversarial parser regressions.
+- Browser actions pass user-controlled values through structured CDP arguments instead of interpolating them into executable JavaScript.
+- File/search/screenshot/hash operations validate and consume the same open descriptor, using `O_NOFOLLOW` where supported to prevent symlink-swap/check-then-use races.
+- Temporary desktop captures and telemetry marker creation are now descriptor-bound or atomic.
+- Tool schemas and the 83 granular runtime operations remain unchanged.
+
 ## 0.2.93 — 2026-09-21
 
 - Lockstep release for the device client's fresher npm metadata revalidation during exact release updates.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.93",
+  "version": "0.2.94",
   "description": "First-party ReMCP local device runtime: filesystem, terminal, computer-use, browser, diagnostics and document tools over MCP.",
   "type": "module",
   "license": "MIT",

package/src/documents.mjs

@@ -55,17 +55,70 @@ function unzipEntry(buffer, wanted) {
 
 const DOCX_ENTITIES = { '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"', '&apos;': "'" };
 
+function xmlTagName(tag) {
+  let index = 0;
+  while (index < tag.length && /\s/.test(tag[index])) index += 1;
+  let closing = false;
+  if (tag[index] === '/') {
+    closing = true;
+    index += 1;
+    while (index < tag.length && /\s/.test(tag[index])) index += 1;
+  }
+  const start = index;
+  while (index < tag.length && !/\s|\/|>/.test(tag[index])) index += 1;
+  return { name: tag.slice(start, index), closing };
+}
+
+function wordXmlText(xml) {
+  let output = '';
+  let index = 0;
+  while (index < xml.length) {
+    if (xml[index] !== '<') {
+      output += xml[index];
+      index += 1;
+      continue;
+    }
+    if (xml.startsWith('<!--', index)) {
+      const end = xml.indexOf('-->', index + 4);
+      index = end < 0 ? xml.length : end + 3;
+      continue;
+    }
+    if (xml.startsWith('<![CDATA[', index)) {
+      const end = xml.indexOf(']]>', index + 9);
+      if (end < 0) break;
+      output += xml.slice(index + 9, end);
+      index = end + 3;
+      continue;
+    }
+    let quote = '';
+    let end = index + 1;
+    for (; end < xml.length; end += 1) {
+      const character = xml[end];
+      if (quote) {
+        if (character === quote) quote = '';
+        continue;
+      }
+      if (character === '"' || character === "'") {
+        quote = character;
+        continue;
+      }
+      if (character === '>') break;
+    }
+    if (end >= xml.length) break;
+    const { name, closing } = xmlTagName(xml.slice(index + 1, end));
+    if (closing && name === 'w:p') output += '\n';
+    else if (!closing && (name === 'w:br' || name === 'w:cr')) output += '\n';
+    else if (!closing && name === 'w:tab') output += '\t';
+    index = end + 1;
+  }
+  return output;
+}
+
 export function readDocxText(buffer) {
   const document = unzipEntry(buffer, 'word/document.xml');
   if (!document) throw new Error('This file is not a readable .docx (its word/document.xml is missing or compressed in an unsupported way)');
   const xml = document.toString('utf8');
-  // Paragraph and line breaks become newlines, tabs become tabs, everything else is text.
-  const withBreaks = xml
-    .replace(/<w:(?:br|cr)\b[^>]*\/?>/g, '\n')
-    .replace(/<\/w:p>/g, '\n')
-    .replace(/<w:tab\b[^>]*\/?>/g, '\t');
-  const text = withBreaks.replace(/<[^>]+>/g, '');
-  return text
+  return wordXmlText(xml)
     .replace(/&(amp|lt|gt|quot|apos);/g, match => DOCX_ENTITIES[match])
     .replace(/\n{3,}/g, '\n\n')
     .trim();
@@ -78,6 +131,132 @@ function decodePdfString(raw) {
     .replace(/\\([0-7]{1,3})/g, (_match, octal) => String.fromCharCode(Number.parseInt(octal, 8)));
 }
 
+const PDF_HEX = '0123456789abcdefABCDEF';
+
+function readPdfLiteral(content, start) {
+  let raw = '';
+  let depth = 1;
+  let index = start + 1;
+  while (index < content.length) {
+    const character = content[index];
+    if (character === '\\') {
+      raw += character;
+      index += 1;
+      if (index < content.length) {
+        raw += content[index];
+        index += 1;
+      }
+      continue;
+    }
+    if (character === '(') {
+      depth += 1;
+      raw += character;
+      index += 1;
+      continue;
+    }
+    if (character === ')') {
+      depth -= 1;
+      index += 1;
+      if (depth === 0) return { value: decodePdfString(raw), next: index };
+      raw += character;
+      continue;
+    }
+    raw += character;
+    index += 1;
+  }
+  return { value: '', next: content.length };
+}
+
+function readPdfHex(content, start) {
+  let hex = '';
+  let index = start + 1;
+  while (index < content.length && content[index] !== '>') {
+    if (PDF_HEX.includes(content[index])) hex += content[index];
+    index += 1;
+  }
+  if (hex.length % 2) hex += '0';
+  const value = Buffer.from(hex, 'hex').toString('latin1').replace(/\0/g, '');
+  return { value, next: index < content.length ? index + 1 : index };
+}
+
+function readPdfArray(content, start) {
+  const values = [];
+  let index = start + 1;
+  while (index < content.length) {
+    const character = content[index];
+    if (character === ']') return { value: values.join(''), next: index + 1 };
+    if (character === '(') {
+      const token = readPdfLiteral(content, index);
+      if (token.value) values.push(token.value);
+      index = token.next;
+      continue;
+    }
+    if (character === '<' && content[index + 1] !== '<') {
+      const token = readPdfHex(content, index);
+      if (token.value) values.push(token.value);
+      index = token.next;
+      continue;
+    }
+    index += 1;
+  }
+  return { value: values.join(''), next: index };
+}
+
+function pdfTextPieces(content) {
+  const pieces = [];
+  let operand = '';
+  let index = 0;
+  while (index < content.length) {
+    const character = content[index];
+    if (/\s/.test(character)) {
+      index += 1;
+      continue;
+    }
+    if (character === '%') {
+      const newline = content.indexOf('\n', index + 1);
+      index = newline < 0 ? content.length : newline + 1;
+      continue;
+    }
+    if (character === '(') {
+      const token = readPdfLiteral(content, index);
+      operand = token.value;
+      index = token.next;
+      continue;
+    }
+    if (character === '<' && content[index + 1] !== '<') {
+      const token = readPdfHex(content, index);
+      operand = token.value;
+      index = token.next;
+      continue;
+    }
+    if (character === '[') {
+      const token = readPdfArray(content, index);
+      operand = token.value;
+      index = token.next;
+      continue;
+    }
+    const start = index;
+    while (index < content.length && !/\s|[()[\]<>]/.test(content[index])) index += 1;
+    if (index === start) {
+      index += 1;
+      continue;
+    }
+    const operator = content.slice(start, index);
+    if (operator === 'Tj' || operator === 'TJ') {
+      if (operand) pieces.push(operand);
+      operand = '';
+    } else if (operator === "'" || operator === '"') {
+      pieces.push('\n');
+      if (operand) pieces.push(operand);
+      operand = '';
+    } else if (operator === 'T*' || operator === 'Td' || operator === 'TD' || operator === 'ET') {
+      pieces.push('\n');
+      operand = '';
+    }
+  }
+  return pieces;
+}
+
 export function readPdfText(buffer) {
   const raw = buffer.toString('latin1');
   const chunks = [];
@@ -97,23 +276,7 @@ export function readPdfText(buffer) {
   }
   const content = chunks.join('\n');
 
-  const pieces = [];
-  const showText = /(?:\((?:\\.|[^\\()])*\)|<[0-9A-Fa-f\s]+>)\s*Tj|\[((?:[^\][]|\\.)*)\]\s*TJ|\((?:\\.|[^\\()])*\)\s*['"]|T\*|Td|TD|ET/g;
-  for (const match of content.matchAll(showText)) {
-    const token = match[0];
-    if (/^T\*|Td|TD|ET$/.test(token)) { pieces.push('\n'); continue; }
-    if (token.includes('TJ')) {
-      const array = match[1] ?? '';
-      for (const part of array.matchAll(/\((?:\\.|[^\\()])*\)|<[0-9A-Fa-f\s]+>/g)) {
-        const value = part[0];
-        if (value.startsWith('(')) pieces.push(decodePdfString(value.slice(1, -1)));
-        else pieces.push(Buffer.from(value.slice(1, -1).replace(/\s+/g, ''), 'hex').toString('latin1').replace(/\0/g, ''));
-      }
-      continue;
-    }
-    if (token.startsWith('(')) pieces.push(decodePdfString(token.slice(1, token.lastIndexOf(')'))));
-    else if (token.startsWith('<')) pieces.push(Buffer.from(token.slice(1, token.indexOf('>')).replace(/\s+/g, ''), 'hex').toString('latin1').replace(/\0/g, ''));
-  }
+  const pieces = pdfTextPieces(content);
   const text = pieces.join('').replace(/[ \t]+\n/g, '\n').replace(/\n{3,}/g, '\n\n').trim();
   const printable = text.replace(/[^\p{L}\p{N}\p{P}\p{Zs}\n\t]/gu, '');
   if (text.length < 8 || printable.length / Math.max(1, text.length) < 0.7) {

package/src/extended/browser.mjs

@@ -294,6 +294,29 @@ async function evaluate(session, expression, awaitPromise = true) {
   return result.result?.value;
 }
 
+async function callPageFunction(session, functionDeclaration, args = [], awaitPromise = true) {
+  const global = await session.send('Runtime.evaluate', {
+    expression: 'globalThis',
+    returnByValue: false,
+    awaitPromise: false,
+  });
+  if (global.exceptionDetails || !global.result?.objectId) {
+    throw new Error(global.exceptionDetails?.exception?.description || global.exceptionDetails?.text || 'Could not access the page execution context');
+  }
+  const result = await session.send('Runtime.callFunctionOn', {
+    objectId: global.result.objectId,
+    functionDeclaration,
+    arguments: args.map(value => ({ value })),
+    returnByValue: true,
+    awaitPromise,
+    userGesture: true,
+  });
+  if (result.exceptionDetails) {
+    throw new Error(result.exceptionDetails.exception?.description || result.exceptionDetails.text || 'JavaScript function call failed');
+  }
+  return result.result?.value;
+}
+
 export async function browserTabs(args = {}) {
   const targets = await listBrowserTargets(args.endpoint);
   return jsonResult(targets.filter(item => item.type === 'page').slice(0, 500).map(item => ({
@@ -559,18 +582,41 @@ export async function browserFind(args) {
   });
 }
 
-function elementLookup(args) {
-  const selector = optionalString(args.selector);
-  const needle = optionalString(args.text);
-  if (!selector && !needle) throw new Error('selector or text is required');
-  return `(() => {
-    const selector = ${JSON.stringify(selector)};
-    const needle = ${JSON.stringify(needle)};
-    let el = selector ? document.querySelector(selector) : null;
-    if (!el && needle) el = Array.from(document.querySelectorAll('*')).find(x => ((x.innerText || x.textContent || '').trim().toLowerCase().includes(needle.toLowerCase())));
-    return el;
-  })()`;
-}
+const PAGE_ELEMENT_ACTION = `function(selector, needle, action, value) {
+  let el = selector ? document.querySelector(selector) : null;
+  if (!el && needle) {
+    const lower = String(needle).toLowerCase();
+    el = Array.from(document.querySelectorAll('*')).find(node =>
+      String(node.innerText || node.textContent || '').trim().toLowerCase().includes(lower)
+    ) || null;
+  }
+  if (!el) throw new Error('Element not found');
+  if (action === 'click' || action === 'type' || action === 'scroll_into_view') {
+    el.scrollIntoView({block:'center', inline:'center'});
+  }
+  if (action === 'focus' || action === 'type') el.focus();
+  if (action === 'select') {
+    el.value = value;
+    el.dispatchEvent(new Event('input', {bubbles:true}));
+    el.dispatchEvent(new Event('change', {bubbles:true}));
+  } else if (action === 'set_value') {
+    const proto = Object.getPrototypeOf(el);
+    const own = Object.getOwnPropertyDescriptor(proto, 'value');
+    const parent = Object.getPrototypeOf(proto);
+    const inherited = parent ? Object.getOwnPropertyDescriptor(parent, 'value') : null;
+    const setter = own?.set || inherited?.set;
+    if (setter) setter.call(el, value); else el.value = value;
+    el.dispatchEvent(new Event('input', {bubbles:true}));
+    el.dispatchEvent(new Event('change', {bubbles:true}));
+  }
+  const b = el.getBoundingClientRect();
+  if (action === 'click' && (!b.width || !b.height)) throw new Error('Element has no clickable bounds');
+  return {
+    tag: el.tagName.toLowerCase(),
+    value: 'value' in el ? String(el.value) : '',
+    x: b.x, y: b.y, width: b.width, height: b.height,
+  };
+}`;
 
 export function browserActionInputValue(args = {}, action = '') {
   // text is the public field models naturally use for type, while set_value/select historically
@@ -616,19 +662,14 @@ export async function browserAction(args) {
       await session.send('Input.dispatchKeyEvent', { type: 'keyUp', key });
       return jsonResult({ target_id: target.id, action, key });
     }
-    const lookup = elementLookup(args);
+    const selector = optionalString(args.selector);
+    const needle = optionalString(args.text);
+    if (!selector && !needle) throw new Error('selector or text is required');
     const value = browserActionInputValue(args, action);
     const option = String(args.option ?? value);
 
     if (action === 'click') {
-      const rect = await evaluate(session, `(() => {
-        const el = ${lookup};
-        if (!el) throw new Error('Element not found');
-        el.scrollIntoView({block:'center',inline:'center'});
-        const b = el.getBoundingClientRect();
-        if (!b.width || !b.height) throw new Error('Element has no clickable bounds');
-        return { tag:el.tagName.toLowerCase(), x:b.x, y:b.y, width:b.width, height:b.height };
-      })()`);
+      const rect = await callPageFunction(session, PAGE_ELEMENT_ACTION, [selector, needle, 'click', '']);
       const x = Number(rect.x) + Number(rect.width) / 2;
       const y = Number(rect.y) + Number(rect.height) / 2;
       await session.send('Input.dispatchMouseEvent', { type:'mouseMoved', x, y, button:'none' });
@@ -638,31 +679,18 @@ export async function browserAction(args) {
     }
 
     if (action === 'type') {
-      const focused = await evaluate(session, `(() => {
-        const el = ${lookup};
-        if (!el) throw new Error('Element not found');
-        el.scrollIntoView({block:'center',inline:'center'});
-        el.focus();
-        const b = el.getBoundingClientRect();
-        return { tag:el.tagName.toLowerCase(), value:'value' in el?String(el.value):'', x:b.x, y:b.y, width:b.width, height:b.height };
-      })()`);
+      const focused = await callPageFunction(session, PAGE_ELEMENT_ACTION, [selector, needle, 'type', '']);
       await session.send('Input.insertText', { text:value });
-      const current = await evaluate(session, `(() => { const el=${lookup}; return 'value' in el ? String(el.value) : ''; })()`);
-      return jsonResult({ target_id:target.id, action, result:{ ...focused, value:current } });
+      const current = await callPageFunction(session, PAGE_ELEMENT_ACTION, [selector, needle, 'read_value', '']);
+      return jsonResult({ target_id:target.id, action, result:{ ...focused, value:current.value } });
     }
 
-    const expression = `(() => {
-      const el = ${lookup};
-      if (!el) throw new Error('Element not found');
-      ${action === 'focus' ? 'el.focus();' :
-        action === 'scroll_into_view' ? "el.scrollIntoView({block:'center',inline:'center'});" :
-        action === 'select' ? `el.value=${JSON.stringify(option)}; el.dispatchEvent(new Event('input',{bubbles:true})); el.dispatchEvent(new Event('change',{bubbles:true}));` :
-        `const proto=Object.getPrototypeOf(el);const own=Object.getOwnPropertyDescriptor(proto,'value');const parent=Object.getPrototypeOf(proto);const inherited=parent?Object.getOwnPropertyDescriptor(parent,'value'):null;const setter=own?.set||inherited?.set;if(setter)setter.call(el,${JSON.stringify(value)});else el.value=${JSON.stringify(value)};el.dispatchEvent(new Event('input',{bubbles:true}));el.dispatchEvent(new Event('change',{bubbles:true}));`
-      }
-      const b = el.getBoundingClientRect();
-      return { tag: el.tagName.toLowerCase(), value: 'value' in el ? String(el.value) : '', x: b.x, y: b.y, width: b.width, height: b.height };
-    })()`;
-    return jsonResult({ target_id: target.id, action, result: await evaluate(session, expression) });
+    const pageValue = action === 'select' ? option : value;
+    return jsonResult({
+      target_id: target.id,
+      action,
+      result: await callPageFunction(session, PAGE_ELEMENT_ACTION, [selector, needle, action, pageValue]),
+    });
   });
 }
 

package/src/extended/common.mjs

@@ -2,8 +2,8 @@ import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { execFile, spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { mkdtemp, rm } from 'node:fs/promises';
+import { constants, existsSync } from 'node:fs';
+import { mkdtemp, open, rm } from 'node:fs/promises';
 import { StringDecoder } from 'node:string_decoder';
 import { promisify } from 'node:util';
 import { ToolError, fail, structured, text } from '../util.mjs';
@@ -259,6 +259,18 @@ export async function spawnDetachedWithInput(file, args = [], input = '', option
   });
 }
 
+export async function readPrivateTempFile(file, maxBytes) {
+  const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+  try {
+    const info = await handle.stat();
+    if (!info.isFile()) throw new ToolError('Temporary capture is not a regular file');
+    if (info.size > maxBytes) throw new ToolError(`Captured file is ${info.size} bytes, above the ${maxBytes}-byte inline limit`);
+    return { info, data: await handle.readFile() };
+  } finally {
+    await handle.close();
+  }
+}
+
 export async function tempDir(prefix = 'remcp-') {
   return mkdtemp(path.join(os.tmpdir(), prefix));
 }

package/src/extended/desktop-linux.mjs

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import process from 'node:process';
-import { readFile, stat } from 'node:fs/promises';
+
 import { image, multi, text } from '../util.mjs';
 import { capturePortalScreenshot, isWaylandSession } from '../screenshot-portal.mjs';
 import { hasWaylandRemoteDesktopGrant, portalPointerButton, portalPointerMotion, portalPointerMotionAbsolute, portalScroll, portalShortcut, portalTypeText, waylandPortalCandidate } from '../wayland-remote-desktop.mjs';
@@ -9,6 +9,7 @@ import {
   commandExists,
   jsonResult,
   optionalString,
+  readPrivateTempFile,
   removeTemp,
   requireEnum,
   runFile,
@@ -1274,9 +1275,7 @@ export async function screenshotRegion(args = {}) {
     } else {
       unavailable('Region screenshots', isWaylandSession() ? 'the XDG Desktop Portal plus ffmpeg, or grim, is required' : 'install ImageMagick import');
     }
-    const info = await stat(target);
-    if (info.size > 4 * 1024 * 1024) throw new Error(`captured region is ${info.size} bytes; request a smaller region so it fits the inline image limit`);
-    const data = await readFile(target);
+    const {data} = await readPrivateTempFile(target, 4 * 1024 * 1024);
     return multi([{type:'text',text:`Captured ${width}x${height} at ${x},${y}.`}, image(data.toString('base64'),'image/png')]);
   } finally { await removeTemp(dir); }
 }

package/src/extended/desktop-macos.mjs

@@ -1,11 +1,12 @@
 import path from 'node:path';
-import { readFile, stat } from 'node:fs/promises';
+
 import { image, multi, text } from '../util.mjs';
 import {
   clamp,
   escapeAppleScript,
   jsonResult,
   optionalString,
+  readPrivateTempFile,
   removeTemp,
   requireEnum,
   runFile,
@@ -379,8 +380,7 @@ export async function screenshotRegion(args = {}) {
   const dir=await tempDir('remcp-region-'),target=path.join(dir,'region.png');
   try{
     await runFile('/usr/sbin/screencapture',['-x','-R',`${x},${y},${width},${height}`,target],{label:'screenshot region'});
-    const info=await stat(target);if(info.size>4*1024*1024)throw new Error(`captured region is ${info.size} bytes; request a smaller region so it fits the inline image limit`);
-    const data=await readFile(target);
+    const {data}=await readPrivateTempFile(target,4*1024*1024);
     return multi([{type:'text',text:`Captured ${width}x${height} at ${x},${y}.`},image(data.toString('base64'),'image/png')]);
   }finally{await removeTemp(dir);}
 }

package/src/extended/desktop-windows.mjs

@@ -1,12 +1,13 @@
 import path from 'node:path';
 import process from 'node:process';
-import { readFile, stat } from 'node:fs/promises';
+
 import { image, multi, text } from '../util.mjs';
 import {
   clamp,
   escapePowerShellSingle,
   jsonResult,
   optionalString,
+  readPrivateTempFile,
   removeTemp,
   requireEnum,
   runPowerShell,
@@ -486,8 +487,7 @@ export async function screenshotRegion(args = {}) {
   try{
     const safe=escapePowerShellSingle(target);
     await runPowerShell(`Add-Type -AssemblyName System.Drawing;$b=New-Object System.Drawing.Bitmap(${width},${height});$g=[System.Drawing.Graphics]::FromImage($b);$g.CopyFromScreen(${x},${y},0,0,$b.Size);$b.Save('${safe}',[System.Drawing.Imaging.ImageFormat]::Png);$g.Dispose();$b.Dispose()`,{label:'screenshot region'});
-    const info=await stat(target);if(info.size>4*1024*1024)throw new Error(`captured region is ${info.size} bytes; request a smaller region so it fits the inline image limit`);
-    const data=await readFile(target);
+    const {data}=await readPrivateTempFile(target,4*1024*1024);
     return multi([{type:'text',text:`Captured ${width}x${height} at ${x},${y}.`},image(data.toString('base64'),'image/png')]);
   }finally{await removeTemp(dir);}
 }

package/src/index.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import process from 'node:process';
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { advertisedTools as advertisedCoreTools, toolDefinitions as coreToolDefinitions } from './catalog.mjs';
 import { allExtendedTools, advertisedExtendedTools, extendedToolDefinitions } from './extended/catalog.mjs';
@@ -76,10 +76,12 @@ function announceTelemetryOnce() {
   if (!telemetryEnabled()) return;
   const marker = path.join(runtimeConfigDir, '.telemetry-notice');
   try {
-    if (existsSync(marker)) return;
     mkdirSync(runtimeConfigDir, { recursive: true, mode: 0o700 });
-    writeFileSync(marker, `${new Date().toISOString()}\n`, { mode: 0o600 });
-  } catch { return; }
+    writeFileSync(marker, `${new Date().toISOString()}\n`, { mode: 0o600, flag: 'wx' });
+  } catch (error) {
+    if (error?.code === 'EEXIST') return;
+    return;
+  }
   console.error('ReMCP runtime: anonymous usage metrics are on (tool names, timings, outcomes only - never file paths, commands or output). They go to your own ReMCP account through the paired agent. Disable with `remcp telemetry off`.');
 }
 

package/src/tools/files.mjs

@@ -1,9 +1,9 @@
 import path from 'node:path';
 import os from 'node:os';
 import { spawnSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { constants, createReadStream } from 'node:fs';
-import { access, chmod, chown, copyFile, cp, lstat, mkdir, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { access, chmod, chown, copyFile, cp, lstat, mkdir, mkdtemp, open, readFile, readdir, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
 import { pipeline } from 'node:stream/promises';
 import { liveConfig, runtimeConfig } from '../config.mjs';
 import { documentKind, readDocxText, readPdfText } from '../documents.mjs';
@@ -40,6 +40,42 @@ function assertRegularFile(info, absolute) {
   return info;
 }
 
+const READ_NOFOLLOW = constants.O_RDONLY | (constants.O_NOFOLLOW || 0);
+const READWRITE_NOFOLLOW = constants.O_RDWR | (constants.O_NOFOLLOW || 0);
+
+async function openRegularFile(absolute, flags = READ_NOFOLLOW) {
+  const handle = await open(absolute, flags);
+  try {
+    const info = assertRegularFile(await handle.stat(), absolute);
+    return { handle, info };
+  } catch (error) {
+    await handle.close().catch(() => {});
+    throw error;
+  }
+}
+
+async function readRegularBuffer(absolute, maxBytes = Infinity) {
+  const { handle, info } = await openRegularFile(absolute);
+  try {
+    if (info.size > maxBytes) fail(`File is too large to read inline (${info.size} bytes)`);
+    return { info, buffer: await handle.readFile() };
+  } finally {
+    await handle.close();
+  }
+}
+
+async function overwriteOpenFile(handle, content) {
+  const buffer = Buffer.from(content, 'utf8');
+  await handle.truncate(0);
+  let offset = 0;
+  while (offset < buffer.length) {
+    const { bytesWritten } = await handle.write(buffer, offset, buffer.length - offset, offset);
+    if (!bytesWritten) throw new Error('Could not finish writing the open file');
+    offset += bytesWritten;
+  }
+  await handle.truncate(buffer.length);
+}
+
 // Traversal helper for every multi-file tool. A symbolic link inside an allowed root can point
 // anywhere, so links are never followed and each collected path is resolved through
 // resolveSafePath again before a tool reads or writes it. `stat` follows links, which is exactly
@@ -85,10 +121,13 @@ async function confineAll(paths) {
 }
 
 async function readTextFile(absolute) {
-  const info = await stat(absolute).catch(() => fail(`File not found: ${displayPath(absolute)}`));
-  assertRegularFile(info, absolute);
-  if (info.size > MAX_INLINE_FILE_BYTES) fail(`File is too large to read inline (${info.size} bytes)`);
-  const buffer = await readFile(absolute);
+  let opened;
+  try { opened = await readRegularBuffer(absolute, MAX_INLINE_FILE_BYTES); }
+  catch (error) {
+    if (error?.code === 'ENOENT') fail(`File not found: ${displayPath(absolute)}`);
+    throw error;
+  }
+  const { info, buffer } = opened;
   const decoded = decodeText(buffer);
   if (decoded.encoding === 'utf8' && looksBinary(buffer)) {
     fail(`${displayPath(absolute)} looks like a binary file and cannot be read as text. Use read_image for images, or get_file_info and hash_file for other binaries.`);
@@ -101,10 +140,7 @@ export async function readFileTool(args) {
   // Documents first: a .docx or .pdf is not text, and the binary guard below would refuse it.
   const kind = documentKind(absolute);
   if (kind) {
-    const info = await stat(absolute);
-    assertRegularFile(info, absolute);
-    if (info.size > MAX_INLINE_FILE_BYTES) fail(`File is too large to read inline (${info.size} bytes)`);
-    const buffer = await readFile(absolute);
+    const { buffer } = await readRegularBuffer(absolute, MAX_INLINE_FILE_BYTES);
     const extracted = kind === 'docx' ? readDocxText(buffer) : readPdfText(buffer);
     const documentLines = splitLines(extracted);
     const offset = Number.isFinite(Number(args.offset)) ? Math.trunc(Number(args.offset)) : 0;
@@ -157,15 +193,20 @@ export async function readMultipleFilesTool(args) {
 
 export async function readImageTool(args) {
   const absolute = await resolveSafePath(args.path);
-  const info = assertRegularFile(await stat(absolute).catch(() => fail(`File not found: ${displayPath(absolute)}`)), absolute);
-  if (info.size > MAX_IMAGE_BYTES) fail(`Image is ${info.size} bytes, above the ${MAX_IMAGE_BYTES}-byte inline limit`);
+  let opened;
+  try { opened = await readRegularBuffer(absolute, MAX_IMAGE_BYTES); }
+  catch (error) {
+    if (error?.code === 'ENOENT') fail(`File not found: ${displayPath(absolute)}`);
+    throw error;
+  }
+  const { info, buffer } = opened;
   const mimeType = IMAGE_TYPES.get(path.extname(absolute).toLowerCase());
   if (!mimeType) fail(`${displayPath(absolute)} is not a supported image type (${[...IMAGE_TYPES.keys()].join(', ')})`);
   if (mimeType === 'image/svg+xml') {
-    const { content } = await readTextFile(absolute);
-    return text(`SVG image ${displayPath(absolute)} (${info.size} bytes):\n${content}`);
+    const decoded = decodeText(buffer);
+    if (decoded.encoding === 'utf8' && looksBinary(buffer)) fail(`${displayPath(absolute)} looks like a binary file`);
+    return text(`SVG image ${displayPath(absolute)} (${info.size} bytes):\n${decoded.text}`);
   }
-  const buffer = await readFile(absolute);
   return multi([
     { type: 'text', text: `${displayPath(absolute)} — ${mimeType}, ${info.size} bytes` },
     image(buffer.toString('base64'), mimeType),
@@ -174,12 +215,22 @@ export async function readImageTool(args) {
 
 export async function hashFileTool(args) {
   const absolute = await resolveSafePath(args.path);
-  const info = assertRegularFile(await stat(absolute).catch(() => fail(`File not found: ${displayPath(absolute)}`)), absolute);
+  let opened;
+  try { opened = await openRegularFile(absolute); }
+  catch (error) {
+    if (error?.code === 'ENOENT') fail(`File not found: ${displayPath(absolute)}`);
+    throw error;
+  }
+  const { handle, info } = opened;
   const algorithm = String(args.algorithm || 'sha256').toLowerCase();
-  if (!['sha256', 'sha1', 'md5'].includes(algorithm)) fail('algorithm must be sha256, sha1, or md5');
+  if (!['sha256', 'sha1', 'md5'].includes(algorithm)) { await handle.close(); fail('algorithm must be sha256, sha1, or md5'); }
   const hash = createHash(algorithm);
-  await pipeline(createReadStream(absolute), hash);
-  return text(`${algorithm} ${hash.digest('hex')}  ${displayPath(absolute)} (${info.size} bytes)`);
+  try {
+    await pipeline(createReadStream(absolute, { fd: handle.fd, autoClose: false }), hash);
+    return text(`${algorithm} ${hash.digest('hex')}  ${displayPath(absolute)} (${info.size} bytes)`);
+  } finally {
+    await handle.close();
+  }
 }
 
 async function listEntry(base, depth, maxDepth, prefix, pattern) {
@@ -230,11 +281,11 @@ export async function getFileInfoTool(args) {
     permissions: `0${(info.mode & 0o777).toString(8)}`,
   };
   if (info.isFile() && info.size <= MAX_INLINE_FILE_BYTES) {
-    const buffer = await readFile(absolute).catch(() => null);
-    if (buffer) {
-      const decoded = decodeText(buffer);
+    const opened = await readRegularBuffer(absolute, MAX_INLINE_FILE_BYTES).catch(() => null);
+    if (opened) {
+      const decoded = decodeText(opened.buffer);
       if (decoded.encoding !== 'utf8') payload.encoding = decoded.encoding;
-      if (decoded.encoding !== 'utf8' || !looksBinary(buffer)) {
+      if (decoded.encoding !== 'utf8' || !looksBinary(opened.buffer)) {
         const lines = splitLines(decoded.text);
         payload.lineCount = lines.length;
         payload.lastLine = Math.max(0, lines.length - 1);
@@ -284,12 +335,17 @@ export async function writeFileTool(args) {
 // large file is read as a sequence of base64 slices and written back the same way.
 export async function readBinaryTool(args) {
   const absolute = await resolveSafePath(args.path);
-  const info = assertRegularFile(await stat(absolute).catch(() => fail(`File not found: ${displayPath(absolute)}`)), absolute);
+  let opened;
+  try { opened = await openRegularFile(absolute); }
+  catch (error) {
+    if (error?.code === 'ENOENT') fail(`File not found: ${displayPath(absolute)}`);
+    throw error;
+  }
+  const { handle, info } = opened;
   const offset = Math.max(0, Number.isFinite(Number(args.offset_bytes)) ? Math.trunc(Number(args.offset_bytes)) : 0);
   const length = clampInteger(args.length_bytes, MAX_BINARY_CHUNK_BYTES, 1, MAX_BINARY_CHUNK_BYTES);
   const start = Math.min(offset, info.size);
   const end = Math.min(info.size, start + length);
-  const handle = await open(absolute, 'r');
   try {
     const buffer = Buffer.alloc(end - start);
     if (buffer.length) await handle.read(buffer, 0, buffer.length, start);
@@ -449,23 +505,29 @@ export async function replaceInFilesTool(args) {
   for (const file of files) {
     if (changed.length >= maxFiles) break;
     if (glob && !glob.test(path.basename(file))) continue;
-    const fileInfo = await stat(file).catch(() => null);
-    if (!fileInfo || fileInfo.size > MAX_INLINE_FILE_BYTES) continue;
-    const buffer = await readFile(file).catch(() => null);
-    if (!buffer) continue;
-    const decoded = decodeText(buffer);
-    if (decoded.encoding === 'utf8' && looksBinary(buffer)) continue;
-    scanned += 1;
-    const original = decoded.text;
-    const count = isRegex ? (original.match(matcher) || []).length : original.split(pattern).length - 1;
-    if (!count) continue;
-    if (isRegex) matcher.lastIndex = 0;
-    const updated = isRegex ? original.replace(matcher, replacement) : original.split(pattern).join(replacement);
-    if (updated === original) continue;
-    assertWritableSize(updated);
-    if (!dryRun) await writeFile(file, updated, 'utf8');
-    const stats = diffStats(original, updated);
-    changed.push({ file: displayPath(file), replacements: count, added: stats.added, removed: stats.removed });
+    let opened;
+    try { opened = await openRegularFile(file, dryRun ? READ_NOFOLLOW : READWRITE_NOFOLLOW); }
+    catch { continue; }
+    const { handle, info: fileInfo } = opened;
+    try {
+      if (fileInfo.size > MAX_INLINE_FILE_BYTES) continue;
+      const buffer = await handle.readFile();
+      const decoded = decodeText(buffer);
+      if (decoded.encoding === 'utf8' && looksBinary(buffer)) continue;
+      scanned += 1;
+      const original = decoded.text;
+      const count = isRegex ? (original.match(matcher) || []).length : original.split(pattern).length - 1;
+      if (!count) continue;
+      if (isRegex) matcher.lastIndex = 0;
+      const updated = isRegex ? original.replace(matcher, replacement) : original.split(pattern).join(replacement);
+      if (updated === original) continue;
+      assertWritableSize(updated);
+      if (!dryRun) await overwriteOpenFile(handle, updated);
+      const stats = diffStats(original, updated);
+      changed.push({ file: displayPath(file), replacements: count, added: stats.added, removed: stats.removed });
+    } finally {
+      await handle.close();
+    }
   }
   if (!changed.length) return text(`No matches for ${JSON.stringify(pattern)} in ${displayPath(root)} (${scanned} text files scanned).`);
   const rows = changed.map(entry => `${dryRun ? 'would change' : 'changed'} ${entry.file} · ${entry.replacements} replacement(s) · +${entry.added}/-${entry.removed} lines`);
@@ -963,55 +1025,62 @@ function windowsScreenshotScript(file) {
 }
 
 export async function takeScreenshotTool(args) {
-  const directory = await resolveSafePath(args.directory || os.tmpdir(), 'directory');
-  await mkdir(directory, { recursive: true });
-  const file = path.join(directory, `remcp-screenshot-${Date.now()}.png`);
+  const requestedDirectory = args.directory ? await resolveSafePath(args.directory, 'directory') : '';
+  const temporaryDirectory = requestedDirectory ? '' : await mkdtemp(path.join(os.tmpdir(), 'remcp-screenshot-'));
+  const directory = requestedDirectory || temporaryDirectory;
+  if (requestedDirectory) await mkdir(directory, { recursive: true });
+  const file = path.join(directory, `capture-${randomUUID()}.png`);
   const attempts = [];
-  if (process.platform === 'win32') {
-    const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', windowsScreenshotScript(file)], { encoding: 'utf8', timeout: 30000 });
-    attempts.push(`powershell: ${(result.stderr || '').trim() || `exit ${result.status}`}`);
-  } else {
-    // GNOME and other modern Wayland compositors intentionally prevent X11/wlroots
-    // screenshot commands from reading the desktop. The freedesktop Screenshot portal
-    // is the compositor-supported API and must run before command-line fallbacks.
-    if (process.platform === 'linux' && isWaylandSession()) {
-      try {
-        await capturePortalScreenshot(file);
-      } catch (error) {
-        const message = error instanceof Error ? error.message : `xdg-desktop-portal: ${String(error)}`;
-        attempts.push(message);
-        if (error && typeof error === 'object' && error.code === 'PORTAL_CANCELLED') {
-          fail(`Screen capture was cancelled in the desktop permission dialog (${message}).`);
+  let preserveCapture = false;
+  try {
+    if (process.platform === 'win32') {
+      const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', windowsScreenshotScript(file)], { encoding: 'utf8', timeout: 30000 });
+      attempts.push(`powershell: ${(result.stderr || '').trim() || ('exit ' + result.status)}`);
+    } else {
+      if (process.platform === 'linux' && isWaylandSession()) {
+        try {
+          await capturePortalScreenshot(file);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : `xdg-desktop-portal: ${String(error)}`;
+          attempts.push(message);
+          if (error && typeof error === 'object' && error.code === 'PORTAL_CANCELLED') {
+            fail(`Screen capture was cancelled in the desktop permission dialog (${message}).`);
+          }
+        }
+      }
+      if (!await pathExists(file)) {
+        for (const candidate of SCREENSHOT_COMMANDS) {
+          if (spawnSync('which', [candidate.command], { encoding: 'utf8' }).status !== 0) continue;
+          const result = spawnSync(candidate.command, candidate.args(file), { encoding: 'utf8', timeout: 30000 });
+          if (result.status === 0 && await pathExists(file)) break;
+          attempts.push(`${candidate.command}: ${(result.stderr || '').trim() || ('exit ' + result.status)}`);
         }
       }
     }
-    if (!await pathExists(file)) {
-      for (const candidate of SCREENSHOT_COMMANDS) {
-        if (spawnSync('which', [candidate.command], { encoding: 'utf8' }).status !== 0) continue;
-        const result = spawnSync(candidate.command, candidate.args(file), { encoding: 'utf8', timeout: 30000 });
-        if (result.status === 0 && await pathExists(file)) break;
-        attempts.push(`${candidate.command}: ${(result.stderr || '').trim() || `exit ${result.status}`}`);
+    if (!await pathExists(file)) fail(screenshotAdvice(attempts));
+
+    const { handle, info } = await openRegularFile(file);
+    try {
+      if (info.size <= MAX_IMAGE_BYTES) {
+        const buffer = await handle.readFile();
+        preserveCapture = args.keep === true;
+        return multi([
+          { type: 'text', text: `Screenshot of ${os.hostname()} (${info.size} bytes)${preserveCapture ? (' saved at ' + displayPath(file)) : ''}` },
+          image(buffer.toString('base64'), 'image/png'),
+        ]);
       }
+      preserveCapture = true;
+      return text(`Screenshot of ${os.hostname()} captured: ${info.size} bytes, above the ${MAX_IMAGE_BYTES}-byte inline limit, so it is saved at ${displayPath(file)} instead of being returned as an image. Fetch it with read_binary using chunks of up to ${MAX_BINARY_CHUNK_BYTES} bytes (offset_bytes and length_bytes), or ask for a smaller region.`);
+    } finally {
+      await handle.close();
+    }
+  } finally {
+    if (!preserveCapture) {
+      if (temporaryDirectory) await rm(temporaryDirectory, { recursive: true, force: true }).catch(() => {});
+      else await rm(file, { force: true }).catch(() => {});
     }
   }
-  if (!await pathExists(file)) {
-    fail(screenshotAdvice(attempts));
-  }
-  const info = await stat(file);
-  if (info.size <= MAX_IMAGE_BYTES) {
-    const buffer = await readFile(file);
-    if (args.keep !== true) await rm(file, { force: true });
-    return multi([
-      { type: 'text', text: `Screenshot of ${os.hostname()} (${info.size} bytes)${args.keep === true ? ` saved at ${displayPath(file)}` : ''}` },
-      image(buffer.toString('base64'), 'image/png'),
-    ]);
-  }
-  // A big screen is not an error: the PNG stays on the computer and the model is told how to fetch it
-  // in chunks, which is the same path every other large file takes. Failing here used to lose the
-  // screenshot entirely.
-  return text(`Screenshot of ${os.hostname()} captured: ${info.size} bytes, above the ${MAX_IMAGE_BYTES}-byte inline limit, so it is saved at ${displayPath(file)} instead of being returned as an image. Fetch it with read_binary using chunks of up to ${MAX_BINARY_CHUNK_BYTES} bytes (offset_bytes and length_bytes), or ask for a smaller region.`);
 }
-
 export const fileToolHandlers = {
   read_file: readFileTool,
   read_files: readFilesTool,

package/src/tools/search.mjs

@@ -1,5 +1,6 @@
 import path from 'node:path';
-import { readdir, readFile, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { open, readdir, stat } from 'node:fs/promises';
 import { spawn, spawnSync } from 'node:child_process';
 import { runtimeConfig } from '../config.mjs';
 import { countEvent, recordEvent } from '../telemetry.mjs';
@@ -152,10 +153,17 @@ async function runFallback(session, { path: target, matcher, searchType, filePat
       appendSearchResults(session, [displayPath(file)]);
       return;
     }
-    const info = await stat(file).catch(() => null);
-    if (!info || info.size > MAX_FALLBACK_FILE_BYTES) return;
-    const buffer = await readFile(file).catch(() => null);
-    if (!buffer || looksBinary(buffer)) return;
+    const handle = await open(file, constants.O_RDONLY | (constants.O_NOFOLLOW || 0)).catch(() => null);
+    if (!handle) return;
+    let buffer;
+    try {
+      const info = await handle.stat();
+      if (!info.isFile() || info.size > MAX_FALLBACK_FILE_BYTES) return;
+      buffer = await handle.readFile();
+    } finally {
+      await handle.close();
+    }
+    if (looksBinary(buffer)) return;
     const lines = splitLines(buffer.toString('utf8'));
     for (let index = 0; index < lines.length; index += 1) {
       if (session.status !== 'running' || collected >= maxResults) return;