yunti-browser-runtime 0.1.2 → 0.2.0

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 = []
@@ -511,15 +544,30 @@ export function createToolDispatcher({
       }
       return clickAtCoordinate(tabId, session, x, y)
     }
-    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 = {}) {
@@ -534,7 +582,20 @@ export function createToolDispatcher({
         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 roundedX = Math.round(x)
+      const roundedY = Math.round(y)
+      return {
+        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. 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) {
@@ -542,13 +603,20 @@ export function createToolDispatcher({
     }
     const point = await resolveSelectorCenter(tabId, selector)
     await mouseMove(tabId, point.x, point.y)
+    const roundedX = Math.round(point.x)
+    const roundedY = Math.round(point.y)
     return {
       hovered: true,
       selector,
-      x: Math.round(point.x),
-      y: Math.round(point.y),
+      x: roundedX,
+      y: roundedY,
       browserSessionId: session.browserSessionId,
       method: "selector",
+      action: "hover",
+      target: { selector, method: "selector", x: roundedX, y: roundedY },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Selector hover dispatched. Observe again, read page state, or use a fresh uid when possible to verify menus, tooltips, or hover-only controls.",
     }
   }
   
@@ -557,76 +625,803 @@ 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();
+      try {
+        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();
+            const rect = el.getBoundingClientRect();
+            const style = getComputedStyle(el);
+            const type = String(el.type || '').toLowerCase();
+            const disabled = Boolean(el.disabled || el.getAttribute('aria-disabled') === 'true');
+            const readOnly = Boolean(el.readOnly || el.getAttribute('aria-readonly') === 'true');
+            const hidden = Boolean(el.hidden || style.display === 'none' || style.visibility === 'hidden' || Number(style.opacity) === 0 || rect.width <= 0 || rect.height <= 0);
+            const valueEditable = tag === 'input' || tag === 'textarea';
+            const blockedInputType = tag === 'input' && ['button', 'checkbox', 'color', 'file', 'hidden', 'image', 'radio', 'range', 'reset', 'submit'].includes(type);
+            const editable = el.isContentEditable || tag === 'select' || (valueEditable && !blockedInputType);
+            if (tag === 'select') {
+              const opts = Array.from(el.options);
+              return { tag: 'select', type, disabled, readOnly, hidden, editable, options: opts.map(o => ({ value: o.value, text: o.text.slice(0, 80) })), selectedIndex: el.selectedIndex };
+            }
+            const beforeText = el.isContentEditable ? String(el.textContent || '') : '';
+            if (el.isContentEditable) {
+              el.focus();
+              el.textContent = '';
+            } else if (valueEditable && !blockedInputType && !disabled && !readOnly && !hidden) {
+              el.focus();
+              el.select();
+            }
+            return {
+              tag,
+              type,
+              contentEditable: el.isContentEditable,
+              disabled,
+              readOnly,
+              hidden,
+              editable,
+              before: el.isContentEditable ? { textLength: beforeText.length } : undefined,
+            };
+          })()`,
+            returnByValue: true,
           }
-          return { tag, type: el.type, contentEditable: el.isContentEditable };
-        })()`,
-          returnByValue: true,
+        )
+        const elInfo = elements?.result?.value
+
+        if (elInfo === "not found") {
+          return buildUidFillFailureResult(session, uid, {
+            code: "ELEMENT_NOT_FOUND",
+            error: `No element found at uid ${uid} coordinates`,
+          })
+        }
+
+        if (elInfo?.hidden || elInfo?.disabled || elInfo?.readOnly || elInfo?.editable === false) {
+          return buildUidFillFailureResult(session, uid, {
+            code: "TARGET_NOT_EDITABLE",
+            error: buildFillEditabilityError(uid, elInfo),
+            element: summarizeFillTarget(elInfo),
+          })
         }
-      )
-      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,
+              action: "fill",
+              target: { uid, method: "select" },
+              ok: true,
+              recoverable: false,
+              nextStepHint: "Select value dispatched. Observe again, read page state, or evaluate the select value to verify the intended change.",
+            }
+          }
+          return buildUidFillFailureResult(session, uid, {
+            code: "OPTION_NOT_FOUND",
+            error: `Option '${value}' not found in select at uid ${uid}`,
+            availableValues: elInfo.options?.map((option) => option.value).slice(0, 50),
+            availableTexts: elInfo.options?.map((option) => option.text).slice(0, 50),
+          })
+        }
   
-      // Handle select element
-      if (elInfo?.tag === "select") {
-        const targetOption = elInfo.options?.find(
-          o => o.value === value || o.text === value
-        )
-        if (targetOption) {
+        // Type text via CDP Input.dispatchKeyEvent
+        const text = value
+        for (const char of text) {
           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 }));
-              })()`,
-            }
+            "Input.dispatchKeyEvent",
+            { type: "char", text: char, unmodifiedText: char }
           )
-          return { filled: true, uid, method: "select", value: targetOption.value, browserSessionId: session.browserSessionId }
         }
-        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.`)
-      }
-  
-      // Type text via CDP Input.dispatchKeyEvent
-      const text = value
-      for (const char of text) {
-        await chromeDebuggerSendCommand(
+        const method = elInfo?.contentEditable ? "contenteditable" : "keyboard"
+        const before = elInfo?.before
+        await delayCdp(50)
+        const verification = await chromeDebuggerSendCommand(
           { tabId },
-          "Input.dispatchKeyEvent",
-          { type: "char", text: char, unmodifiedText: char }
+          "Runtime.evaluate",
+          {
+            expression: `(() => {
+              const el = document.elementFromPoint(${x}, ${y});
+              if (!el) return { found: false };
+              const tag = el.tagName.toLowerCase();
+              const type = String(el.type || '').toLowerCase();
+              const expected = ${JSON.stringify(text)};
+              const actual = el.isContentEditable
+                ? String(el.textContent || '')
+                : (tag === 'input' || tag === 'textarea')
+                  ? String(el.value || '')
+                  : undefined;
+              if (actual === undefined) {
+                return { found: true, tag, type, contentEditable: el.isContentEditable };
+              }
+              return {
+                found: true,
+                tag,
+                type,
+                contentEditable: el.isContentEditable,
+                valueMatches: actual === expected,
+                valueLength: actual.length,
+                expectedLength: expected.length,
+              };
+            })()`,
+            returnByValue: true,
+          }
         )
-      }
-      return { filled: true, uid, method: "keyboard", value: text, browserSessionId: session.browserSessionId }
+        const verificationInfo = verification?.result?.value
+        const verifiedAfter = verificationInfo?.found && Number.isFinite(Number(verificationInfo.valueLength))
+          ? { textLength: Number(verificationInfo.valueLength) }
+          : undefined
+        const after = verifiedAfter || (elInfo?.contentEditable ? { textLength: text.length } : undefined)
+        if (verificationInfo?.found && verificationInfo.valueMatches === false) {
+          return buildUidFillFailureResult(session, uid, {
+            code: "VALUE_NOT_APPLIED",
+            error: `Filled value did not remain on uid ${uid}`,
+            method,
+            expectedValueLength: Number(verificationInfo.expectedLength),
+            actualValueLength: Number(verificationInfo.valueLength),
+            ...(before ? { before } : {}),
+            after,
+            element: summarizeFillTarget({
+              tag: verificationInfo.tag,
+              type: verificationInfo.type,
+              contentEditable: verificationInfo.contentEditable,
+            }),
+          })
+        }
+        return {
+          filled: true,
+          uid,
+          method,
+          value: text,
+          ...(before ? { before } : {}),
+          ...(after ? { after } : {}),
+          browserSessionId: session.browserSessionId,
+          action: "fill",
+          target: { uid, method },
+          ok: true,
+          recoverable: false,
+          nextStepHint: elInfo?.contentEditable
+            ? "Contenteditable fill dispatched. Observe again, read page text, or evaluate textContent to verify the intended change."
+            : "Fill dispatched. 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",
+      })
+    }
     }
   
-    return chrome.tabs.sendMessage(tabId, {
+    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",
+        })
+      }
+      const { x, y } = point
+      scrollArgs = { ...args, x, y }
+    }
+    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 { x, y } = await resolveUidCenter(tabId, session, uid)
+      await ensureCdpAttached(tabId, "1.3")
+      const result = await chromeDebuggerSendCommand(
+        { tabId },
+        "Runtime.evaluate",
+        {
+          expression: `(() => {
+            const el = document.elementFromPoint(${x}, ${y});
+            if (!el) return { ok: false, code: "ELEMENT_NOT_FOUND", error: "No element found at uid coordinates" };
+            if (el.tagName.toLowerCase() !== "select") {
+              return { ok: false, code: "NOT_SELECT", error: "Element at uid is not a select element" };
+            }
+            const options = Array.from(el.options);
+            const option = options.find((item) => {
+              if (${JSON.stringify(matchMode)} === "text") return item.text.trim() === ${JSON.stringify(targetOption)};
+              return item.value === ${JSON.stringify(targetOption)};
+            });
+            if (!option) {
+              return {
+                ok: false,
+                code: "OPTION_NOT_FOUND",
+                error: ${JSON.stringify(matchMode)} === "text" ? "Option text not found" : "Option value not found",
+                availableValues: options.map((item) => item.value).slice(0, 50),
+                availableTexts: options.map((item) => item.text.trim()).slice(0, 50),
+              };
+            }
+            if (option.disabled) {
+              return {
+                ok: false,
+                code: "OPTION_DISABLED",
+                error: ${JSON.stringify(matchMode)} === "text" ? "Option text is disabled" : "Option value is disabled",
+                disabledValue: option.value,
+                disabledText: option.text.trim(),
+                availableValues: options.map((item) => item.value).slice(0, 50),
+                availableTexts: options.map((item) => item.text.trim()).slice(0, 50),
+              };
+            }
+            el.value = option.value;
+            el.dispatchEvent(new Event("change", { bubbles: true }));
+            el.dispatchEvent(new Event("input", { bubbles: true }));
+            return {
+              ok: true,
+              value: option.value,
+              selectedIndex: el.selectedIndex,
+              optionText: option.text.slice(0, 80),
+            };
+          })()`,
+          returnByValue: true,
+        }
+      )
+      const selectResult = result?.result?.value
+      if (!selectResult?.ok) {
+        return buildUidSelectFailureResult(session, uid, matchMode, targetOption, selectResult)
+      }
+      return {
+        selected: true,
+        uid,
+        value: selectResult.value,
+        text: selectResult.optionText,
+        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. Observe again, read page state, or evaluate the select value to verify the intended change."
+          : "Uid select dispatched by option value. 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 +1443,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,9 +1529,12 @@ export function createToolDispatcher({
   }
   
   async function resolveUidCenter(tabId, session, uid) {
-    const uidMap = snapshotStore.get(session.browserSessionId)
+    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.`)
+      throw new Error(
+        `uid ${uid} not found in the latest page uid map. Run yunti_observe_page or yunti_take_snapshot again before retrying.`
+      )
     }
     const el = uidMap[uid]
   
@@ -724,7 +1561,7 @@ export function createToolDispatcher({
       }
     }
   
-    throw new Error(`Cannot resolve coordinates for uid ${uid}. Element may be off-screen or hidden.`)
+    throw new Error(`Cannot resolve coordinates for uid ${uid}. Element may be off-screen, hidden, or stale. Run yunti_observe_page again before retrying.`)
   }
   
   async function mouseClick(tabId, x, y, clickCount = 1) {
@@ -756,24 +1593,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 +1668,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 +1689,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 +1934,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,18 +1983,52 @@ 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 || "")
@@ -1067,17 +2048,52 @@ export function createToolDispatcher({
       )
     }
   
-    return { typed: true, uid, text, method: "cdp.keyboard", browserSessionId: session.browserSessionId }
+    return {
+      typed: true,
+      uid,
+      text,
+      method: "cdp.keyboard",
+      browserSessionId: session.browserSessionId,
+      action: "type_text",
+      target: { uid, method: "cdp.keyboard" },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Type text dispatched. Observe again, read page state, or evaluate the field value to verify the intended change.",
+    }
   }
   
   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()
@@ -1106,7 +2122,17 @@ export function createToolDispatcher({
       nativeVirtualKeyCode: keyDef.keyCode,
     })
   
-    return { pressed: true, uid, key, browserSessionId: session.browserSessionId }
+    return {
+      pressed: true,
+      uid,
+      key,
+      browserSessionId: session.browserSessionId,
+      action: "press_key",
+      target: { uid, method: "cdp.keyboard" },
+      ok: true,
+      recoverable: false,
+      nextStepHint: "Key press dispatched. Observe again, read page state, or evaluate the field value to verify the intended effect.",
+    }
   }
   
   const KEY_MAP = {