@remcp/runtime 0.2.49 → 0.2.51

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## Unreleased
 
+## 0.2.51 — 2026-09-20
+
+- Linux AT-SPI text/focus operations reject explicit false results, `type_text method=accessibility` remains accessibility-only, and semantic browser text failures direct callers to `browser_action` rather than reporting an unverified paste as success.
+- GNOME Wayland drag requires the consent-backed Remote Desktop portal instead of unreliable XTEST/xdotool delivery.
+- PDF `read_document` falls back from the built-in parser to local `pdftotext` when embedded fonts prevent direct decoding, while preserving the existing no-text error when neither path extracts content.
+- Lockstep patch release with the ReMCP client at `0.2.51`.
+
+## 0.2.50 — 2026-09-20
+
+- Lockstep release with the ReMCP client after the hosted MCP/plugin contract was hardened for current OpenAI/MCP Apps requirements.
+- Computer-use tools retain the 83-tool runtime surface with AI-oriented descriptions, conditional JSON Schema validation, structured outputs, dynamic capability advertising, and semantic Accessibility/DOM-first routing.
+- `browser_navigate` adds `action=new_tab` so CDP automation can create the first page target without a shell/browser-address-bar workaround.
+- Live Linux verification covers Tesseract OCR targeting, XDG RemoteDesktop keyboard/pointer input, Unicode `type_text`, and the complete 39-tool computer-use smoke.
+
 ## 0.2.49 — 2026-09-20
 
 - Terminal process tools now return schema-validated structured session state, output ranges, match results and termination facts alongside their human-readable text.
@@ -21,6 +35,9 @@
 - Chrome DevTools Protocol endpoints are restricted to loopback addresses. New filesystem/document operations continue through the existing resolved-path allowlist, and launch/service/power operations reuse the runtime command policy.
 - Fixed metadata output truncation once the JSON tool contract exceeded the operating-system pipe buffer by waiting for stdout writes to flush before exit.
 - Terminal session tools now expose schema-validated structured `pid`, status, exit information, output ranges/matches, and session lists alongside their human-readable text, so hosted agents can chain process calls without parsing prose.
+- Tool descriptions now state the intended routing boundary for exact-path vs glob reads, singular vs batch filesystem operations, full-screen vs targeted/semantic screenshots, and local runtime settings vs hosted device labels.
+- Desktop action schemas and common guards now reject targetless `ui_action`/`window_action`, coordinate-less pointer moves, zero-motion scrolls, incomplete cross-backend `computer_action` targets, and connectivity tests without host/port before platform adapters can act. Empty `ui_find`/`browser_find` calls are redirected to their snapshot tools, and `wait_for_ui` requires an explicit state/condition instead of silently acting as a no-op.
+- `take_screenshot` is correctly advertised as non-read-only/non-idempotent because kept or oversized captures can persist timestamped files; selector-scoped `browser_snapshot` screenshots restore the original page scroll position before returning so the inspection path remains read-only.
 - No browser/document rendering stack was added; the runtime remains dependency-light and uses native OS facilities plus existing qpdf/poppler/zip helpers when available.
 
 ## 0.2.47 — 2026-09-19

package/README.md

@@ -63,7 +63,7 @@ For frontend QA, use semantic data to operate the page and rendered pixels to ve
 `maxReadLines`, `maxBufferedLines`, and `maxOutputBytes`. Access roots, blocked commands,
 the command guardrail, shell, write limit, runtime name, and unrestricted mode stay with the person
 at the computer. DOCX/XLSX edits operate directly on OOXML, while structural PDF writes use existing
-system tools such as qpdf/poppler when present; ReMCP still does not bundle Chromium, Puppeteer,
+system tools such as qpdf/poppler when present. PDF text reading uses the built-in parser first and can fall back to local `pdftotext` for embedded-font PDFs; ReMCP still does not bundle Chromium, Puppeteer,
 `sharp`, or `exceljs`.
 
 `--print-tools` prints the exact JSON contract (schemas and annotations) the runtime advertises, and
@@ -76,7 +76,7 @@ and the user's request is the authorization. ReMCP adds no per-tool approval pro
 and no dry-run detour unless you ask for one.
 
 Operating-system security boundaries still apply. macOS can require Accessibility/Screen Recording grants,
-and GNOME Wayland requires a one-time XDG RemoteDesktop consent before low-level keyboard/pointer input.
+and GNOME Wayland requires a one-time XDG RemoteDesktop consent before low-level keyboard/pointer/drag input. XTEST/xdotool drag is deliberately not treated as reliable on GNOME Wayland.
 ReMCP does not bypass those controls: after GNOME grants access, the portal restore token is stored locally
 under the runtime config directory with mode `0600` and reused when the portal permits it. Semantic AT-SPI
 UI actions and the XDG Screenshot portal remain separate from that low-level input permission.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.49",
+  "version": "0.2.51",
   "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 every file matching a glob under a directory in one call, each section prefixed with its path and line count. Use this to load a whole project area into context quickly instead of one read per file.',
+    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.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -127,7 +127,7 @@ export const toolDefinitions = [
   {
     name: 'read_multiple_files',
     title: 'Read multiple files',
-    description: 'Read several text files in one call. Each file is returned separately and a failure to read one file does not stop the others.',
+    description: 'Read several explicitly named text files in one call. Use this when the exact paths are already known; each file is returned separately and one failure does not stop the others. Do not use this for glob discovery: use read_files instead. For one path use read_file.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -239,7 +239,7 @@ export const toolDefinitions = [
   {
     name: 'write_file',
     title: 'Write file',
-    description: 'Create a file or change its full content. Parent directories are created automatically. Replaces the file by default; use mode "append" to add to the end. For binary data pass encoding-free base64 through write_binary instead.',
+    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.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -256,7 +256,7 @@ export const toolDefinitions = [
   {
     name: 'write_files',
     title: 'Write multiple files',
-    description: 'Create or replace many files in one call, each with its own path, content, and optional mode. Use this to scaffold a project or apply a multi-file change without one round trip per file.',
+    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.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -427,7 +427,7 @@ export const toolDefinitions = [
   {
     name: 'move_file',
     title: 'Move or rename',
-    description: 'Move or rename a file or directory. Replaces an existing destination file by default; pass overwrite false to refuse instead.',
+    description: 'Move or rename exactly one file or directory from one source to one destination. Replaces an existing destination file by default; pass overwrite false to refuse instead. Use move_paths for two or more moves.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -444,7 +444,7 @@ export const toolDefinitions = [
   {
     name: 'copy_file',
     title: 'Copy file',
-    description: 'Copy one file to a new path, replacing the destination by default. Pass overwrite false to refuse an existing destination. Directories are not copied recursively.',
+    description: 'Copy exactly one regular file to a new path. Directories are not copied recursively. Use copy_paths for directories or two or more copy operations; pass overwrite false to refuse an existing destination.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -461,7 +461,7 @@ export const toolDefinitions = [
   {
     name: 'copy_paths',
     title: 'Copy paths',
-    description: 'Copy many files or whole directories in one call, each with its own source and destination. Directories are copied recursively.',
+    description: 'Copy two or more paths, or copy a directory recursively, in one call. Each item has its own source and destination. For exactly one regular file use copy_file.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -489,7 +489,7 @@ export const toolDefinitions = [
   {
     name: 'move_paths',
     title: 'Move paths',
-    description: 'Move or rename many files or whole directories in one call, each with its own source and destination. Falls back to copy-and-delete across filesystems.',
+    description: 'Move or rename two or more files/directories in one batch, each with its own source and destination. Falls back to copy-and-delete across filesystems. For one source/destination pair use move_file.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -517,7 +517,7 @@ export const toolDefinitions = [
   {
     name: 'delete_path',
     title: 'Delete path',
-    description: 'Delete a file or a directory on the computer. Directories are removed with their contents unless recursive is false. The filesystem root is refused.',
+    description: 'Delete exactly one file or directory. Directories are removed with their contents unless recursive is false; the filesystem root is refused. Use delete_paths for two or more targets, or move_to_trash when deletion should be reversible.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -533,7 +533,7 @@ export const toolDefinitions = [
   {
     name: 'delete_paths',
     title: 'Delete paths',
-    description: 'Delete many files and directories in one call, reporting each result. Use move_to_trash instead when the deletion should be reversible.',
+    description: 'Delete two or more files/directories in one batch and report each result. For one target use delete_path. Use move_to_trash instead when deletion should be reversible.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -582,7 +582,7 @@ export const toolDefinitions = [
   {
     name: 'take_screenshot',
     title: 'Take screenshot',
-    description: 'Capture the screen of the paired computer and return it as an image, for GUI work, visual checks, and demonstrating what is on screen. Uses the standard desktop screenshot portal on Wayland, with grim, gnome-screenshot, spectacle, scrot, ImageMagick import, screencapture, or PowerShell fallbacks depending on the platform.',
+    description: 'Capture the entire desktop only when full-screen pixels are actually needed. Prefer ui_snapshot or browser_snapshot for semantic inspection, and screenshot_region for one window, monitor, or rectangle. This tool uses the platform screenshot portal/utility and returns an image.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -591,7 +591,8 @@ export const toolDefinitions = [
       },
       additionalProperties: false,
     },
-    annotations: readOnly,
+    // keep=true and oversized fallbacks persist a timestamped PNG, so a repeated call can add files.
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
     handler: fileToolHandlers.take_screenshot,
   },
   {
@@ -813,7 +814,7 @@ export const toolDefinitions = [
   {
     name: 'set_config_value',
     title: 'Change runtime setting',
-    description: 'Change one of this runtime’s own preferences on this computer: telemetryEnabled, maxReadLines, maxBufferedLines or maxOutputBytes. The change applies immediately and is saved to runtime.json. Access roots, blocked commands, the command guardrail, the shell and the write limit cannot be set through MCP — they stay with the person at this computer.',
+    description: 'Change one of this local runtime’s own preferences on the selected computer: telemetryEnabled, maxReadLines, maxBufferedLines or maxOutputBytes. This does not rename the paired device; use hosted rename_device for that label. Access roots, blocked commands, shell/guardrails and the write limit remain local-only.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/extended/browser.mjs

@@ -310,10 +310,12 @@ export async function browserSnapshot(args) {
 
     await session.send('Page.enable');
     const selector = optionalString(args.selector);
+    let restoreScroll = null;
     if (selector) {
       const bounds = await evaluate(session, `new Promise((resolve,reject) => {
         const el=document.querySelector(${JSON.stringify(selector)});
         if(!el){reject(new Error('Screenshot element not found'));return;}
+        const originalScrollX=scrollX, originalScrollY=scrollY;
         const initial=el.getBoundingClientRect();
         const desiredTop=Math.max(0, scrollY + initial.top - Math.max(0,(innerHeight-initial.height)/2));
         window.scrollTo({top:desiredTop,left:scrollX,behavior:'instant'});
@@ -328,6 +330,8 @@ export async function browserSnapshot(args) {
             viewport_height:innerHeight,
             scroll_x:scrollX,
             scroll_y:scrollY,
+            original_scroll_x:originalScrollX,
+            original_scroll_y:originalScrollY,
             fully_visible:r.x>=0 && r.y>=0 && r.right<=innerWidth && r.bottom<=innerHeight
           });
         }));
@@ -335,7 +339,9 @@ export async function browserSnapshot(args) {
       if (!bounds || !Number.isFinite(Number(bounds.width)) || !Number.isFinite(Number(bounds.height)) || bounds.width <= 0 || bounds.height <= 0) {
         throw new Error('Screenshot element has invalid bounds');
       }
-      payload.screenshot_target = { selector, ...bounds };
+      restoreScroll = { x:Number(bounds.original_scroll_x || 0), y:Number(bounds.original_scroll_y || 0) };
+      const { original_scroll_x: _originalX, original_scroll_y: _originalY, ...reportedBounds } = bounds;
+      payload.screenshot_target = { selector, ...reportedBounds };
     }
     payload.screenshot = {
       scope: 'viewport',
@@ -343,11 +349,18 @@ export async function browserSnapshot(args) {
       height: await evaluate(session, 'innerHeight').catch(() => null),
     };
     const result = jsonResult(payload);
-    const captured = await session.send('Page.captureScreenshot', {
-      format: 'png',
-      fromSurface: true,
-      captureBeyondViewport: false,
-    });
+    let captured;
+    try {
+      captured = await session.send('Page.captureScreenshot', {
+        format: 'png',
+        fromSurface: true,
+        captureBeyondViewport: false,
+      });
+    } finally {
+      if (restoreScroll) {
+        await evaluate(session, `window.scrollTo({left:${restoreScroll.x},top:${restoreScroll.y},behavior:'instant'})`).catch(() => {});
+      }
+    }
     const data = String(captured?.data || '');
     if (!data) throw new Error('CDP returned no screenshot data');
     if (Buffer.byteLength(data, 'base64') > 8 * 1024 * 1024) throw new Error('Browser screenshot exceeds the 8 MiB inline image limit');
@@ -393,6 +406,7 @@ function findExpression(args) {
 }
 
 export async function browserFind(args) {
+  if (!(args.selector || args.text || args.role)) throw new Error('browser_find requires selector, text, or role; use browser_snapshot to enumerate page structure');
   return withTarget(args, async (session, target) => {
     const matches = await evaluate(session, findExpression(args));
     return jsonResult({ target_id: target.id, count: Array.isArray(matches) ? matches.length : 0, matches: Array.isArray(matches) ? matches : [] });

package/src/extended/catalog.mjs

@@ -34,14 +34,14 @@ const AI_TOOL_DESCRIPTIONS = Object.freeze({
   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.',
   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. Prefer returned id or compact label for subsequent ui_action; refresh only when the UI has changed.',
+  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.',
-  type_text: 'Use this for reliable Unicode text entry into a native semantic target or focused control. Prefer method=auto so Accessibility or clipboard restoration preserves the requested characters regardless of keyboard layout. Use method=keys only for deliberate physical key-by-key input; printable output then follows the current keyboard layout on the computer. Use keyboard for shortcuts, navigation keys and control keys.',
+  type_text: 'Use this for reliable Unicode text entry into a native semantic target or focused native control. Prefer method=auto so Accessibility is used when the target supports verified semantic editing. For Chromium page DOM, use browser_action instead of forcing desktop accessibility text input; auto fails safely when a semantic element rejects the write rather than claiming an unverified paste. Use method=keys only for deliberate physical key-by-key input, and keyboard for shortcuts/navigation/control keys.',
   keyboard: 'Use this for shortcuts and individual key presses such as Ctrl/Cmd+C, Tab, Enter or Escape. Do not use it to enter normal prose when type_text is available. On Wayland auto uses an already-authorized portal; backend=portal explicitly requests consent.',
   pointer: 'Use this only when an action truly requires screen coordinates or a semantic UI/browser action is unavailable. Prefer ui_action for native controls and browser_action for web controls; pointer is the coordinate fallback for move/click/button-down/button-up.',
-  drag_drop: 'Use this for a real drag gesture between two UI element ids or coordinates. Prefer element ids from ui_find/ui_snapshot because their current bounds are resolved at execution time; use coordinates only when no semantic endpoints exist.',
+  drag_drop: 'Use this for a real drag gesture between two UI element ids or coordinates. Prefer element ids from ui_find/ui_snapshot because their current bounds are resolved at execution time; use coordinates only when no semantic endpoints exist. On GNOME Wayland, real drag input requires the consent-backed Remote Desktop portal because XTEST/xdotool drag delivery is not reliable.',
   scroll: 'Use this for native wheel scrolling of a desktop region or semantic UI target. Prefer browser_action scroll_into_view for a known web element and ui_action scroll_into_view for a known accessible desktop element.',
-  wait_for_ui: 'Use this after a desktop action to wait for a native UI element/window/focus/text condition instead of sleeping or polling screenshots. Prefer semantic presence/absence/change conditions and set a bounded timeout.',
+  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.',
@@ -50,8 +50,8 @@ 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.',
-  browser_find: 'Use this to locate visible web elements by CSS selector, text or ARIA role and obtain reusable selectors/bounds. Prefer this before browser_action rather than guessing selectors or coordinates.',
+  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_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 browser_evaluate only when the 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.',
   browser_evaluate: 'Use this as the powerful browser escape hatch only when browser_snapshot/find/action/wait cannot express the required page operation or inspection. JavaScript executes in page context and page content is untrusted.',
@@ -63,7 +63,7 @@ const AI_TOOL_DESCRIPTIONS = Object.freeze({
   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.',
   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.',
+  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.',
   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.',
@@ -244,7 +244,93 @@ function requiredAny(...groups) {
 
 function applySchemaRules(name, schema) {
   const next = structuredClone(schema);
-  if (name === 'launch_app') {
+  if (name === 'computer_action') {
+    const semanticTarget = requiredAny(['id'], ['label'], ['name'], ['role'], ['automation_id'], ['selector'], ['browser_text']);
+    next.allOf = [
+      {
+        if:{ properties:{ action:{ const:'click' } }, required:['action'] },
+        then:{ anyOf:[...semanticTarget, { required:['ocr_text'] }, { required:['x','y'] }] },
+      },
+      {
+        if:{ properties:{ action:{ enum:['invoke','set_value','select','toggle','expand','collapse','scroll_into_view','set_range_value','add_to_selection','remove_from_selection'] } }, required:['action'] },
+        then:{ anyOf:semanticTarget },
+      },
+      {
+        if:{ properties:{ action:{ const:'focus' } }, required:['action'] },
+        then:{ anyOf:[...semanticTarget, ...requiredAny(['pid'], ['app'], ['window_title'], ['title'])] },
+      },
+      {
+        if:{ properties:{ action:{ enum:['set_value','set_range_value'] } }, required:['action'] },
+        then:{ required:['value'] },
+      },
+      {
+        if:{ properties:{ action:{ const:'multi_select' } }, required:['action'] },
+        then:{ required:['targets'] },
+      },
+      {
+        if:{ properties:{ action:{ const:'multi_edit' } }, required:['action'] },
+        then:{ required:['edits'] },
+      },
+    ];
+  } else if (name === 'ui_find') {
+    next.anyOf = requiredAny(['id'], ['label'], ['name'], ['role'], ['automation_id']);
+  } else if (name === 'ui_action') {
+    next.allOf = [
+      { anyOf:requiredAny(['id'], ['label'], ['name'], ['role'], ['automation_id']) },
+      {
+        if:{ properties:{ action:{ enum:['set_value','set_range_value'] } }, required:['action'] },
+        then:{ required:['value'] },
+      },
+    ];
+  } else if (name === 'wait_for_ui') {
+    next.anyOf = requiredAny(['state'], ['condition']);
+    next.allOf = [
+      {
+        if:{ properties:{ condition:{ const:'text_exists' } }, required:['condition'] },
+        then:{ required:['text'] },
+      },
+      {
+        if:{ properties:{ condition:{ const:'active_window' } }, required:['condition'] },
+        then:{ anyOf:requiredAny(['text'], ['name'], ['window_title']) },
+      },
+      {
+        if:{ properties:{ condition:{ enum:['element_exists','element_enabled'] } }, required:['condition'] },
+        then:{ anyOf:requiredAny(['id'], ['label'], ['name'], ['role'], ['automation_id']) },
+      },
+      {
+        if:{ properties:{ state:{ enum:['present','absent'] } }, required:['state'] },
+        then:{ anyOf:requiredAny(['id'], ['label'], ['name'], ['role'], ['automation_id']) },
+      },
+    ];
+  } else if (name === 'window_action') {
+    next.allOf = [
+      { anyOf:requiredAny(['id'], ['pid'], ['app'], ['title']) },
+      {
+        if:{ properties:{ action:{ const:'move' } }, required:['action'] },
+        then:{ required:['x','y'] },
+      },
+      {
+        if:{ properties:{ action:{ const:'resize' } }, required:['action'] },
+        then:{ required:['width','height'] },
+      },
+      {
+        if:{ properties:{ action:{ const:'move_resize' } }, required:['action'] },
+        then:{ required:['x','y','width','height'] },
+      },
+    ];
+  } else if (name === 'pointer') {
+    next.allOf = [{
+      if:{ properties:{ action:{ const:'move' } }, required:['action'] },
+      then:{ required:['x','y'] },
+    }];
+  } else if (name === 'scroll') {
+    next.anyOf = requiredAny(['delta_x'], ['delta_y'], ['delta'], ['direction']);
+  } else if (name === 'network') {
+    next.allOf = [{
+      if:{ properties:{ action:{ const:'test' } }, required:['action'] },
+      then:{ required:['host','port'] },
+    }];
+  } else if (name === 'launch_app') {
     next.anyOf = requiredAny(['app'], ['path']);
   } else if (name === 'keyboard') {
     next.anyOf = requiredAny(['shortcut'], ['key'], ['keys']);
@@ -259,6 +345,8 @@ function applySchemaRules(name, schema) {
       { required:['x','y','width','height'] },
       ...requiredAny(['window_id'], ['pid'], ['app'], ['title'], ['monitor'], ['monitor_index']),
     ];
+  } else if (name === 'browser_find') {
+    next.anyOf = requiredAny(['selector'], ['text'], ['role']);
   } else if (name === 'browser_navigate') {
     next.allOf = [{
       if:{ properties:{ action:{ enum:['url','new_tab'] } }, required:['action'] },
@@ -449,10 +537,10 @@ export const extendedToolDefinitions = [
   define('ui_snapshot', 'UI accessibility snapshot', 'Read the active desktop accessibility/UI Automation tree with compact labels, semantic hierarchy, bounds, state and suggested actions. Default scope is the active application/window; scope=desktop requests the full desktop tree. Explicit pid/app/window_title scopes override the active default. browser_dom asks the OS accessibility provider for the web-document subtree when available.', o({ scope:e(['active','desktop'],'Default active. Use desktop only when cross-application discovery is required.'), pid:n('Optional owning process id scope.'), app:s('Optional application/process name substring scope.'), window_title:s('Optional top-level accessibility window/frame title scope.'), browser_dom:b('Prefer the native browser document accessibility subtree instead of browser chrome when supported.'), semantic_tree:b('Include compact semantic hierarchy text; default true.'), max_nodes:n('Maximum nodes; default 500, maximum 5000.'), max_depth:n('Maximum traversal depth; default 8, maximum 32.') }), readOnlyLive, desktopHandlers.ui_snapshot, ['ui']),
   define('ui_find', 'Find UI elements', 'Find native accessible desktop elements by label/id/name/role/AutomationId. Reuses the latest five-second semantic snapshot for fast repeated targeting; refresh=true forces a new OS accessibility capture.', o({ ...uiSelector, refresh:b('Force a fresh accessibility capture instead of the short-lived snapshot cache.'), limit:n('Maximum matches; default 20.'), max_nodes:n(), max_depth:n() }), readOnlyLive, desktopHandlers.ui_find, ['ui']),
   define('ui_action', 'Act on UI element', 'Act on a native accessibility/UI Automation element by id, label or semantic selector. Supports invoke/focus/value/toggle/selection, expand-collapse, range values and scroll-into-view before falling back to coordinates.', o({ action:e(['click','invoke','focus','set_value','select','toggle','expand','collapse','scroll_into_view','set_range_value','add_to_selection','remove_from_selection']), ...uiSelector, value:{description:'New text or numeric range value.'} }, ['action']), openMutating, desktopHandlers.ui_action, ['ui']),
-  define('type_text', 'Type text', 'Enter Unicode text into a semantic accessibility target or focused control. Auto prefers accessibility editing, then reliable clipboard paste with previous clipboard restoration; keys remains available for control-character input.', o({ text:s('Text to enter.'), method:e(['auto','accessibility','clipboard','keys']), clear:b('Clear existing text before input when keyboard/paste fallback is used.'), caret_position:e(['start','idle','end']), press_enter:b('Press Enter after typing.'), delay_ms:n('Per-key delay for method=keys.'), ...uiSelector, window_id:s('Optional XWayland target window id for clipboard/keys methods.'), title:s('Optional target window title substring for clipboard/keys methods.'), ...inputBackendSelector }, ['text']), openMutating, desktopHandlers.type_text, ['input']),
+  define('type_text', 'Type text', 'Enter Unicode text into a native semantic accessibility target or focused native control. Auto prefers verified accessibility editing; explicit semantic targets fail safely when the platform rejects the write instead of claiming an unverified paste. Use browser_action for Chromium page DOM. Clipboard/keys fallbacks remain available for focused/window-level input when appropriate.', o({ text:s('Text to enter.'), method:e(['auto','accessibility','clipboard','keys']), clear:b('Clear existing text before input when keyboard/paste fallback is used.'), caret_position:e(['start','idle','end']), press_enter:b('Press Enter after typing.'), delay_ms:n('Per-key delay for method=keys.'), ...uiSelector, window_id:s('Optional XWayland target window id for clipboard/keys methods.'), title:s('Optional target window title substring for clipboard/keys methods.'), ...inputBackendSelector }, ['text']), openMutating, desktopHandlers.type_text, ['input']),
   define('keyboard', 'Keyboard shortcut', 'Send a keyboard shortcut or key press to the active desktop application or an explicitly selected window. On Wayland deterministic XWayland input should use window_id/pid/app/title; backend=portal explicitly requests the consent-backed XDG RemoteDesktop path.', o({ shortcut:s(), key:s(), keys:{ type:'array', items:{type:'string'} }, ...inputWindowSelector, ...inputBackendSelector }), openMutating, desktopHandlers.keyboard, ['input']),
   define('pointer', 'Pointer action', 'Move the pointer or perform click, double-click, right-click, mouse-down, or mouse-up at desktop screen coordinates. Wayland supports XWayland fallback and an explicitly consented XDG RemoteDesktop backend.', o({ action:e(['move','click','double_click','right_click','down','up']), x:n(), y:n(), button:e(['left','right','middle']), ...inputBackendSelector }, ['action']), openMutating, desktopHandlers.pointer, ['pointer']),
-  define('drag_drop', 'Drag and drop', 'Drag between desktop coordinates or semantic UI element IDs returned by ui_snapshot/ui_find. Element IDs are resolved to the center of their current accessibility bounds before the native pointer adapter runs.', o({ from_x:n(), from_y:n(), to_x:n(), to_y:n(), from_id:s('Source UI element id; use instead of from_x/from_y.'), to_id:s('Destination UI element id; use instead of to_x/to_y.'), button:e(['left','right','middle']), hold_ms:n(), duration_ms:n(), ...inputBackendSelector }), openMutating, desktopHandlers.drag_drop, ['drag']),
+  define('drag_drop', 'Drag and drop', 'Drag between desktop coordinates or semantic UI element IDs returned by ui_snapshot/ui_find. Element IDs are resolved to current accessibility bounds before input. GNOME Wayland requires the consent-backed Remote Desktop portal for real drag delivery; unreliable XTEST/xdotool drag is rejected.', o({ from_x:n(), from_y:n(), to_x:n(), to_y:n(), from_id:s('Source UI element id; use instead of from_x/from_y.'), to_id:s('Destination UI element id; use instead of to_x/to_y.'), button:e(['left','right','middle']), hold_ms:n(), duration_ms:n(), ...inputBackendSelector }), openMutating, desktopHandlers.drag_drop, ['drag']),
   define('scroll', 'Scroll', 'Scroll vertically or horizontally using native wheel input. Target a semantic UI element/label or x/y first so the wheel is delivered to the intended region; direction+wheel_times is a convenience over normalized deltas.', o({ delta_x:n('Horizontal delta; positive means right.'), delta_y:n('Vertical 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 when direction is used; 1..50.'), x:n(), y:n(), ...uiSelector, ...inputBackendSelector }), mutatingNonDestructive, desktopHandlers.scroll, ['pointer']),
   define('wait_for_ui', 'Wait for UI', 'Wait on fresh native accessibility state without screenshot polling. Use state=present/absent/changed or condition=text_exists/active_window/element_exists/element_enabled/focused_element.', o({ state:e(['present','absent','changed'], 'changed captures the first matching semantic state and waits until it differs.'), condition:e(['text_exists','active_window','element_exists','element_enabled','focused_element']), text:s('Text used by text_exists or active_window.'), browser_dom:b('Use native browser document accessibility where supported.'), ...uiSelector, timeout_ms:n('Maximum wait, capped at 120000 ms.'), poll_ms:n('Polling interval, 50..5000 ms.') }), readOnlyLive, desktopHandlers.wait_for_ui, ['ui']),
   define('clipboard', 'Clipboard', 'Read, write, or clear the system text clipboard using native operating-system clipboard facilities.', o({ action:e(['read','write','clear']), text:s('Text to write.') }, ['action']), mutating, desktopHandlers.clipboard, ['clipboard']),
@@ -464,7 +552,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 }), readOnlyLive, 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 recenters the target before capture and returns its exact viewport bounds.', 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.') }), readOnlyLive, browserHandlers.browser_snapshot, ['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.') }), readOnlyLive, 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() }), readOnlyLive, browserHandlers.browser_find, ['browser_cdp']),
   define('browser_action', 'Browser element action', 'Click, focus, type/set a value, select, scroll to, upload files, press a key, or set an exact responsive-test viewport in a debuggable browser page using DOM/CDP semantics.', o({ ...browserTarget, action:e(['click','focus','type','set_value','select','scroll_into_view','upload','press','set_viewport']), selector:s(), text:s(), value:s(), text_value:s(), option:s(), path:s(), paths:{type:'array',items:{type:'string'}}, key:s(), width:n('CSS viewport width for set_viewport.'), height:n('CSS viewport height for set_viewport.'), device_scale_factor:n('Device scale factor for set_viewport; default 1.'), mobile:b('Enable mobile emulation for set_viewport.') }, ['action']), openMutating, browserHandlers.browser_action, ['browser_cdp']),
   define('browser_wait', 'Wait for browser', 'Wait for DOM state, page text, URL, completed loading, a navigation away from the current URL, or a short network-idle period in a debuggable browser page. Use browser_evaluate separately for JavaScript predicates or page-specific inspection.', o({ ...browserTarget, condition:e(['selector','text','url_contains','load','navigation','network_idle']), selector:s(), text:s(), value:s(), poll_ms:n(), idle_ms:n('Required zero-in-flight network quiet window for network_idle; default 500 ms.') }), readOnlyLive, browserHandlers.browser_wait, ['browser_cdp']),

package/src/extended/desktop-linux.mjs

@@ -586,10 +586,14 @@ if target is None:raise Exception("UI element not found")
 if action in ("click","invoke","select","toggle"):
  target.queryAction().doAction(0)
 elif action=="focus":
- target.queryComponent().grabFocus()
+ if target.queryComponent().grabFocus() is False: raise Exception("focus accessibility action returned false")
 elif action=="set_value":
- try: target.queryEditableText().setTextContents(value)
- except: target.queryValue().currentValue=value
+ try:
+  applied=target.queryEditableText().setTextContents(value)
+  if applied is False: raise Exception("editable text write returned false")
+ except Exception as editable_error:
+  try: target.queryValue().currentValue=value
+  except Exception as value_error: raise Exception("set_value failed: editable=%s; value=%s"%(editable_error,value_error))
 elif action=="set_range_value":
  target.queryValue().currentValue=float(value)
 elif action in ("expand","collapse"):
@@ -620,7 +624,10 @@ print(json.dumps({"action":action,"name":target.name or "","role":target.getRole
   try { payload = JSON.parse(result.stdout || ''); } catch {}
   if (payload && !payload.error) return text(JSON.stringify(payload));
   if (payload?.error) unavailable('Linux accessibility action', payload.error);
-  if (result.code !== 0) unavailable('Linux accessibility action', (result.stderr || result.stdout).trim());
+  if (result.code !== 0) {
+    const detail = String(result.stderr || result.stdout || 'AT-SPI action failed').trim().split(/\r?\n/).filter(Boolean).at(-1) || 'AT-SPI action failed';
+    unavailable('Linux accessibility action', detail);
+  }
   return text(result.stdout.trim());
 }
 
@@ -961,9 +968,11 @@ export async function dragDrop(args = {}) {
         return jsonResult({ from:[args.from_x,args.from_y], to:[args.to_x,args.to_y], backend:'xdg-desktop-portal' });
       } catch {}
     }
-    if (backend !== 'portal' && await runXdotool()) return jsonResult({ from:[args.from_x,args.from_y], to:[args.to_x,args.to_y], backend:'xwayland-xdotool' });
+    if (backend === 'x11') {
+      unavailable('Wayland drag and drop', 'XTEST/xdotool drag events are not reliably delivered through GNOME Wayland; use backend=portal');
+    }
     if (backend === 'auto' && waylandPortalCandidate()) portalPermissionHint('Wayland drag and drop');
-    unavailable('Wayland drag and drop', backend === 'x11' ? 'xdotool is unavailable' : 'no working drag backend is available');
+    unavailable('Wayland drag and drop', 'no working consent-backed drag backend is available');
   }
   if (await runXdotool()) return jsonResult({ from:[args.from_x,args.from_y], to:[args.to_x,args.to_y], backend:'xdotool' });
   unavailable('Drag and drop', 'install xdotool');

package/src/extended/desktop.mjs

@@ -273,7 +273,15 @@ export async function listWindows(args = {}) {
     return { ...window, monitor: monitor?.name ?? null, monitor_index: monitor?.index ?? null };
   }));
 }
-export async function windowAction(args = {}) { return adapter.windowAction(args); }
+export async function windowAction(args = {}) {
+  const hasTarget = Boolean(args.id || Number.isInteger(Number(args.pid)) || args.app || args.title);
+  if (!hasTarget) throw new Error('window_action requires id, pid, app, or title');
+  const action = optionalString(args.action);
+  if (action === 'move' && ![args.x,args.y].every(value => Number.isFinite(Number(value)))) throw new Error('window_action move requires x and y');
+  if (action === 'resize' && ![args.width,args.height].every(value => Number.isFinite(Number(value)))) throw new Error('window_action resize requires width and height');
+  if (action === 'move_resize' && ![args.x,args.y,args.width,args.height].every(value => Number.isFinite(Number(value)))) throw new Error('window_action move_resize requires x, y, width and height');
+  return adapter.windowAction(args);
+}
 export async function uiSnapshot(args = {}) {
   const explicitlyScoped = args.pid != null || args.app || args.window_title || args.windowTitle;
   const activeOnly = args.active_only != null
@@ -285,10 +293,18 @@ export async function uiSnapshot(args = {}) {
   return jsonResult(enrichUiPayload(value, effective));
 }
 export async function uiAction(args = {}) {
-  return adapter.uiAction(withResolvedUiLabel(args));
+  const resolved = withResolvedUiLabel(args);
+  const hasTarget = Boolean(resolved.id || resolved.label != null || resolved.name || resolved.role || resolved.automation_id || resolved.automationId);
+  if (!hasTarget) throw new Error('ui_action requires id, label, name, role, or automation_id');
+  const action = optionalString(resolved.action);
+  if (['set_value','set_range_value'].includes(action) && resolved.value == null) throw new Error(`ui_action ${action} requires value`);
+  return adapter.uiAction(resolved);
 }
 export async function keyboard(args = {}) { return adapter.keyboard(args); }
-export async function pointer(args = {}) { return adapter.pointer(args); }
+export async function pointer(args = {}) {
+  if (args.action === 'move' && ![args.x,args.y].every(value => Number.isFinite(Number(value)))) throw new Error('pointer move requires x and y');
+  return adapter.pointer(args);
+}
 export async function clipboard(args = {}) { return adapter.clipboard(args); }
 export async function displayInventory(args = {}) { return adapter.displayInventory(args); }
 export async function cursorPosition(args = {}) { return typeof adapter.cursorPosition === 'function' ? adapter.cursorPosition(args) : jsonResult({ x:null, y:null }); }
@@ -334,6 +350,8 @@ export async function screenshotRegion(args = {}) {
 export async function notification(args = {}) { return adapter.notification(args); }
 export async function scroll(args = {}) {
   const direction = optionalString(args.direction);
+  const hasDelta = [args.delta_x,args.delta_y,args.delta].some(value => value != null && Number.isFinite(Number(value)));
+  if (!direction && !hasDelta) throw new Error('scroll requires direction or a delta');
   const times = clamp(args.wheel_times, 1, 1, 50);
   let deltaX = Number(args.delta_x || 0);
   let deltaY = Number(args.delta_y ?? args.delta ?? 0);
@@ -403,6 +421,8 @@ async function uiMatches(args = {}) {
 }
 
 export async function uiFind(args = {}) {
+  const hasSelector = Boolean(args.id || args.label != null || args.name || args.role || args.automation_id || args.automationId);
+  if (!hasSelector) throw new Error('ui_find requires id, label, name, role, or automation_id; use ui_snapshot to enumerate UI');
   const nodes = await uiMatches(args);
   return jsonResult({ count: nodes.length, nodes });
 }
@@ -473,11 +493,17 @@ export async function waitForUi(args = {}) {
   const timeoutMs = clamp(args.timeout_ms, 10_000, 100, 120_000);
   const pollMs = clamp(args.poll_ms, 250, 50, 5000);
   const rawCondition = optionalString(args.condition);
+  const rawState = optionalString(args.state);
+  if (!rawCondition && !rawState) throw new Error('wait_for_ui requires state or condition');
   const aliases = { text:'text_exists', window:'active_window', element:'element_exists', enabled:'element_enabled', focused:'focused_element' };
   const condition = rawCondition
     ? requireEnum(aliases[rawCondition] || rawCondition, 'condition', ['text_exists','active_window','element_exists','element_enabled','focused_element'])
     : null;
-  const state = condition ? null : requireEnum(args.state || 'present', 'state', ['present', 'absent', 'changed']);
+  const state = condition ? null : requireEnum(rawState, 'state', ['present', 'absent', 'changed']);
+  const hasSelector = Boolean(args.id || args.label != null || args.name || args.role || args.automation_id || args.automationId);
+  if (['element_exists','element_enabled'].includes(condition) && !hasSelector) throw new Error(`wait_for_ui condition=${condition} requires a semantic target`);
+  if (condition === 'active_window' && !(args.text || args.name || args.window_title || args.windowTitle)) throw new Error('wait_for_ui condition=active_window requires text, name, or window_title');
+  if (['present','absent'].includes(state) && !hasSelector) throw new Error(`wait_for_ui state=${state} requires a semantic target`);
   const deadline = Date.now() + timeoutMs;
   const startedAt = Date.now();
   let attempts = 0;
@@ -541,24 +567,37 @@ export async function typeText(args = {}) {
   const value = String(args.text ?? '');
   const method = requireEnum(args.method || 'auto', 'method', ['auto','accessibility','clipboard','keys']);
   const resolvedArgs = args.label != null ? withResolvedUiLabel(args) : args;
-  const hasSelector = Boolean(
+  const hasElementSelector = Boolean(
     optionalString(resolvedArgs.id) || optionalString(resolvedArgs.name) || optionalString(resolvedArgs.role) ||
-    optionalString(resolvedArgs.automation_id || resolvedArgs.automationId) || optionalString(resolvedArgs.app) ||
-    optionalString(resolvedArgs.window_title || resolvedArgs.windowTitle) || Number.isInteger(Number(resolvedArgs.pid))
+    optionalString(resolvedArgs.automation_id || resolvedArgs.automationId)
   );
   const clear = args.clear === true;
   const pressEnter = args.press_enter === true;
   const caret = requireEnum(args.caret_position || 'idle', 'caret_position', ['start','idle','end']);
 
-  if ((method === 'auto' || method === 'accessibility') && hasSelector) {
-    const result = await uiAction({ ...resolvedArgs, action:'set_value', value });
-    const raw = result.content?.[0]?.text || '';
-    let target = raw;
-    try { target = JSON.parse(raw); } catch {}
-    if (pressEnter) await keyboard({ ...resolvedArgs, key:'ENTER' });
-    return jsonResult({ length:value.length, method:'accessibility', target, clear:true, press_enter:pressEnter });
+  if ((method === 'auto' || method === 'accessibility') && hasElementSelector) {
+    try {
+      const result = await uiAction({ ...resolvedArgs, action:'set_value', value });
+      const raw = result.content?.[0]?.text || '';
+      let target = raw;
+      try { target = JSON.parse(raw); } catch {}
+      if (pressEnter) await keyboard({ ...resolvedArgs, key:'ENTER' });
+      return jsonResult({ length:value.length, method:'accessibility', target, clear:true, press_enter:pressEnter });
+    } catch (error) {
+      if (method === 'accessibility') throw error;
+      if (!clear && caret === 'idle' && typeof adapter.typeTextFocused === 'function') {
+        await uiAction({ ...resolvedArgs, action:'focus' });
+        const semantic = await adapter.typeTextFocused(value, resolvedArgs);
+        if (semantic) {
+          if (pressEnter) await keyboard({ ...resolvedArgs, key:'ENTER' });
+          return jsonResult({ length:value.length, method:'accessibility', target:semantic, press_enter:pressEnter });
+        }
+      }
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`Semantic text target rejected accessibility input. Refresh the UI target or use browser_action for browser page content. ${detail}`);
+    }
   }
-  if ((method === 'auto' || method === 'accessibility') && typeof adapter.typeTextFocused === 'function' && !clear && caret === 'idle') {
+  if ((method === 'auto' || method === 'accessibility') && !hasElementSelector && typeof adapter.typeTextFocused === 'function' && !clear && caret === 'idle') {
     const semantic = await adapter.typeTextFocused(value, resolvedArgs);
     if (semantic) {
       if (pressEnter) await keyboard({ ...resolvedArgs, key:'ENTER' });
@@ -566,8 +605,11 @@ export async function typeText(args = {}) {
     }
     if (method === 'accessibility') throw new Error('No focused editable accessibility element is available');
   }
+  if (method === 'accessibility') {
+    throw new Error('Accessibility-only text input requires a semantic element target for replacement, or a focused editable control with clear=false and caret_position=idle');
+  }
 
-  if (hasSelector) await uiAction({ ...resolvedArgs, action:'focus' }).catch(() => null);
+  if (hasElementSelector) await uiAction({ ...resolvedArgs, action:'focus' });
   if (clear) {
     await keyboard({ ...resolvedArgs, shortcut:process.platform === 'darwin' ? 'CMD+A' : 'CTRL+A' });
     await keyboard({ ...resolvedArgs, key:'BACKSPACE' });

package/src/extended/documents.mjs

@@ -127,12 +127,29 @@ async function readXlsx(filePath, args) {
   } finally { await removeTemp(dir); }
 }
 
+async function readPdfDocument(filePath, data) {
+  try {
+    return readPdfText(data);
+  } catch (builtinError) {
+    if (commandExists('pdftotext')) {
+      const extracted = await runFile('pdftotext', ['-enc','UTF-8',filePath,'-'], {
+        label:'PDF text extraction',
+        timeout:60_000,
+        allowFailure:true,
+      });
+      const fallbackText = String(extracted.stdout || '').replace(/\f/g, '\n').trim();
+      if (extracted.code === 0 && fallbackText) return fallbackText;
+    }
+    throw builtinError;
+  }
+}
+
 export async function readDocument(args) {
   const filePath = await resolveSafePath(args.path,'path');
   const lower = filePath.toLowerCase();
   const data = await readFile(filePath);
   if (lower.endsWith('.docx')) return text(readDocxText(data));
-  if (lower.endsWith('.pdf')) return text(readPdfText(data));
+  if (lower.endsWith('.pdf')) return text(await readPdfDocument(filePath,data));
   if (lower.endsWith('.xlsx')) return jsonResult(await readXlsx(filePath,args));
   if (/\.(txt|md|csv|json|xml|yaml|yml)$/i.test(lower)) return text(data.toString('utf8'));
   throw new Error('read_document supports PDF, DOCX, XLSX, TXT, Markdown, CSV, JSON, XML, YAML');