@debugg-ai/debugg-ai-mcp 3.7.4 → 3.9.0

package/README.md

@@ -51,10 +51,38 @@ Runs an AI browser agent against your app. The agent navigates, interacts, and r
 | `credentialRole` | string | Pick a credential by role (e.g. `admin`, `guest`) |
 | `username` | string | Username for login (ephemeral — not persisted) |
 | `password` | string | Password for login (ephemeral — not persisted) |
+| `loginCredentials` | array | Accounts for logins the agent hits **during** the task — `[{username, password, label?}]` |
+| `useEnvironmentCredentials` | boolean | Default `true`. `false` forbids auto-filling the environment's stored credentials |
+| `auth` | object | Auth precondition — `{precondition, entryUrl, deepUrl, environmentId, username, password}` |
 | `repoName` | string | Override auto-detected git repo name (e.g. `my-org/my-repo`) |
 
 One focused check per call. The agent has a ~25-step internal budget; split broader suites across multiple calls.
 
+##### Credentials: pass them as parameters, not prose
+
+Naming an account only in `description` does **not** make the agent use it — it falls back to the environment's stored credential, and the app's rejection of the wrong account comes back looking like an application failure. Anything you pass as a parameter beats the environment default for **every** login in the run, not just the first:
+
+- `username` / `password` (or `credentialId` / `credentialRole`) — the run's identity.
+- `auth.username` / `auth.password` — pins the precondition login when you also use `auth.precondition: "login"`.
+- `loginCredentials` — accounts for a login form the agent reaches **part-way through** the task. This is the one for flows like *set a password → get bounced to sign-in → log in as the account you just created*, where splitting into separate calls would lose browser state.
+
+Set `useEnvironmentCredentials: false` when a silent fallback to the default test user would invalidate the check. The call is rejected if you opt out without naming an account, since the run would have no way to authenticate.
+
+Results report the identity actually used, so a wrong one is visible rather than masquerading as a broken app:
+
+```json
+"logins": [
+  { "username": "qa+invitefix@example.com", "source": "task", "submitted": true, "authenticated": true }
+],
+"credentialWarning": {
+  "requested": "qa+invitefix@example.com",
+  "used": ["qatest123@example.com"],
+  "message": "This run signed in with an environment default credential even though '…' was specified. …"
+}
+```
+
+`source` is `task` | `explicit` | `credential_id` (an account you named) or `env` | `env_default` (the environment's stored account). `credentialWarning` appears only when you named an account and an environment default was used anyway. `loginError` appears when a named account could not be resolved and the run declined to substitute a different one.
+
 Every successful run returns a `browserSession` block alongside the screenshot — presigned S3 URLs for the captured **HAR** (full network trace) and **console log** (every JS console message). Use them to detect refetch loops, hydration errors, and other runtime issues that pass type-checks and unit tests:
 
 ```json

package/dist/handlers/testPageChangesHandler.js

@@ -9,7 +9,7 @@ import { handleExternalServiceError } from '../utils/errors.js';
 import { fetchImageAsBase64, imageContentBlock, resourceLinkBlock, artifactResourceLinks } from '../utils/imageUtils.js';
 import { DebuggAIServerClient } from '../services/index.js';
 import { getEvalTemplateSlug } from '../services/workflows.js';
-import { adaptVerdict } from '../services/verdictAdapter.js';
+import { adaptVerdict, isEnvironmentDefault } from '../services/verdictAdapter.js';
 import { TunnelProvisionError } from '../services/tunnels.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { detectRepoName } from '../utils/gitContext.js';
@@ -55,6 +55,27 @@ function findNgrokErrorMarker(parts) {
     }
     return undefined;
 }
+// Credentials ride in `env` and `contextData.auth` on the way out. Log which
+// accounts a run was given — that is the diagnostic that matters when a run
+// signs in as the wrong user — but never their passwords.
+function redactEnv(env) {
+    const out = { ...env };
+    if (out.password)
+        out.password = '[REDACTED]';
+    if (Array.isArray(out.taskCredentials)) {
+        out.taskCredentials = out.taskCredentials.map((c) => ({
+            username: c.username,
+            ...(c.label ? { label: c.label } : {}),
+            password: '[REDACTED]',
+        }));
+    }
+    return out;
+}
+function redactAuth(auth) {
+    if (!auth)
+        return undefined;
+    return auth.password ? { ...auth, password: '[REDACTED]' } : auth;
+}
 // Concurrency control — max 2 simultaneous browser checks.
 // Additional requests queue and run when a slot opens.
 const MAX_CONCURRENT = 2;
@@ -344,6 +365,13 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
                 auth.entryUrl = input.auth.entryUrl;
             if (input.auth.deepUrl)
                 auth.deepUrl = input.auth.deepUrl;
+            // WHICH account the precondition logs in as. Absent → the environment's
+            // default credential (the pre-existing behaviour, correct for a caller
+            // that named nobody).
+            if (input.auth.username)
+                auth.username = input.auth.username;
+            if (input.auth.password)
+                auth.password = input.auth.password;
             if (Object.keys(auth).length > 0)
                 contextData.auth = auth;
         }
@@ -359,8 +387,29 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             env.username = input.username;
         if (input.password)
             env.password = input.password;
+        // Accounts for logins the agent hits mid-task. The backend keys these by
+        // username so the agent can sign in as the one the task names, instead of
+        // its only login affordance filling the environment's stored account.
+        if (input.loginCredentials && input.loginCredentials.length > 0) {
+            env.taskCredentials = input.loginCredentials.map(c => ({
+                username: c.username,
+                password: c.password,
+                ...(c.label ? { label: c.label } : {}),
+            }));
+        }
+        // Only send the opt-out when it's actually an opt-out — omitting it keeps
+        // the default (environment credentials remain available as a fallback).
+        if (input.useEnvironmentCredentials === false) {
+            env.useEnvironmentCredentials = false;
+        }
         // --- Execute ---
-        logger.info('Sending contextData', { contextData, env: Object.keys(env).length > 0 ? env : undefined });
+        // Log the SHAPE of env, never its secrets. It now carries per-account
+        // passwords (taskCredentials), and this log line is not run through the
+        // logger's shallow top-level redaction.
+        logger.info('Sending contextData', {
+            contextData: { ...contextData, auth: redactAuth(contextData.auth) },
+            env: Object.keys(env).length > 0 ? redactEnv(env) : undefined,
+        });
         if (progressCallback) {
             await progressCallback({ progress: 3, total: TOTAL_STEPS, message: 'Queuing workflow execution...' });
         }
@@ -656,6 +705,32 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
             responsePayload.failureCategory = verdict.failureCategory;
         if (verdict.reason)
             responsePayload.reason = verdict.reason;
+        // --- Which identity did the run actually sign in as? ---
+        // A login as the wrong account and an app rejecting the right one produce
+        // the SAME symptom ("login failed") and used to be indistinguishable from
+        // the result, so an environment-default substitution read as an application
+        // bug. Relay the logins verbatim, and when the caller named an account but
+        // an environment default was used anyway, say so explicitly rather than
+        // leaving the caller to infer it from a failed check.
+        if (verdict.logins)
+            responsePayload.logins = verdict.logins;
+        if (verdict.loginError)
+            responsePayload.loginError = verdict.loginError;
+        const requestedIdentity = input.username
+            ?? input.auth?.username
+            ?? input.loginCredentials?.[0]?.username;
+        const substituted = (verdict.logins ?? []).filter(isEnvironmentDefault);
+        if (requestedIdentity && substituted.length > 0) {
+            responsePayload.credentialWarning = {
+                requested: requestedIdentity,
+                used: substituted.map(l => l.username).filter(Boolean),
+                message: `This run signed in with an environment default credential even though ` +
+                    `'${requestedIdentity}' was specified. Treat a login failure here as a ` +
+                    `credential-resolution problem, not an application failure.`,
+            };
+            logger.warn(`check_app_in_browser: requested identity '${requestedIdentity}' but the run used ` +
+                `environment-default credential(s): ${substituted.map(l => l.username).join(', ')}`);
+        }
         // Bug z15n: OUR tunnel died mid-run, so this 'fail' describes our error page,
         // not the user's app. Relay it as a distinct, retryable infrastructure class
         // so an automated caller doesn't record a UI regression that never happened.

package/dist/handlers/triggerCrawlHandler.js

@@ -20,6 +20,7 @@ import { probeLocalPort, probeTunnelHealth } from '../utils/localReachability.js
 import { extractLocalhostPort } from '../utils/urlParser.js';
 import { resolveTargetUrl, buildContext, findExistingTunnel, ensureTunnel, sanitizeResponseUrls, touchTunnelById, } from '../utils/tunnelContext.js';
 import { getCachedTemplateUuid, invalidateTemplateCache } from '../utils/handlerCaches.js';
+import { detectLocalGitRef } from '../utils/gitContext.js';
 import { getCrawlTemplateSlug } from '../services/workflows.js';
 import { isTransientWorkflowError, transientReasonTag } from '../utils/transientErrors.js';
 import { Telemetry, TelemetryEvents } from '../utils/telemetry.js';
@@ -179,6 +180,18 @@ export async function triggerCrawlHandler(input, context, rawProgressCallback) {
         contextData.headless = true; // D7: the MCP always runs headless — no opt-out.
         if (typeof input.timeoutSeconds === 'number')
             contextData.timeoutSeconds = input.timeoutSeconds;
+        // sentinal-lwtaw.13 (MCP side): the TRIGGER POINT owns the git fact. Attach
+        // the LOCAL checkout's branch + commit so the backend mints a git-backed
+        // Atlas version for this crawl — SAME snake_case contextData keys the
+        // PR-webhook path reads (commit_sha, branch). Best-effort + non-fatal:
+        // detectLocalGitRef never throws and a non-git target attaches nothing
+        // (honest no-git) and still crawls. Keys are set ONLY when present so we
+        // never fabricate a ref.
+        const gitRef = await detectLocalGitRef();
+        if (gitRef.commitSha)
+            contextData.commit_sha = gitRef.commitSha;
+        if (gitRef.branch)
+            contextData.branch = gitRef.branch;
         const env = {};
         if (input.environmentId)
             env.environmentId = input.environmentId;

package/dist/services/verdictAdapter.js

@@ -25,6 +25,12 @@
 /** 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);
+/** Credential sources that mean "the caller named this account for this run". */
+const CALLER_SPECIFIED_SOURCES = new Set(['task', 'explicit', 'credential_id']);
+/** True when this login used an environment default rather than a named account. */
+export function isEnvironmentDefault(login) {
+    return !!login.source && !CALLER_SPECIFIED_SOURCES.has(login.source);
+}
 /**
  * Map a workflow execution onto the MCP relay verdict. Never throws.
  */
@@ -69,5 +75,10 @@ export function adaptVerdict(execution, opts = {}) {
         relay.screenshot = evidence.screenshot;
     if (Array.isArray(evidence?.actionTrace))
         relay.actionTrace = evidence.actionTrace;
+    if (Array.isArray(evidence?.logins) && evidence.logins.length > 0)
+        relay.logins = evidence.logins;
+    if (evidence?.loginError && typeof evidence.loginError === 'object') {
+        relay.loginError = evidence.loginError;
+    }
     return relay;
 }

package/dist/tools/testPageChanges.js

@@ -10,7 +10,9 @@ const BASE_DESCRIPTION = `Give an AI agent eyes on a live website or app. The ag
 
 LOCALHOST SUPPORT: Pass any localhost URL (e.g. http://localhost:3000) and it Just Works. A secure tunnel is automatically created so the remote browser can reach your local dev server — no manual ngrok setup, no port forwarding, no config.
 
-SCOPE PER CALL: Keep each call to ONE focused check — a single page or a short interaction on a single screen (login, submit a form, verify a heading). For anything spanning multiple pages or long multi-step flows, split into SEPARATE calls — the remote browser agent has a ~25-step internal budget per call, and long single calls risk client-side timeouts. Example: instead of "log in, then go to settings, then update profile, then verify," make three calls: (1) log in & verify dashboard, (2) update settings, (3) verify profile change.`;
+SCOPE PER CALL: Keep each call to ONE focused check — a single page or a short interaction on a single screen (login, submit a form, verify a heading). For anything spanning multiple pages or long multi-step flows, split into SEPARATE calls — the remote browser agent has a ~25-step internal budget per call, and long single calls risk client-side timeouts. Example: instead of "log in, then go to settings, then update profile, then verify," make three calls: (1) log in & verify dashboard, (2) update settings, (3) verify profile change.
+
+CREDENTIALS: pass them as PARAMETERS, not only in the description. Naming an account in \`description\` alone does not make the agent use it — it falls back to the environment's stored credential. Use \`username\`/\`password\` (or \`credentialId\`) for the run's identity, \`auth.username\`/\`auth.password\` to pin the precondition login, and \`loginCredentials\` for accounts the agent must use at a login form it hits PART-WAY through the task (e.g. set a password → bounced to sign-in → log in as the account you just created). Anything you specify beats the environment's default for every login in the run; the result reports the identity actually used under \`logins\`.`;
 /**
  * Build the dynamic tool description including available environments/credentials.
  */
@@ -76,24 +78,50 @@ export function buildTestPageChangesTool(ctx) {
                 },
                 username: {
                     type: "string",
-                    description: "A real, existing account email for the target app. Do NOT invent or guess credentials — use one from the available credentials listed above, or ask the user. The browser agent will type this into the login form."
+                    description: "A real, existing account email for the target app. Do NOT invent or guess credentials — use one from the available credentials listed above, or ask the user. The browser agent will type this into the login form. Takes precedence over the environment's default credential for EVERY login in the run."
                 },
                 password: {
                     type: "string",
                     description: "The real password for the username above. Do NOT guess or use placeholder passwords — use credentials from the list above or ask the user."
                 },
+                loginCredentials: {
+                    type: "array",
+                    description: "Accounts the agent may sign in as when it hits a login form DURING the task — not just the first login. Use this for flows that authenticate part-way through, e.g. set a password, get bounced to sign-in, then log in as the account you just provisioned. Stating credentials only in `description` is not enough: pass them here and the agent uses exactly these values. Overrides the environment's default credential.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            username: { type: "string", description: "Account email/username to type into the login form." },
+                            password: { type: "string", description: "That account's password." },
+                            label: { type: "string", description: "Optional human label (e.g. 'newly invited user') to disambiguate in the task text." }
+                        },
+                        required: ["username", "password"],
+                        additionalProperties: false
+                    }
+                },
+                useEnvironmentCredentials: {
+                    type: "boolean",
+                    description: "Default true. Set false to forbid the agent from ever auto-filling the environment's stored credentials — it signs in only as an account this call named (username/password, credentialId, credentialRole, loginCredentials, or auth.username), or not at all. Use when a run must prove a SPECIFIC account's experience and a silent fallback to the default test user would invalidate it."
+                },
                 repoName: {
                     type: "string",
                     description: "GitHub repository name (e.g. 'my-org/my-repo'). Auto-detected from the current git repo — only provide this if you want to run against a different project than the one you're in."
                 },
                 auth: {
                     type: "object",
-                    description: "Optional auth-precondition for a 'log in THEN deep-navigate' check. Set precondition:'login' to authenticate first (using the environment's credentials), then land on deepUrl. Use this instead of hoping the agent signs itself in at a login wall.",
+                    description: "Optional auth-precondition for a 'log in THEN deep-navigate' check. Set precondition:'login' to authenticate first, then land on deepUrl. Use this instead of hoping the agent signs itself in at a login wall. Pass username/password here to pin WHICH account it authenticates as; omit them to use the environment's default credential.",
                     properties: {
                         environmentId: {
                             type: "string",
                             description: "UUID of the environment whose credentials to log in with. See available environments in the tool description above."
                         },
+                        username: {
+                            type: "string",
+                            description: "Account to authenticate as for the precondition login. Overrides the environment's default credential."
+                        },
+                        password: {
+                            type: "string",
+                            description: "Password for auth.username."
+                        },
                         precondition: {
                             type: "string",
                             enum: ["login", "none"],

package/dist/types/index.js

@@ -18,6 +18,28 @@ export const AuthPreconditionSchema = z.object({
     precondition: z.enum(['login', 'none']).optional(),
     entryUrl: z.preprocess(normalizeUrl, z.string().url('entryUrl must be a valid URL (the login page to authenticate on).').optional()),
     deepUrl: z.preprocess(normalizeUrl, z.string().url('deepUrl must be a valid URL (the page to evaluate AFTER login).').optional()),
+    // WHICH account to authenticate as. Without these the environment's default
+    // credential is used — which is correct for a caller that named nobody, and
+    // wrong for one that did. Naming the account here makes it authoritative for
+    // the precondition login.
+    username: z.string().optional(),
+    password: z.string().optional(),
+}).strict();
+/**
+ * A single account the browser agent may sign in as DURING the task.
+ *
+ * The auth precondition covers the FIRST login. This covers every login after
+ * it: a flow that sets a password, gets bounced to a sign-in page, and must
+ * authenticate as the account it just provisioned. Without an explicit channel
+ * for those, the agent's only login affordance filled the environment's stored
+ * account, so "then sign in as <the new user>" was unachievable however the
+ * task was worded — and the app's correct rejection of the wrong account came
+ * back as an application failure.
+ */
+export const LoginCredentialSchema = z.object({
+    username: z.string().min(1, 'username is required for a login credential'),
+    password: z.string().min(1, 'password is required for a login credential'),
+    label: z.string().optional(),
 }).strict();
 /**
  * Tool input validation schemas
@@ -32,8 +54,20 @@ export const TestPageChangesInputSchema = z.object({
     username: z.string().optional(),
     password: z.string().optional(),
     repoName: z.string().optional(),
+    // Accounts for logins the agent hits DURING the task, not just the first one.
+    loginCredentials: z.array(LoginCredentialSchema).max(10, 'loginCredentials accepts at most 10 accounts per run.').optional(),
+    // Opt out of the environment's stored credentials entirely: the agent signs
+    // in only as an account this call named, or not at all.
+    useEnvironmentCredentials: z.boolean().optional(),
     // Auth-precondition deep-link intent (bead 56kd.6) — "log in THEN go to X".
     auth: AuthPreconditionSchema.optional(),
+}).refine((v) => !(v.useEnvironmentCredentials === false
+    && !v.username && !v.credentialId && !v.credentialRole
+    && !(v.loginCredentials && v.loginCredentials.length > 0)
+    && !v.auth?.username), {
+    message: 'useEnvironmentCredentials:false leaves the run with no way to authenticate. '
+        + 'Pass username/password, credentialId, credentialRole, or loginCredentials alongside it.',
+    path: ['useEnvironmentCredentials'],
 });
 export const TriggerCrawlInputSchema = z.object({
     url: z.preprocess(normalizeUrl, z.string().url('Invalid URL. Pass a full URL like "http://localhost:3000" or "https://example.com". Localhost URLs are auto-tunneled to the remote browser.')),

package/dist/utils/gitContext.js

@@ -3,6 +3,9 @@
  * Parses the origin remote URL into "owner/repo" format.
  */
 import { execSync } from 'child_process';
+import { ProjectAnalyzer } from './projectAnalyzer.js';
+import { Logger } from './logger.js';
+const logger = new Logger({ module: 'gitContext' });
 let cached; // undefined = not yet checked
 /**
  * Detect the repo name (e.g. "debugg-ai/debugg-ai-frontend") from git remote origin.
@@ -25,6 +28,29 @@ export function detectRepoName() {
     }
     return cached;
 }
+/**
+ * Detect the LOCAL git ref (branch + commit sha) from the current working
+ * directory — the repo whose dev server the caller is crawling.
+ *
+ * sentinal-lwtaw.13 (MCP side): the TRIGGER POINT owns the git fact. The
+ * environment says WHERE to crawl; the caller supplies the ref it's running so
+ * the backend can mint a git-backed Atlas version. Delegates to
+ * ProjectAnalyzer's existing `.git/HEAD` readers — no new git parsing.
+ *
+ * Best-effort by contract: returns `{}` when cwd isn't a git repo (or the read
+ * fails). NEVER throws and NEVER fabricates a branch/sha — a git-less target
+ * must still crawl (honest no-git). NOT cached (unlike detectRepoName): the
+ * branch/commit change under a long-lived MCP process, so each crawl re-reads.
+ */
+export async function detectLocalGitRef() {
+    try {
+        return await new ProjectAnalyzer().getGitRef(process.cwd());
+    }
+    catch (err) {
+        logger.debug('Could not determine local git ref', err);
+        return {};
+    }
+}
 /**
  * Parse an origin URL into "owner/repo" format.
  * Handles SSH (git@github.com:owner/repo.git) and HTTPS (https://github.com/owner/repo.git).

package/dist/utils/projectAnalyzer.js

@@ -438,6 +438,29 @@ export class ProjectAnalyzer {
     extractRepoName(projectPath) {
         return projectPath.split('/').pop() || 'unknown';
     }
+    /**
+     * Best-effort local git ref (branch + full commit sha) for a project dir.
+     *
+     * Reuses the existing `.git/HEAD` readers (getCurrentBranch /
+     * getCurrentCommitHash) — no new git parsing. NEVER throws and NEVER
+     * fabricates: a non-git dir (or any read failure) yields `{}` so a git-less
+     * crawl target still crawls (honest no-git). Not cached — a long-lived MCP
+     * process must re-read after the caller checks out a branch or commits.
+     */
+    async getGitRef(repoPath) {
+        const projectPath = repoPath || process.cwd();
+        try {
+            const [branch, commitSha] = await Promise.all([
+                this.getCurrentBranch(projectPath),
+                this.getCurrentCommitHash(projectPath),
+            ]);
+            return { branch, commitSha };
+        }
+        catch (error) {
+            logger.debug('Could not determine local git ref', error);
+            return {};
+        }
+    }
     /**
      * Get current git branch (simplified)
      */

package/package.json

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