hypha-debugger 0.2.4 → 0.2.5

package/dist/hypha-debugger.js

@@ -14009,9 +14009,11 @@
   takeScreenshot.__schema__ = {
       name: "takeScreenshot",
       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.",
+          "Downscaled to fit within max_width × max_height (default 1024px) to keep the payload " +
+          "small enough for AI agents. Defaults to JPEG at 0.75 quality. " +
+          "Returns: { data: 'data:image/jpeg;base64,...', format, width, height, size_kb }. " +
+          "Note: the image is in the `data` field as a full data: URL — strip the `data:...;base64,` " +
+          "prefix before base64-decoding.",
       parameters: {
           type: "object",
           properties: {
@@ -14141,7 +14143,11 @@
   }
   executeScript.__schema__ = {
       name: "executeScript",
-      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())".',
+      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())". ' +
+          'Returns: { result, type } on success, or { error } on exception.',
       parameters: {
           type: "object",
           properties: {
@@ -14750,6 +14756,28 @@
           "",
           "- **GET** for functions with no required parameters",
           "- **POST** with JSON body for functions with parameters",
+          "- Append `?_mode=last` to resolve the most recent instance (recommended after page reloads where the clientId changes)",
+          "",
+          "## Response format",
+          "",
+          "All functions return JSON. There are three patterns:",
+          "",
+          "**1. Data-returning functions** (e.g. `take_screenshot`, `get_page_info`, `execute_script`, `get_browser_state`, `get_html`, `get_react_tree`) return function-specific keys:",
+          "",
+          "- `take_screenshot` → `{data, format, width, height, size_kb}` where `data` is a `data:image/jpeg;base64,...` URL (note: field is `data`, not `screenshot` or `image`)",
+          "- `execute_script` → `{result, type}` (or `{error}` on exception)",
+          "- `get_browser_state` → `{url, title, header, content, footer, element_count}`",
+          "- `get_page_info` → `{url, title, viewport_width, viewport_height, ...}`",
+          "- `get_html` → `{html, length, truncated}`",
+          "",
+          "**2. Action functions** (e.g. `click_*`, `input_text`, `select_option`, `scroll`, `navigate`) return:",
+          "",
+          "- `{success: true, message: \"...\"}` — action succeeded",
+          "- `{success: false, message: \"...\"}` — action failed (element not found, etc.)",
+          "",
+          "**3. Errors from the Hypha gateway** (NOT from the service itself) return:",
+          "",
+          "- `{success: false, detail: \"...\"}` — e.g. service not found, call timed out, disconnected. If you see this, the browser tab is probably closed or the debugger crashed.",
           "",
       ].join("\n");
       // Build the function reference
@@ -14771,11 +14799,15 @@
               for (const [param, info] of Object.entries(props)) {
                   const isRequired = required.includes(param);
                   let typeStr = info.type ?? "any";
-                  if (info.enum)
-                      typeStr = info.enum.map((e) => `"${e}"`).join(" | ");
+                  if (info.enum) {
+                      // Use HTML-escaped "or" separator; "|" breaks Markdown tables.
+                      typeStr = info.enum.map((e) => `"${e}"`).join(" / ");
+                  }
                   if (info.items)
                       typeStr = `${info.items.type}[]`;
-                  functionDocs.push(`| \`${param}\` | ${typeStr} | ${isRequired ? "Yes" : "No"} | ${info.description ?? ""} |`);
+                  // Escape pipes in descriptions to avoid breaking table layout
+                  const desc = (info.description ?? "").replace(/\|/g, "\\|");
+                  functionDocs.push(`| \`${param}\` | ${typeStr} | ${isRequired ? "Yes" : "No"} | ${desc} |`);
               }
               functionDocs.push("");
               // Example curl
@@ -14817,14 +14849,17 @@
       const tips = [
           "## Tips",
           "",
-          "- **`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.",
+          "- **`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. Returns `{result, type}`.",
           "- **`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 `take_screenshot`** to visually verify the page state. The image is returned in the `data` field as a `data:image/jpeg;base64,...` URL — strip the `data:...;base64,` prefix before decoding.",
+          "- **Use `remove_highlights`** before a screenshot for a clean view.",
           "- **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 without needing DevTools.",
           "- **Use `navigate`** to go to other pages — same-origin navigation auto-reconnects the debugger.",
+          "- **If you get `{success: false, detail: \"Service not found\"}`** — the browser tab was closed or the debugger disconnected. The user needs to re-click the bookmarklet.",
+          "- **Append `?_mode=last`** to the URL if the service clientId changed (e.g. after page reload) — resolves to the most recent instance.",
           "- All POST endpoints accept JSON body with the parameter names as keys.",
           "",
       ].join("\n");