@debugg-ai/debugg-ai-mcp 4.1.0 → 4.2.1

package/README.md

@@ -75,7 +75,7 @@ Runs an AI browser agent against your app. The agent navigates, interacts, and r
 | `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 |
+| `useEnvironmentCredentials` | boolean | Default `true`. `false` forbids auto-filling the environment's stored credentials; with no account named it means **do not log in at all** |
 | `freshSession` | boolean | Default `false`. `true` forces a real login instead of reusing the warm session held for that account |
 | `auth` | object | Auth precondition — `{precondition, entryUrl, deepUrl, environmentId, username, password}` |
 | `repoName` | string | Override auto-detected git repo name (e.g. `my-org/my-repo`) |
@@ -90,7 +90,9 @@ Naming an account only in `description` does **not** make the agent use it — i
 - `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.
+Set `useEnvironmentCredentials: false` when a silent fallback to the default test user would invalidate the check.
+
+**Checking a page that needs no login at all?** Pass `useEnvironmentCredentials: false` and name no account. That combination means exactly what it says — *do not log in* — and the run skips authentication entirely instead of hunting for a login form. Use it for public pages, marketing sites, docs, and anything pre-auth. It is also faster: on the default (`auto`) the agent will follow a "Log in" link off your page and try the environment's stored account before it evaluates anything.
 
 ##### Session reuse: why a check can report "no login form"
 
@@ -140,13 +142,13 @@ Fires a server-side browser-agent crawl to populate the project's knowledge grap
 
 #### `probe_page`
 
-**Lightweight no-LLM batch page probe.** Pass 1-20 URLs; each navigates, waits for load, and returns rendered state — screenshot + page metadata + structured console errors + network summary. No agent loop, no LLM cost, no scenario assertions. Use it for "did I just break /settings?", multi-route smoke after a refactor, CI per-PR sweeps, and quick is-it-up checks where `check_app_in_browser`'s 60-150s agent loop is overkill.
+**Lightweight no-LLM batch page probe.** Pass 1-20 URLs; each navigates, settles on content (the DOM going quiet, bounded — never on network silence, which a live app never reaches), and returns rendered state — screenshot + page metadata + structured console errors + network summary. No agent loop, no LLM cost, no scenario assertions. Use it for "did I just break /settings?", multi-route smoke after a refactor, CI per-PR sweeps, and quick is-it-up checks where `check_app_in_browser`'s 60-150s agent loop is overkill.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `targets` | array **required** | 1-20 entries: `[{url, waitForSelector?, waitForLoadState?, timeoutMs?}]` |
 | `targets[].url` | string **required** | Public URL or localhost (auto-tunneled) |
-| `targets[].waitForLoadState` | enum | `'load'` (default) / `'domcontentloaded'` / `'networkidle'` |
+| `targets[].waitForLoadState` | enum | `'domcontentloaded'` (default, + a bounded content settle) / `'load'` (also blocks on third-party embeds) / `'networkidle'` (accepted, never issued — a live site's network does not go idle) |
 | `targets[].waitForSelector` | string | Optional CSS selector to wait for after navigation |
 | `targets[].timeoutMs` | number | Per-URL timeout, 1000-30000 (default 10000) |
 | `includeHtml` | boolean | Return raw HTML in each result (default false) |

package/dist/handlers/testPageChangesHandler.js

@@ -3,6 +3,7 @@
  * Executes the App Evaluation Workflow via the 4-step pattern:
  *   find template → execute → poll → result
  */
+import { meansDoNotLogIn, } from '../types/index.js';
 import { config } from '../config/index.js';
 import { Logger } from '../utils/logger.js';
 import { handleExternalServiceError } from '../utils/errors.js';
@@ -419,6 +420,18 @@ async function testPageChangesHandlerInner(input, context, rawProgressCallback)
         if (input.useEnvironmentCredentials === false) {
             env.useEnvironmentCredentials = false;
         }
+        // sentinal-oj7dp.3: opting out of the environment's credentials WITHOUT naming
+        // an account means "do not log in" — say so in the language the backend already
+        // speaks instead of leaving auth_mode on its 'auto' default. On 'auto' the auth
+        // subworkflow hunts for a login on a page that needs none: measured 2026-08-18,
+        // a public-homepage check spent 38 of its 111 seconds following the site's login
+        // link to a sibling host, submitting the environment's default credential three
+        // times, and parking the browser on a login screen the run was then graded
+        // against (execution 2c787273). no_auth short-circuits that cleanly and marks
+        // the run auth.skipped, which is explicitly NOT an auth failure (sentinal-76f8y.12).
+        if (meansDoNotLogIn(input)) {
+            contextData.auth_mode = 'no_auth';
+        }
         // Same rule for the session opt-out: send it only when it IS one, so the
         // default (reuse a warm session when one exists for this account) is
         // expressed by absence rather than by an explicit false.

package/dist/tools/probePage.js

@@ -22,6 +22,8 @@ LOCALHOST SUPPORT: any localhost URL is auto-tunneled. Pre-flight TCP probe fail
 
 BATCH MODE: pass up to 20 targets in one call to share browser session + tunnel — dramatically faster than firing parallel single-URL probes (one execution unit, not N). Per-URL waitForSelector / waitForLoadState / timeoutMs override defaults.
 
+READINESS: navigation settles on CONTENT (the page's DOM going quiet), bounded — not on network silence, which never arrives on a live app, and not on 'load', which blocks on third-party embeds. The default is right for SPAs; reach for waitForSelector, not waitForLoadState, when you need to wait for something specific.
+
 A single failed target's error appears in result.error without failing the whole batch — the other results stay valid.`;
 const TARGET_PROPERTIES = {
     url: {
@@ -35,11 +37,15 @@ const TARGET_PROPERTIES = {
     waitForLoadState: {
         type: 'string',
         enum: ['load', 'domcontentloaded', 'networkidle'],
-        description: "When to consider the page 'loaded' before capturing. Default 'load'. Use 'networkidle' for SPAs to wait until the bundle finishes rendering.",
+        // sentinal-kvoou. This description used to read "Default 'load'. Use 'networkidle'
+        // for SPAs to wait until the bundle finishes rendering" — advice that hangs on
+        // exactly the class of app it names. See __tests__/tools/probePageWaitContract.ts
+        // for the measurement against https://debugg.ai.
+        description: "When to consider the page ready to capture. Default 'domcontentloaded', followed by a bounded content settle (the page's DOM going quiet) — that is what actually makes a client-rendered SPA safe to screenshot, and it needs no override. Only override for a specific reason: 'load' additionally blocks on every sub-resource, including third-party iframes and images we do not control, so a slow embed can time the whole probe out. 'networkidle' is accepted for compatibility but is never issued — a live site's network does not go idle (analytics, polling, websockets, ads) — and behaves as 'domcontentloaded'. To wait on something specific, use waitForSelector.",
     },
     timeoutMs: {
         type: 'number',
-        description: 'Per-URL navigation timeout in milliseconds (1000-30000, default 10000).',
+        description: "Per-URL budget in milliseconds for navigating AND settling this target (1000-30000, default 10000). The content settle spends what the navigation left over, so this is the whole cost of the target, not just the goto.",
     },
 };
 export function buildProbePageTool() {

package/dist/types/index.js

@@ -66,14 +66,23 @@ export const TestPageChangesInputSchema = z.object({
     freshSession: 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'],
 });
+/**
+ * True when the caller opted out of the environment's credentials AND named no
+ * account of their own — i.e. "do not log in at all".
+ *
+ * This used to be a hard validation error ("leaves the run with no way to
+ * authenticate"), which made the single most common check — "is my PUBLIC page
+ * still up?" — the one thing the tool refused to express. It is not an error; it
+ * is an instruction, and the backend already has the enum for it
+ * (auth_mode: no_auth, sentinal-i7fnc). See sentinal-oj7dp.3.
+ */
+export function meansDoNotLogIn(v) {
+    return v.useEnvironmentCredentials === false
+        && !v.username && !v.credentialId && !v.credentialRole
+        && !(v.loginCredentials && v.loginCredentials.length > 0)
+        && !v.auth?.username;
+}
 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.')),
     projectUuid: z.string().uuid().optional(),
@@ -217,7 +226,15 @@ export var LogLevel;
 export const ProbePageTargetSchema = 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.')),
     waitForSelector: z.string().optional(),
-    waitForLoadState: z.enum(['load', 'domcontentloaded', 'networkidle']).default('load'),
+    // sentinal-kvoou: 'domcontentloaded', NOT 'load'. 'load' blocks on every
+    // sub-resource including third-party iframes we do not control — measured against
+    // https://debugg.ai (two YouTube embeds), the 'load' default timed the goto out at
+    // 10s and reported statusCode 0 on a page that renders in 3.5s. Readiness comes from
+    // the backend's bounded CONTENT settle after the goto, not from a load state.
+    // 'networkidle' stays in the enum (this package is published; removing it would turn
+    // an existing caller's probe into a hard validation error) and is neutralized
+    // server-side — never a wait, always domcontentloaded + settle.
+    waitForLoadState: z.enum(['load', 'domcontentloaded', 'networkidle']).default('domcontentloaded'),
     timeoutMs: z.number().int().min(1000, 'timeoutMs minimum is 1000 (1s)').max(30000, 'timeoutMs maximum is 30000 (30s) — longer probes should use check_app_in_browser').default(10000),
 }).strict();
 export const ProbePageInputSchema = z.object({

package/package.json

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