@debugg-ai/debugg-ai-mcp 4.0.0 → 4.2.0

package/README.md

@@ -75,7 +75,8 @@ 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`) |
 
@@ -89,7 +90,20 @@ 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"
+
+Runs don't log in every time. After a verified login the backend captures that account's session and **restores** it on the next run for the same identity, which skips the login entirely — that's why a check can legitimately come back with `submitted: false` and no login form: it was already signed in. A restored run reports itself in `logins` with `reason: "restored_session"`, so you can tell it apart from a run that genuinely found no form.
+
+Sessions are keyed per **account**, so naming a different account never reuses somebody else's. Two ways to bypass reuse:
+
+- `freshSession: true` on a single call — log in for real this once, then re-capture. Use it when the login flow *is* what you're checking, when you suspect the stored session is stale, or when the app's only route between personas is a logout.
+- `environment` tool, `action: "clearSessions"` — invalidate the stored sessions so subsequent runs log in. Narrow with `username` / `credentialId`; unscoped clears require confirmation because every account on the environment then re-authenticates.
+
+Use `action: "sessions"` to see what an environment is currently holding and whether each would be reused.
 
 Results report the identity actually used, so a wrong one is visible rather than masquerading as a broken app:
 
@@ -165,9 +179,13 @@ Team and repo resolve by **either** uuid **or** name (case-insensitive exact mat
 | `create` | `{name, url, description?, projectUuid?, credentials?}` | Created env (optionally seeds credentials) |
 | `update` | `{uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?}` | 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` |
+| `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.
 
+`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.
+
 ### `test_suite`
 
 | Action | Params | Result |

package/dist/handlers/environmentHandler.js

@@ -3,6 +3,7 @@ import { searchEnvironmentsHandler } from './searchEnvironmentsHandler.js';
 import { createEnvironmentHandler } from './createEnvironmentHandler.js';
 import { updateEnvironmentHandler } from './updateEnvironmentHandler.js';
 import { deleteEnvironmentHandler } from './deleteEnvironmentHandler.js';
+import { clearEnvironmentSessionsHandler, listEnvironmentSessionsHandler, } from './environmentSessionsHandler.js';
 export async function environmentHandler(input, ctx) {
     switch (input.action) {
         case 'get':
@@ -23,5 +24,19 @@ export async function environmentHandler(input, ctx) {
                 return refusal;
             return deleteEnvironmentHandler({ uuid: input.uuid, projectUuid: input.projectUuid }, ctx);
         }
+        case 'sessions':
+            return listEnvironmentSessionsHandler(input, ctx);
+        case 'clearSessions': {
+            // Confirmed like a delete when it is UNSCOPED. Clearing one account's
+            // session costs that account one login; clearing an environment's costs
+            // every account on it one, which is a different size of action and should
+            // not happen because a filter was mistyped.
+            if (!input.username && !input.credentialId) {
+                const refusal = await ensureConfirmed('clearSessions', `environment ${input.uuid}`, input, ctx);
+                if (refusal)
+                    return refusal;
+            }
+            return clearEnvironmentSessionsHandler(input, ctx);
+        }
     }
 }

package/dist/handlers/environmentSessionsHandler.js

@@ -0,0 +1,60 @@
+import { Logger } from '../utils/logger.js';
+import { handleExternalServiceError } from '../utils/errors.js';
+import { DebuggAIServerClient } from '../services/index.js';
+import { config } from '../config/index.js';
+const logger = new Logger({ module: 'environmentSessionsHandler' });
+function ok(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+export async function listEnvironmentSessionsHandler(input, _context) {
+    logger.toolStart('environment.sessions', { uuid: input.uuid, username: input.username });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        const sessions = await client.listEnvironmentSessions(input.uuid, {
+            ...(input.username ? { username: input.username } : {}),
+            ...(input.credentialId ? { credentialId: input.credentialId } : {}),
+        });
+        // 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.',
+        });
+    }
+    catch (error) {
+        throw handleExternalServiceError(error, 'DebuggAI', 'environment.sessions');
+    }
+}
+export async function clearEnvironmentSessionsHandler(input, _context) {
+    logger.toolStart('environment.clearSessions', { uuid: input.uuid, username: input.username });
+    try {
+        const client = new DebuggAIServerClient(config.api.key);
+        await client.init();
+        const filters = {
+            ...(input.username ? { username: input.username } : {}),
+            ...(input.credentialId ? { credentialId: input.credentialId } : {}),
+        };
+        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.',
+        });
+    }
+    catch (error) {
+        throw handleExternalServiceError(error, 'DebuggAI', 'environment.clearSessions');
+    }
+}

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,24 @@ 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.
+        if (input.freshSession === true) {
+            env.freshSession = true;
+        }
         // --- Execute ---
         // Log the SHAPE of env, never its secrets. It now carries per-account
         // passwords (taskCredentials), and this log line is not run through the

package/dist/services/index.js

@@ -253,6 +253,37 @@ export class DebuggAIServerClient {
             throw new Error('Client not initialized — call init() first');
         await this.tx.delete(`api/v1/projects/${projectUuid}/environments/${envUuid}/`);
     }
+    /**
+     * Captured authenticated sessions held for an environment (sentinal-cs1hn.5).
+     *
+     * The backend keeps a warm session per account and restores it to skip login.
+     * That cache decides WHO a run signs in as, so it needs to be inspectable —
+     * until it was, a run reusing the wrong account's session looked identical to
+     * a run that simply found no login form.
+     *
+     * The flat route, not the nested one: this is company-scoped server-side and
+     * needs no projectUuid, so a caller holding only an environment UUID can ask.
+     * Never returns the session contents — a session cookie is a bearer credential.
+     */
+    async listEnvironmentSessions(envUuid, filters = {}) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const response = await this.tx.get(`api/v1/environments/${envUuid}/sessions/`, filters);
+        return Array.isArray(response) ? response : (response?.results ?? []);
+    }
+    /**
+     * Invalidate captured sessions so the next run logs in for real.
+     *
+     * Narrow with ``username`` / ``credentialId``; omit both to reset the whole
+     * environment. The backend marks rows invalid rather than deleting them, so
+     * reuse stops immediately while the capture history stays readable.
+     */
+    async clearEnvironmentSessions(envUuid, filters = {}) {
+        if (!this.tx)
+            throw new Error('Client not initialized — call init() first');
+        const response = await this.tx.delete(`api/v1/environments/${envUuid}/sessions/`, { params: filters });
+        return { invalidated: response?.invalidated ?? 0 };
+    }
     /**
      * Fetch a single environment by UUID. Throws AxiosError with status 404 if not found.
      */

package/dist/tools/environment.js

@@ -14,7 +14,11 @@ const DESCRIPTION = `Manage environments (and their login credentials) under a p
   - "list"   {projectUuid?, q?, page?, pageSize?} → paginated environments. projectUuid auto-resolves from the git repo if omitted.
   - "create" {name, url, description?, projectUuid?, credentials?} → create an env, optionally seeding credentials.
   - "update" {uuid, name?, url?, description?, addCredentials?, updateCredentials?, removeCredentialIds?} → patch env + manage credentials.
-  - "delete" {uuid, projectUuid?, confirm?} → delete env (DESTRUCTIVE; requires confirmation).`;
+  - "delete" {uuid, projectUuid?, confirm?} → delete env (DESTRUCTIVE; requires confirmation).
+  - "sessions" {uuid, username?, credentialId?} → captured login sessions this env is holding, and whether each would be reused.
+  - "clearSessions" {uuid, username?, credentialId?, confirm?} → invalidate them so the next run logs in for real.
+
+SESSIONS: runs reuse a warm authenticated session per account instead of logging in every time. That is why a check can report "no login form" — it was already signed in. Use "sessions" to see whose session is held, "clearSessions" to drop it, or pass freshSession:true on a single check_app_in_browser call to bypass reuse without clearing anything.`;
 export function buildEnvironmentTool() {
     return {
         name: 'environment',
@@ -24,7 +28,7 @@ export function buildEnvironmentTool() {
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['get', 'list', 'create', 'update', 'delete'], description: 'Operation to perform.' },
+                action: { type: 'string', enum: ['get', 'list', 'create', 'update', 'delete', 'sessions', 'clearSessions'], description: 'Operation to perform.' },
                 uuid: { type: 'string', description: '[get/update/delete] Environment UUID.' },
                 projectUuid: { type: 'string', description: 'Target project (defaults to git auto-detect).' },
                 q: { type: 'string', description: '[list] Free-text search over env name.' },
@@ -37,7 +41,9 @@ export function buildEnvironmentTool() {
                 addCredentials: { type: 'array', items: CRED_ITEM, description: '[update] Add credentials.' },
                 updateCredentials: { type: 'array', items: { type: 'object', properties: { uuid: { type: 'string' }, label: { type: 'string' }, username: { type: 'string' }, password: { type: 'string' }, role: { type: 'string' } }, required: ['uuid'], additionalProperties: false }, description: '[update] Patch credentials by UUID.' },
                 removeCredentialIds: { type: 'array', items: { type: 'string' }, description: '[update] Delete credentials by UUID.' },
-                confirm: { type: 'boolean', description: '[delete] Set true to confirm deletion (when the client cannot prompt).' },
+                username: { type: 'string', description: '[sessions/clearSessions] Narrow to one account. Matched case-insensitively.' },
+                credentialId: { type: 'string', description: '[sessions/clearSessions] Narrow to one stored credential by UUID.' },
+                confirm: { type: 'boolean', description: '[delete/clearSessions] Set true to confirm (when the client cannot prompt). clearSessions only needs it when no username/credentialId narrows it.' },
             },
             required: ['action'],
             // No top-level oneOf/anyOf/allOf: the Anthropic tool input_schema rejects

package/dist/tools/testPageChanges.js

@@ -102,6 +102,10 @@ export function buildTestPageChangesTool(ctx) {
                     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."
                 },
+                freshSession: {
+                    type: "boolean",
+                    description: "Default false. Set true to force a REAL login instead of reusing the warm session the backend keeps per account. Use when the login flow itself is what you're checking, when you suspect the stored session is stale, or when the app's only route between personas is a logout. Costs one login; the run re-captures afterwards, so later runs stay fast."
+                },
                 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."

package/dist/types/index.js

@@ -59,16 +59,30 @@ export const TestPageChangesInputSchema = z.object({
     // 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(),
+    // Force a REAL login instead of reusing a captured session (sentinal-cs1hn.4).
+    // The backend keeps a warm authenticated session per account and restores it to
+    // skip login; that is right for speed and wrong when the login itself is what
+    // you are checking, or when the app's only route between personas is a logout.
+    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(),
@@ -307,6 +321,12 @@ export const EnvironmentInputSchema = z.discriminatedUnion('action', [
     z.object({ action: z.literal('create'), name: z.string().min(1), url: z.string().url('url is required for standard environments'), description: z.string().optional(), projectUuid: z.string().uuid().optional(), credentials: z.array(CredentialSeedSchema).optional() }).strict(),
     z.object({ action: z.literal('update'), uuid: z.string().uuid(), name: z.string().min(1).optional(), url: z.string().url().optional(), description: z.string().optional(), projectUuid: z.string().uuid().optional(), addCredentials: z.array(CredentialSeedSchema).optional(), updateCredentials: z.array(CredentialUpdateSchema).optional(), removeCredentialIds: z.array(z.string().uuid()).optional() }).strict(),
     z.object({ action: z.literal('delete'), uuid: z.string().uuid(), projectUuid: z.string().uuid().optional(), confirm: z.boolean().optional() }).strict(),
+    // Captured authenticated sessions (sentinal-cs1hn.5). The backend holds a warm
+    // session per account and restores it to skip login; these two actions make that
+    // cache visible and clearable instead of a thing that silently decides who a run
+    // signs in as.
+    z.object({ action: z.literal('sessions'), uuid: z.string().uuid(), projectUuid: z.string().uuid().optional(), username: z.string().min(1).optional(), credentialId: z.string().uuid().optional() }).strict(),
+    z.object({ action: z.literal('clearSessions'), uuid: z.string().uuid(), projectUuid: z.string().uuid().optional(), username: z.string().min(1).optional(), credentialId: z.string().uuid().optional(), confirm: z.boolean().optional() }).strict(),
 ]);
 export const TestSuiteInputSchema = z.discriminatedUnion('action', [
     z.object({ action: z.literal('list'), ...projectIdentifier, search: z.string().optional(), page: _page, pageSize: z.number().int().min(1).max(100).optional() }).strict(),

package/dist/utils/confirmDestructive.js

@@ -10,11 +10,33 @@
  * epic — that epic only has to populate `ctx.elicit`; the confirm-arg path here
  * ships standalone.
  */
-/** Action names treated as destructive. Currently just `delete`. */
-export const DESTRUCTIVE_ACTIONS = new Set(['delete']);
+/**
+ * Action names treated as destructive.
+ *
+ * `clearSessions` is here for BLAST RADIUS, not permanence: invalidating captured
+ * sessions is recoverable (the next run logs in and re-captures), but an unscoped
+ * clear makes EVERY account on an environment re-authenticate, and that should not
+ * happen because a `username` filter was mistyped. The caller-side guard only asks
+ * when the call is unscoped — see environmentHandler.
+ */
+export const DESTRUCTIVE_ACTIONS = new Set(['delete', 'clearSessions']);
 export function isDestructiveAction(action) {
     return DESTRUCTIVE_ACTIONS.has(action);
 }
+/**
+ * How each destructive action is described when we ask. `delete` keeps its exact
+ * pre-existing wording so its behaviour (and tests) are untouched.
+ */
+const PROMPTS = {
+    delete: { verb: 'Delete', noun: 'Deletion', consequence: 'This cannot be undone.' },
+    clearSessions: {
+        verb: 'Clear all captured login sessions for',
+        noun: 'Clearing sessions',
+        // Deliberately NOT "cannot be undone" — that would be false, and a guard that
+        // overstates the stakes trains people to click through it.
+        consequence: 'Every account on it will have to log in again on its next run.',
+    },
+};
 function refusal(error, message) {
     return {
         content: [{ type: 'text', text: JSON.stringify({ error, message }, null, 2) }],
@@ -29,20 +51,24 @@ function refusal(error, message) {
 export async function ensureConfirmed(action, label, input, ctx) {
     if (!isDestructiveAction(action))
         return null;
+    const { verb, noun, consequence } = PROMPTS[action] ?? PROMPTS.delete;
     if (ctx.elicit) {
         const res = await ctx.elicit({
-            message: `Delete ${label}? This cannot be undone.`,
+            message: `${verb} ${label}? ${consequence}`,
             requestedSchema: {
                 type: 'object',
-                properties: { confirm: { type: 'boolean', description: 'Confirm deletion of ' + label } },
+                properties: {
+                    confirm: { type: 'boolean', description: `Confirm: ${verb.toLowerCase()} ${label}` },
+                },
                 required: ['confirm'],
             },
         });
         if (res.action === 'accept' && res.content?.confirm === true)
             return null;
-        return refusal('confirmation_declined', `Deletion of ${label} was not confirmed.`);
+        return refusal('confirmation_declined', `${noun} of ${label} was not confirmed.`);
     }
     if (input.confirm === true)
         return null;
-    return refusal('confirmation_required', `Refusing to delete ${label} without confirmation. Pass confirm:true, or use an elicitation-capable client.`);
+    return refusal('confirmation_required', `Refusing to ${verb.toLowerCase()} ${label} without confirmation. `
+        + 'Pass confirm:true, or use an elicitation-capable client.');
 }

package/package.json

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