hypha-debugger 0.1.9 → 0.1.11

package/dist/hypha-debugger.mjs

@@ -1968,27 +1968,95 @@ async function toJpeg(node, options = {}) {
 
 /**
  * Screenshot capture service using html-to-image.
+ *
+ * Images are downscaled before being returned so agents don't receive
+ * multi-megabyte base64 payloads that can crash their context window.
  */
-async function takeScreenshot(selector, format, quality, scale, max_width, max_height) {
-    const fmt = format ?? "png";
-    const qual = quality ?? 0.92;
-    const scl = scale ?? 1;
-    const target = selector ? document.querySelector(selector) : document.body;
-    if (!target) {
-        return { error: `No element found for selector: ${selector}` };
+/**
+ * Resize an image data URL via a canvas. Returns a new data URL at the
+ * requested format/quality. Maintains aspect ratio: fits within
+ * (maxWidth × maxHeight) without distortion.
+ */
+async function resizeDataUrl(dataUrl, maxWidth, maxHeight, format, quality) {
+    return new Promise((resolve, reject) => {
+        const img = new Image();
+        img.onload = () => {
+            const srcW = img.naturalWidth;
+            const srcH = img.naturalHeight;
+            // Compute scale to fit within bounds (but never upscale)
+            const scale = Math.min(maxWidth / srcW, maxHeight / srcH, 1);
+            const dstW = Math.max(1, Math.round(srcW * scale));
+            const dstH = Math.max(1, Math.round(srcH * scale));
+            const canvas = document.createElement("canvas");
+            canvas.width = dstW;
+            canvas.height = dstH;
+            const ctx = canvas.getContext("2d");
+            if (!ctx) {
+                reject(new Error("Could not get 2D canvas context"));
+                return;
+            }
+            // Fill white background for JPEG (no alpha support)
+            if (format === "jpeg") {
+                ctx.fillStyle = "#ffffff";
+                ctx.fillRect(0, 0, dstW, dstH);
+            }
+            ctx.drawImage(img, 0, 0, dstW, dstH);
+            const mime = format === "jpeg" ? "image/jpeg" : "image/png";
+            const out = canvas.toDataURL(mime, quality);
+            resolve({ dataUrl: out, width: dstW, height: dstH });
+        };
+        img.onerror = () => reject(new Error("Failed to load image for resizing"));
+        img.src = dataUrl;
+    });
+}
+async function takeScreenshot(selector, format, quality, max_width, max_height, full_page) {
+    // Agent-friendly defaults: JPEG, moderate quality, capped at 1024px,
+    // viewport-only (not the entire scrollable page).
+    const fmt = format ?? "jpeg";
+    const qual = quality ?? 0.75;
+    const maxW = max_width ?? 1024;
+    const maxH = max_height ?? 1024;
+    const capturePage = full_page ?? false;
+    // Pick target:
+    //   - explicit selector → that element
+    //   - full_page=true → document.documentElement (the entire scrollable page)
+    //   - default → viewport-sized region (clipped to window size)
+    let target;
+    if (selector) {
+        target = document.querySelector(selector);
+        if (!target) {
+            return { error: `No element found for selector: ${selector}` };
+        }
+    }
+    else if (capturePage) {
+        target = document.documentElement;
+    }
+    else {
+        target = document.body;
     }
     try {
         const node = target;
+        // For viewport-only captures, limit html-to-image's output size
+        // to the viewport dimensions.
+        const viewportW = window.innerWidth;
+        const viewportH = window.innerHeight;
         const captureOptions = {
             quality: qual,
-            pixelRatio: scl,
+            pixelRatio: 1, // always capture at 1x — we'll resize after
             cacheBust: true,
             skipAutoScale: true,
-            // Filter out the debugger overlay itself
             filter: (el) => {
-                return el.id !== "hypha-debugger-host";
+                // Exclude the debugger overlay and cursor from screenshots
+                return (el.id !== "hypha-debugger-host" &&
+                    el.id !== "hypha-debugger-cursor" &&
+                    el.id !== "playwright-highlight-container");
             },
         };
+        if (!selector && !capturePage) {
+            // Viewport-only capture: constrain canvas to window size
+            captureOptions.width = viewportW;
+            captureOptions.height = viewportH;
+        }
         let dataUrl;
         if (fmt === "jpeg") {
             dataUrl = await toJpeg(node, captureOptions);
@@ -1996,26 +2064,15 @@ async function takeScreenshot(selector, format, quality, scale, max_width, max_h
         else {
             dataUrl = await toPng(node, captureOptions);
         }
-        // Get dimensions
-        const rect = node.getBoundingClientRect();
-        let width = Math.round(rect.width * scl);
-        let height = Math.round(rect.height * scl);
-        // Optionally resize if too large
-        if (max_width && width > max_width) {
-            const ratio = max_width / width;
-            width = max_width;
-            height = Math.round(height * ratio);
-        }
-        if (max_height && height > max_height) {
-            const ratio = max_height / height;
-            height = max_height;
-            width = Math.round(width * ratio);
-        }
+        // Resize down to fit within (maxW × maxH) and re-encode
+        const resized = await resizeDataUrl(dataUrl, maxW, maxH, fmt, qual);
+        const sizeKb = Math.round((resized.dataUrl.length * 0.75) / 1024); // rough base64 → bytes
         return {
-            data: dataUrl,
+            data: resized.dataUrl,
             format: fmt,
-            width,
-            height,
+            width: resized.width,
+            height: resized.height,
+            size_kb: sizeKb,
         };
     }
     catch (err) {
@@ -2024,34 +2081,37 @@ async function takeScreenshot(selector, format, quality, scale, max_width, max_h
 }
 takeScreenshot.__schema__ = {
     name: "takeScreenshot",
-    description: "Capture a screenshot of the entire page or a specific element. Returns a base64-encoded data URL.",
+    description: "Capture a screenshot of the current viewport, a specific element, or the full page. " +
+        "Returns a base64-encoded data URL, downscaled to fit within max_width × max_height " +
+        "(default 1024px) to keep the payload small enough for AI agents. Defaults to JPEG " +
+        "format at 0.75 quality for reasonable file size.",
     parameters: {
         type: "object",
         properties: {
             selector: {
                 type: "string",
-                description: "CSS selector of the element to capture. Omit to capture the entire page body.",
+                description: "CSS selector of the element to capture. Omit to capture the viewport (or full page if full_page=true).",
             },
             format: {
                 type: "string",
                 enum: ["png", "jpeg"],
-                description: 'Image format. Default: "png".',
+                description: 'Image format. Default: "jpeg" (much smaller than PNG). Use "png" for sharp text.',
             },
             quality: {
                 type: "number",
-                description: "Image quality (0-1) for JPEG. Default: 0.92.",
-            },
-            scale: {
-                type: "number",
-                description: "Pixel ratio / scale factor. Default: 1. Use 2 for retina.",
+                description: "JPEG quality (0–1). Default: 0.75. Ignored for PNG. Lower = smaller payload.",
             },
             max_width: {
                 type: "number",
-                description: "Maximum width in pixels. Image will be scaled down if larger.",
+                description: "Maximum output width in pixels. Default: 1024. Image is scaled down preserving aspect ratio.",
             },
             max_height: {
                 type: "number",
-                description: "Maximum height in pixels. Image will be scaled down if larger.",
+                description: "Maximum output height in pixels. Default: 1024. Image is scaled down preserving aspect ratio.",
+            },
+            full_page: {
+                type: "boolean",
+                description: "If true, capture the entire scrollable page instead of just the viewport. Default: false.",
             },
         },
     },
@@ -2060,12 +2120,56 @@ takeScreenshot.__schema__ = {
 /**
  * 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
@@ -2080,6 +2184,7 @@ async function executeScript(code, timeout_ms) {
                 serialized = {
                     tag: result.tagName.toLowerCase(),
                     id: result.id,
+                    className: result.className,
                     text: (result.textContent ?? "").trim().slice(0, 500),
                 };
                 type = "HTMLElement";
@@ -2109,13 +2214,13 @@ async function executeScript(code, timeout_ms) {
 }
 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",
@@ -2638,70 +2743,78 @@ function generateSkillMd(serviceFunctions, serviceUrl) {
         "# 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.",
         "",
-        "## Recommended Workflow (Index-Based Interaction)",
+        "## Approaches",
         "",
-        "The most reliable way to interact with a page is using the smart DOM analysis:",
+        "### execute_script — Run Arbitrary JavaScript",
+        "",
+        "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",
@@ -2777,14 +2890,14 @@ function generateSkillMd(serviceFunctions, serviceUrl) {
     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");
@@ -2818,14 +2931,24 @@ function wrapFn(fn) {
     // 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);
         }
@@ -5915,22 +6038,21 @@ class HyphaDebugger {
             `# 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");
     }
     /**