hypha-debugger 0.1.9 → 0.1.10

package/dist/hypha-debugger.js

@@ -10517,12 +10517,56 @@
   /**
    * Arbitrary JavaScript execution service.
    */
+  /**
+   * Attempt to auto-return the last expression in a code block.
+   * If the code doesn't contain an explicit `return`, we try to
+   * add one to the last expression statement so the result is captured.
+   *
+   * Examples:
+   *   "document.title"            → "return (document.title);"
+   *   "const x = 1; x + 2"       → "const x = 1; return (x + 2);"
+   *   "const x = 1\nx + 2"       → "const x = 1\nreturn (x + 2);"
+   *   "for(...) {}"               → unchanged (control flow)
+   *   "return 42"                 → unchanged (explicit return)
+   */
+  function autoReturn(code) {
+      const trimmed = code.trim();
+      // Already has a return statement? Leave it alone.
+      if (/\breturn\b/.test(trimmed))
+          return trimmed;
+      // Split into statements: by newlines first, then by semicolons for
+      // single-line multi-statement code like "const x = 1; x + 2"
+      let lines = trimmed.split("\n").map((l) => l.trim()).filter(Boolean);
+      // If there's only one line with semicolons, split on semicolons
+      if (lines.length === 1 && lines[0].includes(";")) {
+          lines = lines[0].split(";").map((s) => s.trim()).filter(Boolean);
+      }
+      if (lines.length === 0)
+          return trimmed;
+      const lastLine = lines[lines.length - 1];
+      // Don't add return to control flow, declarations, or assignment-only statements
+      if (/^(if|for|while|switch|try|class|function |const |let |var |import |export )/.test(lastLine)) {
+          return trimmed;
+      }
+      // Replace last statement with return
+      lines[lines.length - 1] = "return (" + lastLine.replace(/;$/, "") + ");";
+      return lines.join(";\n");
+  }
   async function executeScript(code, timeout_ms) {
       const timeoutMs = timeout_ms ?? 10000;
       try {
+          // Try with auto-return first, fall back to original code if syntax error
+          let execCode = autoReturn(code);
+          let fn;
+          try {
+              fn = new Function("return (async () => {" + execCode + "})()");
+          }
+          catch {
+              // Auto-return broke the syntax — use original code
+              fn = new Function("return (async () => {" + code + "})()");
+          }
           const result = await Promise.race([
-              // Use async Function to allow top-level await in the code
-              new Function("return (async () => {" + code + "})()")(),
+              fn(),
               new Promise((_, reject) => setTimeout(() => reject(new Error("Execution timed out")), timeoutMs)),
           ]);
           // Serialize the result safely
@@ -10537,6 +10581,7 @@
                   serialized = {
                       tag: result.tagName.toLowerCase(),
                       id: result.id,
+                      className: result.className,
                       text: (result.textContent ?? "").trim().slice(0, 500),
                   };
                   type = "HTMLElement";
@@ -10566,13 +10611,13 @@
   }
   executeScript.__schema__ = {
       name: "executeScript",
-      description: "Execute arbitrary JavaScript code in the page context. Supports async/await. Returns the result of the last expression.",
+      description: 'Execute arbitrary JavaScript code in the page context. Supports async/await. The last expression is auto-returned (no need for explicit "return"). Examples: "document.title", "document.querySelectorAll(\'a\').length", "await fetch(\'/api/data\').then(r => r.json())".',
       parameters: {
           type: "object",
           properties: {
               code: {
                   type: "string",
-                  description: 'JavaScript code to execute. The result of the last expression is returned. Example: "return document.title"',
+                  description: 'JavaScript code to execute. The last expression is automatically returned. Examples: "document.title", "document.querySelector(\'h1\').textContent".',
               },
               timeout_ms: {
                   type: "number",
@@ -11095,70 +11140,78 @@
           "# Web Debugger Skill",
           "",
           "This skill allows you to remotely debug and interact with a web page through HTTP API endpoints.",
+          "Pick the approach that fits your task — they can be combined freely.",
+          "",
+          "## Approaches",
           "",
-          "## Recommended Workflow (Index-Based Interaction)",
+          "### execute_script — Run Arbitrary JavaScript",
           "",
-          "The most reliable way to interact with a page is using the smart DOM analysis:",
+          "The most versatile function. Use it to read/modify page state, call APIs, query the DOM,",
+          "or do anything JavaScript can do. The last expression is auto-returned (no need for `return`).",
           "",
-          "### Step 1: Observe the page",
           "```bash",
-          `curl '{SERVICE_URL}/get_browser_state'`,
-          "```",
-          "This returns all interactive elements indexed as `[0]`, `[1]`, `[2]`, etc.",
-          "Elements are detected via smart heuristics: CSS cursor, ARIA roles, event listeners, tag names.",
-          "Visual highlight labels are overlaid on the page for each detected element.",
+          `# Read page state`,
+          `curl -X POST '{SERVICE_URL}/execute_script' \\`,
+          `  -H 'Content-Type: application/json' -d '{"code": "document.title"}'`,
           "",
-          "Example output:",
-          "```",
-          "[0]<a aria-label=Home>Home />",
-          "[1]<input placeholder=Search... />",
-          "[2]<button>Sign In />",
-          "[3]<select name=language>English />",
-          "[4]<div data-scrollable=\"top=200, bottom=1500\">Content area />",
+          `# Query DOM`,
+          `curl -X POST '{SERVICE_URL}/execute_script' \\`,
+          `  -H 'Content-Type: application/json' -d '{"code": "document.querySelector(\\\"h1\\\").textContent"}'`,
+          "",
+          `# Call an API`,
+          `curl -X POST '{SERVICE_URL}/execute_script' \\`,
+          `  -H 'Content-Type: application/json' -d '{"code": "await fetch(\\\"/api/data\\\").then(r => r.json())"}'`,
+          "",
+          `# Modify the page`,
+          `curl -X POST '{SERVICE_URL}/execute_script' \\`,
+          `  -H 'Content-Type: application/json' -d '{"code": "document.getElementById(\\\"name\\\").value = \\\"Alice\\\""}'`,
           "```",
           "",
-          "### Step 2: Act on elements by index",
+          "### get_browser_state + Index-Based Interaction",
+          "",
+          "Best for UI interaction as a user would — clicking buttons, filling forms, selecting options.",
+          "All interactive elements are detected and indexed as `[0]`, `[1]`, `[2]`, etc.",
+          "",
           "```bash",
-          "# Click a button (e.g. [2] Sign In):",
+          `# Step 1: See all interactive elements`,
+          `curl '{SERVICE_URL}/get_browser_state'`,
+          "",
+          `# Step 2: Act by index`,
           `curl -X POST '{SERVICE_URL}/click_element_by_index' \\`,
           `  -H 'Content-Type: application/json' -d '{"index": 2}'`,
           "",
-          "# Type into an input (e.g. [1] Search):",
           `curl -X POST '{SERVICE_URL}/input_text' \\`,
           `  -H 'Content-Type: application/json' -d '{"index": 1, "text": "hello world"}'`,
           "",
-          "# Select a dropdown option (e.g. [3] Language):",
           `curl -X POST '{SERVICE_URL}/select_option' \\`,
           `  -H 'Content-Type: application/json' -d '{"index": 3, "option_text": "French"}'`,
           "",
-          "# Scroll down:",
           `curl -X POST '{SERVICE_URL}/scroll' \\`,
           `  -H 'Content-Type: application/json' -d '{"direction": "down"}'`,
           "",
-          "# Scroll a specific container (e.g. [4]):",
-          `curl -X POST '{SERVICE_URL}/scroll' \\`,
-          `  -H 'Content-Type: application/json' -d '{"direction": "down", "index": 4}'`,
-          "```",
-          "",
-          "### Step 3: Verify",
-          "```bash",
+          `# Step 3: Verify visually`,
           `curl '{SERVICE_URL}/take_screenshot'`,
           "```",
           "",
-          "### Remove visual highlights (optional, for clean screenshots)",
+          "### get_react_tree — Inspect React Components",
+          "",
+          "If the page uses React, inspect component names, props, state, and hooks:",
           "```bash",
-          `curl '{SERVICE_URL}/remove_highlights'`,
+          `curl '{SERVICE_URL}/get_react_tree'`,
           "```",
           "",
-          "## CSS Selector-Based Functions (Alternative)",
+          "### CSS Selector-Based Functions",
           "",
-          "You can also use CSS selectors directly for precise targeting:",
+          "Use CSS selectors directly when you know the element:",
           "```bash",
           `curl -X POST '{SERVICE_URL}/click_element' \\`,
           `  -H 'Content-Type: application/json' -d '{"selector": "button.submit"}'`,
           "",
           `curl -X POST '{SERVICE_URL}/fill_input' \\`,
           `  -H 'Content-Type: application/json' -d '{"selector": "#email", "value": "user@example.com"}'`,
+          "",
+          `curl -X POST '{SERVICE_URL}/query_dom' \\`,
+          `  -H 'Content-Type: application/json' -d '{"selector": ".product-card"}'`,
           "```",
           "",
           "## How to call functions",
@@ -11234,14 +11287,14 @@
       const tips = [
           "## Tips",
           "",
-          "- **Start with `get_browser_state`** — it's the best way to understand what's on the page and what you can interact with.",
-          "- **Prefer index-based interaction** (`click_element_by_index`, `input_text`, `select_option`) over CSS selectors — indices are more reliable across dynamic pages.",
+          "- **`execute_script` is the most versatile** — use it for reading state, calling APIs, DOM queries, or anything not covered by other functions. The last expression is auto-returned.",
+          "- **`get_browser_state` is the best way to see what's on the page** — it detects all interactive elements and shows them as indexed items.",
           "- **After each action, call `get_browser_state` again** — element indices change when the DOM updates.",
           "- **Use `take_screenshot`** to visually verify the page state. Call `remove_highlights` first for a clean view.",
-          "- **Use `execute_script`** for anything not covered by the built-in functions — it runs arbitrary JavaScript.",
           "- **Use `scroll`** with an element index to scroll inside a specific container (e.g. a chat window, sidebar).",
           "- **Use `get_page_info` with `include_logs=true`** to check for JavaScript errors or debug output.",
-          "- **Use `get_react_tree`** if the page uses React — it gives you component names, props, and state.",
+          "- **Use `get_react_tree`** if the page uses React — it gives you component names, props, and state without needing DevTools.",
+          "- **Use `navigate`** to go to other pages — same-origin navigation auto-reconnects the debugger.",
           "- All POST endpoints accept JSON body with the parameter names as keys.",
           "",
       ].join("\n");
@@ -11275,14 +11328,24 @@
       // Create a wrapper that:
       // 1. Has correct, unminified parameter names (for hypha-rpc getParamNames)
       // 2. Detects when kwargs are passed as a single object and destructures them
+      //
+      // hypha-rpc HTTP handler passes kwargs as a single plain object, e.g.:
+      //   execute_script({code: "..."}) instead of execute_script("...")
+      //   get_react_tree({}) instead of get_react_tree()
+      // We detect this and destructure, or discard empty objects.
       const paramList = paramNames.join(", ");
+      const firstParam = paramNames[0];
       const wrapper = new Function("fn", "paramNames", `return async function(${paramList}) {
       // Detect kwargs-as-object: single argument that is a plain object
-      // whose keys match schema parameter names
-      if (arguments.length === 1 && ${paramList} != null && typeof ${paramList} === "object" && !Array.isArray(${paramList}) && !(${paramList} instanceof Date)) {
-        var _kw = ${paramList};
-        var _firstKey = Object.keys(_kw)[0];
-        if (_firstKey && paramNames.indexOf(_firstKey) !== -1) {
+      if (arguments.length === 1 && ${firstParam} != null && typeof ${firstParam} === "object" && !Array.isArray(${firstParam}) && !(${firstParam} instanceof Date) && ${firstParam}.constructor === Object) {
+        var _kw = ${firstParam};
+        var _keys = Object.keys(_kw);
+        // Empty object {} → call with no args (all defaults)
+        if (_keys.length === 0) {
+          return fn();
+        }
+        // Keys match schema params → destructure
+        if (paramNames.indexOf(_keys[0]) !== -1) {
           var _args = paramNames.map(function(n) { return _kw[n]; });
           return fn.apply(null, _args);
         }
@@ -14372,22 +14435,21 @@
               `# A debugger is attached to a live web page.`,
               `# You can remotely inspect, interact with, and control this page via the HTTP API below.`,
               `#`,
-              `# RECOMMENDED WORKFLOW (index-based, most reliable):`,
-              `#   1. get_browser_state → see all interactive elements as [0], [1], [2], ...`,
-              `#   2. click_element_by_index / input_text / select_option / scroll → act by index`,
-              `#   3. take_screenshot → verify the result visually`,
-              `#`,
-              `# Also available: get_page_info, get_html, query_dom, click_element, fill_input,`,
-              `#   scroll_to, execute_script, navigate, get_react_tree, remove_highlights`,
+              `# APPROACHES (pick what fits your task):`,
+              `#   - execute_script: Run arbitrary JS — fastest for reading/modifying page state, DOM queries, API calls`,
+              `#   - get_browser_state + click/input/select by index: Visual interaction with the page as a user would`,
+              `#   - get_html / query_dom: Read DOM structure with CSS selectors`,
+              `#   - get_react_tree: Inspect React component props, state, and hooks`,
+              `#   - take_screenshot: Visual verification of page state`,
               `#`,
-              `# POST endpoints accept JSON body with parameter names as keys.`,
+              `# All POST endpoints accept JSON body with parameter names as keys.`,
               ``,
               `SERVICE_URL="${serviceUrl}"`,
           ];
           if (token) {
               lines.push(`TOKEN="${token}"`);
           }
-          lines.push(``, `# 1. Get interactive elements (smart DOM analysis with indexed elements):`, `curl "$SERVICE_URL/get_browser_state"${auth}`, ``, `# 2. Click element by index (e.g. click [3]):`, `curl -X POST "$SERVICE_URL/click_element_by_index"${auth} -H "Content-Type: application/json" -d '{"index": 3}'`, ``, `# 3. Type into an input by index:`, `curl -X POST "$SERVICE_URL/input_text"${auth} -H "Content-Type: application/json" -d '{"index": 5, "text": "hello"}'`, ``, `# Take a screenshot:`, `curl "$SERVICE_URL/take_screenshot"${auth}`, ``, `# Execute JavaScript remotely:`, `curl -X POST "$SERVICE_URL/execute_script"${auth} -H "Content-Type: application/json" -d '{"code": "document.title"}'`, ``, `# Full API docs:`, `curl "$SERVICE_URL/get_skill_md"${auth}`);
+          lines.push(``, `# Execute JavaScript (most versatile — read state, call APIs, modify DOM):`, `curl -X POST "$SERVICE_URL/execute_script"${auth} -H "Content-Type: application/json" -d '{"code": "document.title"}'`, ``, `# Smart DOM analysis (indexed interactive elements for click/type/select):`, `curl "$SERVICE_URL/get_browser_state"${auth}`, ``, `# Interact by element index:`, `curl -X POST "$SERVICE_URL/click_element_by_index"${auth} -H "Content-Type: application/json" -d '{"index": 3}'`, `curl -X POST "$SERVICE_URL/input_text"${auth} -H "Content-Type: application/json" -d '{"index": 5, "text": "hello"}'`, ``, `# Screenshot + React inspection:`, `curl "$SERVICE_URL/take_screenshot"${auth}`, `curl "$SERVICE_URL/get_react_tree"${auth}`, ``, `# Navigate (auto-reconnects for same-origin):`, `curl -X POST "$SERVICE_URL/navigate"${auth} -H "Content-Type: application/json" -d '{"url": "/other-page"}'`, ``, `# Full API docs:`, `curl "$SERVICE_URL/get_skill_md"${auth}`);
           return lines.join("\n");
       }
       /**