yunti-browser-runtime 0.1.3 → 0.2.1

package/mcp/tools.js

@@ -13,7 +13,7 @@ export const TOOLS = [
         },
         topic: {
           type: "string",
-          enum: ["all", "browser", "cdp", "tabs", "memory", "network", "console"],
+          enum: ["all", "browser", "cdp", "tabs", "memory", "network", "console", "workflow"],
           description: "Optional topic filter. Defaults to all.",
         },
       },
@@ -51,6 +51,57 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: "yunti_observe_page",
+    description:
+      "Observe the current browser page for agentic operation. Returns an observationId, page/viewport/scroll metadata, a compact interactive text tree, structured elements with fresh uids, scrollable container metadata, redaction metadata, and next-step hints. Prefer this for observe -> act by uid -> verify workflows once available. Sensitive credential-like values are redacted by default; strict redaction also hides likely email, phone, payment-card, and address text surfaces.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        browserSessionId: {
+          type: "string",
+          description:
+            "Optional target Yunti browser session. Use the returned browserSessionId for follow-up actions on the same tab.",
+        },
+        mode: {
+          type: "string",
+          enum: ["viewport", "fullPage"],
+          description:
+            "Observation scope. Defaults to viewport; fullPage is bounded by maxElements and maxTextLength.",
+        },
+        maxElements: {
+          type: "integer",
+          minimum: 1,
+          maximum: 500,
+          description: "Maximum interactive elements to return. Defaults to a bounded runtime value.",
+        },
+        maxTextLength: {
+          type: "integer",
+          minimum: 0,
+          maximum: 60000,
+          description: "Maximum textTree/visible text characters to return.",
+        },
+        includeHidden: {
+          type: "boolean",
+          description: "Include hidden or invisible elements. Defaults to false.",
+        },
+        includeTextTree: {
+          type: "boolean",
+          description: "Include the compact agent-facing interactive text tree. Defaults to true.",
+        },
+        includeRects: {
+          type: "boolean",
+          description: "Include viewport-relative element rectangles. Defaults to true.",
+        },
+        redaction: {
+          type: "string",
+          enum: ["balanced", "strict", "off"],
+          description:
+            "DOM observation redaction mode. Defaults to balanced. Use off only for explicit local debugging; it is not recommended for agent workflows.",
+        },
+      },
+    },
+  },
   {
     name: "yunti_get_selected_context",
     description:
@@ -155,7 +206,7 @@ export const TOOLS = [
   {
     name: "yunti_remember_learning",
     description:
-      "Store an auditable Yunti learning memory such as an API pattern, workflow step, selector, field mapping, or gotcha. Do not store secrets or raw cookies.",
+      "Store an auditable Yunti learning memory such as an API pattern, workflow step, selector, field mapping, or gotcha. Memory input is sanitized before storage, but agents should still avoid storing secrets, raw cookies, or personal data.",
     inputSchema: {
       type: "object",
       required: ["title", "detail"],
@@ -177,7 +228,7 @@ export const TOOLS = [
   },
   {
     name: "yunti_get_learning_memory",
-    description: "Search auditable Yunti learning memories recorded by agents.",
+    description: "Search sanitized auditable Yunti learning memories recorded by agents.",
     inputSchema: {
       type: "object",
       properties: {
@@ -245,7 +296,7 @@ export const TOOLS = [
   {
     name: "yunti_capture_visible_tab",
     description:
-      "Capture a PNG screenshot of the visible area of the active Yunti browser tab through the extension. Reuses the user's current browser without requiring a separate debugging setup.",
+      "Capture a PNG screenshot of the visible area of the active Yunti browser tab through the extension. Screenshots are real visible pixels and are not DOM-redacted; use only when visual evidence is needed.",
     inputSchema: {
       type: "object",
       properties: {
@@ -348,7 +399,7 @@ export const TOOLS = [
   {
     name: "yunti_get_cdp_events",
     description:
-      "Read raw low-level browser protocol events forwarded by the browser extension for the active tab. First internal version does not redact event payloads.",
+      "Read raw low-level browser protocol events forwarded by the browser extension for the active tab. This diagnostic stream intentionally does not redact event payloads; use only for low-level debugging and clear it after debugging.",
     inputSchema: {
       type: "object",
       properties: {
@@ -363,7 +414,7 @@ export const TOOLS = [
   {
     name: "yunti_clear_cdp_events",
     description:
-      "Clear raw CDP events for the active tab, a selected session, or all sessions.",
+      "Clear raw CDP diagnostic events for the active tab, a selected session, or all sessions.",
     inputSchema: {
       type: "object",
       properties: {
@@ -390,13 +441,13 @@ export const TOOLS = [
   {
     name: "yunti_type_text",
     description:
-      "Type or set text in the focused element, a selector target, a uid target (from yunti_take_snapshot), or a coordinate target on the current browser page.",
+      "Type or set text in the focused element, a selector target, a uid target (from yunti_observe_page or yunti_take_snapshot), or a coordinate target on the current browser page.",
     inputSchema: {
       type: "object",
       required: ["text"],
       properties: {
         browserSessionId: { type: "string" },
-        uid: { type: "string", description: "Stable uid from yunti_take_snapshot." },
+        uid: { type: "string", description: "Fresh uid from yunti_observe_page or yunti_take_snapshot." },
         text: { type: "string" },
         selector: { type: "string" },
         x: { type: "number" },
@@ -408,13 +459,13 @@ export const TOOLS = [
   {
     name: "yunti_press_key",
     description:
-      "Send a keyboard key event to the focused element, a uid target (from yunti_take_snapshot), a selector target, or a coordinate target on the current browser page.",
+      "Send a keyboard key event to the focused element, a uid target (from yunti_observe_page or yunti_take_snapshot), a selector target, or a coordinate target on the current browser page.",
     inputSchema: {
       type: "object",
       required: ["key"],
       properties: {
         browserSessionId: { type: "string" },
-        uid: { type: "string", description: "Stable uid from yunti_take_snapshot." },
+        uid: { type: "string", description: "Fresh uid from yunti_observe_page or yunti_take_snapshot." },
         key: { type: "string", description: "Examples: Enter, Escape, Tab, ArrowDown, Backspace." },
         selector: { type: "string" },
         x: { type: "number" },
@@ -425,11 +476,12 @@ export const TOOLS = [
   {
     name: "yunti_scroll",
     description:
-      "Scroll the current browser page or the scrollable container under a viewport coordinate through the extension.",
+      "Scroll the current browser page, a scrollable container by fresh uid, or the scrollable container under a viewport coordinate through the extension.",
     inputSchema: {
       type: "object",
       properties: {
         browserSessionId: { type: "string" },
+        uid: { type: "string", description: "Fresh scrollable container uid from yunti_observe_page. Takes precedence over x/y." },
         x: { type: "number" },
         y: { type: "number" },
         deltaX: { type: "number", default: 0 },
@@ -457,13 +509,13 @@ export const TOOLS = [
   {
     name: "yunti_upload_file",
     description:
-      "Set files on a file input element by uid (from yunti_take_snapshot) or selector. Uses CDP DOM.setFileInputFiles. Paths must be accessible to the browser.",
+      "Set files on a file input element by uid (from yunti_observe_page or yunti_take_snapshot) or selector. Uses CDP DOM.setFileInputFiles. Paths must be accessible to the browser.",
     inputSchema: {
       type: "object",
       required: ["filePaths"],
       properties: {
         browserSessionId: { type: "string" },
-        uid: { type: "string", description: "Stable uid from yunti_take_snapshot for the file input." },
+        uid: { type: "string", description: "Fresh uid from yunti_observe_page or yunti_take_snapshot for the file input." },
         selector: { type: "string", description: "CSS selector for the file input element." },
         filePaths: { type: "array", items: { type: "string" }, description: "Absolute file paths to upload." },
       },
@@ -484,12 +536,12 @@ export const TOOLS = [
   {
     name: "yunti_click",
     description:
-      "Click an element on the current browser page using a uid from yunti_take_snapshot, a CSS selector, or viewport coordinates. Prefer uid for reliability. For coordinate-only clicks, yunti_click_at is the clearer dedicated tool. Dangerous labels require user confirmation.",
+      "Click an element on the current browser page using a uid from yunti_observe_page or yunti_take_snapshot, a CSS selector, or viewport coordinates. Prefer a fresh uid for reliability. For coordinate-only clicks, yunti_click_at is the clearer dedicated tool. Dangerous labels require user confirmation.",
     inputSchema: {
       type: "object",
       properties: {
         browserSessionId: { type: "string" },
-        uid: { type: "string", description: "Stable uid from yunti_take_snapshot (e.g. yunti-1). Takes precedence over selector." },
+        uid: { type: "string", description: "Fresh uid from yunti_observe_page or yunti_take_snapshot (e.g. yunti-1). Takes precedence over selector." },
         selector: { type: "string", description: "CSS selector. Used when uid is not provided." },
         x: { type: "number", description: "Viewport x coordinate fallback. Use together with y; yunti_click_at is preferred for coordinate-only clicks." },
         y: { type: "number", description: "Viewport y coordinate fallback. Use together with x; yunti_click_at is preferred for coordinate-only clicks." },
@@ -500,12 +552,12 @@ export const TOOLS = [
   {
     name: "yunti_hover",
     description:
-      "Hover over an element on the current browser page using a uid from yunti_take_snapshot, a CSS selector, or viewport coordinates. Useful for triggering tooltips, dropdowns, and hover menus.",
+      "Hover over an element on the current browser page using a uid from yunti_observe_page or yunti_take_snapshot, a CSS selector, or viewport coordinates. Useful for triggering tooltips, dropdowns, and hover menus.",
     inputSchema: {
       type: "object",
       properties: {
         browserSessionId: { type: "string" },
-        uid: { type: "string", description: "Stable uid from yunti_take_snapshot (e.g. yunti-1). Takes precedence over selector." },
+        uid: { type: "string", description: "Fresh uid from yunti_observe_page or yunti_take_snapshot (e.g. yunti-1). Takes precedence over selector." },
         selector: { type: "string", description: "CSS selector fallback. The element center is resolved and hovered through CDP." },
         x: { type: "number", description: "Viewport x coordinate fallback. Use together with y." },
         y: { type: "number", description: "Viewport y coordinate fallback. Use together with x." },
@@ -515,13 +567,13 @@ export const TOOLS = [
   {
     name: "yunti_fill",
     description:
-      "Fill an input, textarea, select, or contenteditable element using a uid from yunti_take_snapshot or a CSS selector. Prefer uid for reliability.",
+      "Fill an input, textarea, select, or contenteditable element using a uid from yunti_observe_page or yunti_take_snapshot, or a CSS selector. Prefer a fresh uid for reliability.",
     inputSchema: {
       type: "object",
       required: ["value"],
       properties: {
         browserSessionId: { type: "string" },
-        uid: { type: "string", description: "Stable uid from yunti_take_snapshot (e.g. yunti-3). Takes precedence over selector." },
+        uid: { type: "string", description: "Fresh uid from yunti_observe_page or yunti_take_snapshot (e.g. yunti-3). Takes precedence over selector." },
         selector: { type: "string", description: "CSS selector. Used when uid is not provided." },
         value: { type: "string" },
       },
@@ -530,7 +582,7 @@ export const TOOLS = [
   {
     name: "yunti_list_console_messages",
     description:
-      "List console messages (console.log, console.error, console.warn, etc.) captured from the active browser page via CDP Runtime/Log events. Supports filtering by level and pagination.",
+      "List sanitized console messages (console.log, console.error, console.warn, etc.) captured from the active browser page via CDP Runtime/Log events. Supports filtering by level and pagination.",
     inputSchema: {
       type: "object",
       properties: {
@@ -546,7 +598,7 @@ export const TOOLS = [
   {
     name: "yunti_get_console_message",
     description:
-      "Get a single console message by its msgid from yunti_list_console_messages. Returns full detail including stack trace.",
+      "Get a single sanitized console message by its msgid from yunti_list_console_messages. Returns detail including stack trace.",
     inputSchema: {
       type: "object",
       required: ["msgId"],
@@ -570,21 +622,46 @@ export const TOOLS = [
   },
   {
     name: "yunti_select",
-    description: "Select an option in a select element on the current browser page.",
+    description:
+      "Select an option in a select element on the current browser page. Supports selector/value plus uid/value or uid/text while keeping selector/value compatible.",
     inputSchema: {
       type: "object",
-      required: ["selector", "value"],
+      anyOf: [
+        { required: ["selector", "value"] },
+        { required: ["uid", "value"] },
+        { required: ["uid", "text"] },
+      ],
       properties: {
-        browserSessionId: { type: "string" },
-        selector: { type: "string" },
-        value: { type: "string" },
+        browserSessionId: {
+          type: "string",
+          description: "Optional target Yunti browser session.",
+        },
+        selector: {
+          type: "string",
+          description: "Compatible CSS selector path for the select element.",
+        },
+        uid: {
+          type: "string",
+          description:
+            "Fresh uid path from yunti_observe_page or yunti_take_snapshot. Supports option value or visible text matching.",
+        },
+        value: {
+          type: "string",
+          description:
+            "Option value to select. Supported with selector or uid.",
+        },
+        text: {
+          type: "string",
+          description:
+            "Visible option text to select. Supported with uid when the user-facing label is clearer than the value.",
+        },
       },
     },
   },
   {
     name: "yunti_fill_form",
     description:
-      "Fill multiple form fields at once. Each field specifies a uid (from yunti_take_snapshot) or a selector, and its value. More efficient than calling yunti_fill repeatedly.",
+      "Fill multiple form fields at once. Each field specifies a uid (from yunti_observe_page or yunti_take_snapshot) or a selector, and its value. More efficient than calling yunti_fill repeatedly.",
     inputSchema: {
       type: "object",
       required: ["fields"],
@@ -596,7 +673,7 @@ export const TOOLS = [
             type: "object",
             required: ["value"],
             properties: {
-              uid: { type: "string", description: "Stable uid from yunti_take_snapshot." },
+              uid: { type: "string", description: "Fresh uid from yunti_observe_page or yunti_take_snapshot." },
               selector: { type: "string", description: "CSS selector fallback." },
               value: { type: "string", description: "Value to fill." },
             },
@@ -700,7 +777,7 @@ export const TOOLS = [
   {
     name: "yunti_wait_for",
     description:
-      "Wait for a condition to be met on the page: text appears, a selector becomes visible, the URL changes, or the DOM/network becomes idle. Returns when the condition is met or times out.",
+      "Wait for a condition to be met on the page: text appears, a selector becomes visible, or the URL changes. Returns compatibility fields such as found/text/selector/waitedMs plus structured action fields when available.",
     inputSchema: {
       type: "object",
       properties: {
@@ -768,7 +845,7 @@ export const TOOLS = [
   {
     name: "yunti_take_screenshot",
     description:
-      "Capture a PNG screenshot of the selected browser page. Supports viewport and full-page modes via CDP Page.captureScreenshot.",
+      "Capture a screenshot of the selected browser page. Supports viewport and full-page modes via CDP Page.captureScreenshot. Screenshots are real visible pixels and are not DOM-redacted.",
     inputSchema: {
       type: "object",
       properties: {
@@ -897,6 +974,32 @@ export function toolUsageHints(args = {}) {
         "If an old browserSessionId fails, call yunti_list_browser_targets to refresh the live route inventory.",
       ],
     },
+    yunti_observe_page: {
+      purpose: "Observe the current page for observe -> act by uid -> verify workflows.",
+      required: [],
+      recommended: ["browserSessionId", "mode", "redaction"],
+      examples: [
+        {
+          browserSessionId: "yunti-...",
+          mode: "viewport",
+          includeTextTree: true,
+          redaction: "balanced",
+        },
+      ],
+      notes: [
+        "Use this as the default page-operation refresh step once available.",
+        "Returned uids are fresh for the latest observation in the current browserSessionId; observe again after navigation, DOM changes, or stale uid errors.",
+        "Input-like elements may include editable, fillable, readOnly, fillBlockReason, selectedIndex/selectedValue/selectedText, and select options[] summaries so agents can inspect field state before filling or selecting.",
+        "Default balanced redaction hides credential-like values. Strict redaction additionally hides likely email, phone, Luhn-valid payment-card-like values, address-like text, page titles, labels, names, visible text, placeholders, value previews, and select option text.",
+        "Screenshots are separate and may still contain visible sensitive content.",
+        "Use yunti_get_page_snapshot for lightweight route/title/text overview and yunti_take_snapshot for compatibility with older uid workflows.",
+      ],
+      commonMistakes: [
+        "Do not treat observation uids as permanent selectors across refreshes or tabs.",
+        "Do not use redaction=off unless the user explicitly wants local debugging.",
+        "Do not blindly retry an action after no page change; observe, wait, scroll, or switch tabs based on hints.",
+      ],
+    },
     yunti_list_browser_targets: {
       purpose: "Canonical live Chrome/Edge tab and target inventory.",
       required: [],
@@ -941,6 +1044,62 @@ export function toolUsageHints(args = {}) {
         "If browserSessionId is stale, refresh with yunti_list_browser_targets before retrying.",
       ],
     },
+    yunti_get_cdp_events: {
+      purpose: "Inspect raw low-level CDP events for debugging transport, protocol, or extension behavior.",
+      required: [],
+      recommended: ["browserSessionId", "method", "limit"],
+      notes: [
+        "This tool intentionally returns raw CDP event payloads and does not apply network, console, DOM, or learning-memory sanitization.",
+        "Use sanitized network and console tools first when they can answer the question.",
+        "Filter by method and keep limit small to reduce sensitive payload exposure.",
+        "Clear raw CDP events after debugging with yunti_clear_cdp_events.",
+      ],
+      recovery: [
+        "After reading raw CDP diagnostics, call yunti_clear_cdp_events for the same browserSessionId or allSessions when appropriate.",
+        "If you need to keep a durable note, summarize the safe conclusion with yunti_remember_learning instead of copying raw event payloads.",
+      ],
+      commonMistakes: [
+        "Do not copy raw CDP params into chat, logs, learning memory, or documentation.",
+        "Do not use raw CDP events as the default page observation path; prefer yunti_observe_page, sanitized network tools, and sanitized console tools.",
+      ],
+    },
+    yunti_clear_cdp_events: {
+      purpose: "Delete raw CDP diagnostic events after low-level debugging.",
+      required: [],
+      recommended: ["browserSessionId"],
+      notes: [
+        "Use browserSessionId to clear one tab's raw diagnostics, or allSessions=true with the current userId when ending a broader debugging session.",
+        "Clearing raw CDP events does not clear sanitized network or console diagnostics.",
+      ],
+    },
+    yunti_take_screenshot: {
+      purpose: "Capture visual page evidence for layout, rendering, or user-visible verification.",
+      required: [],
+      recommended: ["browserSessionId", "fullPage"],
+      notes: [
+        "Screenshots are real visible pixels and are not DOM-redacted.",
+        "Use yunti_observe_page with redaction=strict first when structured text is enough.",
+        "Prefer viewport screenshots over fullPage when a smaller visual proof is sufficient.",
+        "Do not store screenshots in learning memory; summarize only safe visual findings.",
+      ],
+      commonMistakes: [
+        "Do not assume DOM redaction hides sensitive content in screenshots.",
+        "Do not use screenshots as the default data extraction path when observe, snapshot, network, console, or evaluate can provide a safer answer.",
+      ],
+    },
+    yunti_capture_visible_tab: {
+      purpose: "Capture the active visible tab for visual verification through the extension fallback path.",
+      required: [],
+      recommended: ["browserSessionId"],
+      notes: [
+        "Like yunti_take_screenshot, this returns real visible pixels and is not DOM-redacted.",
+        "Use it only when visual state matters and structured observations are insufficient.",
+        "Do not store raw screenshot data in learning memory.",
+      ],
+      commonMistakes: [
+        "Do not expose visible secrets from the screenshot; describe only the safe conclusion.",
+      ],
+    },
     yunti_evaluate_script: {
       purpose: "Evaluate JavaScript in the selected browser page.",
       required: ["expression"],
@@ -993,49 +1152,186 @@ export function toolUsageHints(args = {}) {
       ],
       commonMistakes: ["Use id, not title."],
     },
+    yunti_remember_learning: {
+      purpose: "Persist a sanitized local learning memory for future agent runs.",
+      required: ["title", "detail"],
+      recommended: ["kind", "tags", "confidence", "source"],
+      notes: [
+        "Learning memory sanitizes likely secrets and PII-like text before writing to disk.",
+        "Do not intentionally store raw cookies, authorization headers, tokens, passwords, private keys, payment data, or personal contact details.",
+        "Use relatedNetworkEventIds to reference sanitized network observations instead of copying raw payloads into memory.",
+      ],
+      commonMistakes: [
+        "Do not use learning memory as task history or a transcript store.",
+        "Do not store raw CDP event payloads in memory.",
+      ],
+    },
+    yunti_wait_for: {
+      purpose: "Wait for expected text, a visible selector, or a URL substring before observing and continuing with fresh uids.",
+      required: [],
+      recommended: ["browserSessionId", "text or selector or urlContains", "timeoutMs"],
+      notes: [
+        "Use this when the page is rendering asynchronously, loading select options, validating a field, navigating, or appending scroll content.",
+        "At least one of text, selector, or urlContains is required.",
+        "Successful results preserve compatibility fields such as found, text, selector, condition, value, waitedMs, and browserSessionId.",
+        "P6.2.6 structured fields are additive: action=wait_for, target, ok, recoverable, and nextStepHint.",
+        "Timeout results return found=false, ok=false, recoverable=true, code=WAIT_TIMEOUT, recoveryHint, and nextStepHint.",
+        "After a successful wait, call yunti_observe_page before using uids for newly rendered content.",
+      ],
+      recovery: [
+        "WAIT_TIMEOUT: observe the current page, inspect whether the expected condition changed, or adjust text/selector/urlContains before retrying.",
+        "Async form/select work: wait for the expected text/selector/state, observe again, then fill/select with a fresh uid.",
+        "Async scroll work: wait for the next expected text/selector, observe again, then choose a fresh scrollable container uid.",
+        "Wrong tab or stale route: refresh targets with yunti_list_browser_targets and route through the intended browserSessionId.",
+      ],
+      commonMistakes: [
+        "Do not treat WAIT_TIMEOUT as proof the task failed; inspect the page state before deciding.",
+        "Do not keep repeating the same wait condition without observing or adjusting it.",
+        "Do not reuse old uids after waiting for new async content; observe again first.",
+      ],
+    },
     yunti_click: {
-      purpose: "Click by snapshot uid, CSS selector, or viewport coordinates.",
+      purpose: "Click by observe/snapshot uid, CSS selector, or viewport coordinates.",
       required: [],
       recommended: ["browserSessionId", "uid"],
       notes: [
-        "Prefer uid from yunti_take_snapshot for reliability.",
+        "Prefer a fresh uid from yunti_observe_page or yunti_take_snapshot for reliability.",
         "Use selector when uid is unavailable.",
         "Coordinate mode requires both x and y; yunti_click_at is clearer for coordinate-only clicks.",
+        "After clicking, observe again or read page state before deciding whether the action succeeded.",
+        "If the target is missing or stale, observe again; if it may be below the fold, scroll first; if the page is changing, wait before retrying.",
+        "Current results are compatibility-shaped and may include clicked, uid, selector/coordinate, method, and browserSessionId; P6.2 will converge action outputs toward action, target, ok/code, recoverable, nextStepHint, and before/after summaries.",
+      ],
+      recovery: [
+        "Stale or missing uid: call yunti_observe_page again for the current browserSessionId, or yunti_take_snapshot for compatibility workflows.",
+        "Element not visible: use observe scroll hints, yunti_scroll, or a screenshot before falling back to coordinates.",
+        "No visible page change: call yunti_observe_page or yunti_get_page_snapshot to verify, then wait, scroll, switch tabs, or ask the user instead of repeating the same click.",
+        "Wrong page: call yunti_list_browser_targets and switch to the intended browserSessionId.",
+      ],
+      commonMistakes: [
+        "Do not treat a successful dispatch as proof that the page changed.",
+        "Do not repeat the same uid click after a stale uid error; refresh the observation first.",
       ],
     },
     yunti_hover: {
-      purpose: "Hover by snapshot uid, CSS selector, or viewport coordinates.",
+      purpose: "Hover by observe/snapshot uid, CSS selector, or viewport coordinates.",
       required: [],
       recommended: ["browserSessionId", "uid"],
       notes: [
-        "Prefer uid from yunti_take_snapshot for reliability.",
+        "Prefer a fresh uid from yunti_observe_page or yunti_take_snapshot for reliability.",
         "Selector mode resolves the element center and dispatches CDP mouse move.",
         "Coordinate mode requires both x and y.",
+        "Observe again after hover when menus, tooltips, or hover-only controls are expected to appear.",
+        "Current results are compatibility-shaped and may include hovered, uid, selector/coordinate, method, and browserSessionId; P6.2 will converge action outputs toward action, target, ok/code, recoverable, nextStepHint, and before/after summaries.",
+      ],
+      recovery: [
+        "Stale or missing uid: observe again before retrying the hover.",
+        "Expected menu did not appear: wait briefly, observe again, or use screenshot before switching to coordinate fallback.",
       ],
     },
     yunti_fill: {
-      purpose: "Fill an input-like element by snapshot uid or CSS selector.",
+      purpose: "Fill an input-like element by observe/snapshot uid or CSS selector.",
       required: ["value"],
       recommended: ["browserSessionId", "uid", "value"],
       notes: [
         "value is required and may be an empty string when intentionally clearing a field.",
-        "Prefer uid from yunti_take_snapshot for reliability.",
+        "Prefer a fresh uid from yunti_observe_page or yunti_take_snapshot for reliability.",
         "Use selector when uid is unavailable.",
         "Coordinate-only fill is not supported; use uid or selector.",
+        "Uid-targeted contenteditable fills now report method=contenteditable with before/after textLength summaries; still verify the rendered text after the action.",
+        "Failed uid/selector fills may return structured filled=false diagnostics with ok=false, recoverable=true, code, recoveryHint, and nextStepHint instead of only a generic tool error.",
+        "Non-editable, hidden, disabled, or readonly fill targets should return TARGET_NOT_EDITABLE diagnostics instead of being treated as successful fills.",
+        "Uid keyboard/contenteditable fills verify the post-fill value when possible; if the value does not remain, they return VALUE_NOT_APPLIED with expectedValueLength/actualValueLength instead of exposing the raw field value.",
+        "When yunti_fill_form uses yunti_fill internally, failed per-field results may preserve code, recoveryHint, availableValues/availableTexts, and nextStepHint for field-level recovery.",
+        "After filling, verify through yunti_observe_page, yunti_get_page_snapshot, or yunti_evaluate_script when exact field value matters.",
+        "If the input is hidden, disabled, or no longer present, observe again, scroll, wait for rendering, or switch tabs before retrying.",
+        "Current results are compatibility-shaped and may include filled, uid, selector, method, value/valueLength, before/after, code, recoveryHint, and browserSessionId; P6.2 will converge action outputs toward action, target, ok/code, recoverable, nextStepHint, and richer before/after summaries.",
+      ],
+      recovery: [
+        "Stale or missing uid: call yunti_observe_page again and use a fresh editable uid.",
+        "Structured fill failure: follow recoveryHint.nextAction / recoveryHint.decision before retrying the same fill.",
+        "Batch fill partial failure: inspect each yunti_fill_form results[] item; failed fields may carry the same structured recovery details as yunti_fill.",
+        "Async render or validation changed the field: use yunti_wait_for for the expected text/selector/state, then call yunti_observe_page and retry with a fresh editable uid.",
+        "Field not editable: check disabled/editable fields from the observation, then wait, scroll, or ask the user if the control is gated.",
+        "Select option not found: inspect availableValues / availableTexts, then retry with an available option value/text or use yunti_select.",
+        "VALUE_NOT_APPLIED / value did not stick: inspect whether the target is contenteditable, masked, controlled by framework state, or requires typing/press_key semantics before retrying.",
+        "Wrong page: refresh targets with yunti_list_browser_targets and route the fill through the intended browserSessionId.",
       ],
       commonMistakes: [
         "Do not omit value.",
         "Do not pass only x/y coordinates to yunti_fill.",
+        "Do not keep retrying a fill without observing whether the field exists and is editable.",
+      ],
+    },
+    yunti_scroll: {
+      purpose: "Scroll the document, a fresh observed scrollable container uid, or the scrollable container under viewport coordinates.",
+      required: [],
+      recommended: ["browserSessionId", "uid", "deltaY"],
+      notes: [
+        "Prefer a fresh scrollable container uid from yunti_observe_page when the observation exposes scrollableContainers[].",
+        "Uid scroll resolves the observed container center and reuses the existing coordinate/container scroll path.",
+        "Coordinate scroll remains compatible for recovery and debugging when uid is unavailable.",
+        "Coordinate scroll results may include coordinateTarget, scrollContainerFound, coordinateScrollFallback=document, and coordinateFallbackHint so agents can tell whether the coordinate hit a scrollable container or fell back to document scrolling.",
+        "Current results preserve scrolled, deltaX/deltaY, target, before/after, browserSessionId, action, ok, recoverable, and nextStepHint; uid path also adds uid, method=uid, and scrollTarget without replacing target.",
+        "When before/after positions are comparable, results include moved; no movement returns code=NO_SCROLL_MOVEMENT, ok=false, recoverable=true, edgeHint such as possible-bottom-edge when direction can be inferred, and recoveryHint with nextAction/recommendedTools, decision, plus suggestedRetry when an opposite delta can be derived.",
+        "Partial movement returns partialMovement with requested/actual delta summaries, axes, edgeHint, decision=observe-before-continuing-scroll, and an observe-again next action while keeping ok=true.",
+        "Uid scroll failures can return structured scrolled=false diagnostics with code, recoveryHint, and nextStepHint when the uid is missing, stale, hidden, or cannot resolve coordinates.",
+      ],
+      recovery: [
+        "Stale or missing uid: follow recoveryHint.decision, call yunti_observe_page again, and use a fresh scrollable container uid from scrollableContainers[].",
+        "Wrong container moved or did not move: observe again and compare scrollableContainers before/after positions.",
+        "Coordinate fallback moved document instead of a nested panel: inspect coordinateTarget, coordinateScrollFallback, and coordinateFallbackHint; observe again and prefer a fresh scrollable container uid.",
+        "No movement: read recoveryHint.decision, edgeHint, and suggestedRetry; observe again, inspect likely scroll boundaries, try the nearest observed scrollable container uid, or stop repeating the same scroll.",
+        "Partial movement: read partialMovement, observe again, and compare scroll positions before repeating the same scroll.",
+        "Async content is still loading: use yunti_wait_for for the next expected text/selector, then observe again and choose a fresh scrollable container uid before retrying.",
+        "Element still outside viewport: scroll the nearest scrollable container first, then observe and act by fresh uid.",
+        "Wrong tab or stale route: refresh targets with yunti_list_browser_targets and route through the intended browserSessionId.",
+      ],
+      commonMistakes: [
+        "Do not assume document scroll will move nested app panels; use observed scrollable container uids when available.",
+        "Do not overwrite or reinterpret the existing target field; uid scroll adds scrollTarget while preserving target compatibility.",
+        "Do not blindly repeat scroll when moved=false or NO_SCROLL_MOVEMENT appears; read recoveryHint/edgeHint, observe, or inspect boundaries first.",
+        "Do not blindly repeat uid scroll when code=UID_NOT_FOUND or UID_COORDINATES_UNAVAILABLE appears; refresh observation first.",
+        "Do not blindly repeat partial scrolls without observing whether the target container hit an edge.",
+      ],
+    },
+    yunti_select: {
+      purpose: "Select an option in a select element by selector/value, fresh uid/value, or fresh uid/visible text while preserving the current selector/value path.",
+      required: [],
+      recommended: ["browserSessionId", "uid", "value"],
+      notes: [
+        "Current runtime behavior supports selector/value, uid/value, and uid/text; selector/value remains compatible for existing workflows.",
+        "Prefer a fresh uid from yunti_observe_page or yunti_take_snapshot when available, then verify the selected option afterward.",
+        "Use visible option text when the user-facing label is clearer than the option value.",
+        "Current successful results preserve selected, element, value, text, uid/selector, browserSessionId, action, target, ok, recoverable, and nextStepHint.",
+        "Uid and selector option misses, disabled options, and non-select targets now return structured selected=false diagnostics with code, matchMode, targetOption, availableValues/availableTexts when available, disabledValue/disabledText for disabled options, and recoveryHint.",
+      ],
+      recovery: [
+        "Selector path fails: observe again, inspect the select element, then retry with a stable selector or wait for the form to render.",
+        "Selector value does not match: read recoveryHint, inspect available options, then retry with the correct selector/value or fresh uid/value fallback.",
+        "Uid path fails: refresh with yunti_observe_page before retrying the same uid.",
+        "Option is not found: read recoveryHint, inspect available options via availableValues/availableTexts, then retry with the correct uid/text, uid/value, or selector/value fallback.",
+        "Option is disabled: read recoveryHint.disabledValue / disabledText, choose an enabled option, wait for the field to unlock, or ask the user before retrying.",
+        "Options are populated asynchronously: use yunti_wait_for for the expected option text or form state, then observe again and select with a fresh uid/text or uid/value.",
+        "Uid target is not a select element: read recoveryHint.decision, observe again, target the actual select uid, or use selector/value fallback.",
+        "Wrong tab or stale route: refresh targets with yunti_list_browser_targets and route through the intended browserSessionId.",
+      ],
+      commonMistakes: [
+        "Do not pass text without uid; selector path remains selector/value compatible.",
+        "Do not remove selector/value compatibility while adding uid support.",
+        "Do not treat a selected=true result as final proof when the workflow depends on the changed page state; observe or evaluate the field value.",
+        "Do not blindly retry the same selector if the page is still rendering or the option list is dynamic.",
       ],
     },
   }
   const topicMap = {
-    browser: ["yunti_get_page_snapshot", "yunti_list_browser_targets", "yunti_list_pages"],
+    browser: ["yunti_observe_page", "yunti_wait_for", "yunti_get_page_snapshot", "yunti_list_browser_targets", "yunti_list_pages"],
     cdp: ["yunti_cdp_send_command", "yunti_evaluate_script"],
     tabs: ["yunti_new_page", "yunti_close_page", "yunti_select_page", "yunti_list_browser_targets"],
     memory: ["yunti_get_learning_memory", "yunti_remember_learning", "yunti_forget_learning_memory"],
     network: ["yunti_get_network_log", "yunti_list_network_requests", "yunti_get_network_request", "yunti_clear_network_requests"],
     console: ["yunti_list_console_messages", "yunti_get_console_message", "yunti_clear_console_messages"],
+    workflow: ["yunti_get_tool_usage_hints", "yunti_list_browser_targets", "yunti_observe_page", "yunti_wait_for"],
   }
   const selectedNames = requestedTool
     ? [requestedTool]
@@ -1052,16 +1348,20 @@ export function toolUsageHints(args = {}) {
     }
   }
   return {
-    version: "2026-07-02",
+    version: "2026-07-05",
     coreRules: [
       "Every browser-facing yunti_* tool call requires userId.",
       "browserSessionId is the current user's browser route; tabId and targetId are selectors, not permissions.",
       "yunti_list_browser_targets is the canonical live browser inventory.",
       "yunti_list_pages is a compatibility alias for the same live target inventory.",
+      "For page operations, prefer observe -> act by fresh uid -> observe/verify once yunti_observe_page is available.",
       "If an old browserSessionId is disconnected or stale, call yunti_list_browser_targets with the current userId to recover the latest browserSessionId and live targets.",
       "After yunti_new_page, use the returned browserSessionId for follow-up calls on the new tab.",
       "Sessions expire quickly when the extension stops polling; stale-session errors include the reason and recovery hint.",
       "If a tool call fails due to parameters, inspect this hint output and the tool schema before retrying.",
+      "In 0.2.1+, default observe-first page actions avoid automatic Chrome debugger attachment; prefer yunti_observe_page plus fresh-uid yunti_click/yunti_hover/yunti_fill/yunti_select/yunti_scroll/yunti_type_text/yunti_press_key on anti-debug-sensitive pages.",
+      "Chrome debugger banners may still appear for explicit low-level or advanced tools such as yunti_cdp_send_command, raw CDP diagnostics, performance tracing, screenshot fallback paths, drag, upload, emulation, resize, or legacy snapshot compatibility.",
+      "Prefer sanitized diagnostics before raw CDP events; screenshots are visible pixels and are not DOM-redacted.",
     ],
     workflows: {
       newPage: [
@@ -1086,6 +1386,89 @@ export function toolUsageHints(args = {}) {
         "Call yunti_get_learning_memory to find the id.",
         "Call yunti_forget_learning_memory with that id.",
       ],
+      actionRecovery: [
+        "For page actions, prefer observe -> act by fresh uid -> observe/verify.",
+        "If an action fails with a stale or missing uid, refresh with yunti_observe_page before retrying.",
+        "If the element may be outside the viewport, use observe scroll hints and yunti_scroll before falling back to coordinates.",
+        "If the page is loading or changing, use yunti_wait_for or observe again instead of blind retries.",
+        "For async UI transitions, use yunti_wait_for for expected text/selector/state, read ok/code/nextStepHint, then yunti_observe_page, then continue with a fresh uid instead of reusing the old target.",
+        "If the target tab is uncertain, call yunti_list_browser_targets and switch to the intended browserSessionId.",
+        "Use selector or coordinate fallbacks only as recovery/debugging paths, not as the default when fresh uids are available.",
+      ],
+      defaultPageOperation: [
+        "Call yunti_get_tool_usage_hints when tool usage is uncertain.",
+        "Call yunti_list_browser_targets and choose the intended browserSessionId.",
+        "Call yunti_observe_page before page actions and use fresh uids whenever possible.",
+        "On anti-debug-sensitive pages, stay on the default observe-first action tools; do not switch to CDP unless explicitly needed.",
+        "After every action, verify by observing again or using snapshot, evaluate, screenshot, network, or console tools.",
+        "For async rendering, validation, navigation, option loading, or infinite scroll, call yunti_wait_for, then yunti_observe_page, then continue with a fresh uid.",
+        "If a result has ok=false, code, recoveryHint, or nextStepHint, follow that guidance before retrying.",
+        "Use selector or coordinate fallback only when fresh uids are unavailable or as an explicit recovery/debugging path.",
+      ],
+      confirmationBoundary: [
+        "Ask the user before submitting forms that change production data.",
+        "Ask the user before deleting, approving, purchasing, publishing, or sending messages.",
+        "Ask the user before uploading sensitive files.",
+        "Ask the user before exposing or copying secrets, credentials, cookies, auth headers, tokens, or private keys.",
+        "Ask the user before taking an action whose effect cannot be verified from page state.",
+      ],
+      copyableAgentPrompt: [
+        "Please operate my browser through Yunti Browser Runtime.",
+        "Call yunti_list_browser_targets, choose the intended browserSessionId, then use yunti_observe_page before page actions.",
+        "Prefer fresh uids for click, hover, fill, select, scroll, type, press, upload, and drag operations.",
+        "After each action or wait, observe again and verify the result before continuing.",
+        "For async UI, call yunti_wait_for, then yunti_observe_page, then continue with a fresh uid.",
+        "If ok=false, code, recoveryHint, or nextStepHint appears, follow that guidance before retrying.",
+        "Use selector or coordinate fallback only as recovery/debugging paths.",
+        "Ask me before submitting, deleting, approving, purchasing, publishing, uploading sensitive files, or changing production data.",
+        "Do not expose raw cookies, passwords, auth headers, tokens, private keys, or other secrets.",
+        "Prefer sanitized diagnostics; use raw CDP or screenshots only when needed, and summarize safe findings.",
+        "On anti-debug-sensitive pages, use observe-first page actions because 0.2.1+ avoids automatic Chrome debugger attachment on the default action path.",
+      ],
+      minimalUseCases: {
+        clickByUid: [
+          "Call yunti_list_browser_targets and select the intended browserSessionId.",
+          "Call yunti_observe_page and choose the target element uid from the fresh observation.",
+          "Call yunti_click with browserSessionId and uid.",
+          "Read ok, code, recoverable, recoveryHint, and nextStepHint; if recoverable, follow the hint before retrying.",
+          "Call yunti_observe_page again or use screenshot/evaluate to verify the expected page change.",
+        ],
+        fillForm: [
+          "Call yunti_observe_page and inspect field state: fillable, readOnly, disabled, fillBlockReason, selectedValue, selectedText, and options[].",
+          "Fill editable fields with yunti_fill using fresh uids; select options with yunti_select using uid/value or uid/text.",
+          "For multiple fields, use yunti_fill_form when fields are known and inspect per-field results[].",
+          "If async validation or option loading occurs, call yunti_wait_for, then yunti_observe_page, then continue with fresh uids.",
+          "Before submitting or changing production data, ask the user for confirmation.",
+        ],
+        scrollToFind: [
+          "Call yunti_observe_page and inspect scrollableContainers[].",
+          "Prefer yunti_scroll with a fresh scrollable container uid instead of document scroll for nested panels.",
+          "After scrolling, call yunti_observe_page and search the new textTree/elements for the target.",
+          "If moved=false, partialMovement, edgeHint, or recoveryHint appears, follow that guidance before repeating the same scroll.",
+          "When async content loads after scrolling, call yunti_wait_for, then yunti_observe_page, then continue with a fresh scroll container uid.",
+        ],
+        switchTab: [
+          "Call yunti_list_browser_targets to inspect current tabs and browser targets.",
+          "Choose the intended browserSessionId for Yunti page tools.",
+          "Use yunti_select_page when switching to a registered Yunti page route.",
+          "Use yunti_cdp_send_command with Target.activateTarget only for raw targetId/tabId browser target activation.",
+          "After switching, call yunti_observe_page or yunti_get_page_snapshot to verify the active page before acting.",
+        ],
+        waitForAsyncResult: [
+          "Call yunti_wait_for with expected text, selector, or urlContains.",
+          "If ok=true, call yunti_observe_page and use fresh uids for follow-up actions.",
+          "If code=WAIT_TIMEOUT, observe or inspect current page state before adjusting the condition or retrying.",
+          "Do not reuse pre-wait uids for newly rendered content.",
+          "Verify the final result with observe, snapshot, evaluate, screenshot, network, or console tools.",
+        ],
+      },
+      actionResultContract: [
+        "Current action outputs are compatibility-shaped: click/hover/fill/scroll/wait may return clicked, hovered, filled, scrolled, found, uid, selector, x/y, method, valueLength, waitedMs, before/after, and browserSessionId depending on the tool path.",
+        "P6.2 target shape should be additive and structured: action, browserSessionId, target, ok, code, recoverable, nextStepHint, and before/after summaries where useful.",
+        "Do not remove existing success booleans or selector/coordinate fields while converging on the structured result contract.",
+        "Treat successful dispatch as transport/action execution evidence, then verify page state with yunti_observe_page, yunti_get_page_snapshot, yunti_evaluate_script, screenshot, or CDP when the workflow needs proof.",
+        "Recoverable failures should clearly point to observe, scroll, wait, switch tabs, selector/coordinate fallback, or asking the user.",
+      ],
     },
     tools: selectedTools,
   }