@remcp/runtime 0.2.57 → 0.2.59

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 0.2.59 — 2026-09-20
+
+- Tool descriptions now make routing boundaries explicit across overlapping filesystem, search, process, system, desktop, diagnostics, and document operations so AI hosts prefer the narrowest semantic tool instead of broad shell or fallback tools.
+- Wayland absolute pointer delivery uses the EIS helper path and avoids stale cached-position assumptions when falling back, improving deterministic desktop input on GNOME/Wayland.
+- Lockstep patch release with the ReMCP client at `0.2.59`.
+
+## 0.2.58 — 2026-09-20
+
+- `computer_snapshot` normalizes partial platform-capture failures into schema-stable collections/objects and bounded `{ source, message }` errors instead of leaking error strings into structured output.
+- Output-budget pruning preserves the structured snapshot error contract, and browser snapshot fallbacks reject invalid/error-shaped payloads.
+- Dynamic browser/CDP capability groups now toggle registrations in one batch and emit one `tools/list_changed` notification per transition, preventing concurrent stdio notification writes from exceeding Node's listener limit.
+- Lockstep patch release with the ReMCP client at `0.2.58`.
+
 ## 0.2.57 — 2026-09-20
 
 - ZIP extraction recognizes Info-ZIP `unzip` on Debian/Ubuntu by probing it with `-v`, fixing the false “unzip is not installed” error reproduced during physical 76-tool package verification.

package/package.json

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

package/src/catalog.mjs

@@ -109,7 +109,7 @@ export const toolDefinitions = [
   {
     name: 'read_files',
     title: 'Read files by glob',
-    description: 'Read files discovered by one glob under a directory, each section prefixed with its path and line count. Use this when the exact file list is not already known. If you already know the exact paths, use read_multiple_files; for one known path use read_file.',
+    description: 'Read the contents of files discovered by one glob under a directory, each section prefixed with its path and line count. Use this when the matched file contents are the result you want. Use start_search instead to find filenames or text matches without reading every matched file. If you already know the exact paths, use read_multiple_files; for one known path use read_file.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -142,7 +142,7 @@ export const toolDefinitions = [
   {
     name: 'read_image',
     title: 'Read image',
-    description: 'Return an image file (PNG, JPEG, GIF, WebP, BMP, AVIF, or SVG) as a viewable image, so screenshots and diagrams can be inspected. Fails above the inline size limit.',
+    description: 'Return an image file (PNG, JPEG, GIF, WebP, BMP, AVIF, or SVG) as native MCP image content so screenshots, photos, and diagrams can be inspected or shown. Use read_binary only for byte-for-byte transfer, not merely to display an image. Fails above the inline size limit.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -157,7 +157,7 @@ export const toolDefinitions = [
   {
     name: 'read_binary',
     title: 'Read binary chunk',
-    description: 'Read any file as base64, in chunks, for transferring binaries, images, archives, or documents off the computer. Returns size, offset, and nextOffsetBytes; call again with offset_bytes set to nextOffsetBytes until complete is true.',
+    description: 'Read any file as base64 chunks for byte-for-byte transfer of binaries, archives, documents, or oversized media. For a normal image that should be inspected or shown, use read_image instead. Returns size, offset, and nextOffsetBytes; call again with offset_bytes set to nextOffsetBytes until complete is true.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -239,7 +239,7 @@ export const toolDefinitions = [
   {
     name: 'write_file',
     title: 'Write file',
-    description: 'Create or replace exactly one text file. Parent directories are created automatically; mode "append" adds to the end. Use write_files for two or more independent files, and write_binary for binary bytes.',
+    description: 'Create or replace the complete contents of exactly one text file. Parent directories are created automatically; mode "append" adds to the end. For a small exact-block edit use edit_block, for a known line range use replace_lines, and when you already have a unified diff use apply_patch. Use write_files for two or more independent complete files, and write_binary for binary bytes.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -256,7 +256,7 @@ export const toolDefinitions = [
   {
     name: 'write_files',
     title: 'Write multiple files',
-    description: 'Create or replace two or more text files in one batch, each with its own path, content, and optional mode. Use this for scaffolding or coherent multi-file writes; for one path use write_file.',
+    description: 'Create or replace the complete contents of two or more text files in one batch, each with its own path, content, and optional mode. Use this for scaffolding or coherent multi-file writes; for one path use write_file. For partial edits use edit_block, replace_lines, replace_in_files, or apply_patch instead of rewriting whole files.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -284,7 +284,7 @@ export const toolDefinitions = [
   {
     name: 'apply_patch',
     title: 'Apply patch',
-    description: 'Apply a unified diff to one file or to several files at once, matching each hunk with a little fuzz so small offsets and whitespace differences still apply. This is the fastest way to land a multi-line change a model has already worked out. Pass dry_run to see the result as a diff first.',
+    description: 'Apply an already-prepared unified diff to one file or several files, matching each hunk with a little fuzz so small offsets and whitespace differences still apply. Prefer this when the change is naturally patch-shaped; use edit_block for one exact text block and write_file only when replacing a complete file. Pass dry_run to see the result first.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -320,7 +320,7 @@ export const toolDefinitions = [
   {
     name: 'edit_block',
     title: 'Edit file',
-    description: 'Replace an exact block of text in a file. Provide enough surrounding context to make old_string unique; the call fails unless the number of matches equals expected_replacements. When the exact text is not found, a whitespace-tolerant match is attempted and reported. Pass dry_run to preview the change as a diff without writing.',
+    description: 'Replace one known text block in one file. Provide enough surrounding context to make old_string unique; the call fails unless the number of matches equals expected_replacements. Use write_file for a whole-file replacement and replace_lines for a known line range. When exact text is not found, a whitespace-tolerant match is attempted and reported. Pass dry_run to preview without writing.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -340,7 +340,7 @@ export const toolDefinitions = [
   {
     name: 'replace_lines',
     title: 'Replace lines',
-    description: 'Replace an inclusive 1-based line range with new text. The rest of the file, including its line endings, is preserved. Pass dry_run to preview the change as a diff without writing.',
+    description: 'Replace an inclusive 1-based line range with new text. Use this when line numbers define the target; use edit_block when matching existing text and write_file for a complete rewrite. The rest of the file, including its line endings, is preserved. Pass dry_run to preview without writing.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -359,7 +359,7 @@ export const toolDefinitions = [
   {
     name: 'replace_in_files',
     title: 'Replace in files',
-    description: 'Replace text or a regular expression across the text files under a path and report what changed. Applies immediately; pass dry_run true to preview the affected files first.',
+    description: 'Search and replace the same text or regular expression across multiple text files under a path and report what changed. Use edit_block for one known block in one file and write_file for one complete known file. Applies immediately; pass dry_run true to preview the affected files first.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -598,7 +598,7 @@ export const toolDefinitions = [
   {
     name: 'start_search',
     title: 'Start search',
-    description: 'Start a filename or content search on this computer and return the first results. Content searches return "path:line: text" rows. Use get_more_search_results to page and stop_search to stop a long search.',
+    description: 'Start a filename or content search on this computer and return the first matches without reading every matched file in full. Use read_files instead when a glob is already known and the contents of all matching files are the desired result. Content searches return "path:line: text" rows. Use get_more_search_results to page and stop_search to stop a long search.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -662,7 +662,7 @@ export const toolDefinitions = [
   {
     name: 'start_process',
     title: 'Start process',
-    description: 'Run a shell command on this computer and return its initial output. The process keeps running so read_process_output or interact_with_process can be used later. Commands can change local or external state.',
+    description: 'Run a shell command, script, build, test suite, or terminal server and return its initial output. Prefer dedicated semantic tools for jobs they already cover: launch_app for GUI apps, service for service-manager operations, power_action for lock/sleep/restart/shutdown, network for routine network inspection/tests, event_log for OS logs, installed_apps for software inventory, environment for environment facts, and open_path/reveal_path for opening or revealing files. The process keeps running so read_process_output or interact_with_process can be used later.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -736,7 +736,7 @@ export const toolDefinitions = [
   {
     name: 'force_terminate',
     title: 'Stop session',
-    description: 'Stop a session started with start_process, escalating from SIGTERM to SIGKILL when it does not exit.',
+    description: 'Stop a ReMCP terminal session started with start_process, escalating from SIGTERM to SIGKILL when it does not exit. Use kill_process for an arbitrary operating-system PID that is not a ReMCP terminal session.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -752,7 +752,7 @@ export const toolDefinitions = [
   {
     name: 'list_sessions',
     title: 'List sessions',
-    description: 'List terminal sessions started during this ReMCP runtime session with their status and how long they have been running.',
+    description: 'List only terminal sessions started through ReMCP start_process, with status and runtime. Use list_processes for the computer-wide operating-system process list.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: readOnly,
     outputSchema: LIST_SESSIONS_OUTPUT_SCHEMA,
@@ -761,7 +761,7 @@ export const toolDefinitions = [
   {
     name: 'get_system_info',
     title: 'Get system info',
-    description: 'Report host details for the paired computer: operating system and kernel, CPU model and load, memory pressure, free disk space on the working volume, uptime, and the default shell.',
+    description: 'Report machine health and host facts for the paired computer: operating system and kernel, CPU model/load, memory pressure, free disk space, uptime, and default shell. Use environment for PATH/shell/runtime environment variables and get_runtime_info for ReMCP-specific version, policy, roots, and limits.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: readOnly,
     handler: systemToolHandlers.get_system_info,
@@ -769,7 +769,7 @@ export const toolDefinitions = [
   {
     name: 'list_processes',
     title: 'List processes',
-    description: 'List running operating-system processes on this computer, highest CPU first, with pid, parent pid, CPU and memory usage, and command. Values that look like secrets are masked.',
+    description: 'List the computer-wide operating-system processes, highest CPU first, with pid, parent pid, CPU/memory usage, and command. Use list_sessions when the question is only about commands started through ReMCP start_process. Values that look like secrets are masked.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -783,7 +783,7 @@ export const toolDefinitions = [
   {
     name: 'kill_process',
     title: 'Kill process',
-    description: 'Terminate an operating-system process by pid. Terminates the process and its children on Windows.',
+    description: 'Terminate an arbitrary operating-system process by pid. If the pid belongs to a ReMCP terminal session created by start_process, prefer force_terminate so ReMCP updates the session consistently and handles its process tree. Terminates the process and its children on Windows.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -798,7 +798,7 @@ export const toolDefinitions = [
   {
     name: 'get_runtime_info',
     title: 'Get runtime info',
-    description: 'Report this device runtime: version, allowed roots, command policy, output limits, settable preferences, and whether usage metrics are enabled. Read-only; use set_config_value only for telemetryEnabled, maxReadLines, maxBufferedLines, or maxOutputBytes. Access roots and command security stay local to the computer.',
+    description: 'Report this computer\'s local ReMCP runtime: version, allowed roots, command policy, output limits, settable preferences, and usage-metric setting. Use get_system_info for OS/CPU/memory/disk facts and hosted get_configuration for deployment/account configuration. Read-only; use set_config_value only for telemetryEnabled, maxReadLines, maxBufferedLines, or maxOutputBytes. Access roots and command security stay local to the computer.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: readOnly,
     handler: statsToolHandlers.get_runtime_info,
@@ -806,7 +806,7 @@ export const toolDefinitions = [
   {
     name: 'get_runtime_stats',
     title: 'Get runtime stats',
-    description: 'Report local counters for this runtime session: tool calls and failures, blocked commands, active terminal and search sessions, and usage-metric queue state.',
+    description: 'Report counters from the current local runtime session on this machine: tool calls/failures, blocked commands, active terminal/search sessions, and usage-metric queue state. Use hosted get_usage_statistics for account-level historical usage aggregated across devices and days.',
     inputSchema: { type: 'object', properties: {}, additionalProperties: false },
     annotations: readOnly,
     handler: statsToolHandlers.get_runtime_stats,

package/src/extended/catalog.mjs

@@ -30,9 +30,9 @@ const o = (properties = {}, required = []) => ({ type: 'object', properties, ...
 const AI_TOOL_DESCRIPTIONS = Object.freeze({
   computer_snapshot: 'Use this for the first look at an unfamiliar desktop state when you need one compact bundle of windows, semantic UI, displays, clipboard metadata and optional pixels/browser/OCR. Prefer it over repeated screenshots; narrow later with ui_find, browser_find or screenshot_region.',
   computer_action: 'Use this only when one semantic click/edit/focus/selection action must work across an uncertain target backend and may need Accessibility → browser DOM/CDP → OCR → coordinate fallback, or when multi_select/multi_edit avoids many identical native UI calls. Do not use it when the backend or operation is already known: use ui_action for native controls, browser_action for page DOM, type_text for prose, keyboard for shortcuts, pointer for raw pointer gestures, drag_drop or scroll for those gestures, window_action for windows, and the dedicated clipboard/launch/open/reveal/notification tools for those jobs.',
-  list_windows: 'Use this to discover top-level desktop windows or obtain a stable window id/PID/bounds before window_action, screenshot_region or targeted input. Prefer it over screenshot-based window guessing.',
-  window_action: 'Use this to focus, minimize, maximize, restore, move, resize or close one known top-level window. Select it by id/PID/app/title from list_windows; do not use pointer coordinates for window management when this semantic tool can express the action.',
-  launch_app: 'Use this to start a desktop application by executable/path or friendly application name without a shell. Prefer it over start_process for GUI application launch; use start_process for terminal commands, build tools and shell pipelines.',
+  list_windows: 'Use this to discover top-level desktop windows or obtain a stable window id/PID/bounds before window_action, screenshot_region or targeted input. Use ui_snapshot instead when you need controls inside a window; prefer list_windows over screenshot-based window guessing.',
+  window_action: 'Use this to focus, minimize, maximize, restore, move, resize or close one known top-level window. Select it by id/PID/app/title from list_windows. Use ui_action for controls inside the window; do not use pointer coordinates for window management when this semantic tool can express the action.',
+  launch_app: 'Use this to start a desktop application by executable/path or friendly application name without a shell. Prefer it over start_process for GUI application launch. If the user wants to open a specific file or directory in its associated application, use open_path instead; use start_process for terminal commands, build tools and shell pipelines.',
   ui_snapshot: 'Use this to inspect native desktop Accessibility/UI Automation semantics for the active app before clicking or typing. Prefer scope=active; use scope=desktop only for cross-application discovery. For a Chromium web page with CDP available, prefer browser_snapshot for page DOM semantics.',
   ui_find: 'Use this after ui_snapshot when you need a small set of native UI elements by role/name/label/AutomationId. It requires an element criterion; use ui_snapshot, not an empty ui_find, to enumerate UI. Prefer returned id or compact label for subsequent ui_action; refresh only when the UI has changed.',
   ui_action: 'Use this to invoke, focus, edit, select, toggle, expand/collapse, range-edit or scroll a native accessible UI element. Prefer this over pointer clicks because semantic actions survive layout changes; fall back to pointer only when accessibility cannot perform the requested action.',
@@ -44,8 +44,8 @@ const AI_TOOL_DESCRIPTIONS = Object.freeze({
   wait_for_ui: 'Use this after a desktop action to wait for an explicit native UI state or condition instead of sleeping or polling screenshots. Presence/absence waits need a semantic target; use state=changed for a broad tree change and set a bounded timeout.',
   clipboard: 'Use this for explicit text clipboard read/write/clear operations. Do not use clipboard as a typing workaround directly; type_text already uses safe clipboard paste with restoration when needed.',
   display_inventory: 'Use this before monitor-specific screenshots, cross-monitor geometry or coordinate work to obtain monitor bounds, scale and primary-display information.',
-  screenshot_region: 'Use this when pixels are required for visual verification but only one window, monitor or rectangle matters. Prefer this over a full-desktop screenshot; use ui_snapshot/browser_snapshot first when semantic structure is sufficient.',
-  open_path: 'Use this to open a permitted file or directory in its normal desktop application. Prefer it over shell-specific open/start/xdg-open commands because ReMCP applies filesystem confinement.',
+  screenshot_region: 'Use this when static pixels are required for visual verification but only one window, monitor or rectangle matters. Prefer it over take_screenshot for a full desktop and over record_screen when motion/timing is not required; use ui_snapshot/browser_snapshot first when semantic structure is sufficient.',
+  open_path: 'Use this to open a permitted file or directory in its normal desktop application. Use launch_app when the task is to start an application itself without a particular file. Prefer open_path over shell-specific open/start/xdg-open commands because ReMCP applies filesystem confinement.',
   reveal_path: 'Use this to reveal a permitted local file or directory in Finder/Explorer/file manager without opening the document itself.',
   notification: 'Use this only when the user wants a visible native desktop notification on the paired computer. Do not use it as a substitute for replying in chat.',
   browser_tabs: 'Use this first for CDP browser automation when the target page/tab is not already unambiguous. It lists debuggable Chromium pages from a loopback-only endpoint; use the returned target_id/title/url to scope later browser tools.',
@@ -59,11 +59,11 @@ const AI_TOOL_DESCRIPTIONS = Object.freeze({
   event_log: 'Use this to read bounded recent OS logs (Windows Event Log, macOS unified log or systemd journal) when diagnosing a service/app/system problem. Prefer it over an unbounded shell log dump.',
   network: 'Use this for structured interfaces/DNS/routes/listeners inspection or a bounded TCP connectivity test. Prefer it over shell ip/netstat/nslookup commands for routine diagnostics.',
   installed_apps: 'Use this to answer what software/packages are installed and their versions. Prefer a filter when looking for one product instead of returning the full inventory.',
-  environment: 'Use this for platform/runtime/path/shell facts and only opt into sanitized environment variables when the task truly needs them. Secret-looking values remain masked.',
+  environment: 'Use this for PATH, shell, Node/runtime environment paths, architecture and optionally sanitized environment variables. Use get_system_info for host health such as CPU/memory/disk/uptime, and get_runtime_info for ReMCP policy, roots and limits. Secret-looking values remain masked.',
   audio: 'Use this to read or change the default output volume/mute state. Use action=status for inspection; set_volume requires a 0–100 value.',
-  power_action: 'Use this only when the user explicitly asks to lock, sleep, restart or shut down the computer. It is intentionally guarded by device command policy because restart/shutdown can interrupt work.',
+  power_action: 'Use this only when the user explicitly asks to lock, sleep, restart or shut down the computer. Prefer it over invoking those system actions through start_process; it is intentionally guarded by device command policy because restart/shutdown can interrupt work.',
   record_screen: 'Use this for a short bounded screen recording when motion/timing is necessary to diagnose a UI issue. Prefer screenshot_region for static visual verification because it is cheaper and easier to inspect.',
-  read_document: 'Use this to read structured content from PDF, DOCX, XLSX, TXT, Markdown, CSV, JSON or XML without opening a desktop app. Prefer it over shell extraction or launching Office when the goal is document content. PDF reading uses the built-in parser first and may fall back to local pdftotext when embedded fonts prevent direct decoding.',
+  read_document: 'Use this for structured document content, especially PDF, DOCX and XLSX, and for CSV/JSON/XML when document-style parsing is useful. Use read_file for ordinary source code, logs, configuration, Markdown, or other plain line-oriented text. Prefer read_document over shell extraction or launching Office when the goal is document content; PDF reading uses the built-in parser first and may fall back to local pdftotext when embedded fonts prevent direct decoding.',
   edit_spreadsheet: 'Use this for direct XLSX cell/range/formula edits without launching Excel. Prefer explicit cells/ranges and write to output when preserving the original matters.',
   edit_document: 'Use this for structured DOCX paragraph edits without launching Word. It is best for replace/insert/delete paragraph operations; use native UI automation only when document formatting/layout interaction is required.',
   pdf_action: 'Use this for PDF metadata/annotations inspection or structural merge/split/page extraction. For reading PDF text use read_document; supply an output/output_dir for write actions when preserving originals matters.',

package/src/extended/desktop-linux.mjs

@@ -3,7 +3,7 @@ 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, portalScroll, portalShortcut, portalTypeText, waylandPortalCandidate } from '../wayland-remote-desktop.mjs';
+import { hasWaylandRemoteDesktopGrant, portalPointerButton, portalPointerMotion, portalPointerMotionAbsolute, portalScroll, portalShortcut, portalTypeText, waylandPortalCandidate } from '../wayland-remote-desktop.mjs';
 import {
   clamp,
   commandExists,
@@ -863,9 +863,18 @@ async function portalMoveTo(x, y, options = {}) {
   const targetX = Math.trunc(Number(x));
   const targetY = Math.trunc(Number(y));
   if (!Number.isFinite(targetX) || !Number.isFinite(targetY)) throw new Error('x and y must be finite coordinates');
-  if (options.recalibrate || !portalPointerState) await calibratePortalPointer(options);
   const motionOptions = { ...options };
   delete motionOptions.recalibrate;
+  try {
+    await portalPointerMotionAbsolute(targetX, targetY, motionOptions);
+    portalPointerState = { x:targetX, y:targetY };
+    return;
+  } catch (error) {
+    if (!/requires the EIS Remote Desktop backend/i.test(String(error?.message || error))) throw error;
+  }
+  // Legacy portal fallback: relative motion has no absolute position feedback,
+  // so recalibrate on every move instead of trusting cached coordinates.
+  await calibratePortalPointer(motionOptions);
   await portalPointerMotion(targetX - portalPointerState.x, targetY - portalPointerState.y, motionOptions);
   portalPointerState = { x:targetX, y:targetY };
 }

package/src/extended/desktop.mjs

@@ -137,35 +137,78 @@ function resultValue(result) {
   try { return JSON.parse(raw); } catch { return raw; }
 }
 
+function objectRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+
+function toolResultMessage(result) {
+  const text = result?.content?.find(part => part.type === 'text')?.text;
+  return String(text || 'tool returned an error result').slice(0, 2000);
+}
+
+function snapshotError(source, settled) {
+  if (settled?.status === 'rejected') {
+    return { source, message:String(settled.reason?.message || settled.reason || 'capture rejected').slice(0, 2000) };
+  }
+  if (settled?.status === 'fulfilled' && settled.value?.isError === true) {
+    return { source, message:toolResultMessage(settled.value) };
+  }
+  return null;
+}
+
+function normalizeSnapshotErrors(errors) {
+  if (!Array.isArray(errors)) return [];
+  return errors.slice(0, 50).map((error, index) => {
+    if (objectRecord(error)) {
+      return {
+        ...error,
+        source:String(error.source || 'snapshot').slice(0, 120),
+        message:String(error.message || error.error || 'snapshot capture error').slice(0, 2000),
+      };
+    }
+    return { source:'snapshot', message:String(error ?? `snapshot error ${index + 1}`).slice(0, 2000) };
+  });
+}
+
 function jsonBytes(value) {
   return Buffer.byteLength(JSON.stringify(value), 'utf8');
 }
 
 export function boundedComputerSnapshot(payload) {
+  const normalized = {
+    ...payload,
+    active_window:objectRecord(payload?.active_window),
+    windows:Array.isArray(payload?.windows) ? payload.windows : [],
+    displays:Array.isArray(payload?.displays) ? payload.displays : [],
+    cursor:objectRecord(payload?.cursor) || { x:null, y:null },
+    ui:objectRecord(payload?.ui) || { platform:process.platform, count:0, nodes:[] },
+    clipboard:objectRecord(payload?.clipboard) || { available:false, length:0 },
+    errors:normalizeSnapshotErrors(payload?.errors),
+  };
   const budget = Math.min(768 * 1024, Math.max(16 * 1024, Math.floor(Number(liveConfig('maxOutputBytes') || 0) * 0.35)));
-  const originalBytes = jsonBytes(payload);
+  const originalBytes = jsonBytes(normalized);
   if (originalBytes <= budget) {
-    return { ...payload, snapshot_bytes:originalBytes, snapshot_budget_bytes:budget, snapshot_truncated:false };
+    return { ...normalized, snapshot_bytes:originalBytes, snapshot_budget_bytes:budget, snapshot_truncated:false };
   }
 
   const bounded = {
-    ...payload,
-    windows:Array.isArray(payload.windows) ? [...payload.windows] : payload.windows,
-    errors:Array.isArray(payload.errors) ? payload.errors.map(value => String(value).slice(0, 1000)).slice(0, 50) : payload.errors,
-    ui:payload.ui && typeof payload.ui === 'object' ? {
-      ...payload.ui,
-      ...(Array.isArray(payload.ui.nodes) ? { nodes:[...payload.ui.nodes] } : {}),
-    } : payload.ui,
-    browser:payload.browser && typeof payload.browser === 'object' ? {
-      ...payload.browser,
-      ...(Array.isArray(payload.browser.nodes) ? { nodes:[...payload.browser.nodes] } : {}),
-    } : payload.browser,
-    ocr:payload.ocr && typeof payload.ocr === 'object' ? {
-      ...payload.ocr,
-      text:String(payload.ocr.text || '').slice(0, 50_000),
-      ...(Array.isArray(payload.ocr.words) ? { words:[...payload.ocr.words] } : {}),
-      ...(Array.isArray(payload.ocr.lines) ? { lines:[...payload.ocr.lines] } : {}),
-    } : payload.ocr,
+    ...normalized,
+    windows:[...normalized.windows],
+    errors:normalizeSnapshotErrors(normalized.errors),
+    ui:{
+      ...normalized.ui,
+      ...(Array.isArray(normalized.ui.nodes) ? { nodes:[...normalized.ui.nodes] } : {}),
+    },
+    browser:objectRecord(normalized.browser) ? {
+      ...normalized.browser,
+      ...(Array.isArray(normalized.browser.nodes) ? { nodes:[...normalized.browser.nodes] } : {}),
+    } : undefined,
+    ocr:objectRecord(normalized.ocr) ? {
+      ...normalized.ocr,
+      text:String(normalized.ocr.text || '').slice(0, 50_000),
+      ...(Array.isArray(normalized.ocr.words) ? { words:[...normalized.ocr.words] } : {}),
+      ...(Array.isArray(normalized.ocr.lines) ? { lines:[...normalized.ocr.lines] } : {}),
+    } : undefined,
     snapshot_original_bytes:originalBytes,
     snapshot_budget_bytes:budget,
     snapshot_truncated:true,
@@ -939,15 +982,33 @@ export async function computerSnapshot(args = {}) {
     cursorPosition(),
     captureScreenshot ? computerScreenshotTask(args) : Promise.resolve(null),
   ]);
-  const parse = result => {
-    if (result.status !== 'fulfilled' || !result.value) return null;
-    const raw = result.value.content?.[0]?.text;
-    if (typeof raw !== 'string') return null;
-    try { return JSON.parse(raw); } catch { return raw; }
+  const parse = (result, fallback = null) => {
+    if (result.status !== 'fulfilled' || !result.value || result.value.isError === true) return fallback;
+    return resultValue(result.value) ?? fallback;
   };
-  const clipText = clipboardResult.status === 'fulfilled' ? clipboardResult.value.content?.[0]?.text || '' : '';
-  const windows = parse(windowsResult);
-  const ui = parse(uiResult);
+  const shapeErrors = [];
+  const parsedWindows = parse(windowsResult, []);
+  const windows = Array.isArray(parsedWindows) ? parsedWindows : [];
+  if (parsedWindows !== windows && parsedWindows != null) {
+    shapeErrors.push({ source:'windows', message:'window inventory returned an invalid result shape' });
+  }
+  const parsedDisplays = parse(displaysResult, []);
+  const displays = Array.isArray(parsedDisplays) ? parsedDisplays : [];
+  if (parsedDisplays !== displays && parsedDisplays != null) {
+    shapeErrors.push({ source:'displays', message:'display inventory returned an invalid result shape' });
+  }
+  const parsedCursor = parse(cursorResult, { x:null, y:null });
+  const cursor = objectRecord(parsedCursor) || { x:null, y:null };
+  if (parsedCursor !== cursor && parsedCursor != null) {
+    shapeErrors.push({ source:'cursor', message:'cursor position returned an invalid result shape' });
+  }
+  const parsedUi = includeUi ? parse(uiResult, null) : null;
+  const ui = objectRecord(parsedUi) || { platform:process.platform, count:0, nodes:[], ...(includeUi ? { unavailable:true } : { skipped:true }) };
+  if (includeUi && parsedUi !== ui && parsedUi != null) {
+    shapeErrors.push({ source:'ui', message:'accessibility snapshot returned an invalid result shape' });
+  }
+  const clipboardOk = clipboardResult.status === 'fulfilled' && clipboardResult.value?.isError !== true;
+  const clipText = clipboardOk ? clipboardResult.value.content?.[0]?.text || '' : '';
   const uiNodes = Array.isArray(ui?.nodes) ? ui.nodes : Array.isArray(ui) ? ui : [];
   const focusedNodes = uiNodes.filter(node => node.focused === true);
   const focusScore = node => {
@@ -1002,18 +1063,24 @@ export async function computerSnapshot(args = {}) {
   if (browserRequested && await browserCapabilityAvailable(undefined, 400)) {
     const hint = browserTitleHint(activeWindow);
     try {
-      browser = resultValue(await browserSnapshot({
+      const browserResult = await browserSnapshot({
         ...(hint ? { title:hint } : {}),
         max_nodes:clamp(args.browser_max_nodes, 500, 1, 2000),
         timeout_ms:3000,
-      }));
+      });
+      if (browserResult?.isError === true) throw new Error(toolResultMessage(browserResult));
+      browser = objectRecord(resultValue(browserResult));
+      if (!browser) throw new Error('browser snapshot returned an invalid result shape');
     } catch (error) {
       if (hint) {
         try {
-          browser = resultValue(await browserSnapshot({
+          const fallbackResult = await browserSnapshot({
             max_nodes:clamp(args.browser_max_nodes, 500, 1, 2000),
             timeout_ms:3000,
-          }));
+          });
+          if (fallbackResult?.isError === true) throw new Error(toolResultMessage(fallbackResult));
+          browser = objectRecord(resultValue(fallbackResult));
+          if (!browser) throw new Error('browser snapshot returned an invalid result shape');
         } catch (fallbackError) {
           browserError = String(fallbackError?.message || fallbackError);
         }
@@ -1058,8 +1125,8 @@ export async function computerSnapshot(args = {}) {
     active_app: activeApp,
     active_window: activeWindow,
     windows,
-    displays: parse(displaysResult),
-    cursor: parse(cursorResult),
+    displays,
+    cursor,
     ui,
     ...(browser ? { browser } : {}),
     ...(ocr ? { ocr } : {}),
@@ -1098,12 +1165,18 @@ export async function computerSnapshot(args = {}) {
         : (args.screenshot_monitor != null || args.screenshot_monitor_index != null) ? 'monitor'
         : 'desktop',
     },
-    clipboard: { available:clipboardResult.status === 'fulfilled', length:clipText.length },
+    clipboard: { available:clipboardOk, length:clipText.length },
     errors: [
-      ...[windowsResult, displaysResult, uiResult, clipboardResult, cursorResult, shotResult]
-        .filter(result => result.status === 'rejected')
-        .map(result => String(result.reason?.message || result.reason)),
-      ...(browserError ? [`browser snapshot: ${browserError}`] : []),
+      ...[
+        ['windows', windowsResult],
+        ['displays', displaysResult],
+        ...(includeUi ? [['ui', uiResult]] : []),
+        ['clipboard', clipboardResult],
+        ['cursor', cursorResult],
+        ...(captureScreenshot ? [['screenshot', shotResult]] : []),
+      ].map(([source, result]) => snapshotError(source, result)).filter(Boolean),
+      ...shapeErrors,
+      ...(browserError ? [{ source:'browser', message:browserError.slice(0, 2000) }] : []),
     ],
   };
   const boundedPayload = boundedComputerSnapshot(payload);

package/src/helpers/wayland-eis-helper.py

@@ -214,10 +214,13 @@ class EiSender:
         self.lib.ei_device_unref.restype = c_void_p
         self.lib.ei_device_has_capability.argtypes = [c_void_p, ctypes.c_int]
         self.lib.ei_device_has_capability.restype = ctypes.c_bool
+        self.lib.ei_device_get_region_at.argtypes = [c_void_p, ctypes.c_double, ctypes.c_double]
+        self.lib.ei_device_get_region_at.restype = c_void_p
         self.lib.ei_device_start_emulating.argtypes = [c_void_p, ctypes.c_uint32]
         self.lib.ei_device_stop_emulating.argtypes = [c_void_p]
         self.lib.ei_device_keyboard_key.argtypes = [c_void_p, ctypes.c_uint32, ctypes.c_bool]
         self.lib.ei_device_pointer_motion.argtypes = [c_void_p, ctypes.c_double, ctypes.c_double]
+        self.lib.ei_device_pointer_motion_absolute.argtypes = [c_void_p, ctypes.c_double, ctypes.c_double]
         self.lib.ei_device_button_button.argtypes = [c_void_p, ctypes.c_uint32, ctypes.c_bool]
         self.lib.ei_device_scroll_discrete.argtypes = [c_void_p, ctypes.c_int32, ctypes.c_int32]
         self.lib.ei_device_frame.argtypes = [c_void_p, ctypes.c_uint64]
@@ -243,6 +246,8 @@ class EiSender:
         self.devices = {}
         self.sequence = 1
         self.connected = False
+        self.pointer_device_key = None
+        self.pointer_position = None
 
     def _device_key(self, ptr):
         return int(ptr or 0)
@@ -259,6 +264,9 @@ class EiSender:
     def _drop_device(self, ptr):
         key = self._device_key(ptr)
         state = self.devices.pop(key, None)
+        if key == self.pointer_device_key:
+            self.pointer_device_key = None
+            self.pointer_position = None
         if state:
             if state["emulating"]:
                 try:
@@ -349,6 +357,46 @@ class EiSender:
                 return state["ptr"]
         raise RuntimeError(f"no resumed EIS device with capability {cap}")
 
+    def device_for_absolute(self, x, y):
+        candidates = []
+        for state in self.devices.values():
+            if not state["resumed"] or not state["emulating"]:
+                continue
+            device = state["ptr"]
+            if not self.lib.ei_device_has_capability(device, EI_CAP_POINTER_ABSOLUTE):
+                continue
+            candidates.append(device)
+            if self.lib.ei_device_get_region_at(device, float(x), float(y)):
+                return device
+        if candidates:
+            raise RuntimeError(f"no absolute-pointer EIS region contains desktop coordinate ({x}, {y})")
+        raise RuntimeError("no resumed EIS device with absolute-pointer capability")
+
+    def device_for_pointer_context(self, cap):
+        state = self.devices.get(self.pointer_device_key)
+        if (
+            state
+            and state["resumed"]
+            and state["emulating"]
+            and self.lib.ei_device_has_capability(state["ptr"], cap)
+        ):
+            return state["ptr"]
+        if self.pointer_position is not None:
+            x, y = self.pointer_position
+            for candidate in self.devices.values():
+                if not candidate["resumed"] or not candidate["emulating"]:
+                    continue
+                device = candidate["ptr"]
+                if not self.lib.ei_device_has_capability(device, cap):
+                    continue
+                if self.lib.ei_device_get_region_at(device, float(x), float(y)):
+                    return device
+        return self.device_for(cap)
+
+    def remember_pointer(self, device, position=None):
+        self.pointer_device_key = self._device_key(device)
+        self.pointer_position = position
+
     def frame(self, device):
         self.lib.ei_device_frame(device, self.lib.ei_now(self.ei))
 
@@ -361,13 +409,21 @@ class EiSender:
         elif op == "motion":
             device = self.device_for(EI_CAP_POINTER)
             self.lib.ei_device_pointer_motion(device, float(payload.get("dx", 0)), float(payload.get("dy", 0)))
+            self.remember_pointer(device)
+            self.frame(device)
+        elif op == "motion_absolute":
+            x = float(payload["x"])
+            y = float(payload["y"])
+            device = self.device_for_absolute(x, y)
+            self.lib.ei_device_pointer_motion_absolute(device, x, y)
+            self.remember_pointer(device, (x, y))
             self.frame(device)
         elif op == "button":
-            device = self.device_for(EI_CAP_BUTTON)
+            device = self.device_for_pointer_context(EI_CAP_BUTTON)
             self.lib.ei_device_button_button(device, int(payload["button"]), bool(payload.get("pressed")))
             self.frame(device)
         elif op == "scroll":
-            device = self.device_for(EI_CAP_SCROLL)
+            device = self.device_for_pointer_context(EI_CAP_SCROLL)
             self.lib.ei_device_scroll_discrete(device, int(payload.get("dx", 0)), int(payload.get("dy", 0)))
             self.frame(device)
         elif op == "ping":

package/src/mcp-v2.mjs

@@ -64,15 +64,23 @@ export async function startRuntimeMcpServer({ version, instructions, onError = (
       if (closed) return;
       try {
         const next = new Set((await advertisedExtendedTools()).map(tool => tool.name));
+        let changed = false;
         for (const definition of extendedToolDefinitions) {
           const before = lastSupported.has(definition.name);
           const after = next.has(definition.name);
           if (before === after) continue;
           const registered = registrations.get(definition.name);
-          if (after) registered?.enable();
-          else registered?.disable();
+          if (!registered) continue;
+          // The SDK's enable()/disable() helper emits tools/list_changed immediately. Browser CDP
+          // appears as a seven-tool capability group, so calling those helpers in a loop creates
+          // seven concurrent stdio writes and can exceed Node's listener limit. Mutating the
+          // registration handle is otherwise identical to update({enabled}), then one notification
+          // below publishes the complete new toolset atomically.
+          registered.enabled = after;
+          changed = true;
         }
         lastSupported = next;
+        if (changed) server.sendToolListChanged();
       } catch (error) {
         onError(error instanceof Error ? error : new Error(String(error)));
       }

package/src/wayland-remote-desktop.mjs

@@ -590,6 +590,15 @@ export async function portalPointerMotion(dx, dy, options = {}) {
   await state.remote.NotifyPointerMotion(state.session, {}, Number(dx), Number(dy));
 }
 
+export async function portalPointerMotionAbsolute(x, y, options = {}) {
+  const state = options.state || await ensureWaylandRemoteDesktop(options);
+  if (state.backend === 'xdg-eis') {
+    await state.send({ op:'motion_absolute', x:Number(x), y:Number(y) });
+    return;
+  }
+  throw new ToolError('Absolute pointer motion requires the EIS Remote Desktop backend');
+}
+
 export async function portalPointerButton(button, pressed, options = {}) {
   const state = options.state || await ensureWaylandRemoteDesktop(options);
   const code = String(button || 'left').toLowerCase() === 'right' ? 0x111 : String(button || 'left').toLowerCase() === 'middle' ? 0x112 : 0x110;