yunti-browser-runtime 0.1.3 → 0.2.1

package/extension/tool-handlers.js

@@ -73,12 +73,16 @@ export function createToolDispatcher({
         result = await evaluateScript(tabId, session, event.arguments || {})
       } else if (event.tool === "yunti_take_snapshot") {
         result = await takeSnapshot(tabId, session, event.arguments || {})
+      } else if (event.tool === "yunti_observe_page") {
+        result = await observePage(tabId, session, event.arguments || {})
       } else if (event.tool === "yunti_click") {
         result = await clickByUid(tabId, session, event.arguments || {})
       } else if (event.tool === "yunti_hover") {
         result = await hoverByUid(tabId, session, event.arguments || {})
       } else if (event.tool === "yunti_fill") {
         result = await fillByUid(tabId, session, event.arguments || {})
+      } else if (event.tool === "yunti_select") {
+        result = await selectElement(tabId, session, event.arguments || {})
       } else if (event.tool === "yunti_fill_form") {
         result = await fillForm(tabId, session, event.arguments || {})
       } else if (event.tool === "yunti_wait_for") {
@@ -105,6 +109,8 @@ export function createToolDispatcher({
         result = await typeTextByUid(tabId, session, event.arguments || {})
       } else if (event.tool === "yunti_press_key") {
         result = await pressKeyByUid(tabId, session, event.arguments || {})
+      } else if (event.tool === "yunti_scroll") {
+        result = await scrollPage(tabId, session, event.arguments || {})
       } else {
         result = await chrome.tabs.sendMessage(tabId, {
           type: "yunti_execute_tool",
@@ -343,8 +349,8 @@ export function createToolDispatcher({
     }
   }
   
-  // Snapshot state — maps uid to element info for click/fill/hover
-  const snapshotStore = new Map()
+  // Latest page uid state from yunti_observe_page or yunti_take_snapshot.
+  const pageUidStore = new Map()
   
   async function takeSnapshot(tabId, session, args = {}) {
     const maxElements = Number.isFinite(Number(args.maxElements))
@@ -367,12 +373,7 @@ export function createToolDispatcher({
       elements = await domFallbackSnapshot(tabId, maxElements)
     }
   
-    // Build uid mapping
-    const uidMap = {}
-    for (const el of elements) {
-      uidMap[el.uid] = { ...el }
-    }
-    snapshotStore.set(session.browserSessionId, uidMap)
+    storePageUidMap(session, "snapshot", elements)
   
     return {
       browserSessionId: session.browserSessionId,
@@ -383,6 +384,38 @@ export function createToolDispatcher({
       snapshotId: `snap-${Date.now()}`,
     }
   }
+
+  async function observePage(tabId, session, args = {}) {
+    const observation = await chrome.tabs.sendMessage(tabId, {
+      type: "yunti_execute_tool",
+      tool: "yunti_observe_page",
+      arguments: args,
+    })
+    if (Array.isArray(observation?.elements)) {
+      storePageUidMap(session, "observe", [
+        ...observation.elements,
+        ...(Array.isArray(observation.scrollableContainers) ? observation.scrollableContainers : []),
+      ], {
+        observationId: observation.observationId,
+        uidMapVersion: observation.uidMapVersion,
+      })
+    }
+    return observation
+  }
+
+  function storePageUidMap(session, source, elements, meta = {}) {
+    const uidMap = {}
+    for (const el of elements || []) {
+      if (!el?.uid) continue
+      uidMap[el.uid] = { ...el, source }
+    }
+    pageUidStore.set(session.browserSessionId, {
+      source,
+      uidMap,
+      storedAt: Date.now(),
+      ...meta,
+    })
+  }
   
   function flattenAXTree(nodes, maxElements, includeHidden) {
     const elements = []
@@ -501,7 +534,30 @@ export function createToolDispatcher({
   async function clickByUid(tabId, session, args = {}) {
     const uid = String(args.uid || "").trim()
     if (uid) {
-      return clickViaSnapshotUid(tabId, session, uid)
+      const point = resolveObservedUidCenter(session, uid)
+      if (!point.ok) return buildUidPointFailureResult(session, uid, "click", point.error)
+      const result = await chrome.tabs.sendMessage(tabId, {
+        type: "yunti_execute_tool",
+        tool: "yunti_click",
+        arguments: { ...args, x: point.x, y: point.y },
+      })
+      if (!result || typeof result !== "object" || result.clicked !== true) {
+        return buildUidPointFailureResult(session, uid, "click", result?.error || "Uid click failed")
+      }
+      const roundedX = Math.round(point.x)
+      const roundedY = Math.round(point.y)
+      return {
+        ...result,
+        uid,
+        x: roundedX,
+        y: roundedY,
+        browserSessionId: session.browserSessionId,
+        action: "click",
+        target: { uid, x: roundedX, y: roundedY },
+        ok: true,
+        recoverable: false,
+        nextStepHint: "Click dispatched without attaching Chrome debugger. Observe again or read page state to verify the intended change.",
+      }
     }
     const x = Number(args.x)
     const y = Number(args.y)
@@ -509,23 +565,80 @@ export function createToolDispatcher({
       if (!Number.isFinite(x) || !Number.isFinite(y)) {
         throw new Error("yunti_click coordinate mode requires both x and y. Use yunti_click_at with x/y, or call yunti_take_snapshot and pass uid.")
       }
-      return clickAtCoordinate(tabId, session, x, y)
+      const result = await chrome.tabs.sendMessage(tabId, {
+        type: "yunti_execute_tool",
+        tool: "yunti_click",
+        arguments: { ...args, x, y },
+      })
+      if (!result || typeof result !== "object" || result.clicked !== true) return result
+      const roundedX = Math.round(x)
+      const roundedY = Math.round(y)
+      return {
+        ...result,
+        x: roundedX,
+        y: roundedY,
+        browserSessionId: session.browserSessionId,
+        method: "coordinate",
+        action: "click",
+        target: { method: "coordinate", x: roundedX, y: roundedY },
+        ok: true,
+        recoverable: false,
+        nextStepHint: "Coordinate click dispatched without attaching Chrome debugger. Observe again, read page state, or use a fresh uid when possible to verify the intended change.",
+      }
     }
-    if (!String(args.selector || "").trim()) {
+    const selector = String(args.selector || "").trim()
+    if (!selector) {
       throw new Error("yunti_click requires uid, selector, or both x and y. Call yunti_take_snapshot to get uid, pass a CSS selector, or use yunti_click_at for coordinate-only clicks.")
     }
     // Fall back to content script for selector-based click
-    return chrome.tabs.sendMessage(tabId, {
+    const contentResult = await chrome.tabs.sendMessage(tabId, {
       type: "yunti_execute_tool",
       tool: "yunti_click",
       arguments: args,
     })
+    if (contentResult && typeof contentResult === "object" && contentResult.clicked === true) {
+      return {
+        ...contentResult,
+        selector,
+        browserSessionId: session.browserSessionId,
+        method: "selector",
+        action: "click",
+        target: { selector, method: "selector" },
+        ok: true,
+        recoverable: false,
+        nextStepHint: "Selector click dispatched. Observe again, read page state, or use a fresh uid when possible to verify the intended change.",
+      }
+    }
+    return contentResult
   }
   
   async function hoverByUid(tabId, session, args = {}) {
     const uid = String(args.uid || "").trim()
     if (uid) {
-      return hoverViaSnapshotUid(tabId, session, uid)
+      const point = resolveObservedUidCenter(session, uid)
+      if (!point.ok) return buildUidPointFailureResult(session, uid, "hover", point.error)
+      const result = await chrome.tabs.sendMessage(tabId, {
+        type: "yunti_execute_tool",
+        tool: "yunti_hover",
+        arguments: { ...args, x: point.x, y: point.y },
+      })
+      if (!result || typeof result !== "object" || result.hovered !== true) {
+        return buildUidPointFailureResult(session, uid, "hover", result?.error || "Uid hover failed")
+      }
+      const roundedX = Math.round(point.x)
+      const roundedY = Math.round(point.y)
+      return {
+        ...result,
+        uid,
+        x: roundedX,
+        y: roundedY,
+        browserSessionId: session.browserSessionId,
+        action: "hover",
+        target: { uid, x: roundedX, y: roundedY },
+        ok: true,
+        recoverable: false,
+        nextStepHint: "Hover dispatched without attaching Chrome debugger. Observe again or read page state to verify menus, tooltips, or hover-only controls.",
+      }
     }
     const x = Number(args.x)
     const y = Number(args.y)
@@ -533,22 +646,49 @@ export function createToolDispatcher({
       if (!Number.isFinite(x) || !Number.isFinite(y)) {
         throw new Error("yunti_hover coordinate mode requires both x and y. Call yunti_take_snapshot to get uid, pass selector, or provide both coordinates.")
       }
-      await mouseMove(tabId, x, y)
-      return { hovered: true, x: Math.round(x), y: Math.round(y), browserSessionId: session.browserSessionId, method: "coordinate" }
+      const result = await chrome.tabs.sendMessage(tabId, {
+        type: "yunti_execute_tool",
+        tool: "yunti_hover",
+        arguments: { ...args, x, y },
+      })
+      if (!result || typeof result !== "object" || result.hovered !== true) return result
+      const roundedX = Math.round(x)
+      const roundedY = Math.round(y)
+      return {
+        ...result,
+        hovered: true,
+        x: roundedX,
+        y: roundedY,
+        browserSessionId: session.browserSessionId,
+        method: "coordinate",
+        action: "hover",
+        target: { method: "coordinate", x: roundedX, y: roundedY },
+        ok: true,
+        recoverable: false,
+        nextStepHint: "Coordinate hover dispatched without attaching Chrome debugger. Observe again, read page state, or use a fresh uid when possible to verify menus, tooltips, or hover-only controls.",
+      }
     }
     const selector = String(args.selector || "").trim()
     if (!selector) {
       throw new Error("yunti_hover requires uid, selector, or both x and y. Call yunti_take_snapshot to get uid or pass a CSS selector.")
     }
-    const point = await resolveSelectorCenter(tabId, selector)
-    await mouseMove(tabId, point.x, point.y)
+    const result = await chrome.tabs.sendMessage(tabId, {
+      type: "yunti_execute_tool",
+      tool: "yunti_hover",
+      arguments: args,
+    })
+    if (!result || typeof result !== "object" || result.hovered !== true) return result
     return {
+      ...result,
       hovered: true,
       selector,
-      x: Math.round(point.x),
-      y: Math.round(point.y),
       browserSessionId: session.browserSessionId,
       method: "selector",
+      action: "hover",
+      target: { selector, method: "selector" },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Selector hover dispatched without attaching Chrome debugger. Observe again, read page state, or use a fresh uid when possible to verify menus, tooltips, or hover-only controls.",
     }
   }
   
@@ -557,76 +697,623 @@ export function createToolDispatcher({
     const uid = String(args.uid || "").trim()
     const value = String(args.value)
     if (uid) {
-      const { x, y } = await resolveUidCenter(tabId, session, uid)
-      await mouseClick(tabId, x, y, 1)
-      await delayCdp(100)
-      // Clear existing value
-      const elements = await chromeDebuggerSendCommand(
-        { tabId },
-        "Runtime.evaluate",
-        { expression: `(() => {
-          const el = document.elementFromPoint(${x}, ${y});
-          if (!el) return 'not found';
-          const tag = el.tagName.toLowerCase();
-          if (tag === 'select') {
-            const opts = Array.from(el.options);
-            return { tag: 'select', options: opts.map(o => ({ value: o.value, text: o.text.slice(0, 80) })), selectedIndex: el.selectedIndex };
-          }
-          if (el.isContentEditable) {
-            el.textContent = '';
-          } else if (tag === 'input' || tag === 'textarea') {
-            el.focus();
-            el.select();
-          }
-          return { tag, type: el.type, contentEditable: el.isContentEditable };
-        })()`,
-          returnByValue: true,
+      try {
+        const point = resolveObservedUidCenter(session, uid)
+        if (!point.ok) {
+          return buildUidFillFailureResult(session, uid, {
+            code: "UID_COORDINATES_UNAVAILABLE",
+            error: point.error,
+          })
         }
-      )
-      const elInfo = elements?.result?.value
-  
-      if (elInfo === "not found") throw new Error(`No element found at uid ${uid} coordinates`)
-  
-      // Handle select element
-      if (elInfo?.tag === "select") {
-        const targetOption = elInfo.options?.find(
-          o => o.value === value || o.text === value
-        )
-        if (targetOption) {
-          await chromeDebuggerSendCommand(
-            { tabId },
-            "Runtime.evaluate",
-            {
-              expression: `(() => {
-                const el = document.elementFromPoint(${x}, ${y});
-                if (el) el.value = ${JSON.stringify(targetOption.value)};
-                el.dispatchEvent(new Event('change', { bubbles: true }));
-                el.dispatchEvent(new Event('input', { bubbles: true }));
-              })()`,
-            }
-          )
-          return { filled: true, uid, method: "select", value: targetOption.value, browserSessionId: session.browserSessionId }
+        const result = await chrome.tabs.sendMessage(tabId, {
+          type: "yunti_execute_tool",
+          tool: "yunti_fill",
+          arguments: { ...args, x: point.x, y: point.y },
+        })
+        if (!result || typeof result !== "object" || result.filled !== true) {
+          return buildUidFillFailureResult(session, uid, result)
         }
-        throw new Error(`Option '${value}' not found in select at uid ${uid}. Use yunti_take_snapshot to inspect the select element or pass an available option value/text.`)
-      }
+        const method = result.method || "dom"
+        if (result.valueApplied === false) {
+          return buildUidFillFailureResult(session, uid, {
+            ...result,
+            code: "VALUE_NOT_APPLIED",
+            error: `Filled value did not remain on uid ${uid}`,
+            method,
+            expectedValueLength: value.length,
+          })
+        }
+        return {
+          ...result,
+          filled: true,
+          uid,
+          method,
+          value,
+          browserSessionId: session.browserSessionId,
+          action: "fill",
+          target: { uid, method },
+          ok: true,
+          recoverable: false,
+          nextStepHint: method === "contenteditable"
+            ? "Contenteditable fill dispatched. Observe again, read page text, or evaluate textContent to verify the intended change."
+            : "Fill dispatched without attaching Chrome debugger. Observe again, read page state, or evaluate the field value to verify the intended change.",
+        }
+    } catch (error) {
+      return buildUidFillFailureResult(session, uid, {
+        error: error?.message || "Uid fill failed",
+      })
+    }
+    }
   
-      // Type text via CDP Input.dispatchKeyEvent
-      const text = value
-      for (const char of text) {
-        await chromeDebuggerSendCommand(
-          { tabId },
-          "Input.dispatchKeyEvent",
-          { type: "char", text: char, unmodifiedText: char }
-        )
+    const selector = String(args.selector || "").trim()
+    let result
+    try {
+      result = await chrome.tabs.sendMessage(tabId, {
+        type: "yunti_execute_tool",
+        tool: "yunti_fill",
+        arguments: args,
+      })
+    } catch (error) {
+      return buildSelectorFillFailureResult(session, selector, {
+        error: error?.message || "Selector fill failed",
+      })
+    }
+
+    if (!result || typeof result !== "object" || result.filled !== true) {
+      return buildSelectorFillFailureResult(session, selector, result)
+    }
+
+    return {
+      ...result,
+      selector,
+      method: result.method || "selector",
+      browserSessionId: session.browserSessionId,
+      action: "fill",
+      target: { selector, method: "selector" },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Selector fill dispatched. Observe again, read page state, or evaluate the field value to verify the intended change.",
+    }
+  }
+
+  function buildSelectorFillFailureResult(session, selector, fillResult = {}) {
+    const error = fillResult?.error || "Selector fill failed"
+    const code = fillResult?.code || inferFillFailureCode(error, "SELECTOR_FILL_FAILED")
+    const recoveryHint = {
+      reason: "selector-fill-failed",
+      recommendedTools: ["yunti_observe_page", "yunti_take_snapshot", "yunti_evaluate_script", "yunti_fill"],
+      nextAction: code === "ELEMENT_NOT_FOUND" ? "observe-again" : "inspect-target-element",
+      decision: code === "ELEMENT_NOT_FOUND" ? "refresh-observation-or-selector-before-retry" : "inspect-editability-before-retry",
+      selector,
+      message: "The selector fill could not be completed. Inspect whether the selector still matches an editable element, observe again for a fresh uid, or evaluate the field before retrying.",
+    }
+
+    return {
+      ...(fillResult && typeof fillResult === "object" ? fillResult : {}),
+      filled: false,
+      selector,
+      browserSessionId: session.browserSessionId,
+      action: "fill",
+      target: { selector, method: "selector" },
+      ok: false,
+      recoverable: true,
+      code,
+      error,
+      recoveryHint,
+      nextStepHint: "Selector fill failed. Observe again for a fresh uid, inspect whether the target is editable, or retry with a stable selector before repeating the same fill.",
+    }
+  }
+
+  function buildUidFillFailureResult(session, uid, fillResult = {}) {
+    const availableValues = Array.isArray(fillResult?.availableValues) ? fillResult.availableValues : undefined
+    const availableTexts = Array.isArray(fillResult?.availableTexts) ? fillResult.availableTexts : undefined
+    const error = fillResult?.error || `Cannot fill uid ${uid}`
+    const code = fillResult?.code || inferFillFailureCode(error, "UID_FILL_FAILED")
+    const recoveryHint = {
+      reason: "uid-fill-failed",
+      recommendedTools: ["yunti_observe_page", "yunti_take_snapshot", "yunti_evaluate_script", "yunti_fill"],
+      nextAction: "inspect-target-element",
+      decision: "inspect-editability-before-retry",
+      uid,
+      ...(availableValues ? { availableValues } : {}),
+      ...(availableTexts ? { availableTexts } : {}),
+      message: "The uid fill could not be completed. Refresh observation if the uid may be stale, inspect whether the target is editable, or retry with selector fallback.",
+    }
+
+    if (code === "ELEMENT_NOT_FOUND") {
+      recoveryHint.nextAction = "observe-again"
+      recoveryHint.decision = "refresh-observation-before-retry"
+    } else if (code === "OPTION_NOT_FOUND") {
+      recoveryHint.nextAction = "inspect-available-options"
+      recoveryHint.decision = "inspect-options-before-retry"
+    } else if (code === "VALUE_NOT_APPLIED") {
+      recoveryHint.nextAction = "verify-field-state"
+      recoveryHint.decision = "inspect-controlled-or-masked-field-before-retry"
+      recoveryHint.message = "The fill dispatched, but the field value did not remain afterward. Inspect whether the target is framework-controlled, masked, or requires typing/press_key semantics before retrying."
+    }
+
+    return {
+      ...(fillResult && typeof fillResult === "object" ? fillResult : {}),
+      filled: false,
+      uid,
+      browserSessionId: session.browserSessionId,
+      action: "fill",
+      target: { uid, method: "uid" },
+      ok: false,
+      recoverable: true,
+      code,
+      error,
+      ...(availableValues ? { availableValues } : {}),
+      ...(availableTexts ? { availableTexts } : {}),
+      recoveryHint,
+      nextStepHint: "Uid fill failed. Observe again for a fresh uid, inspect whether the target is editable or a select with available options, or retry with selector fallback before repeating the same fill.",
+    }
+  }
+
+  function inferFillFailureCode(error, fallbackCode) {
+    const message = String(error || "").toLowerCase()
+    if (message.includes("not found") || message.includes("cannot resolve coordinates")) return "ELEMENT_NOT_FOUND"
+    if (message.includes("did not remain") || message.includes("did not stick") || message.includes("not applied")) return "VALUE_NOT_APPLIED"
+    if (
+      message.includes("not editable") ||
+      message.includes("no editable target") ||
+      message.includes("cannot accept text") ||
+      message.includes("disabled") ||
+      message.includes("read only") ||
+      message.includes("readonly") ||
+      message.includes("hidden") ||
+      message.includes("no size")
+    ) return "TARGET_NOT_EDITABLE"
+    return fallbackCode
+  }
+
+  function buildFillEditabilityError(uid, elInfo = {}) {
+    const tag = elInfo?.tag || "unknown"
+    const type = elInfo?.type ? ` type=${elInfo.type}` : ""
+    const reasons = []
+    if (elInfo?.hidden) reasons.push("hidden or has no size")
+    if (elInfo?.disabled) reasons.push("disabled")
+    if (elInfo?.readOnly) reasons.push("readonly")
+    if (elInfo?.editable === false) reasons.push("not editable")
+    const reason = reasons.length ? reasons.join(", ") : "not editable"
+    return `Target at uid ${uid} is not editable (${tag}${type}: ${reason})`
+  }
+
+  function summarizeFillTarget(elInfo = {}) {
+    return {
+      tag: elInfo?.tag,
+      ...(elInfo?.type ? { type: elInfo.type } : {}),
+      ...(elInfo?.contentEditable !== undefined ? { contentEditable: Boolean(elInfo.contentEditable) } : {}),
+      ...(elInfo?.disabled !== undefined ? { disabled: Boolean(elInfo.disabled) } : {}),
+      ...(elInfo?.readOnly !== undefined ? { readOnly: Boolean(elInfo.readOnly) } : {}),
+      ...(elInfo?.hidden !== undefined ? { hidden: Boolean(elInfo.hidden) } : {}),
+      ...(elInfo?.editable !== undefined ? { editable: Boolean(elInfo.editable) } : {}),
+    }
+  }
+
+  async function scrollPage(tabId, session, args = {}) {
+    const uid = String(args.uid || "").trim()
+    let scrollArgs = args
+    if (uid) {
+      let point
+      try {
+        point = await resolveUidCenter(tabId, session, uid)
+      } catch (error) {
+        return buildUidScrollFailureResult(session, uid, {
+          error: error?.message || "Uid scroll failed",
+        })
       }
-      return { filled: true, uid, method: "keyboard", value: text, browserSessionId: session.browserSessionId }
+      const { x, y } = point
+      scrollArgs = { ...args, x, y }
     }
-  
-    return chrome.tabs.sendMessage(tabId, {
+    const result = await chrome.tabs.sendMessage(tabId, {
       type: "yunti_execute_tool",
-      tool: "yunti_fill",
-      arguments: args,
+      tool: "yunti_scroll",
+      arguments: scrollArgs,
     })
+
+    if (!result || typeof result !== "object" || result.scrolled !== true) {
+      return result
+    }
+
+    const hasComparableScrollPosition =
+      Number.isFinite(Number(result.before?.left)) &&
+      Number.isFinite(Number(result.before?.top)) &&
+      Number.isFinite(Number(result.after?.left)) &&
+      Number.isFinite(Number(result.after?.top))
+    const moved = hasComparableScrollPosition
+      ? Number(result.before.left) !== Number(result.after.left) ||
+        Number(result.before.top) !== Number(result.after.top)
+      : undefined
+    const noMovement = moved === false
+    const edgeHint = noMovement ? inferScrollEdgeHint(result.deltaX, result.deltaY) : undefined
+    const recoveryHint = noMovement ? buildScrollRecoveryHint(session, uid, edgeHint, result) : undefined
+    const partialMovement = moved === true ? buildScrollPartialMovementHint(result, scrollArgs) : undefined
+    const coordinateFallbackHint = !uid ? buildCoordinateScrollFallbackHint(result) : undefined
+
+    return {
+      ...result,
+      browserSessionId: session.browserSessionId,
+      action: "scroll",
+      ...(uid ? { uid, method: "uid" } : {}),
+      ...(uid ? { scrollTarget: { uid, method: "uid" } } : {}),
+      ...(moved !== undefined ? { moved } : {}),
+      ...(noMovement ? { code: "NO_SCROLL_MOVEMENT" } : {}),
+      ...(edgeHint ? { edgeHint } : {}),
+      ...(recoveryHint ? { recoveryHint } : {}),
+      ...(partialMovement ? { partialMovement } : {}),
+      ...(coordinateFallbackHint ? { coordinateFallbackHint } : {}),
+      ok: !noMovement,
+      recoverable: noMovement,
+      nextStepHint: noMovement
+        ? `Scroll dispatched but before/after positions did not change${edgeHint ? ` (${edgeHint})` : ""}. Observe again, inspect scroll boundaries, try the nearest scrollable container uid, or stop repeating the same scroll.`
+        : partialMovement
+          ? `Scroll moved partially${partialMovement.edgeHint ? ` (${partialMovement.edgeHint})` : ""}. Observe again and compare scroll positions before repeating the same scroll.`
+        : coordinateFallbackHint
+          ? "Coordinate scroll fell back to document scrolling. Observe again, inspect scrollableContainers[], and prefer a fresh scrollable container uid if a nested panel was intended."
+        : uid
+          ? "Uid-targeted scroll dispatched. Observe again or read page state to verify the intended container position."
+          : "Scroll dispatched. Observe again or read page state to verify the intended viewport or container position.",
+    }
+  }
+
+  function buildCoordinateScrollFallbackHint(result = {}) {
+    if (result.coordinateScrollFallback !== "document") return undefined
+    return {
+      reason: "coordinate-scroll-document-fallback",
+      nextAction: "observe-for-scrollable-container",
+      decision: "prefer-fresh-scrollable-container-uid",
+      recommendedTools: ["yunti_observe_page", "yunti_scroll"],
+      ...(result.coordinateTarget ? { coordinateTarget: result.coordinateTarget } : {}),
+      message: "The coordinate scroll did not find a nested scrollable container and fell back to document scrolling. Observe again and choose a fresh scrollableContainers[] uid when a panel or sidebar was intended.",
+    }
+  }
+
+  function buildUidScrollFailureResult(session, uid, scrollResult = {}) {
+    const error = scrollResult?.error || `Cannot scroll uid ${uid}`
+    const code = scrollResult?.code || inferScrollFailureCode(error)
+    const recoveryHint = {
+      reason: "uid-scroll-failed",
+      recommendedTools: ["yunti_observe_page", "yunti_take_snapshot", "yunti_scroll"],
+      nextAction: "observe-again",
+      decision: "refresh-scrollable-container-uid-before-retry",
+      uid,
+      message: "The uid scroll could not resolve a current target. Refresh observation, choose a fresh scrollable container uid from scrollableContainers[], or use document/coordinate scroll fallback before retrying.",
+    }
+
+    return {
+      ...(scrollResult && typeof scrollResult === "object" ? scrollResult : {}),
+      scrolled: false,
+      uid,
+      browserSessionId: session.browserSessionId,
+      action: "scroll",
+      target: { uid, method: "uid" },
+      ok: false,
+      recoverable: true,
+      code,
+      error,
+      recoveryHint,
+      nextStepHint: "Uid scroll failed. Observe again for a fresh scrollable container uid, inspect scrollableContainers[], or retry with document/coordinate fallback before repeating the same uid scroll.",
+    }
+  }
+
+  function inferScrollFailureCode(error) {
+    const message = String(error || "").toLowerCase()
+    if (message.includes("not found") || message.includes("uid") && message.includes("latest page uid map")) {
+      return "UID_NOT_FOUND"
+    }
+    if (message.includes("cannot resolve coordinates") || message.includes("off-screen") || message.includes("hidden") || message.includes("stale")) {
+      return "UID_COORDINATES_UNAVAILABLE"
+    }
+    return "UID_SCROLL_FAILED"
+  }
+
+  function inferScrollEdgeHint(deltaX, deltaY) {
+    const x = Number(deltaX)
+    const y = Number(deltaY)
+    if (Number.isFinite(y) && y > 0) return "possible-bottom-edge"
+    if (Number.isFinite(y) && y < 0) return "possible-top-edge"
+    if (Number.isFinite(x) && x > 0) return "possible-right-edge"
+    if (Number.isFinite(x) && x < 0) return "possible-left-edge"
+    return "no-delta"
+  }
+
+  function buildScrollPartialMovementHint(result = {}, args = {}) {
+    const beforeLeft = Number(result.before?.left)
+    const beforeTop = Number(result.before?.top)
+    const afterLeft = Number(result.after?.left)
+    const afterTop = Number(result.after?.top)
+    if (
+      !Number.isFinite(beforeLeft) ||
+      !Number.isFinite(beforeTop) ||
+      !Number.isFinite(afterLeft) ||
+      !Number.isFinite(afterTop)
+    ) return undefined
+
+    const requestedDeltaX = Number(result.deltaX ?? args.deltaX ?? 0)
+    const requestedDeltaY = Number(result.deltaY ?? args.deltaY ?? 0)
+    const actualDeltaX = afterLeft - beforeLeft
+    const actualDeltaY = afterTop - beforeTop
+    const axes = []
+    if (isPartialScrollMovement(requestedDeltaX, actualDeltaX)) axes.push("horizontal")
+    if (isPartialScrollMovement(requestedDeltaY, actualDeltaY)) axes.push("vertical")
+    if (!axes.length) return undefined
+
+    return {
+      reason: "partial-scroll-movement",
+      axes,
+      requestedDeltaX,
+      requestedDeltaY,
+      actualDeltaX,
+      actualDeltaY,
+      edgeHint: inferScrollEdgeHint(requestedDeltaX, requestedDeltaY),
+      nextAction: "observe-again",
+      decision: "observe-before-continuing-scroll",
+      message: "The scroll position changed, but less than the requested delta. Observe again before repeating the same scroll to verify whether the target container hit an edge or a different container should be used.",
+    }
+  }
+
+  function isPartialScrollMovement(requestedDelta, actualDelta) {
+    if (!Number.isFinite(requestedDelta) || !Number.isFinite(actualDelta)) return false
+    if (requestedDelta === 0 || actualDelta === 0) return false
+    if (Math.sign(requestedDelta) !== Math.sign(actualDelta)) return false
+    return Math.abs(actualDelta) < Math.abs(requestedDelta)
+  }
+
+  function buildScrollRecoveryHint(session, uid, edgeHint, result = {}) {
+    const hint = {
+      reason: "no-scroll-movement",
+      recommendedTools: ["yunti_observe_page", "yunti_scroll"],
+      nextAction: "observe-again",
+    }
+    if (edgeHint) hint.edgeHint = edgeHint
+    if (uid) {
+      hint.uid = uid
+      hint.currentTarget = "scrollable-container"
+      const target = pageUidStore.get(session.browserSessionId)?.uidMap?.[uid]
+      if (target) {
+        hint.lastObservedContainer = {
+          uid,
+          canScrollVertical: Boolean(target.canScrollVertical),
+          canScrollHorizontal: Boolean(target.canScrollHorizontal),
+          ...(Number.isFinite(Number(target.pixelsAbove)) ? { pixelsAbove: Number(target.pixelsAbove) } : {}),
+          ...(Number.isFinite(Number(target.pixelsBelow)) ? { pixelsBelow: Number(target.pixelsBelow) } : {}),
+          ...(Number.isFinite(Number(target.pixelsLeft)) ? { pixelsLeft: Number(target.pixelsLeft) } : {}),
+          ...(Number.isFinite(Number(target.pixelsRight)) ? { pixelsRight: Number(target.pixelsRight) } : {}),
+        }
+      }
+    } else {
+      hint.currentTarget = "document-or-coordinate-container"
+    }
+    if (edgeHint === "possible-bottom-edge" || edgeHint === "possible-top-edge") {
+      hint.nextAction = uid ? "try-opposite-direction-or-nearest-container" : "observe-for-scrollable-container"
+    } else if (edgeHint === "possible-right-edge" || edgeHint === "possible-left-edge") {
+      hint.nextAction = uid ? "try-opposite-horizontal-direction-or-nearest-container" : "observe-for-horizontal-container"
+    } else if (edgeHint === "no-delta") {
+      hint.nextAction = "provide-nonzero-scroll-delta"
+    }
+    const decision = buildScrollRecoveryDecision(uid, edgeHint)
+    if (decision) hint.decision = decision
+    const suggestedRetry = buildScrollSuggestedRetry(uid, edgeHint, result)
+    if (suggestedRetry) hint.suggestedRetry = suggestedRetry
+    hint.message = "The scroll command dispatched, but the scroll position did not change. Refresh observation before retrying, inspect scroll boundaries, or target a different scrollable container uid."
+    return hint
+  }
+
+  function buildScrollRecoveryDecision(uid, edgeHint) {
+    if (edgeHint === "no-delta") return "provide-nonzero-delta"
+    if (edgeHint === "possible-bottom-edge" || edgeHint === "possible-top-edge") {
+      return uid ? "retry-opposite-vertical-on-same-container-once" : "observe-for-scrollable-container"
+    }
+    if (edgeHint === "possible-right-edge" || edgeHint === "possible-left-edge") {
+      return uid ? "retry-opposite-horizontal-on-same-container-once" : "observe-for-horizontal-scrollable-container"
+    }
+    return undefined
+  }
+
+  function buildScrollSuggestedRetry(uid, edgeHint, result = {}) {
+    const retry = {}
+    const deltaX = Number(result.deltaX)
+    const deltaY = Number(result.deltaY)
+    if (edgeHint === "possible-bottom-edge" || edgeHint === "possible-top-edge") {
+      if (!Number.isFinite(deltaY) || deltaY === 0) return undefined
+      retry.deltaY = -deltaY
+    } else if (edgeHint === "possible-right-edge" || edgeHint === "possible-left-edge") {
+      if (!Number.isFinite(deltaX) || deltaX === 0) return undefined
+      retry.deltaX = -deltaX
+    } else {
+      return undefined
+    }
+    if (uid) retry.uid = uid
+    retry.note = uid
+      ? "Try the opposite direction once on the same observed container, then observe again or switch to a nearer scrollable container if it still does not move."
+      : "Observe first for a scrollable container uid; only use this opposite delta if document scrolling is still the intended target."
+    return retry
+  }
+
+  async function selectElement(tabId, session, args = {}) {
+    const uid = String(args.uid || "").trim()
+    const value = String(args.value ?? "")
+    const text = String(args.text ?? "")
+    if (uid) {
+      const matchMode = text ? "text" : "value"
+      const targetOption = text || value
+      const point = resolveObservedUidCenter(session, uid)
+      if (!point.ok) {
+        return buildUidSelectFailureResult(session, uid, matchMode, targetOption, {
+          code: "UID_COORDINATES_UNAVAILABLE",
+          error: point.error,
+        })
+      }
+      const selectResult = await chrome.tabs.sendMessage(tabId, {
+        type: "yunti_execute_tool",
+        tool: "yunti_select",
+        arguments: { ...args, x: point.x, y: point.y },
+      })
+      if (!selectResult?.selected) {
+        return buildUidSelectFailureResult(session, uid, matchMode, targetOption, selectResult)
+      }
+      return {
+        ...selectResult,
+        selected: true,
+        uid,
+        value: selectResult.value,
+        text: selectResult.text,
+        selectedIndex: selectResult.selectedIndex,
+        browserSessionId: session.browserSessionId,
+        action: "select",
+        target: { uid, method: matchMode === "text" ? "uid.text" : "uid.value" },
+        ok: true,
+        recoverable: false,
+        nextStepHint: matchMode === "text"
+          ? "Uid select dispatched by visible option text without attaching Chrome debugger. Observe again, read page state, or evaluate the select value to verify the intended change."
+          : "Uid select dispatched by option value without attaching Chrome debugger. Observe again, read page state, or evaluate the select value to verify the intended change.",
+      }
+    }
+
+    const selector = String(args.selector || "").trim()
+    let result
+    try {
+      result = await chrome.tabs.sendMessage(tabId, {
+        type: "yunti_execute_tool",
+        tool: "yunti_select",
+        arguments: args,
+      })
+    } catch (error) {
+      return buildSelectorSelectFailureResult(session, selector, args.value, {
+        code: "SELECTOR_SELECT_FAILED",
+        error: error?.message || "Selector select failed",
+      })
+    }
+
+    if (!result || typeof result !== "object" || result.selected !== true) {
+      return buildSelectorSelectFailureResult(session, selector, args.value, result)
+    }
+
+    const requestedValue = String(args.value ?? "")
+    const disabledOption = Array.isArray(result.options)
+      ? result.options.find((option) => String(option?.value ?? "") === requestedValue && option.disabled === true)
+      : undefined
+    if (requestedValue && disabledOption) {
+      return buildSelectorSelectFailureResult(session, selector, requestedValue, {
+        ...result,
+        selected: false,
+        code: "OPTION_DISABLED",
+        error: "Option value is disabled",
+        disabledValue: String(disabledOption.value ?? ""),
+        disabledText: String(disabledOption.text ?? ""),
+      })
+    }
+    if (requestedValue && String(result.value ?? "") !== requestedValue) {
+      return buildSelectorSelectFailureResult(session, selector, requestedValue, {
+        ...result,
+        code: "OPTION_NOT_FOUND",
+        error: "Option value not found",
+        actualValue: result.value,
+      })
+    }
+
+    return {
+      ...result,
+      selector,
+      browserSessionId: session.browserSessionId,
+      action: "select",
+      target: { selector, method: "selector" },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Select dispatched. Observe again, read page state, or evaluate the select value to verify the intended change.",
+    }
+  }
+
+  function buildSelectorSelectFailureResult(session, selector, targetOption, selectResult = {}) {
+    const availableValues = Array.isArray(selectResult?.availableValues) ? selectResult.availableValues : undefined
+    const availableTexts = Array.isArray(selectResult?.availableTexts) ? selectResult.availableTexts : undefined
+    const disabledValue = selectResult?.disabledValue !== undefined ? String(selectResult.disabledValue) : undefined
+    const disabledText = selectResult?.disabledText !== undefined ? String(selectResult.disabledText) : undefined
+    const code = selectResult?.code || (selectResult?.selected === false ? "SELECTOR_SELECT_FAILED" : "SELECTOR_SELECT_FAILED")
+    const error = selectResult?.error || "Selector select failed"
+    const recoveryHint = {
+      reason: "selector-select-failed",
+      recommendedTools: ["yunti_observe_page", "yunti_take_snapshot", "yunti_evaluate_script", "yunti_select"],
+      nextAction: code === "OPTION_NOT_FOUND" || code === "OPTION_DISABLED" ? "inspect-available-options" : "inspect-target-element",
+      decision: code === "OPTION_DISABLED" ? "choose-enabled-option-or-unlock-field" : code === "OPTION_NOT_FOUND" ? "inspect-options-before-retry" : "use-select-element-or-uid-fallback",
+      selector,
+      matchMode: "value",
+      targetOption: String(targetOption ?? ""),
+      ...(availableValues ? { availableValues } : {}),
+      ...(availableTexts ? { availableTexts } : {}),
+      ...(disabledValue ? { disabledValue } : {}),
+      ...(disabledText ? { disabledText } : {}),
+      message: "The selector select could not be completed. Inspect the target select element and available options before retrying, or use a fresh uid/value fallback.",
+    }
+
+    return {
+      ...(selectResult && typeof selectResult === "object" ? selectResult : {}),
+      selected: false,
+      selector,
+      browserSessionId: session.browserSessionId,
+      action: "select",
+      target: { selector, method: "selector" },
+      ok: false,
+      recoverable: true,
+      code,
+      error,
+      matchMode: "value",
+      targetOption: String(targetOption ?? ""),
+      ...(availableValues ? { availableValues } : {}),
+      ...(availableTexts ? { availableTexts } : {}),
+      recoveryHint,
+      nextStepHint: "Selector select failed. Inspect available options, observe again for a fresh uid, or retry with uid/value fallback before repeating the same selector select.",
+    }
+  }
+
+  function buildUidSelectFailureResult(session, uid, matchMode, targetOption, selectResult = {}) {
+    const availableValues = Array.isArray(selectResult.availableValues) ? selectResult.availableValues : undefined
+    const availableTexts = Array.isArray(selectResult.availableTexts) ? selectResult.availableTexts : undefined
+    const disabledValue = selectResult?.disabledValue !== undefined ? String(selectResult.disabledValue) : undefined
+    const disabledText = selectResult?.disabledText !== undefined ? String(selectResult.disabledText) : undefined
+    const recoveryHint = {
+      reason: "uid-select-failed",
+      recommendedTools: ["yunti_observe_page", "yunti_take_snapshot", "yunti_evaluate_script", "yunti_select"],
+      nextAction: "inspect-available-options",
+      decision: selectResult.code === "OPTION_DISABLED" ? "choose-enabled-option-or-unlock-field" : "inspect-options-before-retry",
+      uid,
+      matchMode,
+      targetOption,
+      ...(availableValues ? { availableValues } : {}),
+      ...(availableTexts ? { availableTexts } : {}),
+      ...(disabledValue ? { disabledValue } : {}),
+      ...(disabledText ? { disabledText } : {}),
+      message: "The select option could not be matched. Inspect available options before retrying, refresh observation if the uid may be stale, or use selector/value fallback.",
+    }
+
+    if (selectResult.code === "ELEMENT_NOT_FOUND") {
+      recoveryHint.nextAction = "observe-again"
+      recoveryHint.decision = "refresh-observation-before-retry"
+    } else if (selectResult.code === "NOT_SELECT") {
+      recoveryHint.nextAction = "inspect-target-element"
+      recoveryHint.decision = "use-select-element-or-selector-fallback"
+    }
+
+    return {
+      selected: false,
+      uid,
+      browserSessionId: session.browserSessionId,
+      action: "select",
+      target: { uid, method: matchMode === "text" ? "uid.text" : "uid.value" },
+      ok: false,
+      recoverable: true,
+      code: selectResult.code || "UID_SELECT_FAILED",
+      error: selectResult.error || `Cannot select option at uid ${uid}`,
+      matchMode,
+      targetOption,
+      ...(availableValues ? { availableValues } : {}),
+      ...(availableTexts ? { availableTexts } : {}),
+      ...(disabledValue ? { disabledValue } : {}),
+      ...(disabledText ? { disabledText } : {}),
+      recoveryHint,
+      nextStepHint: "Uid select failed. Inspect available options, observe again for a fresh uid, or retry with selector/value fallback before repeating the same select.",
+    }
   }
 
   function validateFillArgs(args = {}) {
@@ -648,18 +1335,57 @@ export function createToolDispatcher({
   async function clickViaSnapshotUid(tabId, session, uid) {
     const { x, y } = await resolveUidCenter(tabId, session, uid)
     await mouseClick(tabId, x, y, 1)
-    return { clicked: true, uid, x: Math.round(x), y: Math.round(y), browserSessionId: session.browserSessionId }
+    const roundedX = Math.round(x)
+    const roundedY = Math.round(y)
+    return {
+      clicked: true,
+      uid,
+      x: roundedX,
+      y: roundedY,
+      browserSessionId: session.browserSessionId,
+      action: "click",
+      target: { uid, x: roundedX, y: roundedY },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Click dispatched. Observe again or read page state to verify the intended change.",
+    }
   }
   
   async function hoverViaSnapshotUid(tabId, session, uid) {
     const { x, y } = await resolveUidCenter(tabId, session, uid)
     await mouseMove(tabId, x, y)
-    return { hovered: true, uid, x: Math.round(x), y: Math.round(y), browserSessionId: session.browserSessionId }
+    const roundedX = Math.round(x)
+    const roundedY = Math.round(y)
+    return {
+      hovered: true,
+      uid,
+      x: roundedX,
+      y: roundedY,
+      browserSessionId: session.browserSessionId,
+      action: "hover",
+      target: { uid, x: roundedX, y: roundedY },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Hover dispatched. Observe again or read page state to verify menus, tooltips, or hover-only controls.",
+    }
   }
   
   async function clickAtCoordinate(tabId, session, x, y) {
     await mouseClick(tabId, x, y, 1)
-    return { clicked: true, x: Math.round(x), y: Math.round(y), browserSessionId: session.browserSessionId, method: "coordinate" }
+    const roundedX = Math.round(x)
+    const roundedY = Math.round(y)
+    return {
+      clicked: true,
+      x: roundedX,
+      y: roundedY,
+      browserSessionId: session.browserSessionId,
+      method: "coordinate",
+      action: "click",
+      target: { method: "coordinate", x: roundedX, y: roundedY },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Coordinate click dispatched. Observe again, read page state, or use a fresh uid when possible to verify the intended change.",
+    }
   }
   
   async function resolveSelectorCenter(tabId, selector) {
@@ -695,36 +1421,72 @@ export function createToolDispatcher({
   }
   
   async function resolveUidCenter(tabId, session, uid) {
-    const uidMap = snapshotStore.get(session.browserSessionId)
+    const point = resolveObservedUidCenter(session, uid)
+    if (point.ok) return { x: point.x, y: point.y }
+    throw new Error(point.error)
+  }
+
+  function resolveObservedUidCenter(session, uid) {
+    const uidState = pageUidStore.get(session.browserSessionId)
+    const uidMap = uidState?.uidMap
     if (!uidMap || !uidMap[uid]) {
-      throw new Error(`uid ${uid} not found. Run yunti_take_snapshot first.`)
+      return {
+        ok: false,
+        error: `uid ${uid} not found in the latest page uid map. Run yunti_observe_page again before retrying.`,
+      }
     }
     const el = uidMap[uid]
   
     if (el.rect && el.rect.width > 0 && el.rect.height > 0) {
       return {
+        ok: true,
         x: el.rect.x + el.rect.width / 2,
         y: el.rect.y + el.rect.height / 2,
       }
     }
-  
-    // Resolve coordinates via CDP DOM.getBoxModel using backendNodeId
-    if (el.backendNodeId) {
-      await ensureCdpAttached(tabId, "1.3")
-      const boxModel = await chromeDebuggerSendCommand(
-        { tabId },
-        "DOM.getBoxModel",
-        { backendNodeId: el.backendNodeId }
-      )
-      const content = boxModel?.model?.content
-      if (content && content.length >= 4) {
-        const x = (content[0] + content[4]) / 2
-        const y = (content[1] + content[5]) / 2
-        return { x, y }
-      }
+
+    return {
+      ok: false,
+      error: `Cannot resolve coordinates for uid ${uid} without Chrome debugger. Run yunti_observe_page with includeRects enabled, scroll the element into view, or use an explicit selector fallback.`,
+    }
+  }
+
+  function buildUidPointFailureResult(session, uid, action, error) {
+    const code = /not found|latest page uid map/i.test(String(error || "")) ? "UID_NOT_FOUND" : "UID_COORDINATES_UNAVAILABLE"
+    const resultFieldByAction = {
+      click: "clicked",
+      hover: "hovered",
+      type: "typed",
+      press: "pressed",
+    }
+    const resultField = resultFieldByAction[action] || `${action}ed`
+    const recommendedToolByAction = {
+      click: "yunti_click",
+      hover: "yunti_hover",
+      type: "yunti_type_text",
+      press: "yunti_press_key",
+    }
+    const recommendedTool = recommendedToolByAction[action] || "yunti_observe_page"
+    return {
+      [resultField]: false,
+      uid,
+      browserSessionId: session.browserSessionId,
+      action,
+      target: { uid, method: "uid" },
+      ok: false,
+      recoverable: true,
+      code,
+      error: error || `Cannot ${action} uid ${uid}`,
+      recoveryHint: {
+        reason: `uid-${action}-failed`,
+        recommendedTools: ["yunti_observe_page", recommendedTool],
+        nextAction: "observe-again",
+        decision: "refresh-observation-before-retry",
+        uid,
+        message: "The uid could not be resolved without attaching Chrome debugger. Observe again with rects enabled, scroll the target into view, or retry with selector fallback.",
+      },
+      nextStepHint: `Uid ${action} failed without attaching Chrome debugger. Observe again for a fresh visible uid before retrying.`,
     }
-  
-    throw new Error(`Cannot resolve coordinates for uid ${uid}. Element may be off-screen or hidden.`)
   }
   
   async function mouseClick(tabId, x, y, clickCount = 1) {
@@ -756,24 +1518,60 @@ export function createToolDispatcher({
     for (const field of fields) {
       try {
         const uid = String(field.uid || "").trim()
+        let fieldResult
         if (uid) {
-          await fillByUid(tabId, session, { uid, value: String(field.value || "") })
+          fieldResult = await fillByUid(tabId, session, { uid, value: String(field.value || "") })
         } else {
-          await chrome.tabs.sendMessage(tabId, {
-            type: "yunti_execute_tool",
-            tool: "yunti_fill",
-            arguments: { selector: field.selector, value: field.value },
-          })
+          fieldResult = await fillByUid(tabId, session, { selector: field.selector, value: field.value })
         }
-        filled++
-        results.push({ uid: field.uid, selector: field.selector, ok: true })
+        const normalized = buildFillFormFieldResult(field, fieldResult)
+        if (normalized.ok) filled++
+        else failed++
+        results.push(normalized)
       } catch (err) {
         failed++
         results.push({ uid: field.uid, selector: field.selector, ok: false, error: err?.message || String(err) })
       }
     }
   
-    return { filled, failed, results, browserSessionId: session.browserSessionId }
+    return {
+      filled,
+      failed,
+      results,
+      browserSessionId: session.browserSessionId,
+      action: "fill_form",
+      target: {
+        fieldCount: fields.length,
+        filled,
+        failed,
+      },
+      ok: failed === 0,
+      recoverable: failed > 0,
+      nextStepHint: failed === 0
+        ? "Form fill dispatched. Observe again, read page state, or evaluate field values to verify the intended changes."
+        : "Form fill partially failed. Inspect per-field results, observe again for fresh uids, or retry failed fields with selector fallback.",
+    }
+  }
+
+  function buildFillFormFieldResult(field, fieldResult = {}) {
+    const ok = Boolean(fieldResult?.filled || fieldResult?.ok === true)
+    if (ok) return { uid: field.uid, selector: field.selector, ok: true }
+
+    const diagnostics = fieldResult && typeof fieldResult === "object" ? fieldResult : {}
+    const preservedKeys = [
+      "code",
+      "error",
+      "recoveryHint",
+      "availableValues",
+      "availableTexts",
+      "nextStepHint",
+    ]
+    const result = { uid: field.uid, selector: field.selector, ok: false }
+    for (const key of preservedKeys) {
+      if (diagnostics[key] !== undefined) result[key] = diagnostics[key]
+    }
+    if (!result.error) result.error = "fill failed"
+    return result
   }
   
   async function waitForCondition(tabId, session, args = {}) {
@@ -795,7 +1593,12 @@ export function createToolDispatcher({
       if (urlContains) {
         const tab = await chrome.tabs.get(tabId)
         if (tab.url && tab.url.includes(urlContains)) {
-          return { found: true, condition: "urlContains", value: urlContains, waitedMs: Date.now() - startTime, browserSessionId: session.browserSessionId }
+          return buildWaitForSuccess(
+            session,
+            { text, selector, urlContains, timeoutMs },
+            { found: true, condition: "urlContains", value: urlContains },
+            Date.now() - startTime
+          )
         }
       }
   
@@ -811,16 +1614,72 @@ export function createToolDispatcher({
           "Runtime.evaluate",
           { expression, returnByValue: true }
         )
-  
+
         if (result?.result?.value) {
-          return { found: true, ...result.result.value, waitedMs: Date.now() - startTime, browserSessionId: session.browserSessionId }
+          return buildWaitForSuccess(
+            session,
+            { text, selector, urlContains, timeoutMs },
+            result.result.value,
+            Date.now() - startTime
+          )
         }
       }
   
       await delayCdp(200)
     }
   
-    return { found: false, waitedMs: timeoutMs, browserSessionId: session.browserSessionId }
+    return buildWaitForTimeout(session, { text, selector, urlContains, timeoutMs }, timeoutMs)
+  }
+
+  function buildWaitForTarget({ text, selector, urlContains, timeoutMs } = {}) {
+    const target = {}
+    if (text) target.text = text
+    if (selector) target.selector = selector
+    if (urlContains) target.urlContains = urlContains
+    if (timeoutMs !== undefined) target.timeoutMs = timeoutMs
+    return target
+  }
+
+  function buildWaitForSuccess(session, args, match = {}, waitedMs = 0) {
+    const condition = typeof match.condition === "string"
+      ? match.condition
+      : match.found === "selector" || match.found === "text"
+        ? match.found
+        : undefined
+    const result = {
+      found: true,
+      ...match,
+      waitedMs,
+      browserSessionId: session.browserSessionId,
+      action: "wait_for",
+      target: buildWaitForTarget(args),
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Wait condition matched. Call yunti_observe_page and continue with a fresh uid before acting on newly rendered content.",
+    }
+    if (condition && result.condition === undefined) result.condition = condition
+    return result
+  }
+
+  function buildWaitForTimeout(session, args, waitedMs) {
+    return {
+      found: false,
+      waitedMs,
+      browserSessionId: session.browserSessionId,
+      action: "wait_for",
+      target: buildWaitForTarget(args),
+      ok: false,
+      recoverable: true,
+      code: "WAIT_TIMEOUT",
+      recoveryHint: {
+        reason: "condition-not-met-before-timeout",
+        recommendedTools: ["yunti_observe_page", "yunti_get_page_snapshot", "yunti_take_screenshot"],
+        nextAction: "observe-or-adjust-condition",
+        decision: "observe-before-retry",
+        message: "The expected text, selector, or URL state did not appear before the timeout. Observe the page or adjust the wait condition before repeating the same wait.",
+      },
+      nextStepHint: "Wait timed out. Observe the current page, inspect whether the condition changed, or adjust the wait target before retrying.",
+    }
   }
   
   async function handleDialog(tabId, session, args = {}) {
@@ -1000,7 +1859,20 @@ export function createToolDispatcher({
       type: "mouseReleased", x: toX, y: toY, button, clickCount: 1,
     })
   
-    return { dragged: true, from: { x: Math.round(fromX), y: Math.round(fromY) }, to: { x: Math.round(toX), y: Math.round(toY) }, steps, browserSessionId: session.browserSessionId }
+    const from = { x: Math.round(fromX), y: Math.round(fromY) }
+    const to = { x: Math.round(toX), y: Math.round(toY) }
+    return {
+      dragged: true,
+      from,
+      to,
+      steps,
+      browserSessionId: session.browserSessionId,
+      action: "drag",
+      target: { method: "coordinate", from, to },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Drag dispatched. Observe again or read page state to verify the intended movement or drop result.",
+    }
   }
   
   async function uploadFile(tabId, session, args = {}) {
@@ -1036,77 +1908,139 @@ export function createToolDispatcher({
       backendNodeId,
     })
   
-    return { uploaded: true, fileCount: filePaths.length, filePaths, browserSessionId: session.browserSessionId }
+    return {
+      uploaded: true,
+      fileCount: filePaths.length,
+      filePaths,
+      browserSessionId: session.browserSessionId,
+      action: "upload_file",
+      target: uid ? { uid, method: "uid" } : { selector, method: "selector" },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "File upload dispatched. Observe again, read page state, or verify the selected file input before submitting any form.",
+    }
   }
   
   async function typeTextByUid(tabId, session, args = {}) {
     const uid = String(args.uid || "").trim()
     if (!uid) {
       // Fall back to content script for selector/coordinate-based typing
-      return chrome.tabs.sendMessage(tabId, {
+      const selector = String(args.selector || "").trim()
+      const hasX = Number.isFinite(Number(args.x))
+      const hasY = Number.isFinite(Number(args.y))
+      const result = await chrome.tabs.sendMessage(tabId, {
         type: "yunti_execute_tool",
         tool: "yunti_type_text",
         arguments: args,
       })
+
+      if (!result || typeof result !== "object" || result.typed !== true) {
+        return result
+      }
+
+      const target =
+        selector
+          ? { selector, method: "selector" }
+          : hasX && hasY
+            ? { method: "coordinate", x: Math.round(Number(args.x)), y: Math.round(Number(args.y)) }
+            : { method: "focused" }
+
+      return {
+        ...result,
+        browserSessionId: session.browserSessionId,
+        action: "type_text",
+        target,
+        ok: true,
+        recoverable: false,
+        nextStepHint: "Type text dispatched. Observe again, read page state, or evaluate the active field value to verify the intended change.",
+      }
     }
   
     const text = String(args.text || "")
     if (!text) throw new Error("text is required")
   
-    // Click the uid element to focus it
-    const { x, y } = await resolveUidCenter(tabId, session, uid)
-    await mouseClick(tabId, x, y, 1)
-    await delayCdp(100)
+    const point = resolveObservedUidCenter(session, uid)
+    if (!point.ok) return buildUidPointFailureResult(session, uid, "type", point.error)
+    const result = await chrome.tabs.sendMessage(tabId, {
+      type: "yunti_execute_tool",
+      tool: "yunti_type_text",
+      arguments: { ...args, x: point.x, y: point.y },
+    })
+    if (!result || typeof result !== "object" || result.typed !== true) return result
   
-    // Type each character via CDP
-    for (const char of text) {
-      await chromeDebuggerSendCommand(
-        { tabId },
-        "Input.dispatchKeyEvent",
-        { type: "char", text: char, unmodifiedText: char }
-      )
+    return {
+      ...result,
+      typed: true,
+      uid,
+      text,
+      method: result.method || "dom",
+      browserSessionId: session.browserSessionId,
+      action: "type_text",
+      target: { uid, method: result.method || "dom" },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Type text dispatched without attaching Chrome debugger. Observe again, read page state, or evaluate the field value to verify the intended change.",
     }
-  
-    return { typed: true, uid, text, method: "cdp.keyboard", browserSessionId: session.browserSessionId }
   }
   
   async function pressKeyByUid(tabId, session, args = {}) {
     const uid = String(args.uid || "").trim()
     if (!uid) {
-      return chrome.tabs.sendMessage(tabId, {
+      const selector = String(args.selector || "").trim()
+      const hasX = Number.isFinite(Number(args.x))
+      const hasY = Number.isFinite(Number(args.y))
+      const result = await chrome.tabs.sendMessage(tabId, {
         type: "yunti_execute_tool",
         tool: "yunti_press_key",
         arguments: args,
       })
+
+      if (!result || typeof result !== "object" || result.pressed !== true) {
+        return result
+      }
+
+      const target =
+        selector
+          ? { selector, method: "selector" }
+          : hasX && hasY
+            ? { method: "coordinate", x: Math.round(Number(args.x)), y: Math.round(Number(args.y)) }
+            : { method: "focused" }
+
+      return {
+        ...result,
+        browserSessionId: session.browserSessionId,
+        action: "press_key",
+        target,
+        ok: true,
+        recoverable: false,
+        nextStepHint: "Key press dispatched. Observe again, read page state, or evaluate the active field value to verify the intended effect.",
+      }
     }
   
     const key = String(args.key || "").trim()
     if (!key) throw new Error("key is required")
   
-    // Focus the uid element
-    const { x, y } = await resolveUidCenter(tabId, session, uid)
-    await mouseClick(tabId, x, y, 1)
-    await delayCdp(50)
-  
-    // Map common key names to CDP key events
-    const keyDef = normalizeKey(key)
-  
-    await chromeDebuggerSendCommand({ tabId }, "Input.dispatchKeyEvent", {
-      type: "keyDown",
-      key: keyDef.key,
-      code: keyDef.code,
-      windowsVirtualKeyCode: keyDef.keyCode,
-      nativeVirtualKeyCode: keyDef.keyCode,
-    })
-    await chromeDebuggerSendCommand({ tabId }, "Input.dispatchKeyEvent", {
-      type: "keyUp",
-      key: keyDef.key,
-      code: keyDef.code,
-      windowsVirtualKeyCode: keyDef.keyCode,
-      nativeVirtualKeyCode: keyDef.keyCode,
+    const point = resolveObservedUidCenter(session, uid)
+    if (!point.ok) return buildUidPointFailureResult(session, uid, "press", point.error)
+    const result = await chrome.tabs.sendMessage(tabId, {
+      type: "yunti_execute_tool",
+      tool: "yunti_press_key",
+      arguments: { ...args, x: point.x, y: point.y },
     })
+    if (!result || typeof result !== "object" || result.pressed !== true) return result
   
-    return { pressed: true, uid, key, browserSessionId: session.browserSessionId }
+    return {
+      ...result,
+      pressed: true,
+      uid,
+      key,
+      browserSessionId: session.browserSessionId,
+      action: "press_key",
+      target: { uid, method: "dom" },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Key press dispatched without attaching Chrome debugger. Observe again, read page state, or evaluate the field value to verify the intended effect.",
+    }
   }
   
   const KEY_MAP = {