@remcp/runtime 0.2.159 → 0.2.160

package/package.json

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

package/src/error-classes.mjs

@@ -0,0 +1,27 @@
+import { ToolError } from './util.mjs';
+// Error telemetry is a small closed vocabulary. Never return an error message,
+// path, URL, selector, command, or arbitrary error.code to account telemetry.
+const PERMISSION_CODES = new Set(['EACCES', 'EPERM']);
+const MISSING_CODES = new Set(['ENOENT', 'ENOTDIR']);
+const TIMEOUT_CODES = new Set(['ETIMEDOUT', 'ETIME']);
+const CONNECTION_CODES = new Set(['ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH']);
+
+export function classifyRuntimeToolError(error, toolName = '') {
+  const code = typeof error?.code === 'string' ? error.code.toUpperCase() : '';
+  const message = typeof error?.message === 'string' ? error.message.slice(0, 2048).toLowerCase() : '';
+  const browserTool = typeof toolName === 'string' && toolName.startsWith('browser_');
+  if (PERMISSION_CODES.has(code)) return 'permission';
+  if (MISSING_CODES.has(code)) return 'not_found';
+  if (TIMEOUT_CODES.has(code)) return 'timeout';
+  if (browserTool && CONNECTION_CODES.has(code)) return 'browser_unavailable';
+  if (/\bcancelled\b|\bcanceled\b|\baborted by the client\b/.test(message)) return 'cancelled';
+  if (/blocked (?:by|local|private)|outside the directories this device allows|private browser destination|blocked local browser scheme/.test(message)) return 'blocked';
+  if (browserTool && /browser cdp endpoint is unavailable|browser control is unavailable|cdp websocket (?:error|connection timed out)|local cdp endpoint did not become ready/.test(message)) {
+    return 'browser_unavailable';
+  }
+  if (/permission denied|access is denied|not authorized|not authorised|accessibility permission/.test(message)) return 'permission';
+  if (/timed out|timeout after|time limit exceeded/.test(message)) return 'timeout';
+  if (/element not found|no element matches|no matching ui window|target not found|not found in the current/.test(message)) return 'not_found';
+  if (/requires .*|must be (?:a |an |positive |between )|invalid (?:argument|selector|field|parameter)/.test(message)) return 'invalid_input';
+  return error instanceof ToolError ? 'tool_error' : 'runtime_error';
+}

package/src/extended/browser-endpoint.mjs

@@ -396,12 +396,33 @@ export async function filterBrowserTargets(list, { validate = assertResolvedPage
     if (candidates.length >= 1000) break;
   }
   const safe = new Array(candidates.length).fill(false);
+  // A single tab-list request may contain hundreds of pages on the same host.
+  // Every URL is still checked independently for scheme, credentials and private
+  // targets; the bounded DNS/allowlist decision is shared *only within this call*.
+  // Never cache across requests: every new call must revalidate DNS rebinding.
+  const sharedHostChecks = validate === assertResolvedPageUrl ? new Map() : null;
   let cursor = 0;
   await Promise.all(Array.from({ length: Math.min(8, candidates.length) }, async () => {
     while (cursor < candidates.length) {
       const index = cursor++;
       try {
-        await validate(candidates[index].url);
+        const rawUrl = candidates[index].url;
+        if (sharedHostChecks) {
+          const parsedUrl = safePageUrl(rawUrl);
+          // about:blank has no DNS and should not alias a real host.
+          const host = parsedUrl === 'about:blank' ? null : normalizedHost(new URL(parsedUrl).hostname);
+          if (host) {
+            if (!sharedHostChecks.has(host)) {
+              sharedHostChecks.set(host, Promise.resolve().then(() => validate(parsedUrl)));
+            }
+            await sharedHostChecks.get(host);
+          } else {
+            await validate(parsedUrl);
+          }
+        } else {
+          // Custom validators can have URL/path-specific policy: do not coalesce.
+          await validate(rawUrl);
+        }
         safe[index] = true;
       } catch {
         // Exclude unsafe/unresolvable pages without exposing them to the caller.

package/src/extended/browser-read.mjs

@@ -1,3 +1,4 @@
+import { snapshotDelta } from './browser-snapshot-diff.mjs';
 import process from 'node:process';
 import os from 'node:os';
 import path from 'node:path';
@@ -9,7 +10,7 @@ import { preserveInterruptedBrowserSession } from './browser-session-backup.mjs'
 import { clamp, commandExists, jsonResult, optionalString, requireEnum, spawnDetached, unavailable } from './common.mjs';
 
 
-import { assertResolvedBrowserUrl, assertResolvedPageUrl, boundedText, ensureBrowserEndpoint, listBrowserTargets, requestJson } from './browser-endpoint.mjs';
+import { assertResolvedBrowserUrl, assertResolvedPageUrl, boundedText, endpointUrl, ensureBrowserEndpoint, listBrowserTargets, requestJson } from './browser-endpoint.mjs';
 import { createGuardedNewTab, evaluate, withTarget } from './browser-session.mjs';
 
 export async function browserTabs(args = {}) {
@@ -112,13 +113,17 @@ export async function browserSnapshot(args) {
       child_ids: Array.isArray(node.childIds) ? node.childIds.slice(0, 200).map(id => boundedText(id, 256)) : [],
       backend_dom_node_id: node.backendDOMNodeId || null,
     }));
+    const delta = snapshotDelta(simplified,target,limit,{
+      from:args.diff_from,
+      endpoint:endpointUrl(args.endpoint).origin,
+    });
     const payload = {
       target_id: target.id,
       title: target.title,
       url: target.url,
       count: simplified.length,
       truncated: nodes.length > limit,
-      nodes: simplified,
+      ...delta,
     };
     if (!args.include_screenshot) return jsonResult(payload);
 

package/src/extended/browser-session.mjs

@@ -326,8 +326,10 @@ export async function createGuardedNewTab(url, args) {
 }
 
 export async function withTarget(args, callback) {
+  // chooseTarget already validated this exact discovered URL during this call.
+  // The actual page URL is independently checked before and after the action.
+  // Avoid a redundant DNS check for the same target metadata.
   const target = await chooseTarget(args);
-  await assertResolvedPageUrl(target.url);
   const endpoint = endpointUrl(args.endpoint);
   const production = process.env.NODE_ENV === 'production';
   const key = production ? productionSessionKey(endpoint, target) : '';

package/src/extended/browser-snapshot-diff.mjs

@@ -0,0 +1,56 @@
+// Incremental CDP AX snapshots with bounded, opaque, privacy-preserving state.
+// Only keyed HMAC fingerprints are cached; page text/values are never retained.
+import { createHmac, randomBytes, randomUUID } from 'node:crypto';
+
+const secret = randomBytes(32);
+const snapshots = new Map();
+const MAX_SNAPSHOTS = 16;
+const MAX_AGE_MS = 120_000;
+
+function fingerprint(node) {
+  return createHmac('sha256', secret).update(JSON.stringify(node)).digest('hex');
+}
+
+function scopeFor(target, limit, endpoint) {
+  return JSON.stringify([String(endpoint ?? ''),String(target?.id || ''),String(target?.url || ''),limit]);
+}
+
+export function snapshotDelta(nodes, target, limit, {
+  from = null,
+  endpoint = '',
+  now = Date.now(),
+} = {}) {
+  // Pure-data input may contain arbitrary page text. Store only HMACs and IDs,
+  // never node text. Fingerprints cannot be reverse-looked up without the key.
+  for (const [key, record] of snapshots) {
+    if (now - record.created > MAX_AGE_MS) snapshots.delete(key);
+  }
+  const scope = scopeFor(target,limit,endpoint);
+  const digest = new Map();
+  for(let i=0;i<nodes.length;i++){
+    const id = String(nodes[i].node_id || 'index:'+i);
+    digest.set(id, fingerprint(nodes[i]));
+  }
+  const previous = typeof from === 'string' && from.length === 36 && /^[0-9a-f-]{36}$/.test(from)
+    ? snapshots.get(from) : null;
+  const matched = previous && previous.scope === scope && now - previous.created <= MAX_AGE_MS;
+  const updated = [];
+  const removed = [];
+  if (matched) {
+    for(let i=0;i<nodes.length;i++){
+      const id=String(nodes[i].node_id || 'index:'+i);
+      if(previous.digests.get(id)!==digest.get(id))updated.push(nodes[i]);
+    }
+    for(const id of previous.digests.keys())if(!digest.has(id))removed.push(id);
+  }
+  const id = randomUUID();
+  snapshots.set(id, {scope,digests:digest,created:now});
+  while(snapshots.size>MAX_SNAPSHOTS)snapshots.delete(snapshots.keys().next().value);
+  return {
+    snapshot_id:id,
+    diff_status:matched?'delta':from?'unavailable':'full',
+    nodes:matched?updated:nodes,
+    removed_node_ids:matched?removed:[],
+    total_nodes:nodes.length,
+  };
+}

package/src/extended/catalog-schemas.mjs

@@ -36,7 +36,7 @@ export const AI_TOOL_DESCRIPTIONS = Object.freeze({
   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.',
   browser_navigate: 'Use this to open a URL in a new debuggable tab or navigate a known Chromium page by URL, back, forward or reload. Prefer it over typing into the address bar; new_tab also bootstraps browser automation when no page target exists yet.',
-  browser_snapshot: 'Use this to inspect a web page structurally through CDP accessibility. Prefer it over desktop ui_snapshot for page content; add include_screenshot=true only when final pixel/layout verification is needed. A selector may be temporarily centered for capture, but the original page scroll position is restored before the tool returns.',
+  browser_snapshot: 'Use this to inspect a web page structurally through CDP accessibility. Reuse the last snapshot_id as diff_from to return changed/removed semantic nodes rather than retransmitting the whole page after each step; refresh with a full snapshot when unavailable. Prefer it over desktop ui_snapshot for page content; add include_screenshot=true only when final pixel/layout verification is needed. A selector may be temporarily centered for capture, but the original page scroll position is restored before the tool returns.',
   browser_find: 'Use this to locate visible web elements by CSS selector, text or ARIA role and obtain reusable selectors/bounds. It requires an element criterion; use browser_snapshot, not an empty browser_find, to enumerate page structure. Prefer this before browser_action rather than guessing selectors or coordinates.',
   browser_action: 'Use this for deterministic DOM/CDP interaction with a known web element: click/focus/type/value/select/upload/key/scroll or viewport emulation. Prefer it over desktop pointer/ui_action for page content; use action=fill_form with CSS selectors to edit up to 20 visible fields in one tool call without submitting. Use browser_evaluate only when supported actions cannot express the task.',
   browser_wait: 'Use this after browser navigation/action to wait for selector/text/URL/load/navigation/network-idle instead of fixed sleeps or screenshot polling. Use browser_evaluate separately for JavaScript predicates.',

package/src/extended/catalog.mjs

@@ -163,7 +163,7 @@ export const extendedToolDefinitions = [
 
   define('browser_tabs', 'Browser tabs', 'List debuggable Chrome, Edge, or Chromium page targets from a loopback-only Chrome DevTools Protocol endpoint.', o({ ...browserTarget }), readOnlyOpen, browserHandlers.browser_tabs, ['browser_cdp']),
   define('browser_navigate', 'Browser navigate', 'Open a new debuggable tab or navigate a selected browser page by URL, history back/forward, or reload through Chrome DevTools Protocol.', o({ ...browserTarget, action:e(['url','new_tab','back','forward','reload'], 'Default url when url is provided, otherwise reload. new_tab creates the first page target when needed.'), url:s('Destination URL for action=url or action=new_tab.'), wait:b('Wait for the page load event; default true.'), ignore_cache:b('Reload without cache when action=reload.') }), openMutatingNonDestructive, browserHandlers.browser_navigate, ['browser_cdp']),
-  define('browser_snapshot', 'Browser snapshot', 'Return the selected browser page accessibility tree through Chrome DevTools Protocol and, when requested, attach a real rendered viewport PNG for visual verification. A selector is temporarily recentered for capture, its exact viewport bounds are returned, and the prior scroll position is restored before return.', o({ ...browserTarget, max_nodes:n('Maximum AX nodes; default 1500.'), include_screenshot:b('Attach a real CDP-rendered viewport PNG screenshot; default false.'), selector:s('When include_screenshot=true, center this CSS-selected element before capture and report its viewport bounds.') }), readOnlyOpen, browserHandlers.browser_snapshot, ['browser_cdp']),
+  define('browser_snapshot', 'Browser snapshot', 'Return a full or incremental accessibility tree (diff_from snapshot_id) through Chrome DevTools Protocol and, when requested, attach a real rendered viewport PNG for visual verification. A selector is temporarily recentered for capture, its exact viewport bounds are returned, and the prior scroll position is restored before return.', o({ ...browserTarget, max_nodes:n('Maximum AX nodes; default 1500.'), diff_from:s('Optional previous opaque snapshot_id for this exact target/page and node limit. Return changed/removed AX nodes only; if stale or mismatched, safely return a full snapshot.'), include_screenshot:b('Attach a real CDP-rendered viewport PNG screenshot; default false.'), selector:s('When include_screenshot=true, center this CSS-selected element before capture and report its viewport bounds.') }), readOnlyOpen, browserHandlers.browser_snapshot, ['browser_cdp']),
   define('browser_find', 'Find browser element', 'Find visible DOM elements by CSS selector, text, or ARIA role and return reusable selectors plus text, value, and bounding boxes.', o({ ...browserTarget, selector:s('CSS selector.'), text:s('Visible text substring.'), role:s('ARIA role.'), limit:n() }), readOnlyOpen, browserHandlers.browser_find, ['browser_cdp']),
   define('browser_action', 'Browser element action', 'Click, focus, type/set a value, fill up to 20 form fields in one guarded call, select, scroll a page or scrollable element, scroll an element into view, upload files, press a key, or set an exact responsive-test viewport in a debuggable browser page using DOM/CDP semantics.', o({ ...browserTarget, action:e(['click','focus','type','set_value','select','scroll','scroll_into_view','upload','press','set_viewport','fill_form','workflow']), selector:s('CSS selector for the target element; prefer the reusable selector returned by browser_find.'), steps:{type:'array',minItems:1,maxItems:12,description:'Workflow on one page: explicit CSS actions and bounded waits, max 12 seconds. Never silently submits; click must be explicit.',items:{type:'object',additionalProperties:false,properties:{action:e(['fill_form','set_value','select','focus','click','wait_for']),selector:s('CSS selector for action or wait_for.'),value:{type:['string','number','boolean']},fields:{type:'array',description:'CSS-selected field edits within the workflow step; no implicit form submission.',minItems:1,maxItems:20,items:{type:'object',additionalProperties:false,properties:{selector:s(),value:{type:['string','number','boolean']}},required:['selector','value']}},condition:e(['selector','text','url_contains','load']),text:s('Text or URL fragment for wait condition.'),timeout_ms:n('Wait timeout 100..4000 ms; default 1500.')},required:['action']}}, fields:{type:'array',minItems:1,maxItems:20,items:{type:'object',additionalProperties:false,properties:{selector:s('CSS selector.'),value:{type:['string','boolean','number'],description:'New field value; not returned in results.'}},required:['selector','value']},description:'fill_form: 1–20 CSS form fields in one CDP call. Does not submit.'}, browser_text:s('Visible text used only to locate a DOM element; use this instead of overloading text for action=type.'), text:s('For action=type, Unicode text to insert. For non-type element actions without selector/browser_text, visible text may identify the target.'), clear:b('For action=type, clear the current value before inserting text.'), value:s('Value for action=set_value; also accepted as a legacy type payload when text is used as the locator.'), text_value:s('Compatibility alias for the type/set_value text value.'), option:s(), delta_x:n('Horizontal scroll delta; positive means right.'), delta_y:n('Vertical scroll delta; positive means down.'), delta:n('Alias for delta_y.'), direction:e(['up','down','left','right']), wheel_times:n('Number of 120-unit wheel steps for direction; 1..50.'), path:s(), paths:{type:'array',items:{type:'string'}}, key:s(), width:n('CSS viewport width for set_viewport.'), height:n('CSS viewport height for set_viewport.'), device_scale_factor:n('Device scale factor for set_viewport; default 1.'), mobile:b('Enable mobile emulation for set_viewport.') }, ['action']), openMutating, browserHandlers.browser_action, ['browser_cdp']),
   define('browser_wait', 'Wait for browser', 'Wait for DOM state, page text, URL, completed loading, a navigation away from the current URL, or a short network-idle period in a debuggable browser page. Use browser_evaluate separately for JavaScript predicates or page-specific inspection.', o({ ...browserTarget, condition:e(['selector','text','url_contains','load','navigation','network_idle']), selector:s(), text:s(), value:s(), poll_ms:n(), idle_ms:n('Required zero-in-flight network quiet window for network_idle; default 500 ms.') }), readOnlyOpen, browserHandlers.browser_wait, ['browser_cdp']),

package/src/invoke.mjs

@@ -2,18 +2,13 @@ import { toolHandlers } from './catalog.mjs';
 import { extendedToolHandlers } from './extended/catalog.mjs';
 import { describeFilesystemFailure } from './permissions.mjs';
 import { recordEvent } from './telemetry.mjs';
+import { classifyRuntimeToolError } from './error-classes.mjs';
 import { ToolError, text } from './util.mjs';
 
 export function hasTool(name) {
   return toolHandlers.has(name) || extendedToolHandlers.has(name);
 }
 
-function errorKind(error) {
-  if (error instanceof ToolError) return 'tool_error';
-  const code = error?.code;
-  return typeof code === 'string' && code ? code.slice(0, 32) : 'runtime_error';
-}
-
 export async function invokeTool(name, args = {}, extra = {}) {
   const started = performance.now();
   const definition = toolHandlers.get(name) || extendedToolHandlers.get(name);
@@ -26,10 +21,10 @@ export async function invokeTool(name, args = {}, extra = {}) {
   }
   try {
     const result = await definition.handler(args || {}, extra || {});
-    recordEvent('tool_call', { tool: definition.name, durationMs: performance.now() - started, success: result?.isError !== true });
+    recordEvent('tool_call', { tool: definition.name, durationMs: performance.now() - started, success: result?.isError !== true, ...(result?.isError === true ? { errorKind:'tool_error' } : {}) });
     return result;
   } catch (error) {
-    recordEvent('tool_call', { tool: definition.name, durationMs: performance.now() - started, success: false, errorKind: errorKind(error) });
+    recordEvent('tool_call', { tool: definition.name, durationMs: performance.now() - started, success: false, errorKind: classifyRuntimeToolError(error, definition.name) });
     if (error instanceof ToolError) return text(error.message, true);
     return text(`Tool ${name} failed: ${describeFilesystemFailure(error, { path: error?.path })}`, true);
   }