yunti-browser-runtime 0.1.2 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yunti-browser-runtime",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Local browser runtime and MCP tools for AI agents.",
   "license": "MIT",
@@ -39,11 +39,13 @@
   "scripts": {
     "mcp": "node mcp/server.js",
     "bridge": "YUNTI_BROWSER_BRIDGE_ONLY=1 node mcp/server.js",
+    "console": "YUNTI_BROWSER_BRIDGE_ONLY=1 node mcp/server.js",
     "doctor": "node scripts/doctor.js",
     "doctor:json": "node scripts/doctor.js 2>/dev/null",
     "print-config": "node scripts/print-config.js",
     "package:extension": "node scripts/package-extension.js",
     "check:metadata": "node scripts/check-package-metadata.js",
+    "check:action-results": "node scripts/check-action-result-coverage.js",
     "release:check": "node scripts/release-check.js",
     "release:prepublish": "npm run check:metadata && npm run release:check",
     "release:whoami": "npm whoami --registry=https://registry.npmjs.org/",
@@ -52,7 +54,7 @@
     "release:verify-published": "node scripts/check-published-package.js",
     "test": "node --test tests/*.test.js",
     "test:e2e": "node --test tests/e2e.test.js",
-    "check": "node --check bin/yunti-browser-runtime.js && node --check lib/runtime-paths.js && node --check mcp/server.js && node --check mcp/http-server.js && node --check mcp/bridge-hub.js && node --check mcp/tools.js && node --check mcp/redaction.js && node --check mcp/memory.js && node --check mcp/json-rpc.js && node --check scripts/doctor.js && node --check scripts/print-config.js && node --check scripts/package-extension.js && node --check scripts/check-package-metadata.js && node --check scripts/check-published-package.js && node --check scripts/release-check.js && node --check tests/e2e.test.js && node --check extension/background.js && node --check extension/cdp.js && node --check extension/session-manager.js && node --check extension/tool-handlers.js && node --check extension/settings.js && node --check extension/network-monitor.js && node --check extension/content.js && node --check extension/popup.js"
+    "check": "node --check bin/yunti-browser-runtime.js && node --check lib/runtime-paths.js && node --check mcp/server.js && node --check mcp/http-server.js && node --check mcp/bridge-hub.js && node --check mcp/tools.js && node --check mcp/redaction.js && node --check mcp/memory.js && node --check mcp/json-rpc.js && node --check scripts/doctor.js && node --check scripts/print-config.js && node --check scripts/package-extension.js && node --check scripts/check-package-metadata.js && node --check scripts/check-published-package.js && node --check scripts/check-action-result-coverage.js && node --check scripts/release-check.js && node --check tests/e2e.test.js && node --check extension/background.js && node --check extension/cdp.js && node --check extension/session-manager.js && node --check extension/tool-handlers.js && node --check extension/settings.js && node --check extension/network-monitor.js && node --check extension/dom-observer.js && node --check extension/content.js && node --check extension/popup.js"
   },
   "engines": {
     "node": ">=22"

package/scripts/check-action-result-coverage.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const rootDir = resolve(dirname(fileURLToPath(import.meta.url)), "..")
+const coveragePath = join(rootDir, "docs", "ACTION_RESULT_COVERAGE.md")
+const text = readFileSync(coveragePath, "utf8")
+
+const requiredRows = {
+  yunti_click: {
+    success: ["uid", "coordinate", "selector"],
+    failure: ["stale uid", "missing uid"],
+    compatibility: ["clicked", "browserSessionId"],
+  },
+  yunti_hover: {
+    success: ["uid", "coordinate", "selector"],
+    failure: ["stale uid", "missing uid"],
+    compatibility: ["hovered", "browserSessionId"],
+  },
+  yunti_fill: {
+    success: ["uid keyboard", "uid select", "uid contenteditable", "selector"],
+    failure: ["non-editable", "disabled", "readonly", "value not applied"],
+    compatibility: ["filled", "browserSessionId"],
+  },
+  yunti_select: {
+    success: ["selector value", "uid value", "uid text"],
+    failure: ["option miss", "disabled option", "non-select target"],
+    compatibility: ["selected", "browserSessionId"],
+  },
+  yunti_fill_form: {
+    success: ["aggregate success", "partial failure"],
+    failure: ["per-field"],
+    compatibility: ["filled", "failed", "results"],
+  },
+  yunti_wait_for: {
+    success: ["text", "selector", "urlContains"],
+    failure: ["timeout"],
+    compatibility: ["found", "waitedMs", "browserSessionId"],
+  },
+  yunti_scroll: {
+    success: ["document", "uid container", "coordinate container"],
+    failure: ["uid missing", "no movement", "partial movement"],
+    compatibility: ["scrolled", "before", "after"],
+  },
+  yunti_type_text: {
+    success: ["uid", "selector"],
+    failure: ["stale uid", "missing uid"],
+    compatibility: ["typed", "browserSessionId"],
+  },
+  yunti_press_key: {
+    success: ["uid", "selector"],
+    failure: ["stale uid", "missing uid"],
+    compatibility: ["pressed", "browserSessionId"],
+  },
+  yunti_upload_file: {
+    success: ["uid", "selector"],
+    failure: ["stale uid", "missing uid"],
+    compatibility: ["uploaded", "fileCount", "browserSessionId"],
+  },
+  yunti_drag: {
+    success: ["coordinate"],
+    failure: ["coordinate argument validation"],
+    compatibility: ["dragged", "browserSessionId"],
+  },
+}
+
+function normalize(value) {
+  return String(value || "")
+    .replace(/`/g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+}
+
+function parseMatrixRows(markdown) {
+  const rows = new Map()
+  for (const line of markdown.split(/\r?\n/)) {
+    if (!line.startsWith("| `yunti_")) continue
+    const cells = line
+      .split("|")
+      .slice(1, -1)
+      .map((cell) => normalize(cell))
+    if (cells.length < 5) continue
+    rows.set(cells[0], {
+      tool: cells[0],
+      success: cells[1],
+      failure: cells[2],
+      compatibility: cells[3],
+      remaining: cells[4],
+    })
+  }
+  return rows
+}
+
+function includesAll(value, terms) {
+  const haystack = normalize(value).toLowerCase()
+  return terms.filter((term) => !haystack.includes(term.toLowerCase()))
+}
+
+const rows = parseMatrixRows(text)
+const errors = []
+
+for (const [tool, expectation] of Object.entries(requiredRows)) {
+  const row = rows.get(tool)
+  if (!row) {
+    errors.push(`missing coverage row for ${tool}`)
+    continue
+  }
+
+  for (const [column, terms] of Object.entries(expectation)) {
+    const missing = includesAll(row[column], terms)
+    if (missing.length) {
+      errors.push(`${tool} ${column} column missing: ${missing.join(", ")}`)
+    }
+  }
+
+  for (const [column, value] of Object.entries(row)) {
+    if (column === "tool") continue
+    if (!value || /\b(TBD|TODO|unknown)\b/i.test(value)) {
+      errors.push(`${tool} ${column} column is incomplete: ${value || "(empty)"}`)
+    }
+  }
+}
+
+const requiredSnippets = [
+  "Last audited phase: P6.2.7",
+  "npm run check:action-results",
+  "npm run release:check",
+  "Real browser closure: Pending",
+  "YUNTI_E2E=1 npm run test:e2e",
+]
+
+for (const snippet of requiredSnippets) {
+  if (!text.includes(snippet)) {
+    errors.push(`coverage gate missing snippet: ${snippet}`)
+  }
+}
+
+if (errors.length) {
+  console.error("Action result coverage check failed:")
+  for (const error of errors) console.error(`- ${error}`)
+  process.exit(1)
+}
+
+console.error(`Action result coverage check passed (${rows.size} rows).`)

package/scripts/doctor.js

@@ -68,6 +68,7 @@ async function checkBridge() {
       authRequired,
       status: health.status,
       url: bridgeUrl,
+      consoleUrl: `${bridgeUrl}/console`,
       tokenConfigured: Boolean(bridgeToken),
       tokenHeader: bridgeTokenHeader,
       userId: routeUserId,
@@ -85,6 +86,7 @@ async function checkBridge() {
       authorized: false,
       authRequired: Boolean(bridgeToken),
       url: bridgeUrl,
+      consoleUrl: `${bridgeUrl}/console`,
       tokenConfigured: Boolean(bridgeToken),
       tokenHeader: bridgeTokenHeader,
       userId: routeUserId,
@@ -119,6 +121,7 @@ function buildNextSteps(checks) {
   }
   if (checks.bridge.ok && !checks.bridge.extensionConnected) {
     steps.push("Load the extension, open an http/https page, then refresh the target page.")
+    steps.push(`Open the optional local console for live status: ${checks.bridge.consoleUrl}.`)
   }
   if (!checks.mcpServer.ok) {
     steps.push(`Restore the MCP server file at ${checks.mcpServer.path}.`)
@@ -134,6 +137,7 @@ function humanSummary(report) {
     `Yunti Browser Runtime doctor: ${report.ok ? "OK" : "needs attention"}`,
     `- Node: ${report.checks.node.version} (${report.checks.node.ok ? "ok" : "requires >=22"})`,
     `- Bridge: ${report.checks.bridge.reachable ? report.checks.bridge.url : "not reachable"}`,
+    `- Console: ${report.checks.bridge.reachable ? report.checks.bridge.consoleUrl : "not available until bridge starts"}`,
     `- Token: ${report.checks.bridge.authRequired ? report.checks.bridge.authorized ? "valid" : "missing or invalid" : "not required for local loopback"}`,
     `- Sessions: ${report.checks.bridge.visibleSessionCount} visible, active ${report.checks.bridge.activeSessionId || "none"}`,
     `- Extension: ${report.checks.bridge.extensionConnected ? "connected" : "not detected"}`,

package/scripts/package-extension.js

@@ -19,6 +19,7 @@ const allowedFiles = [
   "background.js",
   "cdp.js",
   "content.css",
+  "dom-observer.js",
   "content.js",
   "network-monitor.js",
   "manifest.json",

package/scripts/print-config.js

@@ -95,7 +95,7 @@ function humanOutput(payload) {
     "",
     `Project root: ${payload.projectRoot}`,
     `MCP server: ${payload.mcpServerPath}`,
-    `Bridge port: ${payload.bridge.port}`,
+    `Bridge port: ${payload.bridge.port} (started automatically by the MCP server)`,
     `Token: ${payload.bridge.tokenInstruction}`,
     `Skill: ${payload.skill.sourcePath}`,
     payload.ok ? "" : `Unsupported agent "${payload.agent}". Supported: ${payload.supportedAgents.join(", ")}`,

package/scripts/release-check.js

@@ -11,6 +11,7 @@ const requiredExtensionZipFiles = [
   "background.js",
   "cdp.js",
   "content.css",
+  "dom-observer.js",
   "content.js",
   "network-monitor.js",
   "manifest.json",
@@ -327,6 +328,7 @@ function checkPackageContents() {
     "extension/manifest.json",
     "extension/background.js",
     "extension/content.js",
+    "extension/dom-observer.js",
     "extension/cdp.js",
     "extension/session-manager.js",
     "extension/tool-handlers.js",
@@ -464,6 +466,7 @@ ok = checkVersionConsistency() && ok
 ok = checkCliSmoke() && ok
 ok = checkPrintConfigSmoke() && ok
 ok = checkDoctorSmoke() && ok
+ok = run("npm", ["run", "check:action-results"]) && ok
 ok = run("npm", ["run", "check"]) && ok
 ok = run("npm", ["test"]) && ok
 ok = checkPackageContents() && ok

package/skills/yunti-browser-runtime/SKILL.md

@@ -11,6 +11,61 @@ For any browser task, first call `yunti_get_tool_usage_hints` unless the user is
 
 Then call `yunti_list_browser_targets` to understand the live browser state before choosing a page or tab.
 
+## Default Page Operation Contract
+
+1. Call `yunti_get_tool_usage_hints` when tool usage is uncertain.
+2. Call `yunti_list_browser_targets` and choose the intended `browserSessionId`.
+3. Call `yunti_observe_page` before page actions.
+4. Prefer fresh uids for click, hover, fill, select, scroll, type, press, upload, and drag operations.
+5. After each action, verify by observing again or using snapshot, evaluate, screenshot, network, or console tools.
+6. For async rendering, validation, navigation, option loading, or infinite scroll, call `yunti_wait_for`, then `yunti_observe_page`, then continue with a fresh uid.
+7. If a result has `ok: false`, `code`, `recoveryHint`, or `nextStepHint`, follow that guidance before retrying.
+8. Use selector or coordinate fallback only when fresh uids are unavailable or as an explicit recovery/debugging path.
+
+Ask the user before submitting, deleting, approving, purchasing, publishing, uploading sensitive files, changing production data, exposing secrets, or taking an action whose effect cannot be verified from page state.
+
+## Minimal Use Cases
+
+### Click
+
+1. Call `yunti_list_browser_targets` and select the intended `browserSessionId`.
+2. Call `yunti_observe_page` and choose the target element uid from the fresh observation.
+3. Call `yunti_click` with `browserSessionId` and `uid`.
+4. Read `ok`, `code`, `recoverable`, `recoveryHint`, and `nextStepHint`; if recoverable, follow the hint before retrying.
+5. Call `yunti_observe_page` again or use screenshot/evaluate to verify the expected page change.
+
+### Fill Form
+
+1. Call `yunti_observe_page` and inspect field state: `fillable`, `readOnly`, `disabled`, `fillBlockReason`, `selectedValue`, `selectedText`, and `options[]`.
+2. Fill editable fields with `yunti_fill` using fresh uids; select options with `yunti_select` using `uid` / `value` or `uid` / `text`.
+3. For multiple fields, use `yunti_fill_form` when fields are known and inspect per-field `results[]`.
+4. If async validation or option loading occurs, call `yunti_wait_for`, then `yunti_observe_page`, then continue with fresh uids.
+5. Before submitting or changing production data, ask the user for confirmation.
+
+### Scroll To Find
+
+1. Call `yunti_observe_page` and inspect `scrollableContainers[]`.
+2. Prefer `yunti_scroll` with a fresh scrollable container uid instead of document scroll for nested panels.
+3. After scrolling, call `yunti_observe_page` and search the new `textTree` / `elements` for the target.
+4. If `moved: false`, `partialMovement`, `edgeHint`, or `recoveryHint` appears, follow that guidance before repeating the same scroll.
+5. When async content loads after scrolling, call `yunti_wait_for`, then `yunti_observe_page`, then continue with a fresh scroll container uid.
+
+### Switch Tab
+
+1. Call `yunti_list_browser_targets` to inspect current tabs and browser targets.
+2. Choose the intended `browserSessionId` for Yunti page tools.
+3. Use `yunti_select_page` when switching to a registered Yunti page route.
+4. Use `yunti_cdp_send_command` with `Target.activateTarget` only for raw `targetId` / `tabId` browser target activation.
+5. After switching, call `yunti_observe_page` or `yunti_get_page_snapshot` to verify the active page before acting.
+
+### Wait For Async Result
+
+1. Call `yunti_wait_for` with expected `text`, `selector`, or `urlContains`.
+2. If `ok: true`, call `yunti_observe_page` and use fresh uids for follow-up actions.
+3. If `code: "WAIT_TIMEOUT"`, observe or inspect current page state before adjusting the condition or retrying.
+4. Do not reuse pre-wait uids for newly rendered content.
+5. Verify the final result with observe, snapshot, evaluate, screenshot, network, or console tools.
+
 ## Routing Rules
 
 - Treat `yunti_list_browser_targets` as the canonical live browser inventory.
@@ -24,7 +79,9 @@ Then call `yunti_list_browser_targets` to understand the live browser state befo
 ## Tool Choice
 
 - Use `yunti_get_page_snapshot` for lightweight page text, title, URL, selected text, and page state.
-- Use `yunti_take_snapshot` before uid-based clicks, fills, or hovers.
+- Once available in the connected runtime, use `yunti_observe_page` as the normal page-operation refresh step, then act by fresh uid and observe again to verify.
+- Observation elements may expose `editable`, `fillable`, `readOnly`, `fillBlockReason`, select `selectedIndex` / `selectedValue` / `selectedText`, and `options[]`; inspect those before filling or selecting when field state matters.
+- Use `yunti_take_snapshot` as the compatibility path before uid-based clicks, fills, or hovers.
 - Use `yunti_click`, `yunti_fill`, `yunti_hover`, `yunti_press_key`, and `yunti_type_text` for normal page actions.
 - Use `yunti_take_screenshot` for visual verification.
 - Use `yunti_list_browser_targets` for tab counts, tab selection, target IDs, and whole-browser awareness.
@@ -56,22 +113,88 @@ Then call `yunti_list_browser_targets` to understand the live browser state befo
 
 ## Parameter Rules
 
-- `yunti_click` and `yunti_hover` need `uid`, `selector`, or both `x` and `y`; call `yunti_take_snapshot` first when possible.
+- `yunti_click` and `yunti_hover` need `uid`, `selector`, or both `x` and `y`; prefer a fresh uid from `yunti_observe_page` once available, or call `yunti_take_snapshot` for the current compatibility path.
 - `yunti_fill` requires `value` plus `uid` or `selector`; coordinate-only fill is not supported.
 - `yunti_close_page` accepts `browserSessionId`, not raw `tabId` or `targetId`; use `yunti_cdp_send_command` with `Target.closeTarget` for raw browser targets.
 - `yunti_forget_learning_memory` needs a memory `id`, or `all=true` and `confirmed=true` for deleting everything.
+- `yunti_remember_learning` is for durable patterns and gotchas, not transcripts or raw payloads. It sanitizes likely secrets and PII-like text before storage, but do not intentionally submit secrets, cookies, auth headers, private keys, payment data, or personal contact details.
+
+## Action Recovery
+
+- After `yunti_click`, `yunti_fill`, or `yunti_hover`, observe again or read page state before assuming the action succeeded.
+- If a uid is stale or missing, call `yunti_observe_page` again and retry with a fresh uid.
+- If an 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, wait or observe again instead of blindly repeating the same action.
+- For async UI transitions, use `yunti_wait_for` for expected text, selector, or page state, then call `yunti_observe_page` and continue with a fresh uid instead of reusing an old target.
+- Read `yunti_wait_for` structured fields when present: `ok: true` means the condition matched; `code: "WAIT_TIMEOUT"` means observe or adjust the condition before repeating the same wait.
+- If the target tab is uncertain, call `yunti_list_browser_targets` and continue with the intended `browserSessionId`.
+
+## Action Results
+
+- Current action results may use compatibility fields such as `clicked`, `hovered`, `filled`, `selected`, `scrolled`, `typed`, `pressed`, `uploaded`, `dragged`, aggregate counts like `failed`, per-field `results`, wait fields like `found` / `waitedMs`, `uid`, `selector`, coordinates, `method`, `valueLength`, `before`, `after`, and `browserSessionId`.
+- Structured P6.2 fields are additive when present: prefer `action`, `target`, `ok`, `recoverable`, and `nextStepHint`, while still reading existing compatibility fields.
+- Treat action results as execution evidence, then verify page state when the task depends on the result.
+- Do not require agents to abandon existing result fields while structured action results are being introduced.
+
+## Wait Guidance
+
+- Use `yunti_wait_for` when async rendering, navigation, validation, dynamic select options, or infinite-scroll content needs time to appear.
+- Provide at least one of `text`, `selector`, or `urlContains`; set `timeoutMs` only when the default is not appropriate.
+- Successful waits preserve compatibility fields such as `found`, `text`, `selector`, `condition`, `value`, `waitedMs`, and `browserSessionId`, and may include `action: "wait_for"`, `target`, `ok: true`, `recoverable: false`, and `nextStepHint`.
+- Timeout waits return `found: false`, `ok: false`, `recoverable: true`, `code: "WAIT_TIMEOUT"`, `recoveryHint`, and `nextStepHint`.
+- After a successful wait, call `yunti_observe_page` again and use fresh uids for newly rendered elements. After a timeout, observe or inspect current page state before changing the wait condition or retrying.
+
+## Fill Guidance
+
+- Prefer a fresh `uid` from `yunti_observe_page` or `yunti_take_snapshot` when filling inputs, textareas, selects, or contenteditable targets.
+- Before filling, inspect observation fields such as `fillable`, `readOnly`, `disabled`, `fillBlockReason`, and select `selectedValue` / `selectedText` / `options[]` when available.
+- Uid-targeted contenteditable fills return `method: "contenteditable"` and may include `before` / `after` text length summaries.
+- Treat contenteditable fill results as dispatch evidence, then verify with observe, snapshot, evaluate `textContent`, or a page-specific assertion when exact editor state matters.
+- Selector-based fill remains compatible and may return content-script-shaped fields such as `element` or `valueLength`.
+- Uid and selector fill failures may return structured `filled: false` diagnostics with `code`, `ok: false`, `recoverable: true`, `recoveryHint`, and `nextStepHint`; follow `recoveryHint.nextAction` / `decision` before repeating the same fill.
+- If a field appears after async rendering or validation, wait with `yunti_wait_for`, observe again, and fill with a fresh editable uid.
+- Non-editable, hidden, disabled, or readonly fill targets may return `code: "TARGET_NOT_EDITABLE"`; inspect the target, wait/unlock the field, or choose a different editable uid/selector before retrying.
+- Uid keyboard/contenteditable fills may return `code: "VALUE_NOT_APPLIED"` when the post-fill value does not remain. Use the length-only diagnostics (`expectedValueLength`, `actualValueLength`) and `recoveryHint.decision` to inspect controlled/masked fields before retrying; raw field values are not echoed in this diagnostic.
+- Select-option fill misses may include `availableValues` / `availableTexts`; inspect those options before retrying with `yunti_fill` or `yunti_select`.
+- `yunti_fill_form` preserves per-field compatibility results and may carry the same structured failure details on failed `results[]` items, including `code`, `recoveryHint`, `availableValues` / `availableTexts`, and `nextStepHint`.
+
+## Scroll Guidance
+
+- Prefer a fresh `scrollableContainers[]` uid from `yunti_observe_page` when scrolling nested app panels or sidebars.
+- Uid-targeted scroll resolves the observed container center and reuses the existing coordinate/container scroll path, so coordinate recovery remains compatible.
+- Uid scroll preserves the existing `target` compatibility field and adds `uid`, `method: "uid"`, and `scrollTarget` for structured interpretation.
+- Coordinate scroll results may include `coordinateTarget`, `scrollContainerFound`, `coordinateScrollFallback: "document"`, and `coordinateFallbackHint`; when document fallback appears, observe again and prefer a fresh `scrollableContainers[]` uid for nested panels.
+- When `before` / `after` positions are comparable, scroll results include `moved`; if positions do not change, the result reports `code: "NO_SCROLL_MOVEMENT"`, `ok: false`, `recoverable: true`, directional `edgeHint` values, and a structured `recoveryHint` with `nextAction` / `recommendedTools`, machine-readable `decision`, plus `suggestedRetry` when an opposite delta can be derived.
+- If scroll moves less than requested, results may keep `ok: true` and include `partialMovement` with requested/actual deltas, axes, `edgeHint`, `decision: "observe-before-continuing-scroll"`, and `nextAction: "observe-again"`; observe again before repeating the same scroll.
+- Uid scroll failures may return structured `scrolled: false` diagnostics with `code` such as `UID_NOT_FOUND` or `UID_COORDINATES_UNAVAILABLE`, plus `recoveryHint.decision: "refresh-scrollable-container-uid-before-retry"`; refresh observation and choose a fresh `scrollableContainers[]` uid before retrying.
+- After scrolling, observe again and compare document or container `before` / `after` positions before assuming the needed element is visible. Stop repeating the same scroll when `moved: false` appears; use `recoveryHint`, `decision`, `edgeHint`, and `suggestedRetry` to choose a different container, direction, or recovery path.
+- If scrolling depends on newly loaded content, use `yunti_wait_for`, observe again, and choose a fresh `scrollableContainers[]` uid before continuing.
+
+## Select Guidance
+
+- Current `yunti_select` runtime behavior supports selector/value, uid/value, and uid/visible text.
+- Use `text` with a fresh uid when the user-facing option label is clearer than the option value; selector path remains selector/value compatible.
+- Uid and selector option misses, disabled options, plus non-select targets return structured `selected: false` diagnostics with `code`, `matchMode`, `targetOption`, and `recoveryHint`; option misses include `availableValues` / `availableTexts` when available, and disabled-option failures can include `disabledValue` / `disabledText`.
+- Before retrying a failed select, inspect available options with observe, snapshot, evaluate, a stable selector, or `recoveryHint.decision` instead of blindly repeating it.
+- If select options are populated asynchronously, wait with `yunti_wait_for`, observe again, and select with a fresh uid/value or uid/text.
 
 ## Safety
 
 - Read-only inspection is allowed by default.
 - Before submitting forms, deleting data, uploading sensitive files, approving workflows, making purchases, or changing production data, ask the user for explicit confirmation.
 - Do not expose raw cookies, passwords, authorization headers, or token-like values.
+- Prefer sanitized network and console diagnostics before raw CDP events.
+- Treat `yunti_get_cdp_events` as raw low-level diagnostics. Filter by `method`, keep `limit` small, clear it after debugging with `yunti_clear_cdp_events`, and do not copy raw CDP payloads into chat, docs, or learning memory.
+- Use `yunti_observe_page` with `redaction: "strict"` when a page may contain personal information. Strict DOM redaction hides likely email, phone, Luhn-valid payment-card-like values, address-like text, page titles, labels, names, visible text, placeholders, values, and select option text.
+- Keep `redaction: "off"` only for explicit local debugging.
 - If a tool output appears to include sensitive data, summarize only the safe parts.
+- DOM observation redaction does not mean screenshots are redacted; treat screenshots as visible page pixels. Use screenshots only when visual proof is needed, prefer viewport captures when enough, and summarize safe visual findings instead of storing raw images in learning memory.
 
 ## Recovery
 
 - No connected tab: ask the user to open a page, load the extension, or refresh the page.
 - Stale session: call `yunti_list_browser_targets` and use the latest `browserSessionId`.
+- Stale or missing page uid: observe again once `yunti_observe_page` is available, or take a fresh snapshot for compatibility workflows.
 - Wrong tab: use `yunti_list_browser_targets` to find the intended tab, then route CDP with that tab's `tabId` or `targetId`.
 - Parameter uncertainty: call `yunti_get_tool_usage_hints` with the specific tool name.
 - Missing memory id: call `yunti_get_learning_memory` first, then retry with a returned `id`.