@debugg-ai/debugg-ai-mcp 3.6.0 → 3.7.1

package/dist/handlers/probePageHandler.js

@@ -23,10 +23,10 @@ import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
+import { getPageProbeTemplateSlug } from '../services/workflows.js';
 import { reaggregateByOriginPath, mapConsoleSlice } from '../utils/harSummarizer.js';
 import { fetchImageAsBase64, imageContentBlock } from '../utils/imageUtils.js';
 const logger = new Logger({ module: 'probePageHandler' });
-const TEMPLATE_KEYWORD = 'page probe';
 export async function probePageHandler(input, context, rawProgressCallback) {
     const startTime = Date.now();
     logger.toolStart('probe_page', input);
@@ -49,12 +49,25 @@ export async function probePageHandler(input, context, rawProgressCallback) {
         : undefined;
     const client = new DebuggAIServerClient(config.api.key);
     await client.init();
+    // Bead 56kd.7: cancellation is driven by the MCP request/transport lifecycle
+    // (context.signal), NOT process.stdin. The SDK aborts context.signal when the
+    // client cancels the call OR the transport closes — e.g. an HTTP client drops
+    // the connection. Under the stateless HTTP transport that is the ONLY signal
+    // we get: stdin is not the transport, so the old stdin 'close' listener never
+    // fired and a dropped client kept polling for up to ~10 min. Wiring to
+    // context.signal cancels the poll immediately (parity with 56kd.5).
     const abortController = new AbortController();
-    const onStdinClose = () => {
+    const onAbort = () => {
         abortController.abort();
-        progressDisabled = true;
+        progressDisabled = true; // client is gone — stop emitting
     };
-    process.stdin.once('close', onStdinClose);
+    const requestSignal = context.signal;
+    if (requestSignal) {
+        if (requestSignal.aborted)
+            onAbort();
+        else
+            requestSignal.addEventListener('abort', onAbort, { once: true });
+    }
     // Per-target tunnel contexts. Index aligns with input.targets[].
     const targetContexts = [];
     // Tunnel keys we provisioned this call (for cleanup if creation fails after key acquired).
@@ -154,12 +167,16 @@ export async function probePageHandler(input, context, rawProgressCallback) {
         if (progressCallback) {
             await progressCallback({ progress: ++progressStep, total: TOTAL_STEPS, message: 'Locating page-probe workflow template...' });
         }
-        const templateUuid = await getCachedTemplateUuid(TEMPLATE_KEYWORD, async (name) => {
-            return client.workflows.findTemplateByName(name);
+        // Pin dispatch to the stable slug (bead 56kd.8) — no fuzzy name resolution.
+        // Cache key = the slug so the key and the lookup can never drift apart.
+        const templateSlug = getPageProbeTemplateSlug();
+        const templateUuid = await getCachedTemplateUuid(templateSlug, async () => {
+            return client.workflows.findTemplateBySlug(templateSlug);
         });
         if (!templateUuid) {
-            throw new Error(`Page Probe Workflow Template not found. ` +
-                `Ensure the backend has a template matching "${TEMPLATE_KEYWORD}" seeded and accessible.`);
+            throw new Error(`Page Probe Workflow Template not found (slug "${templateSlug}"). ` +
+                `Ensure the backend has that template seeded and accessible ` +
+                `(GET /api/v1/workflows/?slug=${templateSlug}).`);
         }
         // ── Build contextData (camelCase; axiosTransport snake_cases on the wire) ──
         // Backend's browser.setup node (shared with App Evaluation + Raw Crawl
@@ -325,7 +342,8 @@ export async function probePageHandler(input, context, rawProgressCallback) {
         throw handleExternalServiceError(error, 'DebuggAI', 'probe_page execution');
     }
     finally {
-        process.stdin.removeListener('close', onStdinClose);
+        if (requestSignal)
+            requestSignal.removeEventListener('abort', onAbort);
         // Tunnels intentionally NOT torn down — reuse pattern (bead vwd) +
         // 55-min idle auto-shutoff. Revoke only orphaned keys (we acquired the
         // key but tunnel creation failed before ensureTunnel completed).

package/dist/handlers/testPageChangesHandler.js

@@ -266,6 +266,23 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             contextData.projectId = projectUuid;
         }
         contextData.headless = true; // D7: the MCP always runs headless — no opt-out.
+        // Bead 56kd.6: forward the auth-precondition deep-link intent verbatim per
+        // backend contract sentinal-k8x1f.8 (contextData.auth). Thin relay — express
+        // intent + forward; the backend authenticates then navigates to deepUrl. Only
+        // the fields the caller set are sent (camelCase here → snake_case on the wire).
+        if (input.auth) {
+            const auth = {};
+            if (input.auth.environmentId)
+                auth.environmentId = input.auth.environmentId;
+            if (input.auth.precondition)
+                auth.precondition = input.auth.precondition;
+            if (input.auth.entryUrl)
+                auth.entryUrl = input.auth.entryUrl;
+            if (input.auth.deepUrl)
+                auth.deepUrl = input.auth.deepUrl;
+            if (Object.keys(auth).length > 0)
+                contextData.auth = auth;
+        }
         // --- Build env (credentials/environment) ---
         const env = {};
         if (input.environmentId)

package/dist/handlers/triggerCrawlHandler.js

@@ -20,10 +20,10 @@ import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
+import { getCrawlTemplateSlug } from '../services/workflows.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
 const logger = new Logger({ module: 'triggerCrawlHandler' });
-const TEMPLATE_KEYWORD = 'raw crawl';
 // Bead kbo9: same env-driven retry budget as testPageChangesHandler (kbxy).
 function getMaxTransientRetries() {
     const raw = process.env.DEBUGGAI_TRANSIENT_RETRIES;
@@ -59,12 +59,25 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
     const originalUrl = resolveTargetUrl(input);
     let ctx = buildContext(originalUrl);
     let keyId;
+    // Bead 56kd.7: cancellation is driven by the MCP request/transport lifecycle
+    // (context.signal), NOT process.stdin. The SDK aborts context.signal when the
+    // client cancels the call OR the transport closes — e.g. an HTTP client drops
+    // the connection. Under the stateless HTTP transport that is the ONLY signal
+    // we get: stdin is not the transport, so the old stdin 'close' listener never
+    // fired and a dropped client kept polling for up to ~10 min. Wiring to
+    // context.signal cancels the poll immediately (parity with 56kd.5).
     const abortController = new AbortController();
-    const onStdinClose = () => {
+    const onAbort = () => {
         abortController.abort();
-        progressDisabled = true;
+        progressDisabled = true; // client is gone — stop emitting
     };
-    process.stdin.once('close', onStdinClose);
+    const requestSignal = context.signal;
+    if (requestSignal) {
+        if (requestSignal.aborted)
+            onAbort();
+        else
+            requestSignal.addEventListener('abort', onAbort, { once: true });
+    }
     try {
         // --- Tunnel: reuse existing or provision a fresh one ---
         if (ctx.isLocalhost) {
@@ -137,12 +150,16 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
         if (progressCallback) {
             await progressCallback({ progress: 2, total: 4, message: 'Locating crawl workflow template...' });
         }
-        const templateUuid = await getCachedTemplateUuid(TEMPLATE_KEYWORD, async (name) => {
-            return client.workflows.findTemplateByName(name);
+        // Pin dispatch to the stable slug (bead 56kd.8) — no fuzzy name resolution.
+        // Cache key = the slug so the key and the lookup can never drift apart.
+        const templateSlug = getCrawlTemplateSlug();
+        const templateUuid = await getCachedTemplateUuid(templateSlug, async () => {
+            return client.workflows.findTemplateBySlug(templateSlug);
         });
         if (!templateUuid) {
-            throw new Error(`Raw Crawl Workflow Template not found. ` +
-                `Ensure the backend has a template matching "${TEMPLATE_KEYWORD}" seeded and accessible.`);
+            throw new Error(`Crawl Workflow Template not found (slug "${templateSlug}"). ` +
+                `Ensure the backend has that template seeded and accessible ` +
+                `(GET /api/v1/workflows/?slug=${templateSlug}).`);
         }
         // --- Build contextData + env ---
         const contextData = {
@@ -298,7 +315,8 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
         throw handleExternalServiceError(error, 'DebuggAI', 'crawl execution');
     }
     finally {
-        process.stdin.removeListener('close', onStdinClose);
+        if (requestSignal)
+            requestSignal.removeEventListener('abort', onAbort);
         // Tunnel intentionally NOT torn down (reuse path per bead vwd).
         // If tunnel creation failed after key provision, revoke the orphaned key.
         if (!ctx.tunnelId && keyId) {

package/dist/services/workflows.js

@@ -13,81 +13,43 @@ const POLL_INTERVAL_MAX_MS = 5000;
 const POLL_BACKOFF_MULTIPLIER = 1.5;
 const EXECUTION_TIMEOUT_MS = 10 * 60 * 1000; // 10 min
 /**
- * Stable dispatch slug for the App Evaluation workflow (bug clka). Dispatch
- * pins to this slug so a backend display-name change never breaks
- * check_app_in_browser. Backend contract sentinal-k8x1f.8 exposes the slug on
- * template results; until that deploy lands the resolver falls back to a
- * name-substring search (see EVAL_TEMPLATE_NAME_FALLBACK).
+ * Stable dispatch slugs for the three MCP browser workflows (bug clka /
+ * bead 56kd.8). All three handlers pin to a STABLE slug so a backend
+ * display-name change (or template rework) never breaks dispatch — the
+ * fuzzy name-substring fallback is fully retired now that the backend does
+ * server-side `?slug=` exact matching (contract sentinal-k8x1f.11).
  *
- * Override with the DEBUGGAI_EVAL_TEMPLATE env var to pin a different slug.
+ * Each is env-overridable to pin a different slug without a code change.
  */
-export const EVAL_TEMPLATE_SLUG = 'flow/e2es/app-eval';
-/** Interim name keyword used ONLY when the backend hasn't exposed slugs yet. */
-export const EVAL_TEMPLATE_NAME_FALLBACK = 'app evaluation workflow';
+export const EVAL_TEMPLATE_SLUG = 'flow/e2es/app-eval'; // check_app_in_browser
+export const PAGE_PROBE_TEMPLATE_SLUG = 'flow/tools/probe'; // probe_page
+export const RAW_CRAWL_TEMPLATE_SLUG = 'crawl-execution-workflow-template'; // trigger_crawl
 /** The slug the eval-template dispatch pins to (env-overridable). */
 export function getEvalTemplateSlug() {
     return process.env.DEBUGGAI_EVAL_TEMPLATE || EVAL_TEMPLATE_SLUG;
 }
+/** The slug the page-probe dispatch pins to (env-overridable). */
+export function getPageProbeTemplateSlug() {
+    return process.env.DEBUGGAI_PROBE_TEMPLATE || PAGE_PROBE_TEMPLATE_SLUG;
+}
+/** The slug the raw-crawl dispatch pins to (env-overridable). */
+export function getCrawlTemplateSlug() {
+    return process.env.DEBUGGAI_CRAWL_TEMPLATE || RAW_CRAWL_TEMPLATE_SLUG;
+}
 export const createWorkflowsService = (tx) => {
     const service = {
-        async findTemplateByName(keyword) {
-            // Narrow server-side with `search` AND walk every page. The backend caps
-            // the page size (it ignores page_size), so reading only page 1 silently
-            // hides templates that sort later — that bug made check_app_in_browser
-            // fail in prod because "App Evaluation Workflow Template" sat on page 2.
-            // `search` collapses the candidate set to one page on backends that
-            // support it; `page` paging is the fallback for those that ignore it.
-            const needle = keyword.toLowerCase();
-            const seenNames = [];
-            const MAX_PAGES = 50; // safety valve against a backend that always returns `next`
-            for (let page = 1; page <= MAX_PAGES; page++) {
-                const response = await tx.get('api/v1/workflows/', { isTemplate: true, search: keyword, page });
-                const templates = response?.results ?? [];
-                for (const t of templates) {
-                    seenNames.push(t.name);
-                    if (t.name.toLowerCase().includes(needle))
-                        return t;
-                }
-                if (!response?.next)
-                    break;
-            }
-            if (seenNames.length === 0)
-                return null;
-            throw new Error(`No workflow template matching "${keyword}" found. ` +
-                `Available templates: ${seenNames.map(n => `"${n}"`).join(', ')}. ` +
-                `Ensure the backend has a template with "${keyword}" in its name.`);
-        },
         async findTemplateBySlug(slug) {
-            // Pin dispatch to the stable slug (bug clka). We pass `slug` as a query
-            // param so a slug-aware backend can filter server-side; on backends that
-            // ignore it we still walk the pages and match client-side on the `slug`
-            // field. Returns null if NO result carries a slug field (backend hasn't
-            // deployed the slug contract yet) — the caller then falls back to name
-            // search. `next`-paging mirrors findTemplateByName for the same reason
-            // (the backend caps page size).
-            const MAX_PAGES = 50;
-            for (let page = 1; page <= MAX_PAGES; page++) {
-                const response = await tx.get('api/v1/workflows/', { isTemplate: true, slug, page });
-                const templates = response?.results ?? [];
-                for (const t of templates) {
-                    if (t.slug === slug)
-                        return t;
-                }
-                if (!response?.next)
-                    break;
-            }
-            return null;
+            // Pure server-side slug resolve (bead 56kd.8). The backend does an EXACT
+            // `?slug=` match server-side (contract sentinal-k8x1f.11) and returns
+            // exactly that template, so this is a single GET — NO page-walk, NO
+            // client-side name/slug filtering, NO name-substring fallback. A slug is
+            // the stable template identity, so a backend rename can never break us.
+            const response = await tx.get('api/v1/workflows/', { isTemplate: true, slug });
+            return response?.results?.[0] ?? null;
         },
         async findEvaluationTemplate() {
-            // Primary: resolve by the stable slug so a backend rename can't break us.
-            const slug = getEvalTemplateSlug();
-            const bySlug = await service.findTemplateBySlug(slug);
-            if (bySlug)
-                return bySlug;
-            // Fallback (interim, until backend contract sentinal-k8x1f.8 lands): the
-            // name is specific enough to skip 'App Evaluation Brain' (subworkflow, no
-            // browser lifecycle) which also contains 'app evaluation'.
-            return service.findTemplateByName(EVAL_TEMPLATE_NAME_FALLBACK);
+            // Resolve the App Evaluation template purely by its stable slug.
+            return service.findTemplateBySlug(getEvalTemplateSlug());
         },
         async executeWorkflow(workflowUuid, contextData, env) {
             const body = { contextData };

package/dist/tools/testPageChanges.js

@@ -86,6 +86,30 @@ export function buildTestPageChangesTool(ctx) {
                     type: "string",
                     description: "GitHub repository name (e.g. 'my-org/my-repo'). Auto-detected from the current git repo — only provide this if you want to run against a different project than the one you're in."
                 },
+                auth: {
+                    type: "object",
+                    description: "Optional auth-precondition for a 'log in THEN deep-navigate' check. Set precondition:'login' to authenticate first (using the environment's credentials), then land on deepUrl. Use this instead of hoping the agent signs itself in at a login wall.",
+                    properties: {
+                        environmentId: {
+                            type: "string",
+                            description: "UUID of the environment whose credentials to log in with. See available environments in the tool description above."
+                        },
+                        precondition: {
+                            type: "string",
+                            enum: ["login", "none"],
+                            description: "'login' = authenticate before evaluating; 'none' (default) = no login precondition."
+                        },
+                        entryUrl: {
+                            type: "string",
+                            description: "Optional URL of the login page to authenticate on."
+                        },
+                        deepUrl: {
+                            type: "string",
+                            description: "Optional URL to navigate to and evaluate AFTER login (e.g. a deep settings page). Falls back to `url` if omitted."
+                        },
+                    },
+                    additionalProperties: false
+                },
             },
             required: ["description", "url"],
             additionalProperties: false

package/dist/types/index.js

@@ -3,6 +3,22 @@
  */
 import { z } from 'zod';
 import { normalizeUrl } from '../utils/urlParser.js';
+/**
+ * Auth-precondition deep-link block (bead debugg_ai_mcp-56kd.6).
+ *
+ * A first-class way to express "log in THEN deep-navigate to /settings/x" —
+ * forwarded verbatim into the dispatch contextData.auth per backend contract
+ * sentinal-k8x1f.8. The MCP is a THIN relay: it accepts the intent and forwards
+ * it; the backend authenticates (using the environment's credentials) and then
+ * navigates to deepUrl (falling back to the run's target_url). entryUrl/deepUrl
+ * are normalized the same way as the top-level url.
+ */
+export const AuthPreconditionSchema = z.object({
+    environmentId: z.string().uuid().optional(),
+    precondition: z.enum(['login', 'none']).optional(),
+    entryUrl: z.preprocess(normalizeUrl, z.string().url('entryUrl must be a valid URL (the login page to authenticate on).').optional()),
+    deepUrl: z.preprocess(normalizeUrl, z.string().url('deepUrl must be a valid URL (the page to evaluate AFTER login).').optional()),
+}).strict();
 /**
  * Tool input validation schemas
  */
@@ -16,6 +32,8 @@ export const TestPageChangesInputSchema = z.object({
     username: z.string().optional(),
     password: z.string().optional(),
     repoName: z.string().optional(),
+    // Auth-precondition deep-link intent (bead 56kd.6) — "log in THEN go to X".
+    auth: AuthPreconditionSchema.optional(),
 });
 export const TriggerCrawlInputSchema = 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.')),

package/package.json

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