@debugg-ai/debugg-ai-mcp 6.0.3 → 6.1.0

package/CHANGELOG.md

@@ -5,6 +5,44 @@ All notable changes to the DebuggAI MCP project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed — REST client now CONNECT-tunnels through HTTPS_PROXY / honors NO_PROXY (platform-y2ob.3)
+- The API client (axios) sent an absolute-URI request to the proxy, which CONNECT-only proxies reject with HTTP 405, so a proxied user failed before any tunnel was attempted. It now opens a CONNECT tunnel via the same proxy selection and NO_PROXY matching as the tunnel websocket. A 407 names the proxy host (never its credentials). No proxy, or a NO_PROXY match: unchanged.
+
+### Fixed — a failed project lookup no longer reads as "no project linked" (platform-y2ob.4)
+- check_app_in_browser and trigger_crawl swallowed any error from the repo-to-project lookup and then said no project is linked to the repo. A lookup error now returns `ProjectLookupFailed` with the HTTP status and the backend's message; only a successful lookup that finds nothing says `ProjectRequired`.
+
+### Fixed — probe_page no longer hides a failed run; check_app_in_browser ProjectRequired says what to pass (platform-y2ob.1, platform-y2ob.2)
+
+- `probe_page`: when the backend records the execution as failed/error, the response is `isError` and carries the recorded `status`, `errorMessage`, `agentError` and `errorInfo` verbatim, and each result's `error` is that message. A target that returns no page data now reports the execution status and that no page data came back instead of null fields with no reason.
+- `check_app_in_browser`: `ProjectRequired` now uses the same text as `trigger_crawl` (shared in `utils/projectRequired.ts`), naming `projectUuid` and `repoName`.
+
+### Fixed — tunnel provision reports its client version; no downgrade advice (platform-65o4)
+
+- `POST api/v1/tunnels/` now sends `client_version`, so the backend's `Tunnel.client_version` is no longer empty and failing client versions can be told apart.
+- The two error branches that said "Pin @debugg-ai/debugg-ai-mcp@4.4.1" now say to run `npx @debugg-ai/debugg-ai-mcp@latest` and restart the MCP client; a backend that still answers ngrok is reported as out of date.
+- The live tunnel test accepts a loopback `ws://` relay, so it runs against a local stack.
+
+### Fixed — foreign tunnel addresses no longer rewritten to localhost (platform-o7wv)
+- `replaceTunnelUrls` / `sanitizeResponseUrls` rewrote EVERY `*.tunnel.debugg.ai` host in a response to the caller's localhost origin, hiding real fixed addresses (e.g. a `pub-rt-...` tunnel). Now only the hostname(s) of the tunnel this session opened (`ctx.tunnelId` / session tunnel) are mapped back; all other tunnel-domain addresses are left as is. The session's own tunnel behaves as before.
+
+### Fixed — trigger_crawl fails before the tunnel when no project can be determined (platform-xmkv)
+
+- `trigger_crawl` never resolved a project (the `projectUuid` doc said "auto-detected" but only an explicit value was sent), so from a repo with no matching project the backend answered `Missing required field(s) in context_data: project_id`, which names no tool parameter and reads as a tunnel failure. It now resolves `projectUuid` > a named `environmentId` > `repoName` > the git checkout, sends the result as `projectId`, and returns `ProjectRequired` (input-validation text, tells you to pass `projectUuid` or `repoName`) BEFORE the port probe or any tunnel.
+- `check_app_in_browser` runs the same `ProjectRequired` check before provisioning a tunnel instead of after.
+- `probe_page` revokes a tunnel key whose `ensureTunnel` failed (bead xkoh.9). The old cleanup indexed a list that is empty exactly on that path, and was misaligned when a public target preceded a localhost one.
+
+### Added — the debugg tunnel honours HTTPS_PROXY (platform-neog)
+
+The tunnel's control websocket now goes through an HTTP CONNECT proxy when
+`HTTPS_PROXY` / `https_proxy` / `ALL_PROXY` / `all_proxy` is set, unless the relay
+host matches `NO_PROXY` / `no_proxy` (host, `.suffix`, `*.suffix`, `host:port`, `*`).
+`http://user:pass@host:port` proxy auth works. A proxy 407 or an unreachable proxy
+now says so, naming only the proxy host:port (never credentials). With no proxy
+variable set, behaviour is unchanged. Replaces the old "proxies are not supported"
+message. New dependency: `https-proxy-agent`.
+
 ## [6.0.0] — 2026-10-04 — BREAKING
 
 ### Changed — responses are the backend's data, not MCP-authored text

package/dist/handlers/probePageHandler.js

@@ -108,6 +108,9 @@ export async function probePageHandler(input, context, rawProgressCallback) {
     // bare key ids because revoking follows the transport the backend picked
     // (it routes to the tunnel's own revoke endpoint).
     const acquiredProvisions = [];
+    // Provisions whose ensureTunnel completed with a live tunnelId. Anything in
+    // acquiredProvisions but not here is an orphaned key (platform-xmkv).
+    const connectedProvisions = new Set();
     // Progress budget: 1 pre-flight + 1 template + 1 execute + N per-target captures + 1 done
     const TOTAL_STEPS = 3 + input.targets.length + 1;
     let progressStep = 0;
@@ -168,6 +171,8 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                             const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
                             throw new Error(`Tunnel creation failed for ${ctx.originalUrl}: ${msg}`);
                         }
+                        if (tunneled.tunnelId)
+                            connectedProvisions.add(tunnel);
                         // NOTE: the tunnel health probe used to run right here, immediately
                         // after ensureTunnel. Under the session-tunnel + Caddy model that is
                         // WRONG — ensureTunnel only confirms the tunnel reaches Caddy, not
@@ -217,6 +222,9 @@ export async function probePageHandler(input, context, rawProgressCallback) {
         const browserSessions = [];
         let lastExecutionDurationMs;
         let completedOffset = 0;
+        // Executions the backend recorded as failed/error (platform-y2ob.1) —
+        // surfaced verbatim at top level, never swallowed into empty results.
+        const failedExecutions = [];
         for (const group of groups) {
             // §2.4: acquire this session's shared Caddy route for the group's port
             // BEFORE dispatching — held for the group's whole execute+poll cycle,
@@ -327,6 +335,9 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                     }
                 }, abortController.signal);
                 lastExecutionDurationMs = finalExecution.durationMs ?? undefined;
+                const executionFailed = isFailedStatus(finalExecution.status);
+                if (executionFailed)
+                    failedExecutions.push(finalExecution);
                 if (finalExecution.browserSession)
                     browserSessions.push(finalExecution.browserSession);
                 // ── Format this group's results into the shared, ORIGINAL-order arrays ──
@@ -371,6 +382,13 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                     if (typeof data.surferPageUuid === 'string' && data.surferPageUuid) {
                         result.surferPageUuid = data.surferPageUuid;
                     }
+                    // platform-y2ob.1: a target with no page data must never read as a
+                    // clean success. Relay the backend's recorded failure verbatim; when
+                    // it recorded none, state what was observed.
+                    if (!result.error && !hasPageData(data)) {
+                        result.error = executionFailureText(finalExecution)
+                            ?? `Execution status: ${finalExecution.status ?? 'unknown'}; no page data was returned for this target.`;
+                    }
                     // Bead debugg_ai_mcp-6cfv.6 fix: sanitize each result against ITS
                     // OWN target's tunnel context, never the whole accumulated payload.
                     // Under the old per-port-tunnel model every target had a distinct
@@ -411,6 +429,18 @@ export async function probePageHandler(input, context, rawProgressCallback) {
         // (single-execution) response shape any existing caller already parses.
         if (executionIds.length > 1)
             responsePayload.executionIds = executionIds;
+        if (failedExecutions.length > 0) {
+            // Backend's recorded status + message, verbatim (same fields
+            // check_app_in_browser relays: errorMessage, agentError, errorInfo).
+            const f = failedExecutions[0];
+            responsePayload.status = f.status;
+            if (f.errorMessage)
+                responsePayload.errorMessage = f.errorMessage;
+            if (f.state?.error)
+                responsePayload.agentError = f.state.error;
+            if (f.errorInfo)
+                responsePayload.errorInfo = f.errorInfo;
+        }
         if (browserSessions.length === 1) {
             responsePayload.browserSession = browserSessions[0];
         }
@@ -447,7 +477,9 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                 }
             }
         }
-        return { content: responseContent };
+        return failedExecutions.length > 0
+            ? { content: responseContent, isError: true }
+            : { content: responseContent };
     }
     catch (error) {
         const duration = Date.now() - startTime;
@@ -463,16 +495,27 @@ export async function probePageHandler(input, context, rawProgressCallback) {
         // 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).
-        // NOTE (bead debugg_ai_mcp-xkoh.9): `tc` is undefined when ensureTunnel
-        // threw, so this condition does not fire on the very path it describes.
-        // That is a pre-existing defect with its own bead and is deliberately NOT
-        // fixed here; only the endpoint the revoke goes to changed.
-        for (let i = 0; i < acquiredProvisions.length; i++) {
-            const provision = acquiredProvisions[i];
-            const tc = targetContexts[i];
-            if (tc && !tc.tunnelId && provision) {
-                client.tunnels.revoke(provision).catch(err => logger.warn(`Failed to revoke unused tunnel ${provision.tunnelId}: ${err}`));
-            }
+        // Revoke only orphaned keys: provisioned, but ensureTunnel threw or
+        // returned no tunnelId. (The old check indexed targetContexts by provision
+        // position, which is undefined exactly when ensureTunnel threw, and
+        // misaligned whenever a public target preceded a localhost one.)
+        for (const provision of acquiredProvisions) {
+            if (connectedProvisions.has(provision))
+                continue;
+            client.tunnels.revoke(provision).catch(err => logger.warn(`Failed to revoke unused tunnel ${provision.tunnelId}: ${err}`));
         }
     }
 }
+function isFailedStatus(status) {
+    return typeof status === 'string' && ['failed', 'error'].includes(status.toLowerCase());
+}
+function hasPageData(data) {
+    return ['capturedUrl', 'finalUrl', 'url', 'title'].some(k => typeof data?.[k] === 'string' && data[k])
+        || typeof data?.statusCode === 'number';
+}
+/** The backend's own recorded failure text for an execution, verbatim. */
+function executionFailureText(exec) {
+    if (!isFailedStatus(exec?.status))
+        return null;
+    return exec.errorMessage || exec.state?.error || `Execution status: ${exec.status}`;
+}

package/dist/handlers/testPageChangesHandler.js

@@ -21,6 +21,7 @@ import { extractLocalhostPort, rewriteLocalhostInText } from '../utils/urlParser
 import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache, invalidateProjectCache, } from '../utils/handlerCaches.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+import { projectRequiredMessage, projectLookupFailedPayload } from '../utils/projectRequired.js';
 const logger = new Logger({ module: 'testPageChangesHandler' });
 // Bead kbxy: bounded retry on known transient backend signatures (Pydantic
 // JSON parse errors, 502s, ECONNRESETs). Default 1 retry; env-overridable
@@ -199,6 +200,43 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
     const MAX_EXEC_STEPS = 25;
     const TOTAL_STEPS = SETUP_STEPS + MAX_EXEC_STEPS;
     try {
+        // --- Project: resolve + validate BEFORE any tunnel ---
+        const repoName = input.repoName || detectRepoName();
+        // An environment belongs to one project, so naming one names the project:
+        // the backend files the run under it (platform-98fv.21). The working folder's
+        // repo name is only a guess, used when no environment is named.
+        const namedEnvironmentId = input.environmentId || input.auth?.environmentId;
+        let lookupError;
+        const projectUuid = !namedEnvironmentId && repoName
+            ? await getCachedProjectUuid(repoName, async (repo) => {
+                try {
+                    return await client.findProjectByRepoName(repo);
+                }
+                catch (err) {
+                    logger.warn(`Failed to look up project for repo "${repo}": ${err}`);
+                    lookupError = err;
+                    return null;
+                }
+            })
+            : undefined;
+        // Fail fast + actionable when project_id can't be resolved (pinned backend
+        // semantics: project_id is required). Checked BEFORE any tunnel is
+        // provisioned (platform-xmkv): a tunnel bought for a call that cannot run
+        // is a billed leak, and beats a backend node failing mid-run.
+        if (!projectUuid && !namedEnvironmentId && lookupError !== undefined && repoName) {
+            // The lookup FAILED — not "no project linked" (platform-y2ob.4).
+            const payload = projectLookupFailedPayload(repoName, lookupError);
+            logger.warn(`check_app_in_browser: ${payload.message}`);
+            return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+        }
+        if (!projectUuid && !namedEnvironmentId) {
+            const payload = {
+                error: 'ProjectRequired',
+                message: projectRequiredMessage(repoName),
+            };
+            logger.warn(`check_app_in_browser: ${payload.message}`);
+            return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+        }
         // --- Tunnel: reuse existing or provision a fresh one ---
         if (ctx.isLocalhost) {
             // Bead 1om: pre-flight local port probe BEFORE committing to backend
@@ -319,47 +357,16 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         if (progressCallback) {
             await progressCallback({ progress: 2, total: TOTAL_STEPS, message: 'Locating evaluation workflow template...' });
         }
-        const repoName = input.repoName || detectRepoName();
-        // An environment belongs to one project, so naming one names the project:
-        // the backend files the run under it (platform-98fv.21). The working folder's
-        // repo name is only a guess, used when no environment is named.
-        const namedEnvironmentId = input.environmentId || input.auth?.environmentId;
-        const [templateUuid, projectUuid] = await Promise.all([
-            // Cache key = the dispatch slug so the cache key and the lookup can never
-            // drift apart (bug clka: the key used to be a decoupled 'app evaluation'
-            // literal while the lookup searched a different string).
-            getCachedTemplateUuid(getEvalTemplateSlug(), async () => {
-                return client.workflows.findEvaluationTemplate();
-            }),
-            !namedEnvironmentId && repoName
-                ? getCachedProjectUuid(repoName, async (repo) => {
-                    try {
-                        return await client.findProjectByRepoName(repo);
-                    }
-                    catch (err) {
-                        logger.warn(`Failed to look up project for repo "${repo}": ${err}`);
-                        return null;
-                    }
-                })
-                : Promise.resolve(undefined),
-        ]);
+        // --- Resolve template (post-tunnel) ---
+        // Cache key = the dispatch slug so the cache key and the lookup can never
+        // drift apart (bug clka: the key used to be a decoupled 'app evaluation'
+        // literal while the lookup searched a different string).
+        const templateUuid = await getCachedTemplateUuid(getEvalTemplateSlug(), async () => {
+            return client.workflows.findEvaluationTemplate();
+        });
         if (!templateUuid) {
             throw new Error(`App Evaluation workflow template not found (slug "${getEvalTemplateSlug()}").`);
         }
-        // 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 && !namedEnvironmentId) {
-            const payload = {
-                error: 'ProjectRequired',
-                message: repoName
-                    ? `No DebuggAI project found for repo "${repoName}".`
-                    : 'No git repository detected and no repoName passed.',
-            };
-            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 = {
             targetUrl: ctx.targetUrl ?? originalUrl,

package/dist/handlers/triggerCrawlHandler.js

@@ -21,11 +21,12 @@ import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, acquirePortRoute, releasePortRoute, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { randomUUID } from 'node:crypto';
-import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
-import { detectLocalGitRef } from '../utils/gitContext.js';
+import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
+import { detectLocalGitRef, detectRepoName } from '../utils/gitContext.js';
 import { getCrawlTemplateSlug } from '../services/workflows.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
+import { projectRequiredMessage, projectLookupFailedPayload } from '../utils/projectRequired.js';
 const logger = new Logger({ module: 'triggerCrawlHandler' });
 // Bead kbo9: same env-driven retry budget as testPageChangesHandler (kbxy).
 function getMaxTransientRetries() {
@@ -84,6 +85,41 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
             requestSignal.addEventListener('abort', onAbort, { once: true });
     }
     try {
+        // --- Project: resolve BEFORE any tunnel (platform-xmkv) ---
+        // The backend requires a project; failing here costs nothing, failing after
+        // provisioning leaves a billed tunnel behind and surfaces as a raw backend
+        // "Missing required field(s) in context_data: project_id" that names no
+        // tool parameter. Precedence: projectUuid > a named environment (it belongs
+        // to one project, the backend resolves it) > repoName > the git checkout.
+        let projectUuid = input.projectUuid;
+        let lookupError;
+        const repoName = input.repoName || detectRepoName();
+        if (!projectUuid && !input.environmentId && repoName) {
+            projectUuid = await getCachedProjectUuid(repoName, async (repo) => {
+                try {
+                    return await client.findProjectByRepoName(repo);
+                }
+                catch (err) {
+                    logger.warn(`Failed to look up project for repo "${repo}": ${err}`);
+                    lookupError = err;
+                    return null;
+                }
+            });
+        }
+        if (!projectUuid && !input.environmentId && lookupError !== undefined && repoName) {
+            // The lookup FAILED — not "no project linked" (platform-y2ob.4).
+            const payload = projectLookupFailedPayload(repoName, lookupError);
+            logger.warn(`trigger_crawl: ${payload.message}`);
+            return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+        }
+        if (!projectUuid && !input.environmentId) {
+            const payload = {
+                error: 'ProjectRequired',
+                message: projectRequiredMessage(repoName),
+            };
+            logger.warn(`trigger_crawl: ${payload.message}`);
+            return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
+        }
         // --- Tunnel: reuse existing or provision a fresh one ---
         if (ctx.isLocalhost) {
             // Bead 1om: pre-flight local port probe BEFORE provision/tunnel/backend.
@@ -191,8 +227,8 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
         const contextData = {
             targetUrl: ctx.targetUrl ?? ctx.originalUrl,
         };
-        if (input.projectUuid)
-            contextData.projectId = input.projectUuid;
+        if (projectUuid)
+            contextData.projectId = projectUuid;
         contextData.headless = true; // D7: the MCP always runs headless — no opt-out.
         if (typeof input.timeoutSeconds === 'number')
             contextData.timeoutSeconds = input.timeoutSeconds;

package/dist/services/tunnel/debuggTransport.js

@@ -21,6 +21,7 @@ import * as tls from 'node:tls';
 import WebSocket from 'ws';
 import { Logger } from '../../utils/logger.js';
 import { buildHandshakeHeaders, interpretHandshakeResponse, webSocketTransport, CloseCode, ErrorCode, MAX_FRAME_SIZE, PROBE_TIMEOUT_MS, TunnelSession, } from './protocol/index.js';
+import { resolveTunnelProxy } from './proxy.js';
 import { registerControlProbe, unregisterControlProbe } from './probeRegistry.js';
 const logger = new Logger({ module: 'debuggTransport' });
 /** A DebuggSocketLike is always usable as the protocol module's WebSocketLike. */
@@ -29,6 +30,7 @@ void _socketIsWebSocketLike;
 const DEFAULT_RECONNECT_BACKOFF_MS = [250, 500, 1000, 2000, 5000, 10000];
 const defaultSocketFactory = (url, init) => new WebSocket(url, {
     headers: init.headers,
+    ...(init.agent ? { agent: init.agent } : {}),
     // Both ends disable it: dev-server payloads are already compressed and
     // deflate's per-connection buffers break the protocol's bounded-memory
     // property (bead debugg_ai_mcp-xkoh.1.2 §0).
@@ -100,7 +102,8 @@ class DebuggTransport {
         });
         // The token rides in a header and NEVER in the URL: the ALB and nginx log
         // URLs, not headers.
-        const socket = this.socketFactory(state.relayUrl, { headers });
+        const proxy = resolveTunnelProxy(state.relayUrl);
+        const socket = this.socketFactory(state.relayUrl, proxy ? { headers, agent: proxy.agent } : { headers });
         // ATTACH THE SESSION NOW, not on 'open', and not after connect() resolves.
         //
         // The server registers a tunnel the instant the handshake completes and may
@@ -145,7 +148,7 @@ class DebuggTransport {
                 }
             };
             const timer = setTimeout(() => {
-                fail(egressError(state, 'the connection timed out', 'ETIMEDOUT'));
+                fail(egressError(state, 'the connection timed out', 'ETIMEDOUT', proxy));
                 abandon();
             }, this.handshakeTimeoutMs);
             timer.unref?.();
@@ -187,14 +190,14 @@ class DebuggTransport {
                 const status = res?.statusCode ?? 0;
                 const result = interpretHandshakeResponse(status, res?.headers ?? {});
                 abandon();
-                fail(handshakeFailureError(state, status, result.ok ? undefined : result.supported, result.ok ? true : result.retryable));
+                fail(handshakeFailureError(state, status, result.ok ? undefined : result.supported, result.ok ? true : result.retryable, proxy));
             });
             socket.on('error', (err) => {
                 // Before the upgrade completes this is always a connection-level
                 // failure: DNS, TLS, refused, or blocked egress.
                 if (!settled)
                     abandon();
-                fail(egressError(state, err.message, err.code));
+                fail(egressError(state, err.message, err.code, proxy));
             });
         });
     }
@@ -356,7 +359,7 @@ function tunnelError(message, retryable) {
 function terminal(message) {
     return tunnelError(message, false);
 }
-function handshakeFailureError(state, status, supported, retryable) {
+function handshakeFailureError(state, status, supported, retryable, proxy) {
     switch (status) {
         case 401:
             // The word "authtoken" is load-bearing: TunnelManager's connect ladder
@@ -371,28 +374,32 @@ function handshakeFailureError(state, status, supported, retryable) {
                 `${supported ? `, server supports ${supported.join(', ')}` : ''}). ` +
                 'Update @debugg-ai/debugg-ai-mcp.');
         case 407:
-            return terminal(`an HTTP proxy at your network edge intercepted the tunnel connection to ${hostOf(state.relayUrl)} ` +
-                'and demanded authentication (HTTP 407). The tunnel needs a DIRECT outbound HTTPS (443) ' +
-                'connection; proxies are not supported.');
+            return terminal(proxy
+                ? `the HTTP proxy ${proxy.display} (from ${proxy.varName}) demanded authentication for the tunnel ` +
+                    `connection to ${hostOf(state.relayUrl)} (HTTP 407). Put valid credentials in the proxy URL ` +
+                    `(http://user:password@${proxy.display}) or ask your network admin to allow it.`
+                : `an HTTP proxy at your network edge intercepted the tunnel connection to ${hostOf(state.relayUrl)} ` +
+                    'and demanded authentication (HTTP 407). Set HTTPS_PROXY=http://user:password@host:port so the ' +
+                    'tunnel connects through it, or allow a direct outbound HTTPS (443) connection.');
         default:
             return tunnelError(`the debugg tunnel server refused the connection (HTTP ${status})`, retryable);
     }
 }
 /**
- * A connection-level failure reaching the relay. This client does NOT honour
- * HTTPS_PROXY (the retired ngrok agent did, which is the one capability lost
- * in the cutover — design §5 "open gap"), so the message says plainly what has
- * to be allowed instead of reading as a generic tunnel error.
+ * A connection-level failure reaching the relay (or, when HTTPS_PROXY is in
+ * use, the proxy in front of it). Says plainly what has to be allowed instead
+ * of reading as a generic tunnel error. Never includes proxy credentials.
  */
-function egressError(state, detail, code) {
+function egressError(state, detail, code, proxy) {
     const relayHost = hostOf(state.relayUrl);
-    const proxyVar = ['HTTPS_PROXY', 'https_proxy', 'ALL_PROXY', 'all_proxy'].find((name) => process.env[name]);
-    const proxyNote = proxyVar
-        ? ` This environment sets ${proxyVar}, which the tunnel connection does NOT use — HTTP(S) proxies are not supported for it.`
-        : ' HTTP(S) proxies are not supported for the tunnel connection.';
+    if (proxy) {
+        return tunnelError(`could not connect to the debugg tunnel server at ${relayHost} through the HTTP proxy ${proxy.display} ` +
+            `(from ${proxy.varName}) (${code ?? 'connection failed'}: ${detail}). Check that the proxy is reachable ` +
+            `and allows CONNECT to ${relayHost}, or set NO_PROXY=${relayHost} to connect directly.`, true);
+    }
     return tunnelError(`could not reach the debugg tunnel server at ${relayHost} (${code ?? 'connection failed'}: ${detail}). ` +
-        `Testing a local app needs a direct outbound HTTPS connection to ${relayHost} on port 443 — ` +
-        `allow it in your firewall, VPN or container network rules.${proxyNote}`, true);
+        `Testing a local app needs outbound HTTPS to ${relayHost} on port 443 — allow it in your firewall, ` +
+        'VPN or container network rules, or set HTTPS_PROXY=http://host:port if you reach the internet through an HTTP proxy.', true);
 }
 // ── Address handling ─────────────────────────────────────────────────────────
 /**

package/dist/services/tunnel/proxy.js

@@ -0,0 +1,65 @@
+import { HttpsProxyAgent } from 'https-proxy-agent';
+const PROXY_VARS = ['HTTPS_PROXY', 'https_proxy', 'ALL_PROXY', 'all_proxy'];
+function defaultPort(url) {
+    if (url.port)
+        return Number(url.port);
+    return url.protocol === 'wss:' || url.protocol === 'https:' ? 443 : 80;
+}
+/** curl-style NO_PROXY: comma/space list, `*`, `.suffix`, `*.suffix`, `host`, `host:port`. */
+export function noProxyMatches(target, noProxy) {
+    const host = target.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    const port = defaultPort(target);
+    for (const raw of noProxy.split(/[,\s]+/)) {
+        let entry = raw.trim().toLowerCase();
+        if (!entry)
+            continue;
+        if (entry === '*')
+            return true;
+        let entryPort;
+        const m = /^(.*):(\d+)$/.exec(entry);
+        if (m && !m[1].includes(':')) {
+            entry = m[1];
+            entryPort = Number(m[2]);
+        }
+        if (entryPort !== undefined && entryPort !== port)
+            continue;
+        entry = entry.replace(/^\*?\./, '');
+        if (!entry)
+            continue;
+        if (host === entry || host.endsWith(`.${entry}`))
+            return true;
+    }
+    return false;
+}
+export function resolveTunnelProxy(relayUrl, env = process.env) {
+    const varName = PROXY_VARS.find((name) => env[name]?.trim());
+    if (!varName)
+        return undefined;
+    let target;
+    try {
+        target = new URL(relayUrl);
+    }
+    catch {
+        return undefined;
+    }
+    const noProxy = env.NO_PROXY ?? env.no_proxy;
+    if (noProxy && noProxyMatches(target, noProxy))
+        return undefined;
+    const value = env[varName].trim();
+    let proxyUrl;
+    try {
+        proxyUrl = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `http://${value}`);
+    }
+    catch {
+        return undefined;
+    }
+    if (proxyUrl.protocol !== 'http:' && proxyUrl.protocol !== 'https:')
+        return undefined;
+    if (!proxyUrl.hostname)
+        return undefined;
+    return {
+        varName,
+        display: `${proxyUrl.hostname}${proxyUrl.port ? `:${proxyUrl.port}` : ''}`,
+        agent: new HttpsProxyAgent(proxyUrl.toString()),
+    };
+}

package/dist/services/tunnels.js

@@ -3,6 +3,7 @@
  * Provisions short-lived debugg tunnel tokens for MCP-managed tunnel setup.
  * Called before executeWorkflow so the tunnel URL is known before execution starts.
  */
+import { config } from '../config/index.js';
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
 import { isValidTunnelDomain, registerTunnelDomain, } from '../utils/tunnelDomains.js';
 /**
@@ -111,7 +112,11 @@ export const createTunnelsService = (tx) => {
     async function provision(purpose = 'workflow') {
         let response;
         try {
-            response = await tx.post('api/v1/tunnels/', { purpose, transports: [...SUPPORTED_TRANSPORTS] });
+            response = await tx.post('api/v1/tunnels/', {
+                purpose,
+                transports: [...SUPPORTED_TRANSPORTS],
+                client_version: config.server.version,
+            });
         }
         catch (err) {
             throw classifyProvisionError(err);
@@ -135,9 +140,9 @@ export const createTunnelsService = (tx) => {
             throw new TunnelProvisionError({
                 message: 'Tunnel provisioning selected the ngrok transport, which this version of ' +
                     '@debugg-ai/debugg-ai-mcp no longer implements (it offered: ' +
-                    `${SUPPORTED_TRANSPORTS.join(', ')}). Either the backend has not been moved off ngrok yet, ` +
-                    'or this account is still pinned to it. Pin @debugg-ai/debugg-ai-mcp@4.4.1 until the ' +
-                    'backend serves debugg tunnels.',
+                    `${SUPPORTED_TRANSPORTS.join(', ')}). Run ` +
+                    '`npx @debugg-ai/debugg-ai-mcp@latest` and restart your MCP client. If the backend still ' +
+                    'answers ngrok, the backend is out of date; please report it.',
                 retryable: false,
             });
         }
@@ -154,8 +159,8 @@ export const createTunnelsService = (tx) => {
         if (!response.relayUrl || !response.tunnelDomain) {
             throw new TunnelProvisionError({
                 message: 'Tunnel provisioning returned no relayUrl/tunnelDomain, so there is no debugg tunnel to ' +
-                    'connect to. This backend predates the debugg tunnel server; pin ' +
-                    '@debugg-ai/debugg-ai-mcp@4.4.1 until it is upgraded.',
+                    'connect to. Run `npx @debugg-ai/debugg-ai-mcp@latest` and restart your MCP client. If the ' +
+                    'backend still answers without a relayUrl, the backend is out of date; please report it.',
                 retryable: false,
             });
         }

package/dist/utils/axiosTransport.js

@@ -1,13 +1,22 @@
 // utils/axiosTransport.ts
 import axios from "axios";
 import { objToCamelCase, objToSnakeCase, } from "./objectNaming.js";
+import { resolveTunnelProxy } from "../services/tunnel/proxy.js";
 /**
  * A tiny wrapper around axios that keeps all your interceptors
  * but gives service factories a clean, typed surface.
  */
 export class AxiosTransport {
     axios;
-    constructor({ baseUrl, apiKey, tokenType = 'token', instance }) {
+    constructor({ baseUrl, apiKey, tokenType = 'token', instance, env = process.env }) {
+        // HTTPS_PROXY / NO_PROXY via the same selection the tunnel websocket uses
+        // (platform-y2ob.3). axios's built-in env proxy sends an absolute-URI
+        // request, which CONNECT-only proxies answer 405; use a CONNECT tunnel.
+        // No proxy applies => the config below is exactly what it always was.
+        const proxy = instance ? undefined : resolveTunnelProxy(baseUrl, env);
+        const proxyConfig = proxy
+            ? { proxy: false, httpAgent: proxy.agent, httpsAgent: proxy.agent }
+            : {};
         // Use an injected instance or create one that mimics `axiosServices`
         // Use provided apiKey as the Token. Must be requested on the app.
         this.axios =
@@ -15,6 +24,7 @@ export class AxiosTransport {
                 axios.create({
                     baseURL: baseUrl.replace(/\/+$/, "/"),
                     timeout: 30_000,
+                    ...proxyConfig,
                     headers: {
                         Accept: "application/json",
                         "Content-Type": "application/json",
@@ -27,6 +37,13 @@ export class AxiosTransport {
             res.data = objToCamelCase(res.data);
             return res;
         }, (err) => {
+            if (proxy && err.response?.status === 407) {
+                const e407 = new Error(`the HTTP proxy ${proxy.display} (from ${proxy.varName}) demanded authentication for the connection to ` +
+                    `${new URL(baseUrl).host} (HTTP 407). Put valid credentials in the proxy URL ` +
+                    `(http://user:password@${proxy.display}) or ask your network admin to allow it.`);
+                e407.statusCode = 407;
+                return Promise.reject(e407);
+            }
             const data = err.response?.data;
             if (data) {
                 const strField = (v) => typeof v === 'string' && v ? v : null;

package/dist/utils/projectRequired.js

@@ -0,0 +1,31 @@
+/**
+ * Shared ProjectRequired text (platform-y2ob.2): says what was observed and
+ * what to pass. Used by check_app_in_browser and trigger_crawl.
+ */
+export function projectRequiredMessage(repoName) {
+    const observed = repoName
+        ? `Could not determine the DebuggAI project: no project is linked to git repo "${repoName}".`
+        : 'Could not determine the DebuggAI project: this is not a git repo and no repoName was passed.';
+    return observed
+        + ' Pass `projectUuid` (list yours with the `project` tool, action "list") or `repoName` (the "org/repo" of a linked project).';
+}
+/**
+ * A repo->project lookup that FAILED (platform-y2ob.4), as opposed to one that
+ * succeeded and found nothing. Only the latter may say "not linked": a 405 or a
+ * network error says nothing about whether a project exists. Reports the HTTP
+ * status and the backend's message verbatim.
+ */
+export function projectLookupFailedPayload(repoName, err) {
+    const e = err;
+    const statusCode = typeof e?.statusCode === 'number' ? e.statusCode : undefined;
+    const reason = err instanceof Error ? err.message : String(err);
+    const how = statusCode !== undefined
+        ? `HTTP ${statusCode}: ${reason}`
+        : `${e?.networkCode ? `${e.networkCode}: ` : ''}${reason}`;
+    return {
+        error: 'ProjectLookupFailed',
+        message: `Could not look up the DebuggAI project for git repo "${repoName}" (${how}). `
+            + 'This is a lookup failure, not a missing link: pass `projectUuid` to skip the lookup, or fix the connection and retry.',
+        detail: { repoName, ...(statusCode !== undefined ? { statusCode } : {}), ...(e?.networkCode ? { networkCode: e.networkCode } : {}) },
+    };
+}

package/dist/utils/tunnelContext.js

@@ -179,5 +179,14 @@ export function sanitizeResponseUrls(value, ctx) {
     if (!ctx.isLocalhost)
         return value;
     const origin = new URL(ctx.originalUrl).origin;
-    return replaceTunnelUrls(value, origin);
+    const ids = [];
+    if (ctx.tunnelId)
+        ids.push(ctx.tunnelId);
+    try {
+        const sessionTunnel = tunnelManager.getSessionTunnelInfo(getSessionKey());
+        if (sessionTunnel?.tunnelId)
+            ids.push(sessionTunnel.tunnelId);
+    }
+    catch { /* no session tunnel: ctx.tunnelId alone decides */ }
+    return replaceTunnelUrls(value, origin, ids);
 }

package/dist/utils/urlParser.js

@@ -2,7 +2,7 @@
  * URL Parser Utilities
  * Helper functions for parsing and validating URLs, specifically for detecting localhost URLs
  */
-import { tunnelUrlPattern } from './tunnelDomains.js';
+import { tunnelUrlPattern, extractTunnelIdFromHost } from './tunnelDomains.js';
 /**
  * Normalize a user-supplied URL string before validation.
  * Handles bare hostnames without a scheme (e.g. "localhost:3000" → "http://localhost:3000").
@@ -95,18 +95,32 @@ export function isLocalhostUrl(urlString) {
  * Covers EVERY known tunnel domain (utils/tunnelDomains.ts), including the
  * retired `ngrok.debugg.ai` one a historical run's stored URLs still carry: a
  * domain this does not know is a hostname that leaks to the caller.
+ *
+ * When `ownTunnelIds` is given, ONLY hosts whose tunnel id (leftmost label) is
+ * listed are rewritten; foreign tunnel-domain addresses are left untouched.
+ * Omitted = legacy rewrite-everything behavior.
  */
-export function replaceTunnelUrls(value, localhostOrigin) {
+export function replaceTunnelUrls(value, localhostOrigin, ownTunnelIds) {
     if (typeof value === 'string') {
-        return value.replace(tunnelUrlPattern(), localhostOrigin.replace(/\/$/, ''));
+        const target = localhostOrigin.replace(/\/$/, '');
+        if (ownTunnelIds === undefined)
+            return value.replace(tunnelUrlPattern(), target);
+        const own = new Set(ownTunnelIds.filter((id) => !!id).map(id => id.toLowerCase()));
+        // Only hosts of tunnels THIS session opened are mapped back; any other
+        // tunnel-domain address (a fixed runner/pub- tunnel, another user's) is
+        // a real public address and stays exactly as is.
+        return value.replace(tunnelUrlPattern(), (match) => {
+            const id = extractTunnelIdFromHost(match);
+            return id !== null && own.has(id.toLowerCase()) ? target : match;
+        });
     }
     if (Array.isArray(value)) {
-        return value.map(item => replaceTunnelUrls(item, localhostOrigin));
+        return value.map(item => replaceTunnelUrls(item, localhostOrigin, ownTunnelIds));
     }
     if (value !== null && typeof value === 'object') {
         const result = {};
         for (const [k, v] of Object.entries(value)) {
-            result[k] = replaceTunnelUrls(v, localhostOrigin);
+            result[k] = replaceTunnelUrls(v, localhostOrigin, ownTunnelIds);
         }
         return result;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@debugg-ai/debugg-ai-mcp",
-  "version": "6.0.3",
+  "version": "6.1.0",
   "description": "Zero-Config, Fully AI-Managed End-to-End Testing for all code gen platforms.",
   "type": "module",
   "caddy": "2.11.3",
@@ -60,6 +60,7 @@
     "@modelcontextprotocol/sdk": "^1.27.0",
     "@radically-straightforward/caddy": "^2.0.12",
     "axios": "^1.9.0",
+    "https-proxy-agent": "^7.0.6",
     "mkdirp": "^3.0.1",
     "posthog-node": "^5.26.0",
     "uuid": "^11.1.0",