@debugg-ai/debugg-ai-mcp 3.5.3 → 3.7.0

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

@@ -91,12 +91,26 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
     const originalUrl = resolveTargetUrl(input);
     let ctx = buildContext(originalUrl);
     let keyId;
+    // Cancellation is driven by the MCP request/transport lifecycle, 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, holding one of just
+    // MAX_CONCURRENT=2 slots. Wiring to context.signal cancels the poll and frees
+    // the slot immediately.
     const abortController = new AbortController();
-    const onStdinClose = () => {
+    const onAbort = () => {
         abortController.abort();
         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 });
+    }
     // Progress budget: 3 setup steps + 25 execution steps = 28 total
     const SETUP_STEPS = 3;
     const MAX_EXEC_STEPS = 25;
@@ -226,8 +240,22 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             throw new Error('App Evaluation Workflow Template not found. ' +
                 'Ensure the template is seeded in the backend (GET /api/v1/workflows/?is_template=true).');
         }
-        if (repoName && !projectUuid) {
-            logger.info(`No project found for repo "${repoName}" — proceeding without project_id`);
+        // Fail fast + actionable when project_id can't be resolved (pinned backend
+        // semantics: project_id is required). Surfacing "link this repo to a
+        // project" now — before executeWorkflow — beats letting a backend workflow
+        // node fail mid-run several minutes into the evaluation.
+        if (!projectUuid) {
+            const detail = repoName
+                ? `Repo "${repoName}" isn't linked to a DebuggAI project.`
+                : 'No git repository was detected to resolve a project from.';
+            const payload = {
+                error: 'ProjectRequired',
+                message: `project_id is required but could not be resolved. ${detail} ` +
+                    'Link this repo to a project at https://debugg.ai (Projects → connect your repository), then retry. ' +
+                    'To evaluate a different repo than the current one, pass repoName.',
+            };
+            logger.warn(`check_app_in_browser: ${payload.message}`);
+            return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
         }
         // --- Build context data (camelCase here — axiosTransport auto-converts to snake_case) ---
         const contextData = {
@@ -238,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)
@@ -593,7 +638,8 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         throw handleExternalServiceError(error, 'DebuggAI', 'test execution');
     }
     finally {
-        process.stdin.removeListener('close', onStdinClose);
+        if (requestSignal)
+            requestSignal.removeEventListener('abort', onAbort);
         // Tunnel is intentionally NOT torn down here — tunnelManager reuses it on
         // subsequent calls to the same port and auto-shutoffs after 55 min idle.
         // Process-exit cleanup happens via stopAllTunnels() in the SIGINT/SIGTERM

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/index.js

@@ -90,7 +90,7 @@ export function buildConfiguredServer() {
  * singleton in main(), and once per request by the HTTP transport (stateless).
  */
 function registerHandlers(srv) {
-    srv.setRequestHandler(CallToolRequestSchema, async (req) => {
+    srv.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
         const typedReq = req;
         const requestId = `req_${Date.now()}`;
         const requestLogger = logger.child({ requestId });
@@ -123,6 +123,9 @@ function registerHandlers(srv) {
                 progressToken: typeof progressToken === 'string' ? progressToken : undefined,
                 requestId,
                 timestamp: new Date(),
+                // Cancellation source for long-running handlers: the SDK aborts this
+                // signal when the client cancels the call or the transport closes.
+                signal: extra?.signal,
             };
             const progressCallback = createProgressCallback(srv, typeof progressToken === 'string' || typeof progressToken === 'number' ? String(progressToken) : undefined);
             requestLogger.info(`Executing tool: ${name}`);

package/dist/services/projectContext.js

@@ -1,7 +1,12 @@
 /**
  * Project Context Service
- * At startup: detect repo → resolve project → fetch environments + credentials.
- * Exposes the result so tool descriptions can be enriched dynamically.
+ * At startup (lazily, on first tool call): detect repo → resolve project →
+ * fetch environments + credential LABELS. Exposes the result so tool
+ * descriptions can be enriched dynamically (see tools/index.ts).
+ *
+ * Thin relay: we consume the backend's environment/credential contract and
+ * surface LABELS ONLY — never a password or any other secret. The
+ * backend→internal field mapping lives in ONE place: mapEnvironments().
  */
 import { config } from '../config/index.js';
 import { DebuggAIServerClient } from './index.js';
@@ -10,14 +15,54 @@ import { Logger } from '../utils/logger.js';
 const logger = new Logger({ module: 'projectContext' });
 let cached = null;
 let inFlight = null;
+const STARTUP_TIMEOUT_MS = 10_000;
 /**
- * Resolve the current project context: repo → project → environments → credentials.
+ * The ONE place the backend environment/credential contract is mapped to our
+ * internal shape. Pinned contract (backend epic sentinal-k8x1f.8):
+ *
+ *   GET /api/v1/environments/?project=<uuid>
+ *     → [{ uuid, name, url, is_default, is_active, endpoint_type,
+ *          credentials: [{ label, username }] }]
+ *
+ * (The axios transport auto-converts snake_case → camelCase, so we read
+ * `isDefault`/`isActive`/`endpointType` here.) Password is write-only and
+ * NEVER returned; we defensively copy only label/username (+ uuid/role if the
+ * backend ever includes them) — we never spread a raw credential object, so a
+ * secret can't leak into a tool description even if the contract regresses.
+ */
+export function mapEnvironments(rawEnvs) {
+    return (rawEnvs ?? [])
+        // Surface only active environments (is_active !== false).
+        .filter((e) => e?.isActive !== false)
+        .map((env) => ({
+        uuid: env.uuid,
+        name: env.name,
+        url: env.url || env.activeUrl || '',
+        isDefault: env.isDefault ?? false,
+        isActive: env.isActive ?? true,
+        endpointType: env.endpointType ?? null,
+        credentials: (env.credentials ?? [])
+            .filter((c) => c && c.isActive !== false)
+            .map((c) => ({
+            label: c.label || c.username,
+            username: c.username,
+            ...(c.uuid ? { uuid: c.uuid } : {}),
+            ...(c.role !== undefined ? { role: c.role } : {}),
+            environmentName: env.name,
+            environmentUuid: env.uuid,
+        })),
+    }));
+}
+/**
+ * Resolve the current project context: repo → project → environments →
+ * credential labels.
  *
  * Caches the first successful result. Concurrent calls share a single in-flight
- * promise. Failures are NOT cached — the next call will retry — so a transient
- * network error on the first tool call doesn't permanently disable the service.
+ * promise. Failures are NOT cached — the next call retries — so a transient
+ * network error on the first tool call doesn't permanently disable enrichment.
+ * The whole resolution is bounded by STARTUP_TIMEOUT_MS so a slow/hung backend
+ * can never block boot or a tool call.
  */
-const STARTUP_TIMEOUT_MS = 10_000;
 export async function resolveProjectContext() {
     if (cached)
         return cached;
@@ -67,40 +112,15 @@ async function resolveProjectContextInner(repoName) {
             return null;
         }
         logger.info(`Resolved project: ${project.name} (${project.uuid})`);
-        // Fetch environments for this project
-        const envResponse = await client.tx.get(`api/v1/projects/${project.uuid}/environments/`);
-        const rawEnvs = envResponse?.results ?? [];
-        // Fetch credentials for each environment in parallel
-        const environments = await Promise.all(rawEnvs
-            .filter((e) => e.isActive)
-            .map(async (env) => {
-            let credentials = [];
-            try {
-                const credResponse = await client.tx.get(`api/v1/projects/${project.uuid}/environments/${env.uuid}/credentials/`);
-                credentials = (credResponse?.results ?? [])
-                    .filter((c) => c.isActive)
-                    .map((c) => ({
-                    uuid: c.uuid,
-                    label: c.label || c.username,
-                    username: c.username,
-                    role: c.role,
-                    environmentName: env.name,
-                    environmentUuid: env.uuid,
-                }));
-            }
-            catch {
-                // Some environments may not support credentials
-            }
-            return {
-                uuid: env.uuid,
-                name: env.name,
-                url: env.url || env.activeUrl || '',
-                credentials,
-            };
-        }));
+        // Pinned contract: environments (with credentials inlined) for the project.
+        const envResponse = await client.tx.get('api/v1/environments/', {
+            project: project.uuid,
+        });
+        const rawEnvs = Array.isArray(envResponse) ? envResponse : (envResponse?.results ?? []);
+        const environments = mapEnvironments(rawEnvs);
         cached = { repoName, project, environments };
         const totalCreds = environments.reduce((n, e) => n + e.credentials.length, 0);
-        logger.info(`Project context ready: ${environments.length} environments, ${totalCreds} credentials`);
+        logger.info(`Project context ready: ${environments.length} environments, ${totalCreds} credential labels`);
         return cached;
     }
     catch (err) {
@@ -111,3 +131,8 @@ async function resolveProjectContextInner(repoName) {
 export function getProjectContext() {
     return cached;
 }
+/** Test-only: reset the module cache so each test starts clean. */
+export function __resetProjectContextForTests() {
+    cached = null;
+    inFlight = null;
+}

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/index.js

@@ -6,9 +6,36 @@ import { buildEnvironmentTool, buildValidatedEnvironmentTool } from './environme
 import { buildExecutionsTool, buildValidatedExecutionsTool } from './executions.js';
 import { buildTestSuiteTool, buildValidatedTestSuiteTool } from './testSuite.js';
 import { buildTestCaseTool, buildValidatedTestCaseTool } from './testCase.js';
+import { resolveProjectContext } from '../services/projectContext.js';
 let _tools = null;
 let _validatedTools = null;
 const toolRegistry = new Map();
+let enrichmentTriggered = false;
+/**
+ * Lazily resolve project → environments → credential labels ON FIRST USE and
+ * rebuild the tool definitions so the enriched description (available
+ * environments + credential labels) is served on the next tools/list.
+ *
+ * Fire-and-forget: this never blocks the triggering call. resolveProjectContext
+ * has its own 10s timeout, so boot and the first tool call are never gated on a
+ * slow backend. Idempotent — the first invocation wins; the cached context
+ * makes subsequent resolves free.
+ */
+function triggerEnrichmentOnce() {
+    if (enrichmentTriggered)
+        return;
+    enrichmentTriggered = true;
+    resolveProjectContext()
+        .then((ctx) => {
+        // Only rebuild when we actually resolved a linked project; otherwise the
+        // base description stays (no project detected / not linked).
+        if (ctx)
+            initTools(ctx);
+    })
+        .catch(() => {
+        // Best-effort enrichment — a failure leaves the base description in place.
+    });
+}
 /**
  * Initialize tools with project context (call once after resolveProjectContext).
  *
@@ -46,10 +73,12 @@ export function initTools(ctx) {
 export function getTools() {
     if (!_tools)
         initTools(null);
+    triggerEnrichmentOnce();
     return _tools;
 }
 export function getTool(name) {
     if (!_validatedTools)
         initTools(null);
+    triggerEnrichmentOnce();
     return toolRegistry.get(name);
 }

package/dist/tools/testPageChanges.js

@@ -26,12 +26,16 @@ export function buildToolDescription(ctx) {
         `\nAVAILABLE ENVIRONMENTS & CREDENTIALS (pass environmentId + credentialId for authenticated testing):`,
     ];
     for (const env of envsWithCreds) {
-        lines.push(`\n  Environment: "${env.name}" (${env.uuid})${env.url ? ` — ${env.url}` : ''}`);
+        const defaultTag = env.isDefault ? ' [default]' : '';
+        lines.push(`\n  Environment: "${env.name}" (${env.uuid})${defaultTag}${env.url ? ` — ${env.url}` : ''}`);
         for (const cred of env.credentials) {
-            const parts = [`    - "${cred.label}" (${cred.uuid}) — user: ${cred.username}`];
+            // The backend contract surfaces credential LABELS (never passwords). The
+            // uuid/role are optional — shown only when the backend includes them.
+            const idPart = cred.uuid ? ` (${cred.uuid})` : '';
+            let line = `    - "${cred.label}"${idPart} — user: ${cred.username}`;
             if (cred.role)
-                parts[0] += `, role: ${cred.role}`;
-            lines.push(parts[0]);
+                line += `, role: ${cred.role}`;
+            lines.push(line);
         }
     }
     lines.push(`\nTo use: pass environmentId and credentialId from above. Or provide username/password directly.`);
@@ -82,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.5.3",
+  "version": "3.7.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "bin": {