@debugg-ai/debugg-ai-mcp 4.4.0 → 5.0.0

package/README.md

@@ -13,9 +13,10 @@ AI-powered browser testing via the [Model Context Protocol](https://modelcontext
 **Testing `http://localhost:...` URLs requires the `caddy` binary** — `check_app_in_browser`,
 `probe_page`, and `trigger_crawl` tunnel localhost targets through a local Caddy reverse proxy.
 This installs automatically: the `@radically-straightforward/caddy` npm dependency downloads a
-pinned Caddy release for your platform during `npm install`/`npx`, same as this project already
-does for the `ngrok` binary — nothing to install yourself in the normal case. If that download
-never ran (`npm install --ignore-scripts`, an offline/air-gapped install), point `CADDY_BIN` at
+pinned Caddy release for your platform during `npm install`/`npx` — nothing to install yourself in
+the normal case. It is now the **only** binary this package downloads; the tunnel client itself is
+pure TypeScript — it replaced the `ngrok` package, which fetched the ngrok agent.
+If that download never ran (`npm install --ignore-scripts`, an offline/air-gapped install), point `CADDY_BIN` at
 your own install (`brew install caddy` / `apt install caddy` / see
 [caddyserver.com/docs/install](https://caddyserver.com/docs/install)) — missing it surfaces as a
 clear error on the first localhost-URL call, not a silent hang. Public-URL calls, every
@@ -63,7 +64,7 @@ The server exposes **8** tools: three **Browser** tools plus one **action-based*
 
 #### `check_app_in_browser`
 
-Runs an AI browser agent against your app. The agent navigates, interacts, and reports back with screenshots. Localhost URLs are auto-tunneled via ngrok.
+Runs an AI browser agent against your app. The agent navigates, interacts, and reports back with screenshots. Localhost URLs are auto-tunneled through the debugg tunnel server.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -254,7 +255,8 @@ clients without resource support keep using the tools.
 ### Security invariants
 
 - Passwords are write-only. They never appear in any response body from any tool.
-- Tunnel URLs (`*.ngrok.debugg.ai`) are stripped from all browser-agent responses, including agent-authored text.
+- Tunnel URLs (`*.tunnel.debugg.ai`, and the retired `*.ngrok.debugg.ai` that historical runs still
+  reference) are stripped from all browser-agent responses, including agent-authored text.
 - 404s from the backend surface as `isError: true` with `{error: 'NotFound', ...}`, never as thrown exceptions.
 - Missing `DEBUGGAI_API_KEY` surfaces as a structured tool error on first invocation — the server still registers and lists tools normally.
 
@@ -341,11 +343,11 @@ flow against the advertised authorization server. The bearer is request-scoped
 
 stdio installs need none of these.
 
-**Multi-replica deployments (go/no-go before rollout):** tunnel state (the ngrok session tunnel,
+**Multi-replica deployments (go/no-go before rollout):** tunnel state (the session tunnel,
 its Caddy instance, and its port-route lock) is in-process, keyed per caller by a hash of the
 bearer token — there is no cross-process coordination. Running several replicas behind a plain
 round-robin load balancer means one caller's calls can land on different replicas and mint one
-tunnel **per replica they hit** instead of one for the whole session (extra ngrok cost, bounded by
+tunnel **per replica they hit** instead of one for the whole session (bounded by
 replica count, self-healing via the existing 55-minute idle auto-shutoff — never a cross-session
 correctness bug, since any single tool call stays on one replica for its whole duration). To get
 the intended "one tunnel per session" behavior on a multi-replica HTTP deployment, configure

package/dist/handlers/probePageHandler.js

@@ -106,7 +106,7 @@ export async function probePageHandler(input, context, rawProgressCallback) {
     // Tunnel keys we provisioned this call (for cleanup if creation fails after key acquired).
     // The provisions this call acquired, in target order. Provisions rather than
     // bare key ids because revoking follows the transport the backend picked
-    // (ngrok keys and debugg tunnels have different endpoints).
+    // (it routes to the tunnel's own revoke endpoint).
     const acquiredProvisions = [];
     // Progress budget: 1 pre-flight + 1 template + 1 execute + N per-target captures + 1 done
     const TOTAL_STEPS = 3 + input.targets.length + 1;
@@ -257,7 +257,7 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                             detail: {
                                 code: health.code,
                                 status: health.status,
-                                ngrokErrorCode: health.ngrokErrorCode,
+                                tunnelErrorCode: health.tunnelErrorCode,
                                 elapsedMs: health.elapsedMs,
                             },
                         };

package/dist/handlers/runTestSuiteHandler.js

@@ -6,7 +6,7 @@ import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
 import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { buildContext, sanitizeResponseUrls } from '../utils/tunnelContext.js';
-import { tunnelManager } from '../services/ngrok/tunnelManager.js';
+import { tunnelManager } from '../services/tunnel/tunnelManager.js';
 import { config } from '../config/index.js';
 import { resolveProject, resolveTestSuite } from '../utils/resolveProject.js';
 const logger = new Logger({ module: 'runTestSuiteHandler' });
@@ -68,7 +68,7 @@ export async function runTestSuiteHandler(input, _context) {
                     // and its PortLock would give this handler no real protection —
                     // the lock would release back to contention seconds after
                     // triggering a suite that goes on to use the port for much longer.
-                    // So it gets its OWN tunnel, dialing ngrok directly, bypassing
+                    // So it gets its OWN tunnel, dialing the app directly, bypassing
                     // Caddy/PortLock entirely (never deduped/reused — always fresh).
                     let tunnel;
                     try {
@@ -88,7 +88,7 @@ export async function runTestSuiteHandler(input, _context) {
                         const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
                         return errorResp('TunnelCreationFailed', `Tunnel creation failed for ${input.targetUrl}. (Detail: ${msg})`);
                     }
-                    // Health probe — catches ERR_NGROK_8012 and bind mismatches before
+                    // Health probe — catches an upstream-refused tunnel and bind mismatches before
                     // the remote agent wastes steps trying to reach the server.
                     if (dedicated.url) {
                         const health = await probeTunnelHealth(dedicated.url);
@@ -104,7 +104,7 @@ export async function runTestSuiteHandler(input, _context) {
                             // revoking a live tunnel's credential would kill what we preserved.
                             // (On the eviction branch markTunnelDead already revokes it.)
                             tunnelId = dedicated.tunnelId;
-                            return errorResp('TunnelTrafficBlocked', `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`, { code: health.code, ngrokErrorCode: health.ngrokErrorCode, elapsedMs: health.elapsedMs });
+                            return errorResp('TunnelTrafficBlocked', `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`, { code: health.code, tunnelErrorCode: health.tunnelErrorCode, elapsedMs: health.elapsedMs });
                         }
                     }
                     effectiveTargetUrl = dedicated.url;
@@ -125,7 +125,7 @@ export async function runTestSuiteHandler(input, _context) {
         // at all — safe only by accident of `result`'s narrow return type never
         // having carried a tunnel hostname in practice. Add the same defensive
         // pass every other handler already runs, so a future backend field that
-        // echoes back the (dedicated, ngrok-direct) tunnel URL can never leak it
+        // echoes back the (dedicated, app-direct) tunnel URL can never leak it
         // to a caller who only knows their own localhost address.
         const sanitizedPayload = sanitizeCtx ? sanitizeResponseUrls(responsePayload, sanitizeCtx) : responsePayload;
         return {

package/dist/handlers/testPageChangesHandler.js

@@ -16,7 +16,7 @@ import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, acqui
 import { randomUUID } from 'node:crypto';
 import { detectRepoName } from '../utils/gitContext.js';
 import { disposeUnhealthyTunnel } from '../utils/tunnelDisposition.js';
-import { probeLocalPort, probeTunnelHealth, extractNgrokErrorCode } from '../utils/localReachability.js';
+import { probeLocalPort, probeTunnelHealth, extractTunnelErrorCode } from '../utils/localReachability.js';
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { getCachedTemplateUuid, getCachedProjectUuid, invalidateTemplateCache, invalidateProjectCache, } from '../utils/handlerCaches.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
@@ -35,12 +35,12 @@ function getMaxTransientRetries() {
         return 1;
     return Math.min(n, 3);
 }
-// Bug z15n: scan run evidence for ngrok's interstitial marker. The marker is a
+// Bug z15n: scan run evidence for the tunnel server's interstitial marker. It is a
 // stable, recognizable string the REMOTE BROWSER saw — positive evidence that it
 // hit our tunnel's error page rather than the user's app. Non-string parts are
 // serialized (the action trace is the usual carrier); a part we can't serialize
 // is simply skipped — it is not evidence either way.
-function findNgrokErrorMarker(parts) {
+function findTunnelErrorMarker(parts) {
     for (const part of parts) {
         if (part === undefined || part === null || part === '')
             continue;
@@ -51,7 +51,7 @@ function findNgrokErrorMarker(parts) {
         catch {
             continue;
         }
-        const code = extractNgrokErrorCode(text);
+        const code = extractTunnelErrorCode(text);
         if (code)
             return code;
     }
@@ -202,7 +202,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // --- Tunnel: reuse existing or provision a fresh one ---
         if (ctx.isLocalhost) {
             // Bead 1om: pre-flight local port probe BEFORE committing to backend
-            // provision + ngrok session. If the user's dev server isn't listening,
+            // provision + tunnel session. If the user's dev server isn't listening,
             // fail in ~1.5s with a structured error instead of burning 5 minutes
             // on a browser agent trying to reach a dead tunnel.
             const localPort = extractLocalhostPort(ctx.originalUrl);
@@ -251,7 +251,13 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                     }
                     provision = tunnel;
                     try {
-                        ctx = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.revokeNgrokKey(tunnel.keyId));
+                        ctx = await ensureTunnel(ctx, tunnel.tunnelKey, tunnel.tunnelId, tunnel.keyId, () => client.tunnels.revoke(tunnel), 
+                        // The provision IS the transport selection. Omitting it here is
+                        // not a no-op: without it ensureTunnel gets no relayUrl or
+                        // tunnelDomain at all, so the flagship tool cannot connect a
+                        // tunnel the backend just issued. The other three
+                        // handlers pass it; this one was missed.
+                        tunnel);
                     }
                     catch (tunnelError) {
                         const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
@@ -281,7 +287,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                         : undefined,
                 });
                 // Bead 1om: verify traffic actually flows through the tunnel. The
-                // tunnel can be established (ngrok.connect returns OK) yet refuse
+                // tunnel can be established (connect returns OK) yet refuse
                 // to forward traffic — e.g., IPv4/IPv6 bind mismatch, or the dev
                 // server died between the pre-flight probe and here. Catch it now,
                 // in ~1s, not via a 5-minute browser-agent false-pass.
@@ -294,11 +300,11 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                             detail: {
                                 code: health.code,
                                 status: health.status,
-                                ngrokErrorCode: health.ngrokErrorCode,
+                                tunnelErrorCode: health.tunnelErrorCode,
                                 elapsedMs: health.elapsedMs,
                             },
                         };
-                        logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.ngrokErrorCode ?? ''} in ${health.elapsedMs}ms`);
+                        logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.tunnelErrorCode ?? ''} in ${health.elapsedMs}ms`);
                         // Evict ONLY on a code proving the endpoint is gone; every other
                         // failure keeps the tunnel we are already paying for, because a
                         // teardown+re-provision costs two billed hours and this probe cannot
@@ -702,7 +708,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // --- Post-hoc tunnel reclassification (bugs z15n, 4bui) ---
         // The pre-flight probe above proves the tunnel was alive when we handed it to
         // the remote browser — it can still die mid-run. When it does, the browser
-        // lands on ngrok's ERR_NGROK_* interstitial and the backend, which only sees
+        // lands on the tunnel server's DEBUGG_TUNNEL_* interstitial and the backend, which only sees
         // "the page didn't contain what I was asked about", returns a normal 'fail'
         // whose reason blames the USER'S page for OUR dead tunnel (execution
         // a8f07747: 217s, 7 steps, failureCategory 'fail').
@@ -710,7 +716,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // THE MARKER IS REQUIRED (bug 4bui). Reclassifying overrides the backend's
         // verdict, so it demands positive evidence of the claim we are actually
         // making: that the remote browser hit OUR error page DURING THE RUN. Only
-        // the ERR_NGROK_* marker recorded BY the run is evidence of that.
+        // the DEBUGG_TUNNEL_* marker recorded BY the run is evidence of that.
         //
         // The re-probe is NOT such evidence and can no longer trigger this on its
         // own. It answers a different question — "is the tunnel healthy NOW?" —
@@ -722,12 +728,12 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // independently returned a FALSE NETWORK_ERROR on healthy servers ~1 in 5
         // runs (bug k6yq), so the false positive was reachable with nothing
         // whatsoever wrong. (k6yq is now fixed: the cause was not the suspected DNS
-        // race but an HTTP/2 GOAWAY from the ngrok edge on a freshly created
+        // race but a connection-level flake against a freshly created
         // tunnel, which probeTunnelHealth now retries. The marker requirement
         // stands on its own regardless — the probe never decides this.)
         //
         // Requiring the marker loses no coverage: a real mid-run death fires BOTH
-        // arms (live-confirmed — re-probe NETWORK_ERROR *and* marker ERR_NGROK_3200),
+        // arms (live-confirmed — re-probe NETWORK_ERROR *and* an endpoint-gone marker),
         // so the marker alone still catches it. The probe is kept purely as
         // CORROBORATION in `detail` — it tells the caller whether the tunnel is
         // still down now or has since recovered. Per epic 56kd ("relay honestly,
@@ -735,7 +741,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // during the run is the relay inventing a cause.
         let tunnelFault;
         if (verdict.outcome === 'fail' && ctx.isLocalhost && ctx.tunnelId && ctx.targetUrl) {
-            const marker = findNgrokErrorMarker([
+            const marker = findTunnelErrorMarker([
                 verdict.reason,
                 finalExecution.state?.error,
                 finalExecution.errorMessage,
@@ -746,18 +752,18 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             // never decides whether we reclassify, only what we report alongside it.
             const probe = await probeTunnelHealth(ctx.targetUrl).catch(() => undefined);
             if (marker) {
-                tunnelFault = { probe, ngrokErrorCode: marker };
+                tunnelFault = { probe, tunnelErrorCode: marker };
                 logger.warn(`Reclassifying backend 'fail' as an infrastructure fault for ${executionUuid}: ` +
                     `the run recorded ${marker} (re-probe now: ` +
                     `${probe ? (probe.healthy ? 'healthy — tunnel has since recovered' : probe.code) : 'unavailable'})`);
             }
             else if (probe && !probe.healthy) {
                 // Deliberately NOT reclassifying. The tunnel looks unhealthy now, but
-                // the run recorded no ngrok interstitial, so we have no evidence the
+                // the run recorded no tunnel interstitial, so we have no evidence the
                 // browser ever saw one — the tunnel most likely died after the run (or
                 // the probe flaked). Relay the backend's verdict and log the tension.
                 logger.info(`Post-run tunnel re-probe for ${executionUuid} was unhealthy (${probe.code}) but the run ` +
-                    'recorded no ERR_NGROK_* marker, so the browser reached the app during the run. Relaying ' +
+                    'recorded no DEBUGG_TUNNEL_* marker, so the browser reached the app during the run. Relaying ' +
                     "the backend's verdict verbatim rather than blaming the tunnel.");
             }
         }
@@ -823,23 +829,23 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         // The backend's original verdict is preserved verbatim, never swallowed.
         //
         // Bug 4bui: the stated cause leads with the MARKER, because the marker is the
-        // evidence that justified getting here — the run itself recorded ngrok's
+        // evidence that justified getting here — the run itself recorded the tunnel's
         // interstitial. The probe only corroborates (and may legitimately say the
         // tunnel has recovered by now), so it rides in `detail`, never as the cause.
         if (tunnelFault) {
-            const { probe, ngrokErrorCode } = tunnelFault;
+            const { probe, tunnelErrorCode } = tunnelFault;
             responsePayload.backendVerdict = { outcome: verdict.outcome, reason: verdict.reason };
             responsePayload.outcome = 'error';
             responsePayload.success = false;
             responsePayload.failureCategory = 'infrastructure';
             responsePayload.error = 'TunnelOfflineDuringRun';
             responsePayload.message =
-                'During this run the remote browser landed on our tunnel\'s ngrok error page instead of your ' +
+                'During this run the remote browser landed on our tunnel\'s error page instead of your ' +
                     'app, so the check evaluated our error page rather than your UI. This is an infrastructure ' +
                     'fault on our side, not a failed check — retry it. The backend\'s original verdict is ' +
                     'preserved under `backendVerdict`.';
             responsePayload.reason =
-                `The run recorded ngrok's ${ngrokErrorCode} interstitial, so the remote browser reached ` +
+                `The run recorded our tunnel's ${tunnelErrorCode} interstitial, so the remote browser reached ` +
                     'our tunnel error page instead of your app.' +
                     (probe
                         ? probe.healthy
@@ -848,7 +854,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                                 `${probe.status ? ` (HTTP ${probe.status})` : ''}.)`
                         : '');
             responsePayload.detail = {
-                ngrokErrorCode,
+                tunnelErrorCode,
                 probeCode: probe?.code,
                 probeStatus: probe?.status,
                 probeHealthy: probe?.healthy,
@@ -874,7 +880,7 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         }
         // Backend release 2026-04-25: browser_session block on execution detail
         // carries presigned S3 URLs for HAR + console log + recording. Pass through
-        // verbatim — sanitizeResponseUrls below only strips ngrok hosts so S3 URLs
+        // verbatim — sanitizeResponseUrls below only strips tunnel hosts so S3 URLs
         // are preserved. Resolves client-feedback items #1 (network) + #7 (console).
         if (finalExecution.browserSession) {
             responsePayload.browserSession = finalExecution.browserSession;

package/dist/handlers/triggerCrawlHandler.js

@@ -85,7 +85,7 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
     try {
         // --- Tunnel: reuse existing or provision a fresh one ---
         if (ctx.isLocalhost) {
-            // Bead 1om: pre-flight local port probe BEFORE provision/ngrok/backend.
+            // Bead 1om: pre-flight local port probe BEFORE provision/tunnel/backend.
             const localPort = extractLocalhostPort(ctx.originalUrl);
             if (typeof localPort === 'number') {
                 const probe = await probeLocalPort(localPort);
@@ -155,11 +155,11 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
                             detail: {
                                 code: health.code,
                                 status: health.status,
-                                ngrokErrorCode: health.ngrokErrorCode,
+                                tunnelErrorCode: health.tunnelErrorCode,
                                 elapsedMs: health.elapsedMs,
                             },
                         };
-                        logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.ngrokErrorCode ?? ''} in ${health.elapsedMs}ms`);
+                        logger.warn(`Tunnel health probe failed for ${ctx.targetUrl}: ${health.code} ${health.tunnelErrorCode ?? ''} in ${health.elapsedMs}ms`);
                         // Evict ONLY on a code proving the endpoint is gone; every other failure
                         // keeps the tunnel we are already paying for, because a teardown+
                         // re-provision costs two billed hours and this probe cannot tell a dead

package/dist/index.js

@@ -271,7 +271,7 @@ function safeLog(level, message, meta) {
  */
 async function gracefulShutdown(signal) {
     safeLog('info', `Received ${signal}, shutting down gracefully`);
-    const { tunnelManager } = await import('./services/ngrok/tunnelManager.js');
+    const { tunnelManager } = await import('./services/tunnel/tunnelManager.js');
     await tunnelManager.stopAllTunnels().catch((err) => safeLog('warn', 'stopAllTunnels failed during shutdown', { error: String(err) }));
     await Telemetry.shutdown();
     process.exit(0);

package/dist/services/caddy/caddyProxy.js

@@ -83,8 +83,9 @@ export function isDockerEnv() {
 // @radically-straightforward/caddy is a dependency (package.json's "caddy"
 // field pins the exact version — see its postinstall) that downloads Caddy
 // from the project's own GitHub releases and drops it at
-// node_modules/.bin/caddy(.exe). Same pattern this repo already uses for the
-// ngrok binary (the "ngrok" npm package's own postinstall). Pinned rather
+// node_modules/.bin/caddy(.exe). It is now the ONLY binary this package pulls
+// down at install time — the ngrok package, whose postinstall fetched the ngrok
+// agent the same way, is gone. Pinned rather
 // than "latest" deliberately: a real config incompatibility with a Caddy
 // version (--adapter json rejected by 2.11.3) was found and fixed during
 // development of this file — "latest" silently shipping a breaking change
@@ -273,7 +274,7 @@ export function buildPatchBody(target, inDocker) {
         upstreams: [{ dial }],
     };
     if (isHttpsLocal) {
-        // Local self-signed certs — doesn't touch the public leg's real ngrok TLS.
+        // Local self-signed certs — doesn't touch the public leg's real TLS.
         body.transport = { protocol: 'http', tls: { insecure_skip_verify: true } };
     }
     return body;
@@ -370,7 +371,7 @@ export class CaddyProxyManager {
             }
             // Network-level failure against a previously-healthy admin port —
             // the process is presumed dead. Exactly one respawn-and-retry, then
-            // propagate uncaught — no loop (matches ngrokAgentSession.ts's
+            // propagate uncaught — no loop (matches the transport's
             // onTerminated philosophy: lazy, bounded, next-call-triggered).
             logger.warn(`Caddy admin API unreachable on port ${adminPort} — assuming process died, respawning once: ${err}`);
             this.markDead();
@@ -520,7 +521,7 @@ export class CaddyProxyManager {
      * successfully-bound proxy port (if any); attempt 2 falls back to a fresh
      * one. `CaddyPortReclaimError` means BOTH attempts failed — Caddy is fully
      * down. `onPortChanged` fires on the "succeeded but moved" case, which is
-     * the signal TunnelManager needs to evict the now-orphaned ngrok tunnel.
+     * the signal TunnelManager needs to evict the now-orphaned tunnel.
      */
     async doStart() {
         sweepOrphanedConfigs(this.configDir);
@@ -593,7 +594,7 @@ export class CaddyProxyManager {
         }
     }
     /** Restart policy: lazy, bounded, next-call-triggered — no background
-     *  watchdog (matches ngrokAgentSession.ts's onTerminated philosophy). This
+     *  watchdog (matches the transport's onDead philosophy). This
      *  handler only marks state as dead; it never itself triggers a respawn. */
     installExitHandler(child) {
         child.once('exit', (code, signal) => {

package/dist/services/index.js

@@ -473,15 +473,6 @@ export class DebuggAIServerClient {
             isActive: c.isActive,
         };
     }
-    /**
-     * Revoke an ngrok API key by its key ID.
-     * Call this after workflow execution completes to clean up the short-lived key.
-     */
-    async revokeNgrokKey(ngrokKeyId) {
-        if (!this.tx)
-            throw new Error('Client not initialized — call init() first');
-        await this.tx.post('api/v1/ngrok/revoke/', { ngrokKeyId });
-    }
     // ── E2E Suite Management ──────────────────────────────────────────────────
     async createTestSuite(input) {
         if (!this.tx)

package/dist/services/tunnel/debuggTransport.js

@@ -3,7 +3,7 @@
  *
  * One websocket per tunnel to the relayUrl a provision response supplies,
  * speaking the wire protocol in services/tunnel/protocol/ (spec: bead
- * debugg_ai_mcp-xkoh.1.2). It replaces the `ngrok` package, which downloads and
+ * debugg_ai_mcp-xkoh.1.2). It replaced the `ngrok` package, which downloaded and
  * spawns a native agent; `ws` is the only new dependency and is pure JS.
  *
  * This file owns exactly four things — the socket, the reconnect policy, the
@@ -324,7 +324,7 @@ class DebuggTransport {
         });
         socket.on('error', () => {
             if (!established) {
-                // The ERR_NGROK_8012 analogue: the tunnel is fine, the app refused.
+                // The tunnel is fine; the app refused the connection.
                 // The server renders DEBUGG_TUNNEL_UPSTREAM_REFUSED from this code and
                 // tunnelDisposition keeps the tunnel.
                 stream.reset(ErrorCode.UPSTREAM_UNREACHABLE);
@@ -359,9 +359,9 @@ function terminal(message) {
 function handshakeFailureError(state, status, supported, retryable) {
     switch (status) {
         case 401:
-            // The word "authtoken" is load-bearing: TunnelManager matches it to
-            // render its "invalid auth token" message, the same one an ngrok auth
-            // failure produces.
+            // The word "authtoken" is load-bearing: TunnelManager's connect ladder
+            // matches it to stop retrying and render its "invalid auth token"
+            // message.
             return terminal('the debugg tunnel server rejected the authtoken (HTTP 401) — the tunnel key is invalid, ' +
                 'expired or revoked. A new one is provisioned on the next call.');
         case 400:
@@ -379,10 +379,10 @@ function handshakeFailureError(state, status, supported, retryable) {
     }
 }
 /**
- * A connection-level failure reaching the relay. This is the one place where
- * the debugg transport can be WORSE than ngrok for a user — ngrok's agent
- * honours HTTPS_PROXY and this client does not — 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. 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.
  */
 function egressError(state, detail, code) {
     const relayHost = hostOf(state.relayUrl);

package/dist/services/tunnel/protocol/constants.js

@@ -163,14 +163,14 @@ export const HandshakeError = Object.freeze({
 });
 // ── Server error markers (server emits, client parses) ───────────────────────
 export const TunnelErrorMarker = Object.freeze({
-    /** No client connected — the ERR_NGROK_3200 analogue. */
+    /** No client connected — 404, matching what the retired ngrok edge served. */
     OFFLINE: 'DEBUGG_TUNNEL_OFFLINE',
     /** Unknown or revoked tunnel id. */
     UNKNOWN: 'DEBUGG_TUNNEL_UNKNOWN',
-    /** The client could not dial the local app — the ERR_NGROK_8012 analogue. */
+    /** The client could not dial the local app — 502. */
     UPSTREAM_REFUSED: 'DEBUGG_TUNNEL_UPSTREAM_REFUSED',
 });
-/** HTTP status each marker is served with, chosen to match the ngrok codes they replace. */
+/** HTTP status each marker is served with, chosen to match the codes they replaced. */
 export const MARKER_HTTP_STATUS = Object.freeze({
     [TunnelErrorMarker.OFFLINE]: 404,
     [TunnelErrorMarker.UNKNOWN]: 404,

package/dist/services/tunnel/transport.js

@@ -1,15 +1,34 @@
 /**
- * TunnelTransport — the one step of tunnel creation that differs between ngrok
- * and the debugg tunnel server.
+ * TunnelTransport — the boundary between tunnel LIFECYCLE (tunnelManager.ts:
+ * who owns a tunnel, when it is reused, when it is torn down) and tunnel
+ * TRANSPORT (debuggTransport.ts: the websocket mux that actually carries
+ * bytes).
  *
- * STUB (bead debugg_ai_mcp-xkoh.5.3, phase 2.1). Types and signatures only; the
- * implementations arrive in phase 4.1 (debugg_ai_mcp-xkoh.5.7).
+ * This started life as a two-implementation seam so the ngrok client and the
+ * debugg client could run side by side through the rollout. ngrok is gone and
+ * there is exactly one implementation now, but the interface is KEPT and the
+ * two-implementation machinery around it is not — see the note below.
+ *
+ * WHY KEEP AN INTERFACE WITH ONE IMPLEMENTATION: it is the injection point
+ * (`tunnelManager.transport`) every tunnel-lifecycle test drives, in the same
+ * spirit as `caddyFactory`. Without it, testing eviction, the retry ladder or
+ * the idle timer means standing up a real websocket against a real relay.
+ * It also keeps debuggTransport's ~600 lines of framing, flow control and
+ * reconnect out of TunnelManager, which is the reason the file boundary is
+ * worth having regardless of how many implementations exist.
+ *
+ * WHAT WAS REMOVED WITH ngrok, because it was ceremony the moment the second
+ * implementation went away:
+ *   - `TunnelTransportKind` and the `Record<kind, TunnelTransport>` registry —
+ *     a map with one key, keyed by a union with one member.
+ *   - `prepare()`, `resetAfterFailedAttempt()` and `onAllTunnelsStopped()` —
+ *     three optional hooks that existed ONLY for the ngrok agent process
+ *     (pre-warm, agent reset between retries, module reset when the agent may
+ *     have exited). debugg has no out-of-process agent, so every one of them
+ *     was a no-op on the only surviving implementation.
  *
  * Everything above this seam is unchanged: handlers, utils/tunnelContext.ts,
- * the per-session Caddy instance, PortLock, URL rewriting, the retry ladder,
- * the idle timer and the session keying all behave exactly as they do today
- * (docs/debugg-tunnel-server-design-2026-09-19.md §5). TunnelManager picks an
- * implementation from the provision response and calls it where it calls
- * ngrok.connect() today.
+ * the per-session Caddy instance, PortLock, URL rewriting, the retry ladder and
+ * the idle timer (docs/debugg-tunnel-server-design-2026-09-19.md §5).
  */
 export {};

package/dist/services/{ngrok → tunnel}/tunnelFaultInjection.js

@@ -6,27 +6,27 @@
  *   - DEBUGG_TUNNEL_FAULT_MODE env var explicitly set
  *
  * Modes (comma-separated, parseable by parseFaultMode):
- *   fail-connect-N:<count>      — fail the first <count> ngrok.connect() attempts
+ *   fail-connect-N:<count>      — fail the first <count> transport connect() attempts
  *   empty-url-N:<count>         — return empty URL from first <count> connect() attempts
  *   delay-connect:<ms>          — sleep <ms> before each connect() call
- *   inspector-unreachable:1     — the local ngrok agent inspector observes nothing
- *                                 (bead lc62: proves reconciliation is add-only, i.e.
- *                                 a blind inspector cannot cost a re-provision)
- *   inspector-adopt:<port>      — the inspector reports one synthetic live tunnel on
- *                                 <port>, exercising re-adoption end to end without
- *                                 provisioning a real, billable tunnel
  *
  * Examples:
  *   DEBUGG_TUNNEL_FAULT_MODE=fail-connect-N:2
  *   DEBUGG_TUNNEL_FAULT_MODE=delay-connect:2000,fail-connect-N:1
- *   DEBUGG_TUNNEL_FAULT_MODE=inspector-adopt:3000
+ *
+ * Two further modes — `inspector-unreachable` and `inspector-adopt` — went
+ * away with the ngrok agent inspector they drove. Both existed to exercise
+ * re-adoption of a tunnel already registered with the local ngrok agent, a
+ * mechanism that the per-session-tunnel cutover retired ("no sharing, ever")
+ * and that the debugg transport has no equivalent of: it owns its own socket
+ * and there is no out-of-process agent holding tunnels to discover.
  */
 export function parseFaultMode(raw) {
     if (!raw)
         return null;
     const mode = {};
     for (const token of raw.split(',').map((s) => s.trim()).filter(Boolean)) {
-        const m = token.match(/^(fail-connect-N|empty-url-N|delay-connect|inspector-unreachable|inspector-adopt):(\d+)$/);
+        const m = token.match(/^(fail-connect-N|empty-url-N|delay-connect):(\d+)$/);
         if (!m)
             continue;
         const [, name, valStr] = m;
@@ -37,12 +37,6 @@ export function parseFaultMode(raw) {
             mode.emptyUrlN = val;
         else if (name === 'delay-connect')
             mode.delayConnectMs = val;
-        // Value-less switch, but kept in the `name:<digits>` grammar so one regex
-        // covers every mode. Any non-zero value turns it on.
-        else if (name === 'inspector-unreachable')
-            mode.inspectorUnreachable = val !== 0;
-        else if (name === 'inspector-adopt')
-            mode.inspectorAdoptPort = val;
     }
     return Object.keys(mode).length > 0 ? mode : null;
 }