@yuzc-001/grasp 0.6.6

package/scripts/update-star-history.mjs

@@ -0,0 +1,274 @@
+import { writeFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const repository = process.env.STAR_HISTORY_REPO || process.env.GITHUB_REPOSITORY || 'Yuzc-001/grasp';
+const [owner, repo] = repository.split('/');
+
+if (!owner || !repo) {
+  throw new Error(`Invalid repository name: ${repository}`);
+}
+
+const outputPath = new URL('../star-history.svg', import.meta.url);
+const token = process.env.GITHUB_TOKEN;
+
+async function main() {
+  const starredAtValues = await fetchStargazers();
+  const series = buildSeries(starredAtValues);
+  const svg = buildSvg(series);
+
+  await writeFile(outputPath, svg, 'utf8');
+  console.log(`Updated ${fileURLToPath(outputPath)} with ${series.at(-1)?.count ?? 0} stars`);
+}
+
+async function fetchStargazers() {
+  try {
+    return await fetchStargazersWithToken(token);
+  } catch (error) {
+    if (token && error?.status === 401) {
+      console.warn('GITHUB_TOKEN is invalid locally, retrying without authentication');
+      return fetchStargazersWithToken();
+    }
+
+    throw error;
+  }
+}
+
+async function fetchStargazersWithToken(authToken) {
+  const headers = {
+    Accept: 'application/vnd.github.v3.star+json',
+    'User-Agent': 'grasp-star-history-updater',
+    'X-GitHub-Api-Version': '2022-11-28',
+  };
+
+  if (authToken) {
+    headers.Authorization = `Bearer ${authToken}`;
+  }
+
+  const starredAtValues = [];
+
+  for (let page = 1; ; page += 1) {
+    const response = await fetch(
+      `https://api.github.com/repos/${owner}/${repo}/stargazers?per_page=100&page=${page}`,
+      { headers },
+    );
+
+    if (!response.ok) {
+      const body = await response.text();
+      const error = new Error(
+        `GitHub API request failed on page ${page}: ${response.status} ${response.statusText}\n${body}`,
+      );
+      error.status = response.status;
+      throw error;
+    }
+
+    const entries = await response.json();
+
+    if (!Array.isArray(entries) || entries.length === 0) {
+      break;
+    }
+
+    for (const entry of entries) {
+      if (entry?.starred_at) {
+        starredAtValues.push(entry.starred_at);
+      }
+    }
+
+    if (entries.length < 100) {
+      break;
+    }
+  }
+
+  return starredAtValues.sort((left, right) => Date.parse(left) - Date.parse(right));
+}
+
+function buildSeries(starredAtValues) {
+  const today = toUtcDay(new Date());
+
+  if (starredAtValues.length === 0) {
+    return [{ date: today, count: 0 }];
+  }
+
+  const dailyAdds = new Map();
+
+  for (const value of starredAtValues) {
+    const day = toUtcDay(value);
+    dailyAdds.set(day, (dailyAdds.get(day) || 0) + 1);
+  }
+
+  const startDay = [...dailyAdds.keys()].sort()[0];
+  const series = [];
+  let running = 0;
+
+  for (
+    let cursor = new Date(`${startDay}T00:00:00Z`);
+    cursor <= new Date(`${today}T00:00:00Z`);
+    cursor.setUTCDate(cursor.getUTCDate() + 1)
+  ) {
+    const day = toUtcDay(cursor);
+    running += dailyAdds.get(day) || 0;
+    series.push({ date: day, count: running });
+  }
+
+  return series;
+}
+
+function buildSvg(series) {
+  const width = 960;
+  const height = 540;
+  const padding = { top: 76, right: 34, bottom: 52, left: 76 };
+  const plotWidth = width - padding.left - padding.right;
+  const plotHeight = height - padding.top - padding.bottom;
+  const lastPoint = series.at(-1);
+  const updatedDay = toUtcDay(new Date());
+  const xDivisor = Math.max(series.length - 1, 1);
+  const { ceiling, ticks } = buildYTicks(lastPoint.count);
+
+  const scaleX = (index) => padding.left + (plotWidth * index) / xDivisor;
+  const scaleY = (value) => padding.top + plotHeight - (plotHeight * value) / ceiling;
+
+  const points = series.map((point, index) => ({
+    x: Number(scaleX(index).toFixed(2)),
+    y: Number(scaleY(point.count).toFixed(2)),
+    date: point.date,
+    count: point.count,
+  }));
+
+  const polylinePoints = points.map((point) => `${point.x},${point.y}`).join(' ');
+  const areaPoints = [
+    `${padding.left},${padding.top + plotHeight}`,
+    ...points.map((point) => `${point.x},${point.y}`),
+    `${padding.left + plotWidth},${padding.top + plotHeight}`,
+  ].join(' ');
+
+  const xTickIndices = buildTickIndices(series.length, 5);
+  const yGrid = ticks
+    .map((tick) => {
+      const y = scaleY(tick);
+      return [
+        `<line x1="${padding.left}" y1="${y}" x2="${padding.left + plotWidth}" y2="${y}" stroke="#D7E3F4" stroke-width="1" />`,
+        `<text x="${padding.left - 12}" y="${y + 4}" text-anchor="end" font-size="12" fill="#48617D">${formatNumber(tick)}</text>`,
+      ].join('');
+    })
+    .join('');
+
+  const xLabels = xTickIndices
+    .map((index) => {
+      const point = points[index];
+      return [
+        `<line x1="${point.x}" y1="${padding.top + plotHeight}" x2="${point.x}" y2="${padding.top + plotHeight + 6}" stroke="#B6C8DE" stroke-width="1" />`,
+        `<text x="${point.x}" y="${padding.top + plotHeight + 24}" text-anchor="middle" font-size="12" fill="#48617D">${escapeXml(formatDate(point.date))}</text>`,
+      ].join('');
+    })
+    .join('');
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-labelledby="title desc">
+  <title id="title">${escapeXml(repository)} star history</title>
+  <desc id="desc">${escapeXml(`Cumulative GitHub stars for ${repository} from ${series[0].date} to ${lastPoint.date}.`)}</desc>
+  <defs>
+    <linearGradient id="areaFill" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#38BDF8" stop-opacity="0.28" />
+      <stop offset="100%" stop-color="#38BDF8" stop-opacity="0.04" />
+    </linearGradient>
+    <linearGradient id="lineStroke" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#0EA5E9" />
+      <stop offset="100%" stop-color="#2563EB" />
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="${width}" height="${height}" rx="22" fill="#F8FBFF" />
+  <rect x="1.5" y="1.5" width="${width - 3}" height="${height - 3}" rx="20.5" fill="none" stroke="#D7E3F4" stroke-width="3" />
+
+  <text x="${padding.left}" y="42" font-size="26" font-weight="700" fill="#0F172A">Star History</text>
+  <text x="${padding.left}" y="64" font-size="13" fill="#48617D">${escapeXml(repository)}</text>
+  <text x="${width - padding.right}" y="42" text-anchor="end" font-size="24" font-weight="700" fill="#0F172A">${formatNumber(lastPoint.count)}</text>
+  <text x="${width - padding.right}" y="64" text-anchor="end" font-size="13" fill="#48617D">Updated ${escapeXml(updatedDay)} UTC</text>
+
+  ${yGrid}
+  <line x1="${padding.left}" y1="${padding.top + plotHeight}" x2="${padding.left + plotWidth}" y2="${padding.top + plotHeight}" stroke="#94AFCB" stroke-width="1.5" />
+  ${xLabels}
+
+  <polygon points="${areaPoints}" fill="url(#areaFill)" />
+  <polyline points="${polylinePoints}" fill="none" stroke="url(#lineStroke)" stroke-width="4" stroke-linecap="round" stroke-linejoin="round" />
+  <circle cx="${points.at(-1).x}" cy="${points.at(-1).y}" r="6.5" fill="#2563EB" />
+  <circle cx="${points.at(-1).x}" cy="${points.at(-1).y}" r="11" fill="#2563EB" fill-opacity="0.16" />
+</svg>
+`;
+}
+
+function buildYTicks(maxValue) {
+  const step = niceStep(Math.max(maxValue, 1) / 4);
+  const ceiling = Math.max(step, Math.ceil(Math.max(maxValue, 1) / step) * step);
+  const ticks = [];
+
+  for (let value = 0; value <= ceiling; value += step) {
+    ticks.push(value);
+  }
+
+  return { ceiling, ticks };
+}
+
+function buildTickIndices(length, desiredCount) {
+  if (length === 1) {
+    return [0];
+  }
+
+  const count = Math.min(length, desiredCount);
+  const indices = new Set();
+
+  for (let index = 0; index < count; index += 1) {
+    indices.add(Math.round(((length - 1) * index) / (count - 1)));
+  }
+
+  return [...indices].sort((left, right) => left - right);
+}
+
+function niceStep(target) {
+  const safeTarget = Math.max(target, 1);
+  const power = 10 ** Math.floor(Math.log10(safeTarget));
+  const scaled = safeTarget / power;
+
+  if (scaled <= 1) {
+    return power;
+  }
+
+  if (scaled <= 2) {
+    return 2 * power;
+  }
+
+  if (scaled <= 5) {
+    return 5 * power;
+  }
+
+  return 10 * power;
+}
+
+function formatDate(day) {
+  return new Intl.DateTimeFormat('en-US', {
+    month: 'short',
+    year: 'numeric',
+    timeZone: 'UTC',
+  }).format(new Date(`${day}T00:00:00Z`));
+}
+
+function formatNumber(value) {
+  return new Intl.NumberFormat('en-US').format(value);
+}
+
+function toUtcDay(value) {
+  return new Date(value).toISOString().slice(0, 10);
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&apos;');
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/skill/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: grasp
+description: Use when an agent needs the visible local Grasp browser runtime for multi-step web tasks or public-web extraction through one interface: confirm the runtime instance, enter URLs, inspect/extract/share page content, switch visible tabs, interact with live pages, fill forms, operate authenticated workspaces, capture screenshots, and recover through handoff after login or CAPTCHA checkpoints.
+---
+
+# Grasp
+
+## When to use
+
+- The task needs a real browser session, not a one-shot headless script
+- The work depends on persistent login state, a visible browser window, or human handoff/recovery
+- The agent needs one interface for page entry, extraction, share/export, forms, workspace actions, screenshots, and low-level browser control
+- The agent must know which runtime instance it is acting on, or it needs to switch between user-visible tabs safely
+
+## Safe defaults
+
+- Treat Grasp as the browser runtime surface. Use MCP tools for page actions instead of recreating interactions in shell scripts.
+- Start with `get_status`. Before page-changing actions, prefer `confirm_runtime_instance(display="windowed")` or confirm the mode you actually expect.
+- If a tool returns `INSTANCE_CONFIRMATION_REQUIRED`, confirm the instance and retry the same action.
+- For first arrival to a URL, prefer `entry(url, intent)`. Use `navigate(url)` only when you intentionally want to move the current page directly.
+- Prefer the high-level surfaces first: runtime loop, form tools, and workspace tools. Drop to hint map, tabs, cookies, dialogs, or `evaluate` only when the higher-level path is not enough.
+- Prefer `list_visible_tabs` / `select_visible_tab` before raw tab primitives such as `get_tabs` or `switch_tab`.
+- Refresh `get_hint_map` after navigation, a page-changing click, a visible DOM change, or scroll-loaded content. Old hint IDs are not safe to reuse after the page changes.
+- Use the handoff flow when the task is blocked by login, CAPTCHA, checkpoints, or other human-only steps.
+- If local CDP is unreachable, Grasp may auto-launch local Chrome or Edge now. If that still does not recover the runtime, ask the user to run `npx -y @yuzc-001/grasp`, `grasp connect`, or `start-chrome.bat` on Windows.
+
+## Recommended workflow
+
+1. `get_status`
+2. `confirm_runtime_instance` when the task needs a confirmed live instance
+3. `entry(url, intent)`
+4. `inspect`
+5. Follow the task surface that matches the job:
+   - `extract` / `extract_structured` / `extract_batch` / `share_page` / `continue`
+   - `form_inspect`
+   - `workspace_inspect`
+6. Use `explain_route` when the route choice needs explanation
+7. If blocked, use handoff and then resume with `continue`
+
+## Task surfaces
+
+### Public web and extraction
+
+Use `entry(..., intent="extract" | "read")`, then stay on `inspect`, `extract`, `extract_structured`, `extract_batch`, `share_page`, `explain_share_card`, and `continue` as long as the runtime surface is enough.
+
+### Forms
+
+Use `form_inspect -> fill_form / set_option / set_date -> verify_form -> safe_submit`.
+
+### Authenticated workspaces
+
+Use `workspace_inspect -> select_live_item -> draft_action -> execute_action -> verify_outcome`.
+
+### Lower-level control
+
+Only when the higher-level surface is not enough, use `get_hint_map`, `click`, `type`, `hover`, `scroll`, `scroll_into_view`, `screenshot`, `wait_for`, `go_back`, `go_forward`, `reload`, raw tab tools, cookies, dialogs, file upload, drag-and-drop, keyboard controls, and `evaluate`.
+
+## Additional resources
+
+- Detailed tool selection, examples, troubleshooting, and compatibility notes: [references/tools.md](references/tools.md)
+- Product framing for the runtime model: [Browser Runtime for Agents](../docs/product/browser-runtime-for-agents.md)

package/skill/references/tools.md

@@ -0,0 +1,306 @@
+# Grasp Reference
+
+## 1. Bootstrap and instance confirmation
+
+Recommended default order:
+
+1. `get_status`
+2. Check whether the runtime instance matches the browser session you expect
+3. Before page-changing actions, call `confirm_runtime_instance`
+
+Typical confirmation flow:
+
+```text
+get_status()
+confirm_runtime_instance(display="windowed")
+```
+
+If `get_status` or another tool reports that CDP is unreachable:
+
+- Grasp may now auto-launch local Chrome or Edge when the endpoint is local
+- If the runtime still does not recover, ask the user to run:
+- `npx -y @yuzc-001/grasp`
+  - `grasp connect`
+  - `start-chrome.bat` on Windows
+
+If tab identity is ambiguous:
+
+- Use `list_visible_tabs`
+- Then use `select_visible_tab`
+
+Only drop to raw tab indices when you truly need them:
+
+- `get_tabs`
+- `switch_tab`
+- `new_tab`
+- `close_tab`
+
+## 2. Intent selection
+
+| intent | When to use it |
+|---|---|
+| `read` | Read-only browsing without page-changing actions |
+| `extract` | Public-web reading, summary, or structured extraction |
+| `act` | General interaction such as clicking, typing, switching, or selecting |
+| `submit` | Filling and submitting forms |
+| `workspace` | Operating authenticated dashboards, inboxes, chat panes, or back-office surfaces |
+| `collect` | Visiting multiple URLs and extracting the same fields repeatedly |
+
+## 3. Default workflows
+
+### 3.1 Runtime loop
+
+```text
+get_status
+confirm_runtime_instance   (when live actions need confirmation)
+entry(url, intent)
+inspect
+extract / extract_structured / extract_batch / share_page / continue
+explain_route              (when route choice matters)
+```
+
+When a high-level tool responds, read the `Boundary: ...` block before picking the next action. The same response also carries structured `agent_boundary` metadata plus `agent_prompt`, which includes the assembled `system_prompt`, prompt segments, and chosen boundary/surface prompt packs for the current step. If a form or workspace tool is used on the wrong surface, expect a `BOUNDARY_MISMATCH` response and follow its recovery step instead of retrying blindly.
+
+### 3.2 Structured extraction
+
+When the task is "turn this page into named fields", prefer:
+
+```text
+entry(url, intent="extract")
+inspect
+extract_structured(fields=[...])
+```
+
+For repeated extraction across multiple URLs:
+
+```text
+extract_batch(urls=[...], fields=[...])
+```
+
+### 3.3 Share and export
+
+When the result should be handed to a human as an artifact rather than just returning raw page text:
+
+```text
+share_page(format="markdown" | "screenshot" | "pdf")
+explain_share_card(width=640)
+```
+
+### 3.4 Forms
+
+```text
+form_inspect
+fill_form(values={...})
+set_option(field="Country", value="Germany")
+set_date(field="Start date", value="2026-04-01")
+verify_form
+safe_submit(mode="preview")
+safe_submit(mode="confirm", confirmation="SUBMIT")
+```
+
+### 3.5 Workspaces
+
+```text
+workspace_inspect
+select_live_item(item="Conversation A")
+draft_action(text="Hello, I have a question...")
+execute_action(mode="preview")
+execute_action(mode="confirm", confirmation="EXECUTE")
+verify_outcome
+```
+
+### 3.6 Handoff and recovery
+
+```text
+inspect or continue
+request_handoff(reason="captcha_required", note="Need human verification")
+mark_handoff_done()
+resume_after_handoff(verify=true)
+continue()
+```
+
+## 4. Tool selection guide
+
+| Need | Preferred tools | Notes |
+|---|---|---|
+| First arrival to a URL | `entry(url, intent)` | Default entry point; do not start with `navigate` unless you intentionally want a direct page jump |
+| Directly change the current page URL | `navigate(url)` | Lower-level navigation path |
+| Inspect current runtime status | `inspect` | Returns route, page state, and continuation hints |
+| Quick current-page summary | `get_page_summary` | Lightweight read |
+| Extract a concise page result | `extract` | Stay on the runtime path |
+| Extract named fields from one page | `extract_structured` | Returns structured output and exports |
+| Extract the same fields from many URLs | `extract_batch` | Writes CSV and JSON artifacts, plus optional Markdown |
+| Export something shareable | `share_page` | `markdown`, `screenshot`, or `pdf` |
+| Explain how a shared artifact would look | `explain_share_card` | Useful before exporting |
+| Explain why the runtime chose a route | `explain_route` | Good for gated or surprising route choices |
+| Decide what should happen next without acting | `continue` | Best after inspection or recovery |
+| Read visible tabs from the active runtime | `list_visible_tabs` / `select_visible_tab` | Prefer these over raw indices |
+| Raw tab control | `get_tabs` / `switch_tab` / `new_tab` / `close_tab` | Use when index-level control is required |
+| Inspect a form | `form_inspect` | Starting point for the form surface |
+| Fill text-like form fields | `fill_form` | Uses a label-to-value map |
+| Set selects, radios, and other option controls | `set_option` | Use after `form_inspect` when control type matters |
+| Set date controls | `set_date` | Use ISO-like values |
+| Re-check missing or risky form fields | `verify_form` | Best before submit |
+| Preview or confirm form submission | `safe_submit` | `preview` first, `confirm` only when ready |
+| Inspect an authenticated workspace | `workspace_inspect` | Starting point for the workspace surface |
+| Switch active workspace item | `select_live_item` | Select by visible label |
+| Draft text into the composer | `draft_action` | Writes without sending |
+| Preview or execute a workspace send | `execute_action` | Use `preview` before `confirm` |
+| Verify the workspace result after send | `verify_outcome` | Confirms what changed and what is next |
+| Handle login or CAPTCHA checkpoints | `request_handoff` / `mark_handoff_done` / `resume_after_handoff` / `continue` | Keep continuity instead of restarting |
+| Find interactable targets | `get_hint_map` | Refresh after page changes |
+| Click, type, or hover | `click` / `type` / `hover` | Preferred low-level interactions |
+| Scroll a known target into view | `scroll_into_view` | Better than guessing pixels |
+| Scroll the page or a nested container | `scroll` | Supports `up`, `down`, `left`, `right`, and `hint_id` targeting |
+| Move browser history or refresh the page | `go_back` / `go_forward` / `reload` | Useful after navigation detours or retry flows |
+| Wait for text, hidden text, or URL changes | `wait_for` | Uses one condition at a time |
+| Wait for DOM selector changes | `watch_element` | Use when you know a CSS selector |
+| Visual verification | `screenshot` | Full page, element clip, or annotated viewport |
+| Keyboard actions | `press_key`, `key_down`, `key_up` | Use `key_down` / `key_up` for combos |
+| Checkbox or radio state | `check` | Idempotent checked/unchecked control |
+| Double-click | `double_click` | Lower-level pointer action |
+| Handle browser dialogs | `handle_dialog` | For alert, confirm, or prompt |
+| Upload files | `upload_file` | Uses an absolute file path array |
+| Drag and drop | `drag` | Lower-level pointer flow |
+| Read browser console output | `get_console_logs` | Great for debugging live pages |
+| Run custom page JavaScript | `evaluate` | Escape hatch; prefer specialized tools first |
+| Read or mutate cookies | `get_cookies` / `set_cookie` / `clear_cookies` | Useful for debugging session state |
+
+## 5. Hint Map rules
+
+- `B*`: buttons
+- `I*`: inputs
+- `L*`: links
+- `S*`: selects
+
+Old hint IDs may be invalid after:
+
+- navigation
+- a click that changes the page
+- a visible DOM update
+- a tab switch
+- scroll-loaded content
+- form submission or workspace state changes
+
+Practical rule:
+
+- Get a hint map before interaction
+- Rebuild the hint map after any visible page change
+- If you only need visual confirmation, prefer `screenshot` instead of forcing a new hint map
+
+## 6. Common scenarios
+
+### 6.1 Read a public page
+
+```text
+entry("https://example.com/article", "extract")
+inspect()
+extract()
+```
+
+### 6.2 Act inside a logged-in page
+
+```text
+get_status()
+confirm_runtime_instance(display="windowed")
+entry("https://app.example.com/dashboard", "act")
+inspect()
+screenshot(annotate=true)
+click(hint_id="B3")
+get_hint_map()
+```
+
+### 6.3 Fill a form
+
+```text
+entry("https://example.com/apply", "submit")
+form_inspect()
+fill_form(values={"Full name":"Taylor Doe","Email":"taylor@example.com"})
+set_option(field="Country", value="Germany")
+set_date(field="Start date", value="2026-04-01")
+verify_form()
+safe_submit(mode="preview")
+```
+
+### 6.4 Operate a workspace
+
+```text
+entry("https://app.example.com/inbox", "workspace")
+workspace_inspect()
+select_live_item(item="Priority thread")
+draft_action(text="Hello, following up on this request...")
+execute_action(mode="preview")
+verify_outcome()
+```
+
+### 6.5 Recover after login or CAPTCHA
+
+```text
+entry("https://protected-site.example", "act")
+inspect()
+request_handoff(reason="captcha_required", note="Need human verification")
+mark_handoff_done()
+resume_after_handoff(verify=true)
+continue()
+```
+
+### 6.6 Work across multiple tabs
+
+```text
+list_visible_tabs()
+select_visible_tab(query="docs")
+extract()
+new_tab(url="https://docs.example.com")
+get_tabs()
+switch_tab(index=0)
+close_tab(index=1)
+```
+
+### 6.7 Scroll inside a nested container
+
+```text
+get_hint_map()
+scroll_into_view(hint_id="L15")
+
+# or step through the scrollable ancestor
+scroll(direction="down", hint_id="L15", amount=200)
+get_hint_map()
+```
+
+### 6.8 Recover after a navigation detour
+
+```text
+go_back()
+go_forward()
+reload()
+inspect()
+```
+
+## 7. Compatibility and legacy tools
+
+These tools still exist for older flows or edge cases, but they are not the preferred path for new tasks:
+
+| Tool | Use it only when |
+|---|---|
+| `confirm_click` | You are intentionally using the older safe-mode click flow and need to bypass its confirmation gate |
+| `get_form_fields` | You are working with an older hint-first form workflow rather than the newer form surface |
+| `get_logs` | You need the Grasp audit log rather than browser console output |
+| `call_webmcp_tool` | The current page exposes a native WebMCP API and that lower-level integration is truly needed |
+
+If you are not sure, prefer the route-aware runtime surface plus the current form/workspace tools described above.
+
+## 8. Troubleshooting
+
+| Problem | What to do |
+|---|---|
+| `connected: false` or `CDP_UNREACHABLE` | Retry `get_status`; Grasp may auto-launch local Chrome or Edge; if not, ask the user to run `npx -y @yuzc-001/grasp`, `grasp connect`, or `start-chrome.bat` |
+| `INSTANCE_CONFIRMATION_REQUIRED` | Call `get_status`, then `confirm_runtime_instance(display="windowed")` or confirm the actual expected mode |
+| `INSTANCE_CONFIRMATION_MISMATCH` | Stop and switch to the correct runtime instance before acting |
+| `TAB_AMBIGUOUS` or `TAB_NOT_FOUND` | Use `list_visible_tabs` and refine `select_visible_tab(query=..., title_contains=..., url_contains=...)` |
+| `get_hint_map` returns nothing useful | The page may still be loading, blocked, or not yet in an interaction-ready state; use `inspect` or `get_page_summary` |
+| Click target disappeared after action | The page changed; call `get_hint_map` again |
+| The target is inside a scrollable pane | Prefer `scroll_into_view`, then `scroll(..., hint_id=...)` if needed |
+| A dialog blocks progress | Use `handle_dialog` |
+| `wait_for` times out | Check the condition text or URL fragment and retry with a larger timeout only if the condition is really expected |
+| `evaluate` returns `undefined` | The expression produced no return value; rewrite it as an expression that returns something |
+| Cookie changes do not stick | Check `domain`, `path`, and whether they match the current page context |