@debugg-ai/debugg-ai-mcp 4.4.1 → 6.0.0

package/CHANGELOG.md

@@ -5,7 +5,67 @@ 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] — BREAKING
+## [6.0.0] — 2026-10-04 — BREAKING
+
+### Changed — responses are the backend's data, not MCP-authored text
+
+Every tool response now relays the backend's fields under the backend's names,
+with its reasons verbatim. The MCP authors text only for what it observed itself
+(its poll deadline, a probe/tunnel failure, input validation).
+
+- `check_app_in_browser`: `outcome` is `pass | fail | error`, or `null` with
+  `skipped: true` and the backend's `skipReason` verbatim for a run that never
+  attempted a test (the raw run outcome is never read). Removed `success`,
+  `failureCategory`, `stepsTaken` / `stepsBudget` / `stepsRemaining` (use the
+  relayed `budget: {maxSteps, usedSteps}`), `failedNode` (use `errorInfo`),
+  `surferOutput`, and the node-rebuilt `actionTrace` / `evaluation` fallbacks.
+  `evaluation` now carries only keys the verdict lacks (it is omitted when it
+  would repeat `outcome` / `reason`). `credentialWarning` is `{requested, used}`
+  (no `message`). A tunnel fault keeps `error`, `backendVerdict`, `detail`; its
+  `message` and `failureCategory: 'infrastructure'` are gone and `reason` states
+  the recorded marker and the probe result.
+- `executions`: `outcome`, `verdict.outcome` and `evaluation.outcome` go through
+  the same `pass | fail | error` allowlist (null stays null for running rows and
+  for never-tested runs; a never-tested list row carries `skipReason`).
+- `trigger_crawl`: a never-tested run reads `outcome: null`, `skipped: true`,
+  `skipReason`.
+- `get` actions return `{project}` / `{execution}` / `{project, environment}` —
+  no echoed `filter`, no single-row `pageInfo`. `list` actions no longer echo
+  `filter`.
+- `environment` `sessions` → `{environmentUuid, sessions}`; `clearSessions` →
+  `{environmentUuid, invalidated}` (no `note`, `scope`, `usableCount`).
+- `authorizedCredentialHostsWarning` is `{requested, returned}` (no `message`).
+- `trigger_crawl`: `crawlSummary` / `knowledgeGraph` carry only reported keys
+  (no derived `imported`, no `0` / `''` defaults).
+- `probe_page`: an unreported `statusCode` / `loadTimeMs` / `finalUrl` is `null`,
+  not `0` or the input URL.
+- `test_suite`: an unreported `runStatus` / run counts are `null` (no invented
+  `NEVER_RUN` / `PENDING` / `0`); `results` per-test `lastRun.outcome` goes
+  through the `pass | fail | error` allowlist. `run`: no `note`. Error messages no longer append advice
+  ("Start your dev server…", "Common causes…", "Ensure the template is seeded…",
+  "Pass … explicitly", "Link this repo…").
+
+### Fixed — localhost URLs inside goal text now point at the tunnel
+
+`check_app_in_browser` rewrites every `http(s)://localhost[:port]` /
+`127.0.0.1` origin inside the goal text onto the run's tunnel origin, keeping path, query and
+fragment. The remote browser used to dial its own loopback for those URLs and the run was
+recorded as the app failing. With no tunnel the text is left unchanged.
+
+### Migration from 5.x
+
+| 5.x field | 6.0.0 |
+|---|---|
+| `success` | removed — read `outcome` (`pass` / `fail` / `error`, or `null` + `skipped` + `skipReason`) |
+| `failureCategory` | removed — read `outcome` and the backend `reason` |
+| `stepsTaken` / `stepsBudget` / `stepsRemaining` | removed — read `budget: {maxSteps, usedSteps}` |
+| `failedNode` | removed — read `errorInfo` |
+| `surferOutput`, rebuilt `actionTrace` / `evaluation` | removed |
+| `project` / `executions` / `environment` `get` → `projects[0]` / `executions[0]` / `environments[0]` + `pageInfo` + `filter` | `{project}` / `{execution}` / `{project, environment}` |
+| `list` → `filter` echo | removed |
+| `*Warning.message`, `note`, error-message advice | removed — structured fields only |
+
+## Earlier changes (recorded before versioned headings resumed)
 
 ### Changed — one ngrok tunnel per session instead of one per local port
 

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 |
 |-----------|------|-------------|
@@ -117,8 +118,7 @@ Results report the identity actually used, so a wrong one is visible rather than
 ],
 "credentialWarning": {
   "requested": "qa+invitefix@example.com",
-  "used": ["qatest123@example.com"],
-  "message": "This run signed in with an environment default credential even though '…' was specified. …"
+  "used": ["qatest123@example.com"]
 }
 ```
 
@@ -142,7 +142,7 @@ URLs are short-lived presigned S3 — refetch the parent execution via `executio
 
 #### `trigger_crawl`
 
-Fires a server-side browser-agent crawl to populate the project's knowledge graph. Localhost URLs tunnel automatically. Returns `{executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?}` with `knowledgeGraph.imported === true` on successful ingestion. The `browserSession` block (HAR + console-log URLs, same shape as above) is also present on completed crawls.
+Fires a server-side browser-agent crawl to populate the project's knowledge graph. Localhost URLs tunnel automatically. Returns `{executionId, status, targetUrl, durationMs, outcome?, crawlSummary?, knowledgeGraph?, browserSession?}` with `knowledgeGraph.skipped === false` on successful ingestion. `crawlSummary` and `knowledgeGraph` carry only the keys the backend's crawl / import nodes reported — a missing count is absent, never a filled-in `0`. The `browserSession` block (HAR + console-log URLs, same shape as above) is also present on completed crawls.
 
 #### `probe_page`
 
@@ -183,12 +183,12 @@ Team and repo resolve by **either** uuid **or** name (case-insensitive exact mat
 | `create` | `{name, url, description?, projectUuid?, credentials?, authorizedCredentialHosts?}` | Created env (optionally seeds credentials) |
 | `update` | `{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?, authorizedCredentialHosts?}` | Patched env; credential ops run **remove → update → add** |
 | `delete` | `{uuid, projectUuid?, confirm?}` | Deletes env (cascades credentials) — **requires confirmation** |
-| `sessions` | `{uuid, username?, credentialId?}` | Captured login sessions the env holds, per account, with `isUsable` and a `usableCount` |
+| `sessions` | `{uuid, username?, credentialId?}` | Captured login sessions the env holds, per account, each with its own `isUsable` |
 | `clearSessions` | `{uuid, username?, credentialId?, confirm?}` | Invalidates them so the next run logs in for real — **unscoped clears require confirmation** |
 
 `projectUuid` auto-resolves from the git repo when omitted. Per-cred failures surface in `credentialWarnings[]` without blocking the env op.
 
-`authorizedCredentialHosts` lists hosts where a run may enter this environment's credentials besides the app's own host — **for cross-domain SSO, add the IdP host here** (e.g. `["auth.example.com"]`). Bare hostnames only: no scheme, path, port or wildcard (subdomains of the app's host are already in scope). On `update` it replaces the list; `[]` clears it. `get`/`list` return it when the server supports it. The response echoes the saved list; if the server did not persist it (older servers ignore the field), the result carries an `authorizedCredentialHostsWarning` saying so instead of a silent success.
+`authorizedCredentialHosts` lists hosts where a run may enter this environment's credentials besides the app's own host — **for cross-domain SSO, add the IdP host here** (e.g. `["auth.example.com"]`). Bare hostnames only: no scheme, path, port or wildcard (subdomains of the app's host are already in scope). On `update` it replaces the list; `[]` clears it. `get`/`list` return it when the server supports it. The response echoes the saved list; if the server did not persist it (older servers ignore the field), the result carries `authorizedCredentialHostsWarning: {requested, returned}` instead of a silent success.
 
 `sessions` / `clearSessions` manage the warm authenticated sessions the backend reuses to skip login (see [Session reuse](#session-reuse-why-a-check-can-report-no-login-form)). Session contents are never returned — a session cookie is a bearer credential. `clearSessions` marks sessions invalid rather than deleting the rows, so reuse stops immediately while the capture history stays readable.
 
@@ -221,11 +221,10 @@ Team and repo resolve by **either** uuid **or** name (case-insensitive exact mat
 
 ### Pagination
 
-Every filter-mode response is paginated. Response shape:
+Every `list` response is paginated. Response shape:
 
 ```json
 {
-  "filter": { "...echoed query params..." },
   "pageInfo": { "page": 1, "pageSize": 20, "totalCount": 47, "totalPages": 3, "hasMore": true },
   "<items>": [ ... ]
 }
@@ -233,6 +232,8 @@ Every filter-mode response is paginated. Response shape:
 
 Pass optional `page` (1-indexed, default 1) and `pageSize` (default 20, max 200; oversized values are clamped). No response is ever silently truncated.
 
+A `get` returns the one object under its singular name — `{project}`, `{execution}`, `{project, environment}` — with no `pageInfo`.
+
 ## Resources
 
 Alongside tools, the server exposes the read-only entities as MCP **resources**
@@ -254,10 +255,27 @@ 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.
 
+## Migration to v6.0.0 (backend verdicts, no MCP-authored text)
+
+A run verdict is `pass | fail | error`, with the backend's `reason` relayed verbatim. A run that
+never attempted a test reads `outcome: null`, `skipped: true`, `skipReason`.
+
+| Removed | Replacement |
+|---------|-------------|
+| `success` | `outcome` |
+| `failureCategory` | `outcome` + `reason` |
+| `stepsTaken` / `stepsBudget` / `stepsRemaining` | `budget: {maxSteps, usedSteps}` |
+| `failedNode` | `errorInfo` |
+| `get` → `projects[0]` / `executions[0]` / `environments[0]` + `pageInfo` + `filter` | `{project}` / `{execution}` / `{project, environment}` |
+| `message` / `note` on warnings and results | structured fields only |
+
+Full list: [CHANGELOG.md](CHANGELOG.md) 6.0.0.
+
 ## Migration to v3.0.0 (action-based tools)
 
 v3 consolidated the 20 per-verb tools into 8 action-based tools. Old tool → new `tool {action}`:
@@ -341,11 +359,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/createEnvironmentHandler.js

@@ -21,7 +21,7 @@ export async function createEnvironmentHandler(input, _context) {
             if (!repoName) {
                 const payload = {
                     error: 'NoProjectResolved',
-                    message: 'No git repo detected and no projectUuid provided. Pass projectUuid (get it from search_projects) or invoke from a directory with a git origin.',
+                    message: 'No git repo detected and no projectUuid provided.',
                 };
                 return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
             }
@@ -29,7 +29,7 @@ export async function createEnvironmentHandler(input, _context) {
             if (!project) {
                 const payload = {
                     error: 'NoProjectResolved',
-                    message: `No DebuggAI project found for repo "${repoName}". Pass projectUuid explicitly.`,
+                    message: `No DebuggAI project found for repo "${repoName}".`,
                 };
                 return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }], isError: true };
             }
@@ -81,10 +81,10 @@ export async function createEnvironmentHandler(input, _context) {
         }
         // Bead q4d4: only the echo proves the backend kept the hosts.
         if (input.authorizedCredentialHosts !== undefined) {
-            const hostsWarning = checkAuthorizedCredentialHostsEcho(input.authorizedCredentialHosts, env.authorizedCredentialHosts, 'create');
+            const hostsWarning = checkAuthorizedCredentialHostsEcho(input.authorizedCredentialHosts, env.authorizedCredentialHosts);
             if (hostsWarning) {
                 payload.authorizedCredentialHostsWarning = hostsWarning;
-                logger.warn(`create_environment: ${hostsWarning.message}`);
+                logger.warn(`create_environment: authorizedCredentialHosts not persisted`, hostsWarning);
             }
         }
         logger.toolComplete('create_environment', Date.now() - start);

package/dist/handlers/createProjectHandler.js

@@ -32,7 +32,7 @@ function resolveName(name, candidates, kind) {
     if (matches.length > 1) {
         return {
             error: 'AmbiguousMatch',
-            message: `Multiple ${kind.toLowerCase()}s match "${name}". Pass ${kind.toLowerCase()}Uuid explicitly.`,
+            message: `Multiple ${kind.toLowerCase()}s match "${name}".`,
             candidates: matches.map(m => ({ uuid: m.uuid, name: m.name })),
         };
     }

package/dist/handlers/environmentSessionsHandler.js

@@ -18,16 +18,7 @@ export async function listEnvironmentSessionsHandler(input, _context) {
         // usableCount, not just the rows: "does this environment currently hold a
         // session that will be restored?" is the question a caller is actually
         // asking, and an expired row still reports status 'valid'.
-        const usableCount = sessions.filter(s => s.isUsable).length;
-        return ok({
-            environmentUuid: input.uuid,
-            sessions,
-            pageInfo: { totalCount: sessions.length, usableCount },
-            note: sessions.length === 0
-                ? 'No captured sessions — every run for this environment logs in for real.'
-                : `${usableCount} of ${sessions.length} session(s) would be restored instead of logging in. `
-                    + 'Use action "clearSessions" to force a real login, or pass freshSession:true on a single run.',
-        });
+        return ok({ environmentUuid: input.uuid, sessions });
     }
     catch (error) {
         throw handleExternalServiceError(error, 'DebuggAI', 'environment.sessions');
@@ -45,14 +36,7 @@ export async function clearEnvironmentSessionsHandler(input, _context) {
         const { invalidated } = await client.clearEnvironmentSessions(input.uuid, filters);
         const scope = input.username ?? input.credentialId ?? 'all accounts';
         logger.info(`environment.clearSessions: invalidated ${invalidated} session(s) for ${scope}`);
-        return ok({
-            environmentUuid: input.uuid,
-            invalidated,
-            scope,
-            note: invalidated === 0
-                ? 'Nothing to clear — no usable captured session matched.'
-                : 'The next run for this identity will perform a real login and re-capture.',
-        });
+        return ok({ environmentUuid: input.uuid, invalidated });
     }
     catch (error) {
         throw handleExternalServiceError(error, 'DebuggAI', 'environment.clearSessions');

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;
@@ -126,7 +126,7 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                     if (!probe.reachable) {
                         const payload = {
                             error: 'LocalServerUnreachable',
-                            message: `No server listening on 127.0.0.1:${port}. Start your dev server on that port before running probe_page. Probe result: ${probe.code} (${probe.detail ?? 'no detail'}).`,
+                            message: `No server listening on 127.0.0.1:${port}.`,
                             detail: {
                                 port,
                                 probeCode: probe.code,
@@ -157,8 +157,7 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                         catch (provisionError) {
                             const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
                             const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
-                            throw new Error(`Failed to provision tunnel for ${ctx.originalUrl}. ` +
-                                `(Detail: ${msg})${diag}`);
+                            throw new Error(`Failed to provision tunnel for ${ctx.originalUrl}: ${msg}${diag}`);
                         }
                         acquiredProvisions.push(tunnel);
                         let tunneled;
@@ -167,7 +166,7 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                         }
                         catch (tunnelError) {
                             const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
-                            throw new Error(`Tunnel creation failed for ${ctx.originalUrl}. (Detail: ${msg})`);
+                            throw new Error(`Tunnel creation failed for ${ctx.originalUrl}: ${msg}`);
                         }
                         // NOTE: the tunnel health probe used to run right here, immediately
                         // after ensureTunnel. Under the session-tunnel + Caddy model that is
@@ -198,9 +197,7 @@ export async function probePageHandler(input, context, rawProgressCallback) {
             return client.workflows.findTemplateBySlug(templateSlug);
         });
         if (!templateUuid) {
-            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}).`);
+            throw new Error(`Page Probe workflow template not found (slug "${templateSlug}").`);
         }
         // ── Group targets by shared Caddy route (§4 multi-port batch decision) ──
         // Single-group batches (the common case — one port, or all-public) behave
@@ -253,11 +250,11 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                     if (!health.healthy) {
                         const payload = {
                             error: 'TunnelTrafficBlocked',
-                            message: `Tunnel established but traffic isn't reaching the dev server. ${health.detail ?? ''}`,
+                            message: `Tunnel established; a request through it to 127.0.0.1:${extractLocalhostPort(groupCtx.originalUrl)} failed: ${health.detail ?? health.code}.`,
                             detail: {
                                 code: health.code,
                                 status: health.status,
-                                ngrokErrorCode: health.ngrokErrorCode,
+                                tunnelErrorCode: health.tunnelErrorCode,
                                 elapsedMs: health.elapsedMs,
                             },
                         };
@@ -358,10 +355,10 @@ export async function probePageHandler(input, context, rawProgressCallback) {
                         finalUrl: typeof data.capturedUrl === 'string' ? data.capturedUrl
                             : typeof data.finalUrl === 'string' ? data.finalUrl
                                 : typeof data.url === 'string' ? data.url
-                                    : target.url,
-                        statusCode: typeof data.statusCode === 'number' ? data.statusCode : 0,
+                                    : null,
+                        statusCode: typeof data.statusCode === 'number' ? data.statusCode : null,
                         title: typeof data.title === 'string' ? data.title : null,
-                        loadTimeMs: typeof data.loadTimeMs === 'number' ? data.loadTimeMs : 0,
+                        loadTimeMs: typeof data.loadTimeMs === 'number' ? data.loadTimeMs : null,
                         consoleErrors: mapConsoleSlice(Array.isArray(data.consoleSlice) ? data.consoleSlice : []),
                         networkSummary: reaggregateByOriginPath(Array.isArray(data.networkSummary) ? data.networkSummary : []),
                     };

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' });
@@ -51,7 +51,7 @@ export async function runTestSuiteHandler(input, _context) {
                 if (typeof port === 'number') {
                     const probe = await probeLocalPort(port);
                     if (!probe.reachable) {
-                        return errorResp('LocalServerUnreachable', `No server listening on 127.0.0.1:${port}. Start your dev server before running the suite. (${probe.code}: ${probe.detail ?? 'no detail'})`, { port, probeCode: probe.code, elapsedMs: probe.elapsedMs });
+                        return errorResp('LocalServerUnreachable', `No server listening on 127.0.0.1:${port}.`, { port, probeCode: probe.code, elapsedMs: probe.elapsedMs });
                     }
                 }
                 if (config.devMode) {
@@ -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 {
@@ -77,7 +77,7 @@ export async function runTestSuiteHandler(input, _context) {
                     catch (provisionError) {
                         const msg = provisionError instanceof Error ? provisionError.message : String(provisionError);
                         const diag = provisionError instanceof TunnelProvisionError ? ` ${provisionError.diagnosticSuffix()}` : '';
-                        return errorResp('TunnelProvisionFailed', `Failed to provision tunnel for ${input.targetUrl}. (Detail: ${msg})${diag}`);
+                        return errorResp('TunnelProvisionFailed', `Failed to provision tunnel for ${input.targetUrl}: ${msg}${diag}`);
                     }
                     acquiredProvision = tunnel;
                     let dedicated;
@@ -86,9 +86,9 @@ export async function runTestSuiteHandler(input, _context) {
                     }
                     catch (tunnelError) {
                         const msg = tunnelError instanceof Error ? tunnelError.message : String(tunnelError);
-                        return errorResp('TunnelCreationFailed', `Tunnel creation failed for ${input.targetUrl}. (Detail: ${msg})`);
+                        return errorResp('TunnelCreationFailed', `Tunnel creation failed for ${input.targetUrl}: ${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; a request through it to 127.0.0.1:${port} failed: ${health.detail ?? health.code}.`, { code: health.code, tunnelErrorCode: health.tunnelErrorCode, elapsedMs: health.elapsedMs });
                         }
                     }
                     effectiveTargetUrl = dedicated.url;
@@ -119,13 +119,12 @@ export async function runTestSuiteHandler(input, _context) {
         const responsePayload = {
             ...result,
             ...(tunnelId ? { tunnelActive: true, originalUrl: input.targetUrl } : {}),
-            note: 'Tests are running asynchronously. Use get_test_suite_results to check progress.',
         };
         // Bead debugg_ai_mcp-6cfv.7: this handler previously had NO sanitize call
         // 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/searchEnvironmentsHandler.js

@@ -71,11 +71,11 @@ export async function searchEnvironmentsHandler(input, _context) {
         if (!projectUuid) {
             const repoName = detectRepoName();
             if (!repoName) {
-                return noProjectResolved(pagination, 'No git repo detected and no projectUuid provided. Pass projectUuid (get via search_projects) or invoke from a directory with a git origin.');
+                return noProjectResolved(pagination, 'No git repo detected and no projectUuid provided.');
             }
             const resolved = await client.findProjectByRepoName(repoName);
             if (!resolved) {
-                return noProjectResolved(pagination, `No DebuggAI project found for repo "${repoName}". Pass projectUuid explicitly.`);
+                return noProjectResolved(pagination, `No DebuggAI project found for repo "${repoName}".`);
             }
             projectUuid = resolved.uuid;
             project = { uuid: resolved.uuid };
@@ -95,9 +95,7 @@ export async function searchEnvironmentsHandler(input, _context) {
                 const creds = await client.listCredentialsForEnvironment(projectUuid, input.uuid).catch(() => []);
                 const payload = {
                     project,
-                    filter: { uuid: input.uuid },
-                    pageInfo: { page: 1, pageSize: 1, totalCount: 1, totalPages: 1, hasMore: false },
-                    environments: [{ ...env, credentials: creds.map(stripPassword) }],
+                    environment: { ...env, credentials: creds.map(stripPassword) },
                 };
                 logger.toolComplete('search_environments', Date.now() - start);
                 return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
@@ -118,7 +116,6 @@ export async function searchEnvironmentsHandler(input, _context) {
         }
         const payload = {
             project,
-            filter: { q: input.q ?? null },
             pageInfo,
             environments: withCreds,
         };

package/dist/handlers/searchExecutionsHandler.js

@@ -13,6 +13,7 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { config } from '../config/index.js';
 import { toPaginationParams } from '../utils/pagination.js';
+import { withUserFacingOutcomes } from '../services/verdictAdapter.js';
 import { fetchImageAsBase64, imageContentBlock, resourceLinkBlock, artifactResourceLinks } from '../utils/imageUtils.js';
 const logger = new Logger({ module: 'searchExecutionsHandler' });
 function notFound(uuid) {
@@ -33,11 +34,7 @@ export async function searchExecutionsHandler(input, _context) {
         if (input.uuid) {
             try {
                 const execution = await client.workflows.getExecution(input.uuid);
-                const payload = {
-                    filter: { uuid: input.uuid },
-                    pageInfo: { page: 1, pageSize: 1, totalCount: 1, totalPages: 1, hasMore: false },
-                    executions: [execution],
-                };
+                const payload = { execution: withUserFacingOutcomes(execution) };
                 logger.toolComplete('search_executions', Date.now() - start);
                 const content = [
                     { type: 'text', text: JSON.stringify(payload, null, 2) },
@@ -88,7 +85,6 @@ export async function searchExecutionsHandler(input, _context) {
                         ? [resourceLinkBlock(gifUrl, `run-recording-${input.uuid}.gif`, {
                                 mimeType: 'image/gif',
                                 title: 'Run recording',
-                                description: 'Animated recording of the execution (presigned URL — open or fetch on demand).',
                             })]
                         : []),
                     ...artifactResourceLinks(execution.browserSession),
@@ -116,12 +112,8 @@ export async function searchExecutionsHandler(input, _context) {
             pageSize: pagination.pageSize,
         });
         const payload = {
-            filter: {
-                status: input.status ?? null,
-                projectUuid: input.projectUuid ?? null,
-            },
             pageInfo,
-            executions,
+            executions: executions.map(withUserFacingOutcomes),
         };
         logger.toolComplete('search_executions', Date.now() - start);
         return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };

package/dist/handlers/searchProjectsHandler.js

@@ -36,11 +36,7 @@ export async function searchProjectsHandler(input, _context) {
         if (input.uuid) {
             try {
                 const project = await client.getProject(input.uuid);
-                const payload = {
-                    filter: { uuid: input.uuid },
-                    pageInfo: { page: 1, pageSize: 1, totalCount: 1, totalPages: 1, hasMore: false },
-                    projects: [project],
-                };
+                const payload = { project };
                 logger.toolComplete('search_projects', Date.now() - start);
                 return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
             }
@@ -53,7 +49,6 @@ export async function searchProjectsHandler(input, _context) {
         const pagination = toPaginationParams({ page: input.page, pageSize: input.pageSize });
         const { pageInfo, projects } = await client.listProjects(pagination, input.q);
         const payload = {
-            filter: { q: input.q ?? null },
             pageInfo,
             projects: projects.map((p) => ({
                 uuid: p.uuid,