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

package/dist/services/verdictAdapter.js

@@ -7,24 +7,119 @@
  *
  * Backend contract (camelCase after axiosTransport conversion). The containers
  * are TOP-LEVEL siblings of `state` on the execution-detail response:
- *   execution.verdict:  { outcome: pass|fail|inconclusive|error|timeout, reason }
+ *   execution.verdict:  { outcome: pass|fail|error|null, reason, skipped? }
+ *                       (outcome null + skipped: true = never attempted a test)
  *   execution.budget:   { maxSteps, usedSteps }
  *   execution.evidence: { screenshot, actionTrace }
  * `verdict` is SINGULAR — distinct from the pre-existing plural `verdicts`
  * (RunVerdict array) and the raw `outcome` string, neither of which we read.
  *
- * Principle: relay, never invent.
- *   - `verdict.outcome` is relayed VERBATIM; `success` = (outcome === 'pass').
- *   - Anything else (fail/inconclusive/error/timeout) → success:false with
- *     `failureCategory = outcome` — NOT a fabricated 'assertion-mismatch'.
- *   - A missing / null / unrecognized verdict maps to `inconclusive`, never to
- *     `fail` and never to the raw execution status.
- *   - Budget comes from the response, not a client-side constant (the constant
- *     is only a fallback for pre-contract backends).
+ * EVERY verdict a user sees is pass | fail | error (platform-98fv.16,
+ * 2026-10-04). `inconclusive`, `unverified`, `unknown` and `abandoned` are gone
+ * as user-facing values: they told a user nothing they could act on. They now
+ * become `error` carrying the reason "No verdict recorded", which at least says
+ * what happened.
+ *
+ * Principle: relay, never invent — but never relay a non-answer either.
+ *   - pass/fail are relayed verbatim; everything else collapses to `error`.
+ *   - nothing derived from the outcome is added beside it (no `success`, no
+ *     `failureCategory`): a second copy of the verdict is a second thing to
+ *     disagree with it.
+ *   - the backend's own `reason` is shown whenever it sends one. We only
+ *     supply a reason when it did not.
+ *   - a missing / null / unrecognized verdict on a FINISHED run is `error`,
+ *     never `fail`, never the raw execution status and never the raw run
+ *     outcome (`state.outcome` is internal: it can be cancelled / timeout /
+ *     skipped).
+ *   - a run that NEVER ATTEMPTED A TEST has no verdict (platform-98fv.16): the
+ *     backend sends `verdict: { outcome: null, reason, skipped: true }` and the
+ *     relay is `outcome: null, skipped: true, skipReason: <reason verbatim>`.
+ *   - a run still going has no verdict yet: `outcome: null`.
+ *   - `budget` is the backend's container, relayed verbatim or not at all.
+ *
+ * `timeout` deserves its own note because it is OURS, not the backend's. The
+ * MCP synthesises it when its own 10-minute poll deadline expires
+ * (services/workflows.ts) — which is a different event from the backend saying
+ * a run timed out. Both are `error`, because neither is a verdict about the
+ * user's app, but the REASON keeps them apart: ours says we stopped waiting and
+ * the run may still be going, theirs says whatever the backend said. Merging
+ * them would erase the answer to the first question anyone asks.
+ */
+/** The ONLY outcomes a user ever sees. */
+export const USER_FACING_OUTCOMES = ['pass', 'fail', 'error'];
+/**
+ * A reason is a FACTUAL RECORD: what we did, what we saw, what happened. No
+ * hedges ("may", "likely"), no blame, no advice, and no fixed sentence per
+ * category — a canned string reads as an explanation while carrying no
+ * information, and the reader cannot tell one occurrence from another.
+ *
+ * So these are built from the actual values observed, and every number in them
+ * is real.
  */
-/** The verdict enum the backend emits (bead sentinal-k8x1f.2). */
-export const KNOWN_OUTCOMES = ['pass', 'fail', 'inconclusive', 'error', 'timeout'];
-const KNOWN = new Set(KNOWN_OUTCOMES);
+/**
+ * THE mapping, exported because more than one field carries an outcome and they
+ * must never disagree: the headline `outcome` and the nested
+ * `evaluation.outcome` are read by the same person in the same payload. The
+ * backend keeps them consistent by deriving both from one verdict
+ * (sentinal-sk5sl.1); once the MCP re-maps one of them, it has to re-map the
+ * other through the same function or it reintroduces exactly the contradiction
+ * that design removed.
+ */
+export function toUserFacingOutcome(raw) {
+    // Deliberately an allowlist, not a denylist of known non-answers: a value a
+    // future backend invents must land on `error` too, rather than leaking
+    // through because nobody added it to a list.
+    const v = typeof raw === 'string' ? raw.trim() : '';
+    return v === 'pass' || v === 'fail' ? v : 'error';
+}
+/**
+ * An execution record as the executions tool relays it: the backend object
+ * verbatim, except the three fields a user reads as the run's verdict —
+ * `outcome`, `verdict.outcome`, `evaluation.outcome` — which go through the
+ * same allowlist as check_app_in_browser. A null/absent outcome (a run still
+ * going) stays null: "no verdict yet" is not an error. Internal run state
+ * (`state.*`, node output) keeps its raw values.
+ */
+export function withUserFacingOutcomes(execution) {
+    if (!execution || typeof execution !== 'object')
+        return execution;
+    const mapIfSet = (v) => (typeof v === 'string' && v.trim() !== '' ? toUserFacingOutcome(v) : v);
+    const e = { ...execution };
+    if ('outcome' in e)
+        e.outcome = mapIfSet(e.outcome);
+    for (const key of ['verdict', 'evaluation']) {
+        if (e[key] && typeof e[key] === 'object' && 'outcome' in e[key]) {
+            e[key] = { ...e[key], outcome: mapIfSet(e[key].outcome) };
+        }
+    }
+    return e;
+}
+export function noVerdictReason(rawOutcome) {
+    const seen = typeof rawOutcome === 'string' && rawOutcome.trim() !== '' ? rawOutcome.trim() : null;
+    return seen
+        ? `Backend returned outcome '${seen}' with no reason.`
+        : 'Backend returned no outcome and no reason.';
+}
+/**
+ * OUR deadline expiring is not the backend reporting a timeout, and the two
+ * must stay distinguishable: one means we stopped listening, the other means
+ * the run stopped. This states only what we observed — no claim about whether
+ * the run is still going, because we do not know.
+ */
+export function pollTimeoutReason(facts) {
+    const parts = [];
+    parts.push(facts.executionUuid
+        ? `No result from execution ${facts.executionUuid}`
+        : 'No result from the execution');
+    if (typeof facts.elapsedMs === 'number') {
+        parts.push(`after ${Math.round(facts.elapsedMs / 1000)}s of polling`);
+    }
+    if (typeof facts.pollCount === 'number') {
+        parts.push(`(${facts.pollCount} polls)`);
+    }
+    const head = parts.join(' ');
+    return facts.lastStatus ? `${head}; last status: ${facts.lastStatus}.` : `${head}.`;
+}
 /** Credential sources that mean "the caller named this account for this run". */
 const CALLER_SPECIFIED_SOURCES = new Set(['task', 'explicit', 'credential_id']);
 /**
@@ -59,42 +154,73 @@ export function credentialSubstitutions(logins, namedIdentities) {
  * Map a workflow execution onto the MCP relay verdict. Never throws.
  */
 export function adaptVerdict(execution, opts = {}) {
-    const state = execution?.state ?? null;
     // Contract containers live at the TOP LEVEL of the execution response
     // (siblings of `state`), NOT nested under state.
     const verdict = execution?.verdict ?? null;
     const budget = execution?.budget ?? null;
     const evidence = execution?.evidence ?? null;
-    // --- Outcome (verbatim relay, inconclusive on anything unrecognized) ---
-    let outcome;
-    if (opts.outcomeOverride) {
-        outcome = opts.outcomeOverride;
+    // --- Outcome: pass | fail | error, or null for no verdict ---
+    // Only the explicit verdict. NEVER the raw run outcome (state.outcome is the
+    // run's internal record — cancelled / timeout / skipped) and never
+    // execution.status.
+    const rawOutcome = opts.outcomeOverride ?? verdict?.outcome;
+    const raw = typeof rawOutcome === 'string' ? rawOutcome.trim() : '';
+    const isOurPollTimeout = opts.outcomeOverride === 'timeout';
+    const backendReason = typeof verdict?.reason === 'string' && verdict.reason.trim() !== '' ? verdict.reason : null;
+    if (!isOurPollTimeout && !raw) {
+        // A run that never attempted a test (platform-98fv.16): no verdict, and the
+        // backend's recorded reason, verbatim.
+        if (verdict?.skipped === true) {
+            const skipped = { outcome: null, skipped: true };
+            if (backendReason)
+                skipped.skipReason = backendReason;
+            if (budget && typeof budget === 'object')
+                skipped.budget = budget;
+            return attachEvidence(skipped, evidence);
+        }
+        // Still going: no verdict YET is not an error.
+        if (!TERMINAL_STATUSES.has(String(execution?.status ?? ''))) {
+            const pending = { outcome: null };
+            if (budget && typeof budget === 'object')
+                pending.budget = budget;
+            return attachEvidence(pending, evidence);
+        }
+    }
+    // error covers: the backend's own 'error'/'timeout', every retired non-answer
+    // (inconclusive/unverified/unknown/abandoned), anything a newer backend
+    // invents, and a verdict that never arrived.
+    const outcome = toUserFacingOutcome(raw);
+    const relay = { outcome };
+    if (budget && typeof budget === 'object')
+        relay.budget = budget;
+    // Reason precedence, and the order is the whole point:
+    //   1. the backend's own words, relayed VERBATIM and never rephrased;
+    //   2. our poll deadline, stated as what we observed — only when WE forced
+    //      the timeout, so a backend-reported timeout keeps its own reason;
+    //   3. a factual record of what arrived, when nothing explained itself.
+    // OUR deadline comes first, deliberately. If we never saw a terminal verdict,
+    // any reason we are holding came from a mid-flight poll — it describes a run
+    // still in progress, not its result. Relaying it next to outcome='error'
+    // would pair someone else's "looks good" with our failure.
+    if (isOurPollTimeout) {
+        relay.reason = pollTimeoutReason({
+            executionUuid: execution?.uuid,
+            lastStatus: execution?.status,
+            ...(opts.pollTimeout ?? {}),
+        });
     }
-    else {
-        // Prefer the explicit verdict; fall back to the legacy per-run outcome
-        // field; NEVER fall back to execution.status. Unknown values → inconclusive.
-        const raw = verdict?.outcome ?? state?.outcome;
-        outcome = typeof raw === 'string' && KNOWN.has(raw) ? raw : 'inconclusive';
+    else if (backendReason) {
+        relay.reason = backendReason;
     }
-    const success = outcome === 'pass';
-    // --- Budget (from the response; constant is a fallback only) ---
-    const fallbackBudget = opts.fallbackBudget ?? 0;
-    const stepsBudget = typeof budget?.maxSteps === 'number' ? budget.maxSteps : fallbackBudget;
-    const stepsTaken = typeof budget?.usedSteps === 'number'
-        ? budget.usedSteps
-        : (typeof state?.stepsTaken === 'number' ? state.stepsTaken : 0);
-    const stepsRemaining = Math.max(0, stepsBudget - stepsTaken);
-    const relay = {
-        outcome,
-        success,
-        stepsBudget,
-        stepsTaken,
-        stepsRemaining,
-    };
-    if (!success)
-        relay.failureCategory = outcome;
-    if (typeof verdict?.reason === 'string' && verdict.reason)
-        relay.reason = verdict.reason;
+    else if (outcome === 'error') {
+        relay.reason = noVerdictReason(raw);
+    }
+    return attachEvidence(relay, evidence);
+}
+/** The run lifecycle states after which no verdict will arrive. */
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled']);
+/** The backend's evidence container onto the relay, verbatim. */
+function attachEvidence(relay, evidence) {
     if (typeof evidence?.screenshot === 'string' && evidence.screenshot)
         relay.screenshot = evidence.screenshot;
     if (Array.isArray(evidence?.actionTrace))

package/dist/services/workflows.js

@@ -93,7 +93,10 @@ export const createWorkflowsService = (tx) => {
                     status: e.status,
                     mode: e.mode,
                     source: e.source,
+                    // The run verdict (pass|fail|error); null in flight AND for a run that
+                    // never attempted a test — then skipReason (backend `skip_reason`) is set.
                     outcome: e.outcome ?? null,
+                    ...(typeof e.skipReason === 'string' && e.skipReason ? { skipReason: e.skipReason } : {}),
                     startedAt: e.startedAt,
                     completedAt: e.completedAt,
                     durationMs: e.durationMs,
@@ -171,7 +174,13 @@ export const createWorkflowsService = (tx) => {
                     finalIntervalMs: intervalMs,
                     timedOut: true,
                 });
-                return { ...lastExecution, timedOut: true };
+                // Carry the facts the deadline path observed, so the reason the user
+                // sees contains real numbers rather than a canned sentence.
+                return {
+                    ...lastExecution,
+                    timedOut: true,
+                    pollTimeout: { elapsedMs: Date.now() - pollStart, pollCount },
+                };
             }
             throw new Error(`Execution ${executionUuid} timed out after ${EXECUTION_TIMEOUT_MS / 1000}s`);
         }

package/dist/utils/authorizedCredentialHosts.js

@@ -4,17 +4,17 @@
  * The MCP ships this field before every backend accepts it (sentinal-oj7dp.23).
  * A backend that does not know the field ignores it and still answers 200, so a
  * create/update "succeeds" whether or not the hosts were saved. The only proof
- * is the response echoing them back — so when it doesn't, say so loudly instead
- * of letting the caller believe cross-domain SSO is now configured.
+ * is the response echoing them back — so when it doesn't, the response carries
+ * the two facts side by side: what was sent, what came back. No prose: the
+ * comparison is the whole message.
  */
 const norm = (hosts) => new Set(hosts.map((h) => h.trim().toLowerCase()));
 /**
- * Compare the requested hosts with the backend's echo. Returns a warning when
- * they differ (as sets, case-insensitively — the backend normalizes), or
- * undefined when the echo confirms them. `op` shapes the advice: a create has
- * already created the environment, so a retry of create would duplicate it.
+ * Compare the requested hosts with the backend's echo. Returns the mismatch
+ * when they differ (as sets, case-insensitively — the backend normalizes), or
+ * undefined when the echo confirms them.
  */
-export function checkAuthorizedCredentialHostsEcho(requested, returned, op) {
+export function checkAuthorizedCredentialHostsEcho(requested, returned) {
     const echoed = Array.isArray(returned) ? returned : null;
     if (echoed) {
         const want = norm(requested);
@@ -22,17 +22,5 @@ export function checkAuthorizedCredentialHostsEcho(requested, returned, op) {
         if (want.size === got.size && [...want].every((h) => got.has(h)))
             return undefined;
     }
-    const hosts = requested.length > 0 ? requested.join(', ') : '(an empty list)';
-    const why = echoed
-        ? `The backend did not persist authorizedCredentialHosts as requested: it holds [${echoed.join(', ')}], not [${requested.join(', ')}].`
-        : 'The backend did not persist authorizedCredentialHosts: it is not yet supported on this DebuggAI server ' +
-            '(the response did not echo the hosts back).';
-    const applied = op === 'create'
-        ? 'The environment itself WAS created, with any credentials listed here — do not re-run create; ' +
-            'set the hosts later with environment {action:"update"}.'
-        : 'Everything else in this update was applied.';
-    const consequence = requested.length > 0
-        ? ` Until the hosts are saved, check_app_in_browser will still refuse to enter credentials on ${hosts} (offscope_host).`
-        : '';
-    return { requested, returned: echoed, message: `${why} ${applied}${consequence}` };
+    return { requested, returned: echoed };
 }

package/dist/utils/confirmDestructive.js

@@ -69,6 +69,5 @@ export async function ensureConfirmed(action, label, input, ctx) {
     }
     if (input.confirm === true)
         return null;
-    return refusal('confirmation_required', `Refusing to ${verb.toLowerCase()} ${label} without confirmation. `
-        + 'Pass confirm:true, or use an elicitation-capable client.');
+    return refusal('confirmation_required', `Refusing to ${verb.toLowerCase()} ${label} without confirm:true.`);
 }

package/dist/utils/errors.js

@@ -18,11 +18,10 @@ export function toMCPError(error, context) {
             stack: error.stack,
             context
         });
-        return new MCPError(MCPErrorCode.INTERNAL_ERROR, error.message, {
-            originalError: error.name,
-            context,
-            stack: error.stack
-        });
+        return new MCPError(MCPErrorCode.INTERNAL_ERROR, error.message, 
+        // The stack is logged above; it is MCP internals, not something the
+        // caller's response should carry.
+        { originalError: error.name, context });
     }
     const errorMessage = String(error);
     logger.error('Converting unknown error to MCP error', { error: errorMessage, context });

package/dist/utils/imageUtils.js

@@ -92,7 +92,6 @@ export function artifactResourceLinks(source) {
         out.push(resourceLinkBlock(value, name, {
             mimeType: MIME_BY_EXT[ext],
             title: titleize(key),
-            description: 'Execution artifact (presigned URL — open or fetch on demand).',
         }));
     }
     return out;

package/dist/utils/resolveProject.js

@@ -19,7 +19,7 @@ export function resolveByName(name, candidates, kind) {
     if (matches.length > 1) {
         return {
             error: 'AmbiguousMatch',
-            message: `Multiple ${kind.toLowerCase().replace('testsuite', 'test suite')}s match "${name}". Pass the uuid directly.`,
+            message: `Multiple ${kind.toLowerCase().replace('testsuite', 'test suite')}s match "${name}".`,
             candidates: matches.map(m => ({ uuid: m.uuid, name: m.name })),
         };
     }

package/dist/utils/urlParser.js

@@ -134,6 +134,39 @@ export function retargetTunnelUrl(tunnelOrigin, requestedUrl) {
         return tunnelOrigin;
     }
 }
+/**
+ * Rewrite every localhost / 127.0.0.1 URL inside FREE TEXT onto the tunnel.
+ *
+ * The goal text is read by a browser running in OUR cloud, not on the user's
+ * machine, so "go to http://localhost:3017" tells it to dial its own loopback.
+ * It gets connection refused and the run is recorded as the app failing, while
+ * the tunnel was working the whole time (15 of 431 judged prod runs in 30 days,
+ * platform-98fv.16).
+ *
+ * Deliberately narrow:
+ *   - only a real origin match (scheme + host + optional port) is touched, so
+ *     a word like "localhostname" survives;
+ *   - path, query and fragment are preserved, because the goal usually depends
+ *     on them;
+ *   - with no tunnel URL, the text is returned UNCHANGED. Inventing a
+ *     destination would be worse than leaving a wrong one visible.
+ */
+export function rewriteLocalhostInText(text, tunnelUrl) {
+    if (!text || !tunnelUrl)
+        return text;
+    let origin;
+    try {
+        const u = new URL(tunnelUrl);
+        origin = `${u.protocol}//${u.host}`;
+    }
+    catch {
+        return text;
+    }
+    // scheme://(localhost|127.0.0.1)[:port] — the trailing boundary stops
+    // "localhostname" matching, while still allowing a path/query/fragment.
+    const LOCAL_ORIGIN = /\bhttps?:\/\/(?:localhost|127\.0\.0\.1)(?::\d+)?(?=[/?#\s]|$)/gi;
+    return text.replace(LOCAL_ORIGIN, origin);
+}
 /**
  * Generate a tunneled URL for a localhost URL
  */

package/package.json

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