@yuzc-001/grasp 0.6.6

package/examples/README.md

@@ -0,0 +1,31 @@
+## Example Client Configs
+
+Use these examples when you want to connect an AI client to the local Grasp runtime:
+
+- `claude-desktop.json` for Claude Desktop / Cursor style JSON MCP config
+- `codex-config.toml` for Codex CLI TOML MCP config
+
+All examples point to the same local runtime entry:
+
+```text
+command = npx
+args    = -y grasp
+```
+
+Set up the runtime first with:
+
+```bash
+npx -y @yuzc-001/grasp
+```
+
+## Hero Demo Intent Mapping
+
+These examples are not only config snippets. They map to the current Route by Evidence live smoke routes:
+
+- public URL (`https://example.com/`) -> `public_read`
+- public form (`https://httpbin.org/forms/post`) -> `form_runtime`
+- logged-in task page (`https://mp.weixin.qq.com/`) -> `live_session`
+- authenticated workspace (`https://mp.weixin.qq.com/cgi-bin/message?...`) -> `workspace_runtime`
+- blocked challenge page (`https://www.scrapingcourse.com/cloudflare-challenge`) -> `handoff`, then `resume_after_handoff`
+
+The demo goal is not “show more tools.” It is “show that one URL gets one best path first.”

package/examples/claude-desktop.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "grasp": {
+      "command": "npx",
+      "args": ["-y", "@yuzc-001/grasp"]
+    }
+  }
+}

package/examples/codex-config.toml

@@ -0,0 +1,4 @@
+[mcp_servers.grasp]
+type    = "stdio"
+command = "npx"
+args    = ["-y", "@yuzc-001/grasp"]

package/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Grasp CLI entry point
+ *
+ *   grasp              — start MCP server (for Claude Desktop / Cursor)
+ *   grasp status       — show Chrome connection status
+ *   grasp logs         — show audit log  (--lines N, --follow)
+ *   grasp --version    — print version
+ *   grasp --help       — print help
+ */
+
+import { pathToFileURL } from 'node:url';
+
+export async function main(argv = process.argv.slice(2)) {
+  const [cmd, ...rest] = argv;
+
+  if (cmd === 'connect' || cmd === undefined) {
+    // 'connect' = explicit setup wizard
+    // no args = also run connect when called by human (not piped to MCP)
+    const isMcpMode = !process.stdin.isTTY && cmd === undefined;
+    if (isMcpMode) {
+      // stdin is a pipe — AI client is calling us, start MCP server
+      const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+      const { createGraspServer, SERVER_INFO } = await import('./src/server/index.js');
+      try {
+        const { server } = createGraspServer();
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error(`[Grasp] MCP Server v${SERVER_INFO.version} started.`);
+      } catch (err) {
+        console.error(`[Grasp] Failed to start MCP server: ${err.message}`);
+        process.exit(1);
+      }
+    } else {
+      const { runConnect } = await import('./src/cli/cmd-connect.js');
+      await runConnect();
+    }
+  } else if (cmd === 'status') {
+    const { runStatus } = await import('./src/cli/cmd-status.js');
+    await runStatus();
+  } else if (cmd === 'logs') {
+    const { runLogs } = await import('./src/cli/cmd-logs.js');
+    await runLogs(rest);
+  } else if (cmd === 'explain') {
+    const { runExplain } = await import('./src/cli/cmd-explain.js');
+    await runExplain();
+  } else if (cmd === '--version' || cmd === '-v') {
+    const { SERVER_INFO } = await import('./src/server/index.js');
+    console.log(SERVER_INFO.version);
+  } else if (cmd === '--help' || cmd === '-h') {
+    printHelp();
+  }
+}
+
+export function renderHelpText() {
+  return `
+  Grasp — route-aware Agent Web Runtime
+  Connect Chrome once. Let agents work inside a visible browser runtime, extract structured results, and resume real pages.
+
+  Usage:
+    grasp                  Bootstrap the runtime and connect Chrome for first use
+    grasp connect          Same as above
+    grasp status           Show runtime state, current page, and recent activity
+    grasp logs             Show recent audit log
+      --lines N            Number of lines to show (default: 50)
+      --follow, -f         Stream new entries in real-time
+    grasp explain          Explain the latest route decision
+    grasp --version        Print version
+    grasp --help           Print this help
+
+  First runtime steps:
+ 1. npx -y @yuzc-001/grasp  Bootstrap the runtime and connect your AI client
+    2. Open any real page  Keep using the dedicated chrome-grasp profile
+                           This runtime profile is separate from arbitrary browser windows you may already have open
+    3. Ask your AI         Call get_status / entry(url, intent) / inspect / extract or continue / explain_route
+                           Use extract_structured(fields=[...]) or extract_batch(urls=[...], fields=[...]) for structured exports
+                           Use share_page(format="markdown" | "screenshot" | "pdf") when the result needs a shareable artifact
+`;
+}
+
+export function printHelp() {
+  console.log(renderHelpText());
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  await main();
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@yuzc-001/grasp",
+  "version": "0.6.6",
+  "description": "Visible AI browser runtime with persistent sessions, verified actions, structured extraction, and recoverable handoff.",
+  "main": "index.js",
+  "bin": {
+    "grasp": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "src",
+    "examples",
+    "scripts",
+    "skill",
+    "start-chrome.bat",
+    "grasp.skill"
+  ],
+  "type": "module",
+  "scripts": {
+    "start": "node index.js",
+    "dev": "node --watch index.js",
+    "test": "node --test",
+    "test:watch": "node --test --watch"
+  },
+  "dependencies": {
+    "@chenglou/pretext": "^0.0.3",
+    "@modelcontextprotocol/sdk": "^1.8.0",
+    "playwright-core": "^1.58.2",
+    "zod": "^3.25.76"
+  },
+  "keywords": [
+    "mcp",
+    "route-aware-agent-web-runtime",
+    "browser-runtime-for-agents",
+    "browser-runtime",
+    "session-continuity",
+    "agent-browser"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Yuzc-001/grasp.git"
+  },
+  "homepage": "https://github.com/Yuzc-001/grasp#readme",
+  "bugs": {
+    "url": "https://github.com/Yuzc-001/grasp/issues"
+  },
+  "license": "MIT"
+}

package/scripts/grasp_openclaw_ctl.sh

@@ -0,0 +1,122 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+RUNTIME_DIR="${GRASP_RUNTIME_DIR:-$ROOT_DIR/.runtime/openclaw}"
+PROFILE_DIR="${GRASP_PROFILE_DIR:-/root/snap/chromium/common/grasp-openclaw-profile}"
+LOG_DIR="$RUNTIME_DIR/logs"
+PID_DIR="$RUNTIME_DIR/pids"
+CHROME_LOG="$LOG_DIR/chromium.log"
+GRASP_LOG="$LOG_DIR/grasp.log"
+CHROME_PID_FILE="$PID_DIR/chromium.pid"
+GRASP_PID_FILE="$PID_DIR/grasp.pid"
+CHROME_BIN="${CHROME_BIN:-/usr/bin/chromium-browser}"
+CDP_URL="${CHROME_CDP_URL:-http://127.0.0.1:9222}"
+CDP_PORT="${CHROME_CDP_PORT:-9222}"
+
+mkdir -p "$PROFILE_DIR" "$LOG_DIR" "$PID_DIR"
+
+is_pid_running() {
+  local file="$1"
+  [[ -f "$file" ]] || return 1
+  local pid
+  pid="$(cat "$file" 2>/dev/null || true)"
+  [[ -n "$pid" ]] || return 1
+  kill -0 "$pid" 2>/dev/null
+}
+
+start_chrome() {
+  if is_pid_running "$CHROME_PID_FILE"; then
+    return 0
+  fi
+  nohup "$CHROME_BIN" \
+    --headless=new \
+    --no-sandbox \
+    --disable-dev-shm-usage \
+    --remote-debugging-address=127.0.0.1 \
+    --remote-debugging-port="$CDP_PORT" \
+    --user-data-dir="$PROFILE_DIR" \
+    about:blank \
+    >"$CHROME_LOG" 2>&1 &
+  echo $! > "$CHROME_PID_FILE"
+}
+
+wait_for_cdp() {
+  for _ in $(seq 1 20); do
+    if curl -fsS "$CDP_URL/json/version" >/dev/null 2>&1; then
+      return 0
+    fi
+    sleep 1
+  done
+  return 1
+}
+
+start_grasp_probe() {
+  if is_pid_running "$GRASP_PID_FILE"; then
+    return 0
+  fi
+  nohup bash -lc "cd '$ROOT_DIR' && node index.js status" >"$GRASP_LOG" 2>&1 &
+  echo $! > "$GRASP_PID_FILE"
+}
+
+cmd_start() {
+  start_chrome
+  if ! wait_for_cdp; then
+    echo "CDP_UNREACHABLE"
+    exit 1
+  fi
+  start_grasp_probe
+  echo "started"
+}
+
+cmd_status() {
+  echo "runtime_dir=$RUNTIME_DIR"
+  echo "profile_dir=$PROFILE_DIR"
+  echo "cdp_url=$CDP_URL"
+  if is_pid_running "$CHROME_PID_FILE"; then
+    echo "chromium=running"
+  else
+    echo "chromium=stopped"
+  fi
+  if curl -fsS "$CDP_URL/json/version" >/dev/null 2>&1; then
+    echo "cdp=connected"
+  else
+    echo "cdp=disconnected"
+  fi
+  if is_pid_running "$GRASP_PID_FILE"; then
+    echo "grasp_probe=running"
+  else
+    echo "grasp_probe=stopped"
+  fi
+  if [[ -f "$GRASP_LOG" ]]; then
+    echo "--- grasp_status ---"
+    tail -n 20 "$GRASP_LOG" || true
+  fi
+}
+
+cmd_logs() {
+  echo "--- chromium.log ---"
+  tail -n 60 "$CHROME_LOG" 2>/dev/null || true
+  echo
+  echo "--- grasp.log ---"
+  tail -n 60 "$GRASP_LOG" 2>/dev/null || true
+}
+
+cmd_stop() {
+  if is_pid_running "$GRASP_PID_FILE"; then
+    kill "$(cat "$GRASP_PID_FILE")" 2>/dev/null || true
+  fi
+  if is_pid_running "$CHROME_PID_FILE"; then
+    kill "$(cat "$CHROME_PID_FILE")" 2>/dev/null || true
+  fi
+  rm -f "$GRASP_PID_FILE" "$CHROME_PID_FILE"
+  echo "stopped"
+}
+
+case "${1:-status}" in
+  start) cmd_start ;;
+  status) cmd_status ;;
+  logs) cmd_logs ;;
+  stop) cmd_stop ;;
+  *) echo "usage: $0 {start|status|logs|stop}" >&2; exit 2 ;;
+esac

package/scripts/run-search-benchmark.mjs

@@ -0,0 +1,287 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runSearchTaskTool } from '../src/server/tasks/search-task.js';
+import { createServerState } from '../src/server/state.js';
+
+function mean(items) {
+  if (items.length === 0) return 0;
+  return items.reduce((sum, value) => sum + value, 0) / items.length;
+}
+
+export function summarizeSearchBenchmark(results = [], options = {}) {
+  const suite = options.suite ?? 'search-task';
+  const total = results.length;
+  const successCount = results.filter((r) => r.status === 'completed').length;
+  const successRate = total === 0 ? 0 : successCount / total;
+  const avgToolCalls = mean(results.map((r) => r.toolCalls ?? 0));
+  const avgRetries = mean(results.map((r) => r.retries ?? 0));
+  const totalRetryAttempts = results.reduce((sum, result) => sum + (result.retries ?? 0), 0);
+  const successfulRetryAttempts = results.reduce((sum, result) => {
+    if (result.status === 'completed' && (result.retries ?? 0) > 0) {
+      return sum + 1;
+    }
+    return sum;
+  }, 0);
+  const recoverySuccessRate = totalRetryAttempts === 0
+    ? 1
+    : successfulRetryAttempts / totalRetryAttempts;
+
+  return {
+    suite,
+    successRate,
+    avgToolCalls,
+    avgRetries,
+    recoverySuccessRate,
+  };
+}
+
+function createFakeBenchmarkPage({ url = 'https://example.com/', title = 'Benchmark Page' } = {}) {
+  return {
+    url: () => url,
+    title: async () => title,
+    evaluate: async () => 'complete',
+  };
+}
+
+function createSnapshot({
+  query = 'pi agent 是啥',
+  title = 'Search',
+  url = 'https://example.com/search',
+  contentText = '',
+  domRevision = 0,
+  searchInput = { id: 'I1', type: 'textbox', label: 'Search' },
+  submitControl = { id: 'B1', type: 'button', label: 'Search' },
+} = {}) {
+  const ranking = {
+    search_input: searchInput ? [{ ...searchInput }] : [],
+    command_button: submitControl ? [{ ...submitControl }] : [],
+  };
+  const hints = [
+    ...(searchInput ? [{ ...searchInput, semantic: 'search_input' }] : []),
+    ...(submitControl ? [{ ...submitControl, semantic: 'submit_control' }] : []),
+  ];
+  return {
+    query,
+    title,
+    url,
+    hints,
+    ranking,
+    content: { text: contentText },
+    domRevision,
+    submitCandidate: submitControl ? { ...submitControl } : null,
+  };
+}
+
+async function runToolScenario({
+  name,
+  description,
+  query = 'pi agent 是啥',
+  maxAttempts = 3,
+  pageUrl,
+  pageTitle,
+  observer,
+  verifier,
+  waitThenReverify,
+}) {
+  const state = createServerState();
+  const page = createFakeBenchmarkPage({ url: pageUrl, title: pageTitle });
+  const actionBreakdown = {
+    type: 0,
+    typeWithEnter: 0,
+    click: 0,
+    pressKey: 0,
+    waitStable: 0,
+  };
+
+  const result = await runSearchTaskTool({
+    state,
+    query,
+    max_attempts: maxAttempts,
+    deps: {
+      getActivePage: async () => page,
+      observer,
+      verifier,
+      waitThenReverify,
+      typeAction: async (_page, _hintId, _text, pressEnter) => {
+        actionBreakdown.type += 1;
+        if (pressEnter) actionBreakdown.typeWithEnter += 1;
+      },
+      clickAction: async () => {
+        actionBreakdown.click += 1;
+      },
+      pressKeyAction: async () => {
+        actionBreakdown.pressKey += 1;
+      },
+      waitStableAction: async () => {
+        actionBreakdown.waitStable += 1;
+        return { stable: true, attempts: 1 };
+      },
+      extractContentAction: async () => ({ text: 'fixture content' }),
+      syncStateAction: async () => undefined,
+    },
+  });
+
+  return {
+    scenario: name,
+    description,
+    status: result.status,
+    attempts: result.attempts,
+    toolCalls: result.toolCalls,
+    retries: result.retries,
+    recovered: result.recovered,
+    actionBreakdown,
+  };
+}
+
+export function createSearchBenchmarkScenarios() {
+  return [
+    {
+      name: 'grok-question',
+      description: 'Grok 搜索提问',
+      async run() {
+        return runToolScenario({
+          name: 'grok-question',
+          description: 'Grok 搜索提问',
+          pageUrl: 'https://grok.com/',
+          pageTitle: 'Grok',
+          observer: async () => ({
+            snapshot: createSnapshot({
+              title: 'Grok',
+              url: 'https://grok.com/',
+              searchInput: { id: 'I1', type: 'textbox', label: '向 Grok 提问' },
+              submitControl: { id: 'B2', type: 'button', label: '发送' },
+            }),
+          }),
+          verifier: async () => ({ ok: true, evidence: { answerStarted: true } }),
+        });
+      },
+    },
+    {
+      name: 'google-search',
+      description: 'Google 搜索',
+      async run() {
+        return runToolScenario({
+          name: 'google-search',
+          description: 'Google 搜索',
+          pageUrl: 'https://www.google.com/',
+          pageTitle: 'Google',
+          observer: async () => ({
+            snapshot: createSnapshot({
+              title: 'Google',
+              url: 'https://www.google.com/',
+              searchInput: { id: 'I1', type: 'searchbox', label: 'Search Google' },
+              submitControl: null,
+            }),
+          }),
+          verifier: async () => ({ ok: true, evidence: { resultsVisible: true } }),
+        });
+      },
+    },
+    {
+      name: 'overlay-site-search',
+      description: '带弹层干扰的站内搜索',
+      async run() {
+        return runToolScenario({
+          name: 'overlay-site-search',
+          description: '带弹层干扰的站内搜索',
+          pageUrl: 'https://docs.example.com/',
+          pageTitle: 'Docs Search',
+          observer: async () => ({
+            snapshot: createSnapshot({
+              title: 'Docs Search',
+              url: 'https://docs.example.com/',
+              searchInput: { id: 'I3', type: 'combobox', label: '站内搜索' },
+              submitControl: { id: 'B4', type: 'button', label: '搜索' },
+            }),
+          }),
+          verifier: (() => {
+            let attempts = 0;
+            return async ({ plan }) => {
+              attempts += 1;
+              if (attempts === 1 && plan.mode === 'primary_submit') {
+                return { ok: false, error_code: 'NO_EFFECT', evidence: { overlay: true } };
+              }
+              return { ok: true, evidence: { resultPaneChanged: true } };
+            };
+          })(),
+        });
+      },
+    },
+    {
+      name: 'streaming-answer',
+      description: '流式回答页面等待稳定',
+      async run() {
+        let verifyCount = 0;
+        return runToolScenario({
+          name: 'streaming-answer',
+          description: '流式回答页面等待稳定',
+          pageUrl: 'https://chat.example.com/',
+          pageTitle: 'Streaming Answer',
+          observer: async () => ({
+            snapshot: createSnapshot({
+              title: 'Streaming Answer',
+              url: 'https://chat.example.com/',
+              searchInput: { id: 'I9', type: 'textbox', label: 'Ask anything' },
+              submitControl: { id: 'B9', type: 'button', label: 'Send' },
+            }),
+          }),
+          verifier: async () => {
+            verifyCount += 1;
+            return verifyCount === 1
+              ? { ok: false, error_code: 'LOADING_PENDING', evidence: { streamOpen: true } }
+              : { ok: true, evidence: { streamSettled: true } };
+          },
+        });
+      },
+    },
+    {
+      name: 'result-content-extract',
+      description: '结果页正文抽取',
+      async run() {
+        return runToolScenario({
+          name: 'result-content-extract',
+          description: '结果页正文抽取',
+          pageUrl: 'https://example.com/pi-agent',
+          pageTitle: 'Pi Agent',
+          observer: async () => ({
+            snapshot: createSnapshot({
+              title: 'Pi Agent',
+              url: 'https://example.com/pi-agent',
+              contentText: 'Pi Agent is a minimal coding-agent runtime.',
+              searchInput: { id: 'I6', type: 'textbox', label: 'Search docs' },
+              submitControl: { id: 'B6', type: 'button', label: 'Search docs' },
+            }),
+          }),
+          verifier: async ({ snapshot }) => ({
+            ok: true,
+            evidence: { extractedText: snapshot.content.text },
+          }),
+        });
+      },
+    },
+  ];
+}
+
+export async function runSearchBenchmark(scenarios = createSearchBenchmarkScenarios(), options = {}) {
+  const { silent = false } = options;
+  const results = [];
+  for (const scenario of scenarios) {
+    const result = await scenario.run();
+    results.push(result);
+  }
+  const summary = summarizeSearchBenchmark(results, options);
+  const payload = {
+    summary,
+    results,
+  };
+  if (!silent) {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+  return payload;
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMain) {
+  runSearchBenchmark();
+}