@debugg-ai/debugg-ai-mcp 2.4.1 → 2.6.0

package/dist/tools/probePage.js

@@ -0,0 +1,89 @@
+/**
+ * Probe Page Tool Definition.
+ *
+ * Lightweight no-LLM batch page probe — navigate + capture state for 1-20
+ * URLs in one backend execution. Returns screenshots, page metadata,
+ * structured console errors, and per-URL networkSummary (origin+pathname
+ * aggregation that surfaces refetch loops as a single entry).
+ *
+ * NOT an agent: no LLM in the critical path; no interaction (clicks/fills);
+ * no scenario verification. For those, use check_app_in_browser.
+ */
+import { ProbePageInputSchema } from '../types/index.js';
+import { probePageHandler } from '../handlers/probePageHandler.js';
+const DESCRIPTION = `Probe one or more URLs and return their rendered state — screenshot, page metadata (title/finalUrl/statusCode/loadTimeMs), structured console errors, and per-URL network summary (refetch loops collapse into one row by origin+pathname).
+
+WHEN TO USE: "did I just break /settings?" / "smoke-test these 5 routes after my refactor" / "what's actually rendering at /dashboard?" — fast (<10s for 1 URL, <25s for 20), no LLM cost, no agent loop.
+
+NOT FOR: scenario verification (sign in → click X → assert Y), interaction (clicks, form fills, scrolls), or anything requiring agent decisions. Use check_app_in_browser for those.
+
+LOCALHOST SUPPORT: any localhost URL is auto-tunneled. Pre-flight TCP probe fails fast (<2s) if the dev server isn't listening.
+
+BATCH MODE: pass up to 20 targets in one call to share browser session + tunnel — dramatically faster than firing parallel single-URL probes (one execution unit, not N). Per-URL waitForSelector / waitForLoadState / timeoutMs override defaults.
+
+A single failed target's error appears in result.error without failing the whole batch — the other results stay valid.`;
+const TARGET_PROPERTIES = {
+    url: {
+        type: 'string',
+        description: 'URL to probe. Public URL or localhost URL (auto-tunneled).',
+    },
+    waitForSelector: {
+        type: 'string',
+        description: 'Optional CSS selector to wait for after navigation completes. Useful for SPAs that mount content asynchronously.',
+    },
+    waitForLoadState: {
+        type: 'string',
+        enum: ['load', 'domcontentloaded', 'networkidle'],
+        description: "When to consider the page 'loaded' before capturing. Default 'load'. Use 'networkidle' for SPAs to wait until the bundle finishes rendering.",
+    },
+    timeoutMs: {
+        type: 'number',
+        description: 'Per-URL navigation timeout in milliseconds (1000-30000, default 10000).',
+    },
+};
+export function buildProbePageTool() {
+    return {
+        name: 'probe_page',
+        title: 'Probe Page',
+        description: DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                targets: {
+                    type: 'array',
+                    minItems: 1,
+                    maxItems: 20,
+                    items: {
+                        type: 'object',
+                        properties: TARGET_PROPERTIES,
+                        required: ['url'],
+                        additionalProperties: false,
+                    },
+                    description: '1-20 URLs to probe. Each entry can carry its own per-URL wait config.',
+                },
+                includeHtml: {
+                    type: 'boolean',
+                    description: "If true, each result includes the page's outerHTML. Default false to keep response size sane.",
+                },
+                captureScreenshots: {
+                    type: 'boolean',
+                    description: 'If true (default), one PNG screenshot is returned per target. Set false for very large batches or when only the structured data matters.',
+                },
+                repoName: {
+                    type: 'string',
+                    description: "GitHub repository name (e.g. 'my-org/my-repo'). Auto-detected from the current git repo — only provide this to scope the probe to a different project context.",
+                },
+            },
+            required: ['targets'],
+            additionalProperties: false,
+        },
+    };
+}
+export function buildValidatedProbePageTool() {
+    const tool = buildProbePageTool();
+    return {
+        ...tool,
+        inputSchema: ProbePageInputSchema,
+        handler: probePageHandler,
+    };
+}

package/dist/types/index.js

@@ -152,3 +152,20 @@ export var LogLevel;
     LogLevel["INFO"] = "info";
     LogLevel["DEBUG"] = "debug";
 })(LogLevel || (LogLevel = {}));
+// ── probe-page ────────────────────────────────────────────────────────────
+// Lightweight no-LLM page-probe tool. Each target gets its own wait config;
+// targets[] is the batch — one workflow execution covers up to 20 URLs sharing
+// browser session + tunnel. Strict schema: forbidden agent fields like
+// `description` and `credentialId` reject (zero-LLM contract).
+export const ProbePageTargetSchema = z.object({
+    url: z.preprocess(normalizeUrl, z.string().url('Invalid URL. Pass a full URL like "http://localhost:3000" or "https://example.com". Localhost URLs are auto-tunneled to the remote browser.')),
+    waitForSelector: z.string().optional(),
+    waitForLoadState: z.enum(['load', 'domcontentloaded', 'networkidle']).default('load'),
+    timeoutMs: z.number().int().min(1000, 'timeoutMs minimum is 1000 (1s)').max(30000, 'timeoutMs maximum is 30000 (30s) — longer probes should use check_app_in_browser').default(10000),
+}).strict();
+export const ProbePageInputSchema = z.object({
+    targets: z.array(ProbePageTargetSchema).min(1, 'targets must have at least one URL').max(20, 'targets capped at 20 per call — split larger sweeps across multiple calls'),
+    includeHtml: z.boolean().default(false),
+    captureScreenshots: z.boolean().default(true),
+    repoName: z.string().optional(),
+}).strict();

package/dist/utils/errors.js

@@ -83,7 +83,6 @@ export function handleConfigurationError(error) {
  * Handle external service errors (e.g., API calls)
  */
 export function handleExternalServiceError(error, serviceName, operation) {
-    const context = `${serviceName}${operation ? `:${operation}` : ''}`;
     if (error instanceof Error) {
         logger.error('External service error', {
             serviceName,

package/dist/utils/harSummarizer.js

@@ -0,0 +1,193 @@
+/**
+ * harSummarizer — pure HAR + console aggregation utilities.
+ *
+ * Aggregation key for networkSummary: `origin + pathname` (per system reqs).
+ * Refetch loops with varying query strings collapse into a single entry.
+ *
+ * Pure functions — no I/O, no async — so they can be reused by the future
+ * `summarize_execution` tool.
+ */
+/**
+ * Re-aggregate backend's pre-grouped network_summary entries by
+ * `origin + pathname` (vs backend's full-URL key). Collapses refetch loops:
+ * 5 separate `/api/poll?n=0..4` entries become 1 entry with count: 5.
+ *
+ * Backend `browser.capture` (commit 154e1e69) emits network_summary already
+ * grouped by full URL with shape `{url, count, methods[], statuses{}, resource_types[]}`.
+ * That preserves the per-request granularity but defeats the original
+ * client #1 use case ("endpoint hit N times" refetch detection). MCP-side
+ * re-aggregation runs once over the small pre-grouped list — cheap.
+ */
+export function reaggregateByOriginPath(entries) {
+    if (!Array.isArray(entries))
+        return [];
+    const buckets = new Map();
+    for (const e of entries) {
+        try {
+            const url = e?.url;
+            if (typeof url !== 'string')
+                continue;
+            const parsed = new URL(url);
+            const key = `${parsed.origin}${parsed.pathname}`;
+            const count = typeof e.count === 'number' ? e.count : 0;
+            const statuses = e.statuses ?? {};
+            const existing = buckets.get(key);
+            if (existing) {
+                existing.count += count;
+                for (const [code, n] of Object.entries(statuses)) {
+                    if (typeof n === 'number') {
+                        existing.statuses[code] = (existing.statuses[code] ?? 0) + n;
+                    }
+                }
+            }
+            else {
+                const out = {
+                    url: key,
+                    count,
+                    statuses: { ...statuses },
+                    totalBytes: 0, // Backend's pre-grouped shape doesn't expose response bytes; placeholder until we wire fetched-bytes.
+                };
+                buckets.set(key, out);
+            }
+        }
+        catch {
+            // malformed URL — skip
+        }
+    }
+    return [...buckets.values()].sort((a, b) => b.count - a.count);
+}
+/**
+ * Map backend's console_slice entry shape to MCP's ConsoleErrorEntry.
+ * Backend shape: {text, level, location: {url, line}, timestamp}
+ * MCP shape:     {level, text, source?, lineNumber?, timestamp?}
+ */
+export function mapConsoleSlice(entries) {
+    if (!Array.isArray(entries))
+        return [];
+    const out = [];
+    for (const e of entries) {
+        if (typeof e !== 'object' || e === null)
+            continue;
+        const entry = {
+            level: typeof e.level === 'string' ? e.level : 'log',
+            text: typeof e.text === 'string' ? e.text : '',
+        };
+        const loc = e.location ?? {};
+        if (typeof loc.url === 'string' && loc.url)
+            entry.source = loc.url;
+        else if (typeof e.source === 'string' && e.source)
+            entry.source = e.source;
+        if (typeof loc.line === 'number')
+            entry.lineNumber = loc.line;
+        else if (typeof e.lineNumber === 'number')
+            entry.lineNumber = e.lineNumber;
+        // Backend timestamps are ISO strings; MCP type uses number (ms since epoch).
+        // Coerce when possible; otherwise pass through unchanged.
+        if (typeof e.timestamp === 'number') {
+            entry.timestamp = e.timestamp;
+        }
+        else if (typeof e.timestamp === 'string') {
+            const parsed = Date.parse(e.timestamp);
+            if (!isNaN(parsed))
+                entry.timestamp = parsed;
+        }
+        out.push(entry);
+    }
+    return out;
+}
+/**
+ * Aggregate HAR `log.entries` into per-endpoint NetworkSummary[], sorted
+ * descending by request count (hottest endpoints first). Malformed entries
+ * (missing request.url or response.status) are skipped, not thrown.
+ */
+export function summarizeHar(harEntries) {
+    if (!Array.isArray(harEntries))
+        return [];
+    const buckets = new Map();
+    for (const entry of harEntries) {
+        try {
+            const reqUrl = entry?.request?.url;
+            const status = entry?.response?.status;
+            if (typeof reqUrl !== 'string' || typeof status !== 'number')
+                continue;
+            // Aggregation key: origin + pathname (refetch loops collapse).
+            let parsed;
+            try {
+                parsed = new URL(reqUrl);
+            }
+            catch {
+                continue;
+            }
+            const key = `${parsed.origin}${parsed.pathname}`;
+            const bytesRaw = entry?.response?.content?.size;
+            const bytes = typeof bytesRaw === 'number' && bytesRaw >= 0 ? bytesRaw : 0;
+            const mime = entry?.response?.content?.mimeType;
+            const mimeStr = typeof mime === 'string' && mime ? mime : '';
+            const existing = buckets.get(key);
+            if (existing) {
+                existing.count++;
+                const sk = String(status);
+                existing.statuses[sk] = (existing.statuses[sk] ?? 0) + 1;
+                existing.totalBytes += bytes;
+                if (mimeStr)
+                    existing.mimeTypes.add(mimeStr);
+            }
+            else {
+                buckets.set(key, {
+                    url: key,
+                    count: 1,
+                    statuses: { [String(status)]: 1 },
+                    totalBytes: bytes,
+                    mimeTypes: mimeStr ? new Set([mimeStr]) : new Set(),
+                });
+            }
+        }
+        catch {
+            // malformed — skip
+        }
+    }
+    return [...buckets.values()]
+        .map(({ mimeTypes, url, count, statuses, totalBytes }) => {
+        const out = { url, count, statuses, totalBytes };
+        // Only attach mimeType when homogeneous — mixed types omit the field.
+        if (mimeTypes.size === 1) {
+            out.mimeType = [...mimeTypes][0];
+        }
+        return out;
+    })
+        .sort((a, b) => b.count - a.count);
+}
+/**
+ * Normalize a console-log JSON array into ConsoleErrorEntry[].
+ * Maps backend's snake_case (`line_number`, `url`) to MCP's camelCase
+ * (`lineNumber`, `source`). Drops entries that aren't plain objects.
+ */
+export function summarizeConsole(consoleEntries) {
+    if (!Array.isArray(consoleEntries))
+        return [];
+    const out = [];
+    for (const e of consoleEntries) {
+        if (typeof e !== 'object' || e === null)
+            continue;
+        const entry = {
+            level: typeof e.level === 'string' ? e.level : 'log',
+            text: typeof e.text === 'string' ? e.text : '',
+        };
+        // source: prefer `url` (backend convention), fall back to `source`
+        const sourceVal = typeof e.url === 'string' && e.url
+            ? e.url
+            : (typeof e.source === 'string' && e.source ? e.source : undefined);
+        if (sourceVal)
+            entry.source = sourceVal;
+        // lineNumber: snake_case from backend → camelCase
+        const lineVal = typeof e.line_number === 'number'
+            ? e.line_number
+            : (typeof e.lineNumber === 'number' ? e.lineNumber : undefined);
+        if (typeof lineVal === 'number')
+            entry.lineNumber = lineVal;
+        if (typeof e.timestamp === 'number')
+            entry.timestamp = e.timestamp;
+        out.push(entry);
+    }
+    return out;
+}

package/dist/utils/projectAnalyzer.js

@@ -45,7 +45,7 @@ export class ProjectAnalyzer {
     /**
      * Analyze codebase for context extraction
      */
-    async analyzeCodebase(repoPath, repoName, branchName, includeChanges = true) {
+    async analyzeCodebase(repoPath, repoName, branchName, _includeChanges = true) {
         try {
             logger.info('Starting codebase analysis', { repoPath, repoName, branchName });
             const analysis = await this.analyzeProject(repoPath);
@@ -384,7 +384,7 @@ export class ProjectAnalyzer {
                     }
                 }
             }
-            catch (error) {
+            catch {
                 // Skip directories we can't read
             }
         };

package/dist/utils/telemetry.js

@@ -52,6 +52,7 @@ export const TelemetryEvents = {
     TOOL_EXECUTED: 'tool.executed',
     TOOL_FAILED: 'tool.failed',
     WORKFLOW_EXECUTED: 'workflow.executed',
+    WORKFLOW_TRANSIENT_RETRY: 'workflow.transient_retry',
     TUNNEL_PROVISIONED: 'tunnel.provisioned',
     TUNNEL_PROVISION_RETRY: 'tunnel.provision_retry',
     TUNNEL_STOPPED: 'tunnel.stopped',

package/dist/utils/transientErrors.js

@@ -0,0 +1,82 @@
+/**
+ * Detect well-known transient failure signatures in completed workflow
+ * executions. When `isTransientWorkflowError` returns true, the MCP handler
+ * auto-retries the workflow (cost: one extra quota unit) — saving the caller
+ * from the 'pure infrastructure noise' failure mode the original client
+ * called out in their feedback (Pydantic JSON parse errors, etc.).
+ *
+ * Be CONSERVATIVE: only patterns documented as transient. False positives
+ * waste quota; false negatives leave existing behavior, which is fine — the
+ * caller still gets a clear error and can decide what to do.
+ *
+ * Bead `kbxy`. Patterns are extracted (not inlined) so they're easy to audit
+ * + extend as new transient signatures get observed in production.
+ */
+/**
+ * Patterns that match transient backend failures worth retrying. Each entry
+ * is a regex tested against `errorMessage` AND `state.error`. Matching ANY
+ * pattern in EITHER field flags the execution as transient.
+ *
+ * To add a new pattern: confirm by sampling production telemetry that the
+ * signature recovers on retry (a one-shot reproduce-then-retry test is
+ * sufficient evidence). Document the source in the comment.
+ */
+const TRANSIENT_PATTERNS = [
+    // The original client complaint. Backend agent's brain.step occasionally
+    // returns malformed JSON for the structured output — Pydantic chokes on
+    // EOF / partial JSON. A fresh agent invocation reliably recovers.
+    { pattern: /Invalid JSON.*EOF while parsing/i, reason: 'pydantic-eof' },
+    { pattern: /Failed to parse AgentOutput/i, reason: 'agent-output-parse' },
+    // Backend-side infrastructure flakes (nginx 502 from upstream + timeouts).
+    // Both observed in production during 2026-04-26 + 2026-04-27 deploys —
+    // recovery on next request is the rule, not the exception.
+    { pattern: /502 Bad Gateway/i, reason: 'nginx-502' },
+    { pattern: /upstream connect timeout/i, reason: 'upstream-timeout' },
+    // Network-layer transient — TCP reset between MCP↔backend or backend↔model.
+    { pattern: /ECONNRESET|connection reset by peer/i, reason: 'econnreset' },
+];
+/**
+ * @returns true if the execution's error fields contain a known transient
+ * signature, indicating a retry has a reasonable chance of succeeding.
+ */
+export function isTransientWorkflowError(execution) {
+    if (!execution)
+        return false;
+    const candidates = [];
+    if (typeof execution.errorMessage === 'string' && execution.errorMessage) {
+        candidates.push(execution.errorMessage);
+    }
+    if (typeof execution.state?.error === 'string' && execution.state.error) {
+        candidates.push(execution.state.error);
+    }
+    if (candidates.length === 0)
+        return false;
+    for (const text of candidates) {
+        for (const { pattern } of TRANSIENT_PATTERNS) {
+            if (pattern.test(text))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * @returns the reason tag for the matched transient pattern (for telemetry),
+ *   or undefined if no pattern matched. Useful when you want to attach a
+ *   classifier to a `workflow.transient_retry` event.
+ */
+export function transientReasonTag(execution) {
+    if (!execution)
+        return undefined;
+    const fields = [];
+    if (typeof execution.errorMessage === 'string' && execution.errorMessage)
+        fields.push(execution.errorMessage);
+    if (typeof execution.state?.error === 'string' && execution.state.error)
+        fields.push(execution.state.error);
+    for (const text of fields) {
+        for (const { pattern, reason } of TRANSIENT_PATTERNS) {
+            if (pattern.test(text))
+                return reason;
+        }
+    }
+    return undefined;
+}

package/dist/utils/urlParser.js

@@ -54,7 +54,7 @@ export function parseUrl(urlString) {
             hash: url.hash
         };
     }
-    catch (error) {
+    catch {
         throw new Error(`Invalid URL format: ${urlString}`);
     }
 }

package/dist/utils/validation.js

@@ -81,7 +81,7 @@ export function validatePort(port) {
     try {
         return commonSchemas.port.parse(port);
     }
-    catch (error) {
+    catch {
         throw new MCPError(MCPErrorCode.VALIDATION_ERROR, `Invalid port number: ${port}. Port must be between 1 and 65535.`, { port });
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {