hypha-debugger 0.1.0 → 0.1.1

package/dist/hypha-debugger.mjs

@@ -47,8 +47,8 @@ const overlayStyles = `
 
   .debugger-panel {
     display: none;
-    width: 320px;
-    max-height: 420px;
+    width: 380px;
+    max-height: 520px;
     background: #1e1e2e;
     color: #cdd6f4;
     border-radius: 8px;
@@ -121,7 +121,7 @@ const overlayStyles = `
     padding: 10px 12px;
     overflow-y: auto;
     flex: 1;
-    max-height: 340px;
+    max-height: 440px;
   }
 
   .info-row {
@@ -145,12 +145,19 @@ const overlayStyles = `
     font-size: 11px;
   }
 
-  .url-section {
+  .instructions-section {
     margin-top: 8px;
     padding-top: 6px;
     border-top: 1px solid #313244;
   }
 
+  .instructions-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 4px;
+  }
+
   .url-label {
     font-size: 11px;
     color: #6c7086;
@@ -159,25 +166,19 @@ const overlayStyles = `
     margin-bottom: 3px;
   }
 
-  .url-row {
-    display: flex;
-    align-items: center;
-    gap: 4px;
-    background: #313244;
-    border-radius: 3px;
-    padding: 4px 6px;
-  }
-
-  .url-text {
-    flex: 1;
+  .instructions-block {
     font-family: 'SF Mono', Monaco, Consolas, monospace;
     font-size: 10px;
-    color: #89b4fa;
+    color: #a6e3a1;
+    background: #11111b;
+    border: 1px solid #313244;
+    border-radius: 4px;
+    padding: 8px;
+    white-space: pre-wrap;
     word-break: break-all;
-    overflow: hidden;
-    display: -webkit-box;
-    -webkit-line-clamp: 2;
-    -webkit-box-orient: vertical;
+    max-height: 200px;
+    overflow-y: auto;
+    line-height: 1.5;
   }
 
   .copy-btn {
@@ -375,7 +376,11 @@ class DebugOverlay {
         }
     }
     setInfo(info) {
-        this.infoBody.innerHTML = "";
+        // Remove only info rows, preserve instructions section
+        const oldRows = this.infoBody.querySelectorAll(".info-row");
+        oldRows.forEach((r) => r.remove());
+        // Insert info rows at the top of infoBody
+        const firstChild = this.infoBody.firstChild;
         for (const [label, value] of Object.entries(info)) {
             const row = document.createElement("div");
             row.className = "info-row";
@@ -388,58 +393,38 @@ class DebugOverlay {
             valueSpan.title = value;
             row.appendChild(labelSpan);
             row.appendChild(valueSpan);
-            this.infoBody.appendChild(row);
+            this.infoBody.insertBefore(row, firstChild);
         }
     }
-    /** Show the service URL with a copy button. */
-    setServiceUrl(url, token) {
+    /** Show the instruction block with a copy-all button. */
+    setInstructions(instructions) {
+        // Remove any existing instruction section
+        const existing = this.infoBody.querySelector(".instructions-section");
+        if (existing)
+            existing.remove();
         const section = document.createElement("div");
-        section.className = "url-section";
-        const urlLabel = document.createElement("div");
-        urlLabel.className = "url-label";
-        urlLabel.textContent = "Service URL";
-        section.appendChild(urlLabel);
-        const urlRow = document.createElement("div");
-        urlRow.className = "url-row";
-        const urlText = document.createElement("span");
-        urlText.className = "url-text";
-        urlText.textContent = url;
-        urlText.title = url;
-        const copyBtn = document.createElement("button");
-        copyBtn.className = "copy-btn";
-        copyBtn.textContent = "Copy";
-        copyBtn.addEventListener("click", () => {
-            navigator.clipboard.writeText(url).then(() => {
-                copyBtn.textContent = "Copied!";
-                setTimeout(() => { copyBtn.textContent = "Copy"; }, 1500);
-            });
-        });
-        urlRow.appendChild(urlText);
-        urlRow.appendChild(copyBtn);
-        section.appendChild(urlRow);
-        const tokenLabel = document.createElement("div");
-        tokenLabel.className = "url-label";
-        tokenLabel.textContent = "Token";
-        tokenLabel.style.marginTop = "6px";
-        section.appendChild(tokenLabel);
-        const tokenRow = document.createElement("div");
-        tokenRow.className = "url-row";
-        const tokenText = document.createElement("span");
-        tokenText.className = "url-text";
-        tokenText.textContent = token.slice(0, 20) + "...";
-        tokenText.title = token;
-        const copyTokenBtn = document.createElement("button");
-        copyTokenBtn.className = "copy-btn";
-        copyTokenBtn.textContent = "Copy";
-        copyTokenBtn.addEventListener("click", () => {
-            navigator.clipboard.writeText(token).then(() => {
-                copyTokenBtn.textContent = "Copied!";
-                setTimeout(() => { copyTokenBtn.textContent = "Copy"; }, 1500);
+        section.className = "instructions-section";
+        const header = document.createElement("div");
+        header.className = "instructions-header";
+        const label = document.createElement("span");
+        label.className = "url-label";
+        label.textContent = "Instructions";
+        const copyAllBtn = document.createElement("button");
+        copyAllBtn.className = "copy-btn";
+        copyAllBtn.textContent = "Copy All";
+        copyAllBtn.addEventListener("click", () => {
+            navigator.clipboard.writeText(instructions).then(() => {
+                copyAllBtn.textContent = "Copied!";
+                setTimeout(() => { copyAllBtn.textContent = "Copy All"; }, 1500);
             });
         });
-        tokenRow.appendChild(tokenText);
-        tokenRow.appendChild(copyTokenBtn);
-        section.appendChild(tokenRow);
+        header.appendChild(label);
+        header.appendChild(copyAllBtn);
+        section.appendChild(header);
+        const pre = document.createElement("pre");
+        pre.className = "instructions-block";
+        pre.textContent = instructions;
+        section.appendChild(pre);
         this.infoBody.appendChild(section);
     }
     addLog(message, type = "call") {
@@ -535,38 +520,34 @@ function collectPageInfo() {
 /**
  * Page information service.
  */
-function getPageInfo() {
-    return collectPageInfo();
+function getPageInfo(include_logs, log_limit, log_level) {
+    const info = collectPageInfo();
+    if (include_logs) {
+        const logs = window.__HYPHA_DEBUGGER__?.consoleLogs ?? [];
+        const limit = log_limit ?? 50;
+        let filtered = log_level ? logs.filter((l) => l.level === log_level) : logs;
+        info.console_logs = filtered.slice(-limit);
+    }
+    return info;
 }
 getPageInfo.__schema__ = {
     name: "getPageInfo",
-    description: "Get information about the current web page including URL, title, viewport size, detected frameworks, and performance timing.",
-    parameters: {
-        type: "object",
-        properties: {},
-    },
-};
-function getConsoleLogs(options) {
-    const logs = window.__HYPHA_DEBUGGER__?.consoleLogs ?? [];
-    const level = options?.level;
-    const limit = options?.limit ?? 100;
-    let filtered = level ? logs.filter((l) => l.level === level) : logs;
-    return filtered.slice(-limit);
-}
-getConsoleLogs.__schema__ = {
-    name: "getConsoleLogs",
-    description: "Retrieve captured console output (log, warn, error, info).",
+    description: "Get information about the current web page including URL, title, viewport size, detected frameworks, and performance timing. Optionally include recent console logs.",
     parameters: {
         type: "object",
         properties: {
-            level: {
-                type: "string",
-                description: 'Filter by log level: "log", "warn", "error", "info". Omit for all levels.',
-                enum: ["log", "warn", "error", "info"],
+            include_logs: {
+                type: "boolean",
+                description: "If true, include recent console output in the response. Default: false.",
             },
-            limit: {
+            log_limit: {
                 type: "number",
-                description: "Maximum number of log entries to return (most recent). Default: 100.",
+                description: "Maximum number of console log entries to include (most recent). Default: 50.",
+            },
+            log_level: {
+                type: "string",
+                description: 'Filter console logs by level: "log", "warn", "error", "info". Omit for all levels.',
+                enum: ["log", "warn", "error", "info"],
             },
         },
     },
@@ -634,8 +615,8 @@ function elementToInfo(el) {
         children_count: el.children.length,
     };
 }
-function queryDom(selector, options) {
-    const limit = options?.limit ?? 20;
+function queryDom(selector, limit) {
+    limit = limit ?? 20;
     const elements = document.querySelectorAll(selector);
     const results = [];
     for (let i = 0; i < Math.min(elements.length, limit); i++) {
@@ -770,86 +751,40 @@ scrollTo.__schema__ = {
         required: ["target"],
     },
 };
-function getComputedStyles(selector, properties) {
-    const el = document.querySelector(selector);
+function getHtml(selector, outer, max_length) {
+    const useOuter = outer ?? true;
+    const maxLen = max_length ?? 50000;
+    const el = selector ? document.querySelector(selector) : document.documentElement;
     if (!el) {
         return { error: `No element found for selector: ${selector}` };
     }
-    const computed = getComputedStyle(el);
-    const result = {};
-    const props = properties ??
-        [
-            "display",
-            "position",
-            "width",
-            "height",
-            "color",
-            "background-color",
-            "font-size",
-            "font-family",
-            "margin",
-            "padding",
-            "border",
-            "opacity",
-            "visibility",
-            "overflow",
-            "z-index",
-        ];
-    for (const prop of props) {
-        result[prop] = computed.getPropertyValue(prop);
-    }
-    return result;
-}
-getComputedStyles.__schema__ = {
-    name: "getComputedStyles",
-    description: "Get computed CSS styles for an element.",
-    parameters: {
-        type: "object",
-        properties: {
-            selector: {
-                type: "string",
-                description: "CSS selector of the element.",
-            },
-            properties: {
-                type: "array",
-                items: { type: "string" },
-                description: 'CSS property names to retrieve, e.g. ["color", "font-size"]. Omit for common defaults.',
-            },
-        },
-        required: ["selector"],
-    },
-};
-function getElementBounds(selector) {
-    const el = document.querySelector(selector);
-    if (!el) {
-        return { error: `No element found for selector: ${selector}` };
-    }
-    const rect = el.getBoundingClientRect();
+    const raw = useOuter ? el.outerHTML : el.innerHTML;
+    const truncated = raw.length > maxLen;
     return {
-        bounds: {
-            x: Math.round(rect.x),
-            y: Math.round(rect.y),
-            width: Math.round(rect.width),
-            height: Math.round(rect.height),
-        },
-        visible: rect.width > 0 &&
-            rect.height > 0 &&
-            getComputedStyle(el).visibility !== "hidden" &&
-            getComputedStyle(el).display !== "none",
+        html: truncated ? raw.slice(0, maxLen) : raw,
+        length: raw.length,
+        truncated,
     };
 }
-getElementBounds.__schema__ = {
-    name: "getElementBounds",
-    description: "Get the bounding rectangle and visibility of a DOM element.",
+getHtml.__schema__ = {
+    name: "getHtml",
+    description: "Get the HTML content of the page or a specific element. Returns outerHTML by default. Useful for understanding page structure.",
     parameters: {
         type: "object",
         properties: {
             selector: {
                 type: "string",
-                description: "CSS selector of the element.",
+                description: "CSS selector of the element. Omit to get the full page HTML.",
+            },
+            outer: {
+                type: "boolean",
+                description: "If true (default), return outerHTML (includes the element itself). If false, return innerHTML (children only).",
+            },
+            max_length: {
+                type: "number",
+                description: "Maximum character length of the returned HTML. Default: 50000. Result will be truncated if longer.",
             },
         },
-        required: ["selector"],
     },
 };
 
@@ -1737,11 +1672,10 @@ async function toJpeg(node, options = {}) {
 /**
  * Screenshot capture service using html-to-image.
  */
-async function takeScreenshot(options) {
-    const selector = options?.selector;
-    const format = options?.format ?? "png";
-    const quality = options?.quality ?? 0.92;
-    const scale = options?.scale ?? 1;
+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}` };
@@ -1749,8 +1683,8 @@ async function takeScreenshot(options) {
     try {
         const node = target;
         const captureOptions = {
-            quality,
-            pixelRatio: scale,
+            quality: qual,
+            pixelRatio: scl,
             cacheBust: true,
             skipAutoScale: true,
             // Filter out the debugger overlay itself
@@ -1759,7 +1693,7 @@ async function takeScreenshot(options) {
             },
         };
         let dataUrl;
-        if (format === "jpeg") {
+        if (fmt === "jpeg") {
             dataUrl = await toJpeg(node, captureOptions);
         }
         else {
@@ -1767,24 +1701,22 @@ async function takeScreenshot(options) {
         }
         // Get dimensions
         const rect = node.getBoundingClientRect();
-        let width = Math.round(rect.width * scale);
-        let height = Math.round(rect.height * scale);
+        let width = Math.round(rect.width * scl);
+        let height = Math.round(rect.height * scl);
         // Optionally resize if too large
-        const maxW = options?.max_width;
-        const maxH = options?.max_height;
-        if (maxW && width > maxW) {
-            const ratio = maxW / width;
-            width = maxW;
+        if (max_width && width > max_width) {
+            const ratio = max_width / width;
+            width = max_width;
             height = Math.round(height * ratio);
         }
-        if (maxH && height > maxH) {
-            const ratio = maxH / height;
-            height = maxH;
+        if (max_height && height > max_height) {
+            const ratio = max_height / height;
+            height = max_height;
             width = Math.round(width * ratio);
         }
         return {
             data: dataUrl,
-            format,
+            format: fmt,
             width,
             height,
         };
@@ -1831,8 +1763,8 @@ takeScreenshot.__schema__ = {
 /**
  * Arbitrary JavaScript execution service.
  */
-async function executeScript(code, options) {
-    const timeoutMs = options?.timeout_ms ?? 10000;
+async function executeScript(code, timeout_ms) {
+    const timeoutMs = timeout_ms ?? 10000;
     try {
         const result = await Promise.race([
             // Use async Function to allow top-level await in the code
@@ -1923,60 +1855,6 @@ navigate.__schema__ = {
         required: ["url"],
     },
 };
-function goBack() {
-    try {
-        window.history.back();
-        return { success: true, message: "Navigated back" };
-    }
-    catch (err) {
-        return { success: false, message: `Back navigation failed: ${err.message ?? err}` };
-    }
-}
-goBack.__schema__ = {
-    name: "goBack",
-    description: "Navigate back in browser history.",
-    parameters: {
-        type: "object",
-        properties: {},
-    },
-};
-function goForward() {
-    try {
-        window.history.forward();
-        return { success: true, message: "Navigated forward" };
-    }
-    catch (err) {
-        return {
-            success: false,
-            message: `Forward navigation failed: ${err.message ?? err}`,
-        };
-    }
-}
-goForward.__schema__ = {
-    name: "goForward",
-    description: "Navigate forward in browser history.",
-    parameters: {
-        type: "object",
-        properties: {},
-    },
-};
-function reload() {
-    try {
-        window.location.reload();
-        return { success: true, message: "Reloading page" };
-    }
-    catch (err) {
-        return { success: false, message: `Reload failed: ${err.message ?? err}` };
-    }
-}
-reload.__schema__ = {
-    name: "reload",
-    description: "Reload the current page.",
-    parameters: {
-        type: "object",
-        properties: {},
-    },
-};
 
 /**
  * React component tree inspection service.
@@ -2096,9 +1974,9 @@ function fiberToInfo(fiber, depth, maxDepth) {
     }
     return info;
 }
-function getReactTree(options) {
-    const selector = options?.selector ?? "#root";
-    const maxDepth = options?.max_depth ?? 5;
+function getReactTree(selector, max_depth) {
+    selector = selector ?? "#root";
+    const maxDepth = max_depth ?? 5;
     const rootEl = document.querySelector(selector);
     if (!rootEl) {
         return { error: `No element found for selector: ${selector}` };
@@ -2142,6 +2020,133 @@ getReactTree.__schema__ = {
     },
 };
 
+/**
+ * Dynamic SKILL.md generation following the agentskills.io specification.
+ * Generates documentation from registered service function schemas.
+ */
+/**
+ * Generate a SKILL.md document from a service definition.
+ * Excludes credentials (service URL, token) — those are provided separately.
+ */
+function generateSkillMd(serviceFunctions, serviceUrl) {
+    const frontmatter = [
+        "---",
+        "name: web-debugger",
+        "description: Remote web page debugger. Inspect DOM, take screenshots, execute JavaScript, fill forms, click elements, and navigate pages — all via HTTP API calls.",
+        "compatibility: Requires network access to the Hypha server. Works with any HTTP client (curl, fetch, Python requests).",
+        "metadata:",
+        '  version: "0.1"',
+        '  author: "hypha-debugger"',
+        "---",
+    ].join("\n");
+    const intro = [
+        "",
+        "# Web Debugger Skill",
+        "",
+        "This skill allows you to remotely debug and interact with a web page through a set of HTTP API endpoints.",
+        "",
+        "## How to call functions",
+        "",
+        "All functions are available as HTTP endpoints. Use the service URL provided in the instructions.",
+        "",
+        "**GET request** (for functions with no required parameters):",
+        "```",
+        `curl '{SERVICE_URL}/get_page_info?_mode=last' -H 'Authorization: Bearer {TOKEN}'`,
+        "```",
+        "",
+        "**POST request** (for functions with parameters):",
+        "```",
+        `curl -X POST '{SERVICE_URL}/query_dom?_mode=last' \\`,
+        `  -H 'Authorization: Bearer {TOKEN}' \\`,
+        `  -H 'Content-Type: application/json' \\`,
+        `  -d '{"selector": "button"}'`,
+        "```",
+        "",
+        "Replace `{SERVICE_URL}` and `{TOKEN}` with the actual values from the instruction block.",
+        "",
+        "**Note:** The `_mode=last` query parameter ensures the latest debugger instance is used,",
+        "even if multiple sessions have connected to the same workspace.",
+        "",
+    ].join("\n");
+    // Build the function reference
+    const functionDocs = ["## Available Functions", ""];
+    const entries = Object.entries(serviceFunctions).filter(([name, fn]) => fn?.__schema__ && name !== "get_skill_md");
+    for (const [name, fn] of entries) {
+        const schema = fn.__schema__;
+        functionDocs.push(`### \`${name}\``);
+        functionDocs.push("");
+        functionDocs.push(schema.description);
+        functionDocs.push("");
+        const props = schema.parameters?.properties;
+        const required = schema.parameters?.required ?? [];
+        if (props && Object.keys(props).length > 0) {
+            functionDocs.push("**Parameters:**");
+            functionDocs.push("");
+            functionDocs.push("| Parameter | Type | Required | Description |");
+            functionDocs.push("|-----------|------|----------|-------------|");
+            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.items)
+                    typeStr = `${info.items.type}[]`;
+                functionDocs.push(`| \`${param}\` | ${typeStr} | ${isRequired ? "Yes" : "No"} | ${info.description ?? ""} |`);
+            }
+            functionDocs.push("");
+            // Example curl
+            if (required.length > 0) {
+                const exampleParams = {};
+                for (const p of required) {
+                    const info = props[p];
+                    if (info?.type === "string")
+                        exampleParams[p] = `<${p}>`;
+                    else if (info?.type === "number")
+                        exampleParams[p] = "0";
+                    else
+                        exampleParams[p] = `<${p}>`;
+                }
+                functionDocs.push("**Example:**");
+                functionDocs.push("```bash");
+                functionDocs.push(`curl -X POST '{SERVICE_URL}/${name}?_mode=last' \\`);
+                functionDocs.push(`  -H 'Authorization: Bearer {TOKEN}' \\`);
+                functionDocs.push(`  -H 'Content-Type: application/json' \\`);
+                functionDocs.push(`  -d '${JSON.stringify(exampleParams)}'`);
+                functionDocs.push("```");
+            }
+            else {
+                functionDocs.push("**Example:**");
+                functionDocs.push("```bash");
+                functionDocs.push(`curl '{SERVICE_URL}/${name}?_mode=last' -H 'Authorization: Bearer {TOKEN}'`);
+                functionDocs.push("```");
+            }
+        }
+        else {
+            functionDocs.push("**Parameters:** None");
+            functionDocs.push("");
+            functionDocs.push("**Example:**");
+            functionDocs.push("```bash");
+            functionDocs.push(`curl '{SERVICE_URL}/${name}?_mode=last' -H 'Authorization: Bearer {TOKEN}'`);
+            functionDocs.push("```");
+        }
+        functionDocs.push("");
+    }
+    const tips = [
+        "## Tips",
+        "",
+        "- **Start with `get_page_info`** to understand the page structure, URL, title, and viewport.",
+        "- **Use `query_dom`** with CSS selectors to find elements before clicking or filling them.",
+        "- **Use `take_screenshot`** to visually verify the page state.",
+        "- **Use `execute_script`** for anything not covered by the built-in functions — it runs arbitrary JavaScript.",
+        "- **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.",
+        "- All POST endpoints accept JSON body with the parameter names as keys.",
+        "- All endpoints require the `Authorization: Bearer {TOKEN}` header.",
+        "",
+    ].join("\n");
+    return [frontmatter, intro, functionDocs.join("\n"), tips].join("\n");
+}
+
 /**
  * Core debugger class: connects to Hypha and registers the debug service.
  */
@@ -2187,93 +2192,16 @@ class HyphaDebugger {
             if (this.config.token)
                 connectConfig.token = this.config.token;
             this.server = await connect(connectConfig);
-            // Wrap service functions with logging
-            const wrapFn = (fn, name) => {
-                const wrapped = async (...args) => {
-                    this.overlay?.addLog(`${name}(${this.summarizeArgs(args)})`, "call");
-                    try {
-                        const result = await fn(...args);
-                        const hasError = result && typeof result === "object" && "error" in result;
-                        if (hasError) {
-                            this.overlay?.addLog(`${name}: ${result.error}`, "error");
-                        }
-                        else {
-                            this.overlay?.addLog(`${name} -> OK`, "result");
-                        }
-                        return result;
-                    }
-                    catch (err) {
-                        this.overlay?.addLog(`${name}: ${err.message}`, "error");
-                        throw err;
-                    }
-                };
-                // Preserve schema
-                if (fn.__schema__) {
-                    wrapped.__schema__ = fn.__schema__;
-                }
-                return wrapped;
-            };
             // Register debug service
-            const service = {
-                id: this.config.service_id,
-                name: this.config.service_name,
-                type: "debugger",
-                description: "Remote web page debugger. Allows inspecting DOM, taking screenshots, executing JavaScript, and interacting with the page.",
-                config: {
-                    visibility: this.config.visibility,
-                },
-                // Service functions
-                get_page_info: wrapFn(getPageInfo, "get_page_info"),
-                get_console_logs: wrapFn(getConsoleLogs, "get_console_logs"),
-                query_dom: wrapFn(queryDom, "query_dom"),
-                click_element: wrapFn(clickElement, "click_element"),
-                fill_input: wrapFn(fillInput, "fill_input"),
-                scroll_to: wrapFn(scrollTo, "scroll_to"),
-                get_computed_styles: wrapFn(getComputedStyles, "get_computed_styles"),
-                get_element_bounds: wrapFn(getElementBounds, "get_element_bounds"),
-                take_screenshot: wrapFn(takeScreenshot, "take_screenshot"),
-                execute_script: wrapFn(executeScript, "execute_script"),
-                navigate: wrapFn(navigate, "navigate"),
-                go_back: wrapFn(goBack, "go_back"),
-                go_forward: wrapFn(goForward, "go_forward"),
-                reload: wrapFn(reload, "reload"),
-                get_react_tree: wrapFn(getReactTree, "get_react_tree"),
-            };
-            this.serviceInfo = await this.server.registerService(service);
-            // Update UI
-            const workspace = this.server.config.workspace;
-            const fullServiceId = this.serviceInfo.id ?? this.config.service_id;
-            // Generate a token for remote HTTP access
-            const sessionToken = await this.server.generateToken();
-            // Build the HTTP service URL
-            const serviceUrl = this.buildServiceUrl(fullServiceId);
+            this.serviceInfo = await this.server.registerService(this.buildServiceDefinition());
+            // Update overlay and build session
+            const session = await this.updateSession();
             if (this.overlay) {
-                this.overlay.setStatus("connected");
-                this.overlay.setInfo({
-                    Status: "Connected",
-                    Server: this.config.server_url,
-                });
-                this.overlay.setServiceUrl(serviceUrl, sessionToken);
                 this.overlay.addLog("Service registered", "result");
             }
-            console.log(`[hypha-debugger] Connected to ${this.config.server_url}`);
-            console.log(`[hypha-debugger] Service ID: ${fullServiceId}`);
-            console.log(`[hypha-debugger] Service URL: ${serviceUrl}`);
-            console.log(`[hypha-debugger] Token: ${sessionToken}`);
-            console.log(`[hypha-debugger] Test it:\n  curl '${serviceUrl}/get_page_info' -H 'Authorization: Bearer ${sessionToken}'`);
-            // Build session object
-            const session = {
-                service_id: fullServiceId,
-                workspace,
-                server: this.server,
-                service_url: serviceUrl,
-                token: sessionToken,
-                destroy: () => this.destroy(),
-            };
             // Store globally
             w.__HYPHA_DEBUGGER__ = w.__HYPHA_DEBUGGER__ ?? {};
             w.__HYPHA_DEBUGGER__.instance = this;
-            w.__HYPHA_DEBUGGER__.session = session;
             return session;
         }
         catch (err) {
@@ -2305,29 +2233,186 @@ class HyphaDebugger {
             delete w.__HYPHA_DEBUGGER__.session;
         }
     }
+    /**
+     * Generate token, build service URL, update overlay instructions, and
+     * return a DebugSession.
+     */
+    async updateSession(extra) {
+        const fullServiceId = this.serviceInfo?.id ?? this.config.service_id;
+        const sessionToken = await this.server.generateToken();
+        const serviceUrl = this.buildServiceUrl(fullServiceId);
+        const workspace = this.server.config?.workspace ?? "";
+        if (this.overlay) {
+            this.overlay.setStatus("connected");
+            this.overlay.setInfo({
+                Status: "Connected",
+                Server: this.config.server_url,
+                ...extra,
+            });
+            this.overlay.setInstructions(this.buildInstructionBlock(serviceUrl, sessionToken));
+        }
+        console.log(`[hypha-debugger] Service URL: ${serviceUrl}`);
+        console.log(`[hypha-debugger] Token: ${sessionToken}`);
+        console.log(`[hypha-debugger] Test:\n  curl '${serviceUrl}/get_page_info?_mode=last' -H 'Authorization: Bearer ${sessionToken}'`);
+        const session = {
+            service_id: fullServiceId,
+            workspace,
+            server: this.server,
+            service_url: serviceUrl,
+            token: sessionToken,
+            destroy: () => this.destroy(),
+        };
+        // Always update global session
+        const w = window;
+        w.__HYPHA_DEBUGGER__ = w.__HYPHA_DEBUGGER__ ?? {};
+        w.__HYPHA_DEBUGGER__.session = session;
+        return session;
+    }
+    /**
+     * Build a stable, predictable service URL.
+     * Strips the clientId prefix so the URL uses only the bare service name.
+     * Callers append ?_mode=last to resolve the most recent instance.
+     */
     buildServiceUrl(serviceId) {
         const base = this.config.server_url.replace(/\/+$/, "");
-        // serviceId format: "workspace/clientId:svcName"
         const slashIdx = serviceId.indexOf("/");
         if (slashIdx !== -1) {
             const workspace = serviceId.substring(0, slashIdx);
             const svcPart = serviceId.substring(slashIdx + 1);
-            return `${base}/${workspace}/services/${svcPart}`;
+            // Strip clientId: "abc123:web-debugger" → "web-debugger"
+            const colonIdx = svcPart.indexOf(":");
+            const svcName = colonIdx !== -1 ? svcPart.substring(colonIdx + 1) : svcPart;
+            return `${base}/${workspace}/services/${svcName}`;
         }
         return `${base}/services/${serviceId}`;
     }
-    getConnectToServer() {
-        // Prefer the static import; fall back to global for UMD/script-tag usage
-        const connect = hyphaRpc.connectToServer;
-        if (connect)
-            return connect;
+    getHyphaModule() {
+        // Check the static import (works when hypha-rpc is bundled or npm-installed)
+        if (hyphaRpc.connectToServer)
+            return hyphaRpc;
+        // hypha-rpc re-exports under a namespace
+        if (hyphaRpc.hyphaWebsocketClient?.connectToServer)
+            return hyphaRpc.hyphaWebsocketClient;
+        // Fall back to global (when hypha-rpc loaded via separate script tag)
         const w = window;
-        if (w.hyphaWebsocketClient?.connectToServer) {
-            return w.hyphaWebsocketClient.connectToServer;
-        }
-        throw new Error("hypha-rpc not found. Install it via npm or include the script tag: " +
+        if (w.hyphaWebsocketClient?.connectToServer)
+            return w.hyphaWebsocketClient;
+        throw new Error("hypha-rpc not found. Install it via npm or load it via: " +
             '<script src="https://cdn.jsdelivr.net/npm/hypha-rpc@0.20.97/dist/hypha-rpc-websocket.min.js"></script>');
     }
+    getConnectToServer() {
+        return this.getHyphaModule().connectToServer;
+    }
+    buildServiceDefinition() {
+        return {
+            id: this.config.service_id,
+            name: this.config.service_name,
+            type: "debugger",
+            description: "Remote web page debugger. Allows inspecting DOM, taking screenshots, executing JavaScript, and interacting with the page.",
+            config: {
+                visibility: this.config.visibility,
+            },
+            get_page_info: this.wrapFn(getPageInfo, "get_page_info"),
+            get_html: this.wrapFn(getHtml, "get_html"),
+            query_dom: this.wrapFn(queryDom, "query_dom"),
+            click_element: this.wrapFn(clickElement, "click_element"),
+            fill_input: this.wrapFn(fillInput, "fill_input"),
+            scroll_to: this.wrapFn(scrollTo, "scroll_to"),
+            take_screenshot: this.wrapFn(takeScreenshot, "take_screenshot"),
+            execute_script: this.wrapFn(executeScript, "execute_script"),
+            navigate: this.wrapFn(navigate, "navigate"),
+            get_react_tree: this.wrapFn(getReactTree, "get_react_tree"),
+            get_skill_md: this.wrapFn(this.createGetSkillMd(), "get_skill_md"),
+        };
+    }
+    createGetSkillMd() {
+        const fn = () => {
+            // Build a schema-only map (avoid calling buildServiceDefinition which would recurse)
+            const schemaFns = {};
+            const fns = {
+                get_page_info: getPageInfo, get_html: getHtml,
+                query_dom: queryDom, click_element: clickElement, fill_input: fillInput,
+                scroll_to: scrollTo, take_screenshot: takeScreenshot,
+                execute_script: executeScript, navigate: navigate,
+                get_react_tree: getReactTree,
+            };
+            for (const [name, f] of Object.entries(fns)) {
+                if (f.__schema__)
+                    schemaFns[name] = f;
+            }
+            this.serviceInfo
+                ? this.buildServiceUrl(this.serviceInfo.id ?? this.config.service_id)
+                : "{SERVICE_URL}";
+            return generateSkillMd(schemaFns);
+        };
+        fn.__schema__ = {
+            name: "getSkillMd",
+            description: "Get the SKILL.md document describing all available debugger functions, their parameters, and usage examples. Follows the agentskills.io specification.",
+            parameters: {
+                type: "object",
+                properties: {},
+            },
+        };
+        return fn;
+    }
+    /** Build the instruction block for the overlay panel. */
+    buildInstructionBlock(serviceUrl, token) {
+        return [
+            `SERVICE_URL="${serviceUrl}"`,
+            `TOKEN="${token}"`,
+            ``,
+            `# Quick test:`,
+            `curl "$SERVICE_URL/get_page_info?_mode=last" -H "Authorization: Bearer $TOKEN"`,
+            ``,
+            `# Full API docs:`,
+            `curl "$SERVICE_URL/get_skill_md?_mode=last" -H "Authorization: Bearer $TOKEN"`,
+        ].join("\n");
+    }
+    /** Wrap a service function with logging and kwargs-to-positional-args support. */
+    wrapFn(fn, name) {
+        const wrapped = async (...args) => {
+            // Hypha's HTTP API calls with keyword arguments (**kwargs),
+            // which arrive on the JS side as a single object argument.
+            // Destructure into positional args based on schema properties.
+            if (args.length === 1 &&
+                args[0] &&
+                typeof args[0] === "object" &&
+                !Array.isArray(args[0]) &&
+                fn.__schema__?.parameters?.properties) {
+                const kwargs = args[0];
+                const props = fn.__schema__.parameters.properties;
+                const paramNames = Object.keys(props);
+                // Check if any kwargs key matches a schema property name
+                const hasMatchingKey = paramNames.some((p) => p in kwargs);
+                if (hasMatchingKey) {
+                    args = paramNames.map((p) => kwargs[p]);
+                    while (args.length > 0 && args[args.length - 1] === undefined) {
+                        args.pop();
+                    }
+                }
+            }
+            this.overlay?.addLog(`${name}(${this.summarizeArgs(args)})`, "call");
+            try {
+                const result = await fn(...args);
+                const hasError = result && typeof result === "object" && "error" in result;
+                if (hasError) {
+                    this.overlay?.addLog(`${name}: ${result.error}`, "error");
+                }
+                else {
+                    this.overlay?.addLog(`${name} -> OK`, "result");
+                }
+                return result;
+            }
+            catch (err) {
+                this.overlay?.addLog(`${name}: ${err.message}`, "error");
+                throw err;
+            }
+        };
+        if (fn.__schema__) {
+            wrapped.__schema__ = fn.__schema__;
+        }
+        return wrapped;
+    }
     summarizeArgs(args) {
         if (args.length === 0)
             return "";
@@ -2346,7 +2431,14 @@ class HyphaDebugger {
 /**
  * hypha-debugger - Injectable debugger for web pages, powered by Hypha RPC.
  *
- * Usage:
+ * Simplest usage (just include the script tag, auto-starts):
+ *   <script src="https://cdn.jsdelivr.net/npm/hypha-rpc@0.20.97/dist/hypha-rpc-websocket.min.js"></script>
+ *   <script src="https://cdn.jsdelivr.net/npm/hypha-debugger/dist/hypha-debugger.min.js"></script>
+ *
+ * With config via data attributes:
+ *   <script src="..." data-server-url="https://hypha.aicell.io" data-service-id="my-debugger"></script>
+ *
+ * Programmatic usage:
  *   import { startDebugger } from 'hypha-debugger';
  *   const session = await startDebugger({ server_url: 'https://hypha.aicell.io' });
  */
@@ -2354,21 +2446,65 @@ class HyphaDebugger {
  * Start the Hypha debugger. Connects to a Hypha server and registers
  * a debug service that remote clients can use to inspect and interact
  * with this web page.
- *
- * @param config - Configuration for the debugger.
- * @returns A session object with service_id, workspace, and destroy().
- *
- * @example
- * ```js
- * import { startDebugger } from 'hypha-debugger';
- * const session = await startDebugger({ server_url: 'https://hypha.aicell.io' });
- * console.log(`Service: ${session.service_id}, Workspace: ${session.workspace}`);
- * ```
  */
 async function startDebugger(config) {
     const debugger_ = new HyphaDebugger(config);
     return debugger_.start();
 }
+/**
+ * Auto-start: when loaded via <script> tag, automatically start the debugger.
+ * Configuration can be provided via data-* attributes on the script tag:
+ *   data-server-url, data-workspace, data-token, data-service-id, data-no-ui
+ *
+ * Set data-manual to disable auto-start.
+ */
+function autoStart() {
+    if (typeof window === "undefined" || typeof document === "undefined")
+        return;
+    // Find our own script tag
+    const scripts = document.querySelectorAll("script[src]");
+    let scriptEl = null;
+    for (const s of Array.from(scripts)) {
+        if (s.src && s.src.includes("hypha-debugger")) {
+            scriptEl = s;
+            break;
+        }
+    }
+    // Skip if data-manual is set
+    if (scriptEl?.hasAttribute("data-manual"))
+        return;
+    // Skip if already started
+    if (window.__HYPHA_DEBUGGER__?.instance)
+        return;
+    const serverUrl = scriptEl?.getAttribute("data-server-url") ?? "https://hypha.aicell.io";
+    const config = {
+        server_url: serverUrl,
+    };
+    if (scriptEl?.getAttribute("data-workspace")) {
+        config.workspace = scriptEl.getAttribute("data-workspace");
+    }
+    if (scriptEl?.getAttribute("data-token")) {
+        config.token = scriptEl.getAttribute("data-token");
+    }
+    if (scriptEl?.getAttribute("data-service-id")) {
+        config.service_id = scriptEl.getAttribute("data-service-id");
+    }
+    if (scriptEl?.hasAttribute("data-no-ui")) {
+        config.show_ui = false;
+    }
+    startDebugger(config).catch((err) => {
+        console.error("[hypha-debugger] Auto-start failed:", err);
+    });
+}
+// Run auto-start after DOM is ready
+if (typeof window !== "undefined") {
+    if (document.readyState === "loading") {
+        document.addEventListener("DOMContentLoaded", autoStart);
+    }
+    else {
+        autoStart();
+    }
+}
 
 export { HyphaDebugger, startDebugger };
 //# sourceMappingURL=hypha-debugger.mjs.map