@thedesignagent/mcp 0.2.5 → 0.3.1

package/README.md

@@ -113,13 +113,27 @@ Screenshots are saved to `~/.thedesignagent/screenshots/` for 24 hours, so you c
 
 ### Pages behind login
 
-Capture a logged-in session once per app:
+When `Visual` lands on a login page it stops before reviewing (nothing is charged) and tells your agent how to save a session. Sessions are stored per site under `~/.thedesignagent/auth/` (readable only by you) and applied to every later screenshot of that site.
+
+There are two ways to save one:
+
+**A login recipe (automatic).** A small script in your repo, `.thedesignagent-login.mjs`, prints either a URL that logs in when opened (a magic link, a dev-only login route) or cookies as JSON. Pipe it into `login`:
+
+```
+node .thedesignagent-login.mjs | npx -y --package=@thedesignagent/mcp thedesignagent-auth login http://localhost:3000/dashboard
+```
+
+It logs in headlessly, checks the page no longer redirects to login, and saves. The Claude Code plugin's `/tda:setup` writes a recipe for Supabase apps.
+
+**Capture by hand.** Opens a browser window; log in and it saves and closes by itself once you leave the login page:
 
 ```
-npx -y --package=@thedesignagent/mcp thedesignagent-auth capture http://localhost:3000
+npx -y --package=@thedesignagent/mcp thedesignagent-auth capture http://localhost:3000/dashboard
 ```
 
-A browser opens; log in, then press Enter (or close the browser). The session is saved under `~/.thedesignagent/auth/` and reused for that origin. When `Visual` hits a login redirect, it tells the agent to ask you to run this command.
+It uses a dedicated browser profile, so later re-captures are often instant. Agents can run it in the background: it ends with `TDA_AUTH_SAVED <origin>` or `TDA_AUTH_FAILED <reason>`, and gives up after 10 minutes.
+
+Check what's saved with `thedesignagent-auth status <url>`.
 
 ## Environment variables
 

package/dist/auth-capture.js

@@ -1,10 +1,40 @@
 #!/usr/bin/env node
+/**
+ * thedesignagent-auth: save a logged-in session so `Visual` can screenshot
+ * pages behind login.
+ *
+ *   capture <app-url>   Opens a browser window; log in. Saves and closes on its own
+ *                       once you leave the login page (or press Enter / close it).
+ *                       Safe to run from an agent in the background.
+ *   login <app-url>     Non-interactive. Reads a login recipe's output on stdin:
+ *                       either a URL that logs in when opened (a magic link, a
+ *                       dev-only login route) or an AuthSeed JSON ({ cookies, ... }).
+ *                       Logs in headlessly, verifies, saves.
+ *   status <app-url>    Says whether a session is saved and when it expires.
+ *
+ * Every run ends with one machine-readable line for agents:
+ *   TDA_AUTH_SAVED <origin>   |   TDA_AUTH_FAILED <reason>   |   TDA_AUTH_STATUS ...
+ */
 import { findChromeExecutable, isLoginUrl } from './screenshot.js';
-import { saveStoredAuth } from './auth-store.js';
+import { authFilePath, loadStoredAuth, saveStoredAuth, BROWSER_PROFILE_DIR } from './auth-store.js';
+import { existsSync } from 'node:fs';
 import { createInterface } from 'node:readline';
+const CAPTURE_TIMEOUT_MS = Number(process.env.TDA_CAPTURE_TIMEOUT_MS ?? 10 * 60 * 1000);
+const POLL_MS = 1500;
 function printUsage() {
-    console.error('Usage: thedesignagent-auth capture <url>');
-    console.error('Example: thedesignagent-auth capture http://localhost:3000');
+    console.error('Usage:');
+    console.error('  thedesignagent-auth capture <app-url>   log in by hand in a browser window');
+    console.error('  thedesignagent-auth login <app-url>     log in from a recipe (URL or AuthSeed JSON on stdin)');
+    console.error('  thedesignagent-auth status <app-url>    show whether a session is saved');
+    console.error('Example: node .thedesignagent-login.mjs | thedesignagent-auth login http://localhost:3000');
+}
+function fail(reason, detail) {
+    console.error('');
+    console.error(`✗ ${reason}`);
+    for (const line of detail ?? [])
+        console.error(`  ${line}`);
+    console.log(`TDA_AUTH_FAILED ${reason}`);
+    process.exit(1);
 }
 async function snapshotSession(browser, page, hostname) {
     try {
@@ -19,144 +49,249 @@ async function snapshotSession(browser, page, hostname) {
             httpOnly: c.httpOnly,
             secure: c.secure,
             sameSite: (c.sameSite === 'Strict' || c.sameSite === 'Lax' || c.sameSite === 'None') ? c.sameSite : undefined,
+            ...(c.expires > 0 && { expires: c.expires }),
         }));
+        // Storage is unreadable on error pages (opaque origin): keep the cookies anyway.
         const storage = await page.evaluate(() => ({
             localStorage: Object.fromEntries(Object.keys(localStorage).map(k => [k, localStorage.getItem(k) ?? ''])),
             sessionStorage: Object.fromEntries(Object.keys(sessionStorage).map(k => [k, sessionStorage.getItem(k) ?? ''])),
-        }));
-        return {
-            cookies,
-            localStorage: storage.localStorage,
-            sessionStorage: storage.sessionStorage,
-            finalUrl: page.url(),
-        };
+        })).catch(() => ({ localStorage: {}, sessionStorage: {} }));
+        return { cookies, localStorage: storage.localStorage, sessionStorage: storage.sessionStorage, finalUrl: page.url() };
     }
     catch {
         return null;
     }
 }
-function waitForEnter() {
-    return new Promise(resolve => {
-        if (!process.stdin.isTTY) {
-            // No TTY (e.g. backgrounded by an agent) — never resolves. Browser-close will trigger instead.
-            return;
-        }
-        const rl = createInterface({ input: process.stdin, output: process.stdout });
-        rl.once('line', () => { rl.close(); resolve('enter'); });
-    });
-}
-function waitForBrowserClose(browser) {
-    return new Promise(resolve => {
-        browser.on('disconnected', () => resolve('closed'));
-    });
-}
-// Post-trigger verification: if the browser is still alive after Enter was
-// pressed, navigate back to the original URL and re-snapshot. Catches "user
-// pressed Enter too early" — the partial session would otherwise be saved
-// silently and fail on every subsequent visual call.
-async function verifyAndSnapshot(browser, page, url, trigger, fallback) {
-    if (trigger !== 'enter' || !browser.connected)
-        return fallback;
+// Navigate back to the app URL and re-snapshot, so a session is only saved
+// once the app itself accepts it (catches "confirmed before login finished").
+async function verifySnapshot(browser, page, url) {
     try {
-        console.log('Verifying session…');
-        await page.goto(url.href, { waitUntil: 'networkidle0', timeout: 15000 });
-        const snap = await snapshotSession(browser, page, url.hostname);
-        return snap ?? fallback;
+        await page.goto(url.href, { waitUntil: 'networkidle2', timeout: 20000 });
+        return await snapshotSession(browser, page, url.hostname);
     }
     catch {
-        return fallback;
+        return null;
     }
 }
-async function main() {
-    const [, , subcommand, urlArg] = process.argv;
-    if (subcommand !== 'capture' || !urlArg) {
-        printUsage();
-        process.exit(1);
-    }
-    let url;
-    try {
-        url = new URL(urlArg);
-    }
-    catch {
-        console.error(`Invalid URL: ${urlArg}`);
-        process.exit(1);
+function saveSnapshot(url, snap, how) {
+    if (isLoginUrl(snap.finalUrl)) {
+        fail('session not accepted', [
+            `Opening ${url.href} still redirected to a login page: ${snap.finalUrl}`,
+            'Login may not have finished (a second factor or enrolment step still pending?).',
+        ]);
     }
+    const seed = {
+        cookies: snap.cookies,
+        ...(Object.keys(snap.localStorage).length && { localStorage: snap.localStorage }),
+        ...(Object.keys(snap.sessionStorage).length && { sessionStorage: snap.sessionStorage }),
+    };
+    const savedPath = saveStoredAuth(url.href, seed);
+    console.log('');
+    console.log(`✓ Logged in (${how}); ${snap.cookies.length} cookies, ${Object.keys(snap.localStorage).length} localStorage entries`);
+    console.log(`✓ Saved to ${savedPath}. Visual now uses it for every page on ${url.origin}.`);
+    console.log(`TDA_AUTH_SAVED ${url.origin}`);
+    process.exit(0);
+}
+async function launch(opts) {
     const chromePath = findChromeExecutable();
-    if (!chromePath) {
-        console.error('Chrome/Chromium not found. Install Google Chrome (or set CHROME_PATH).');
-        process.exit(1);
-    }
+    if (!chromePath)
+        fail('no browser found', ['Install Google Chrome (or Edge, Brave, Chromium), or set CHROME_PATH.']);
     const puppeteer = (await import('puppeteer-core')).default;
-    console.log(`▌TheDesignAgent▐ auth capture`);
-    console.log(`Opening ${url.href} in a browser window…`);
-    const browser = await puppeteer.launch({
+    return puppeteer.launch({
         executablePath: chromePath,
-        headless: false,
+        headless: opts.headless,
         defaultViewport: { width: 1440, height: 900 },
+        // A dedicated profile keeps "remember me" and SSO sessions between
+        // captures, so re-capturing after expiry is often instant.
+        ...(opts.persistent && { userDataDir: BROWSER_PROFILE_DIR }),
         args: ['--no-sandbox', '--disable-setuid-sandbox'],
     });
+}
+// ── capture ──────────────────────────────────────────────────────────────────
+function waitForEnter() {
+    return new Promise(resolve => {
+        if (!process.stdin.isTTY)
+            return; // backgrounded by an agent: rely on auto-detect / close
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        rl.once('line', () => { rl.close(); resolve('enter'); });
+    });
+}
+async function capture(url) {
+    const hadSavedSession = existsSync(authFilePath(url.href));
+    const browser = await launch({ headless: process.env.TDA_CAPTURE_HEADLESS === '1', persistent: true });
     const [page] = await browser.pages();
-    await page.goto(url.href, { waitUntil: 'domcontentloaded', timeout: 30000 });
-    // Continuously snapshot the session as the user navigates, so we always have
-    // a recent capture even if the browser is closed before they confirm.
+    await page.goto(url.href, { waitUntil: 'domcontentloaded', timeout: 30000 }).catch(() => { });
+    console.log('▌TheDesignAgent▐ login capture');
+    console.log(`→ A browser window opened at ${url.href}. Log in to your app there.`);
+    console.log('→ It saves and closes by itself once you reach a logged-in page.');
+    if (process.stdin.isTTY)
+        console.log('  (Or press Enter here, or close the window, when you are done.)');
+    console.log('');
+    // Logged in = we saw a login page on this origin and have now left it (the
+    // page is back on the app, off any login path) for two polls in a row.
+    // If the dedicated profile was already logged in and the app loads straight
+    // away, that counts too when a session was saved before (a re-capture).
+    let sawLogin = isLoginUrl(page.url());
+    let stableOffLogin = 0;
+    const detected = new Promise(resolve => {
+        const timer = setInterval(() => {
+            let current;
+            try {
+                current = new URL(page.url());
+            }
+            catch {
+                return;
+            }
+            const onApp = current.origin === url.origin;
+            if (onApp && isLoginUrl(current.href)) {
+                sawLogin = true;
+                stableOffLogin = 0;
+                return;
+            }
+            if (onApp && (sawLogin || hadSavedSession))
+                stableOffLogin++;
+            else
+                stableOffLogin = 0;
+            if (stableOffLogin >= 2) {
+                clearInterval(timer);
+                resolve('detected');
+            }
+        }, POLL_MS);
+        browser.on('disconnected', () => clearInterval(timer));
+    });
     let lastSnapshot = null;
-    const pollInterval = setInterval(async () => {
+    const snapTimer = setInterval(async () => {
         const snap = await snapshotSession(browser, page, url.hostname);
         if (snap)
             lastSnapshot = snap;
-    }, 2000);
-    const interactiveHint = process.stdin.isTTY
-        ? '→ When you\'re logged in, press Enter in your terminal OR close the browser window.'
-        : '→ When you\'re logged in, close the browser window. (No TTY detected.)';
-    console.log('');
-    console.log('→ Log in to your app in the browser window that just opened.');
-    console.log(interactiveHint);
-    console.log('');
-    const trigger = await Promise.race([waitForEnter(), waitForBrowserClose(browser)]);
-    clearInterval(pollInterval);
-    const verifiedSnapshot = await verifyAndSnapshot(browser, page, url, trigger, lastSnapshot);
-    if (trigger !== 'closed') {
+    }, POLL_MS);
+    const closed = new Promise(resolve => browser.on('disconnected', () => resolve('closed')));
+    const timedOut = new Promise(resolve => setTimeout(() => resolve('timeout'), CAPTURE_TIMEOUT_MS).unref());
+    const trigger = await Promise.race([detected, waitForEnter(), closed, timedOut]);
+    clearInterval(snapTimer);
+    if (trigger === 'timeout') {
         try {
             await browser.close();
         }
-        catch { /* already closing */ }
+        catch { }
+        fail('timed out waiting for login', [`No login completed within ${Math.round(CAPTURE_TIMEOUT_MS / 60000)} minutes. Run it again when ready.`]);
     }
-    if (!verifiedSnapshot) {
-        console.error('');
-        console.error('✗ No session captured — browser may have closed before login completed.');
-        console.error('  Re-run the command and log in before closing the window.');
-        process.exit(1);
+    const snap = trigger === 'closed' ? lastSnapshot : (await verifySnapshot(browser, page, url)) ?? lastSnapshot;
+    try {
+        await browser.close();
+    }
+    catch { }
+    if (!snap)
+        fail('no session captured', ['The window closed before a logged-in page loaded. Run it again.']);
+    saveSnapshot(url, snap, trigger === 'detected' ? 'detected automatically' : trigger === 'enter' ? 'Enter pressed' : 'window closed');
+}
+// ── login (from a recipe) ────────────────────────────────────────────────────
+// Stream stdin: readFileSync(0) throws EAGAIN on a pipe whose writer hasn't
+// finished yet (e.g. a recipe still waiting on a network call).
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', chunk => { data += chunk; });
+        process.stdin.on('end', () => resolve(data));
+        process.stdin.on('error', reject);
+    });
+}
+async function login(url) {
+    if (process.stdin.isTTY)
+        fail('nothing on stdin', ['Pipe a login recipe into this command, e.g. node .thedesignagent-login.mjs | thedesignagent-auth login ' + url.origin]);
+    const input = (await readStdin()).trim();
+    if (!input)
+        fail('empty input', ['The login recipe printed nothing.']);
+    let seed = null;
+    let loginUrl = null;
+    if (input.startsWith('{')) {
+        try {
+            seed = JSON.parse(input);
+        }
+        catch {
+            fail('recipe output is not valid JSON');
+        }
+    }
+    else {
+        loginUrl = input.split('\n')[0].trim();
+        try {
+            new URL(loginUrl);
+        }
+        catch {
+            fail('recipe output is neither a URL nor JSON');
+        }
     }
-    if (isLoginUrl(verifiedSnapshot.finalUrl)) {
-        console.error('');
-        console.error('✗ Session not saved — after capture, navigating to the target URL still');
-        console.error('  redirected to a login page. This usually means:');
-        console.error('  • Login was not fully completed (2FA still pending? form not submitted?)');
-        console.error('  • You confirmed before reaching a logged-in page');
-        console.error('');
-        console.error(`  Final URL after verification: ${verifiedSnapshot.finalUrl}`);
-        console.error('');
-        console.error('  Re-run the command. Make sure you reach a logged-in page in the');
-        console.error('  browser before pressing Enter or closing the window.');
+    const browser = await launch({ headless: true, persistent: false });
+    try {
+        const page = await browser.newPage();
+        if (seed?.cookies?.length) {
+            await page.browserContext().setCookie(...seed.cookies.map(c => ({ ...c, domain: c.domain ?? url.hostname, path: c.path ?? '/' })));
+        }
+        if (seed?.localStorage || seed?.sessionStorage) {
+            await page.evaluateOnNewDocument((ls, ss) => {
+                try {
+                    for (const [k, v] of ls)
+                        localStorage.setItem(k, v);
+                    for (const [k, v] of ss)
+                        sessionStorage.setItem(k, v);
+                }
+                catch { }
+            }, Object.entries(seed.localStorage ?? {}), Object.entries(seed.sessionStorage ?? {}));
+        }
+        if (loginUrl) {
+            await page.goto(loginUrl, { waitUntil: 'networkidle2', timeout: 30000 }).catch(() => { });
+        }
+        const snap = await verifySnapshot(browser, page, url);
+        await browser.close();
+        if (!snap)
+            fail('could not load the app', [`Is the dev server running at ${url.origin}?`]);
+        saveSnapshot(url, snap, loginUrl ? 'login URL' : 'recipe cookies');
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch { }
+    }
+}
+// ── status ───────────────────────────────────────────────────────────────────
+function status(url) {
+    const seed = loadStoredAuth(url.href);
+    if (!seed) {
+        console.log(`No saved session for ${url.origin}.`);
+        console.log(`TDA_AUTH_STATUS none ${url.origin}`);
+        return;
+    }
+    const expiries = (seed.cookies ?? []).map(c => c.expires).filter((e) => typeof e === 'number' && e > 0);
+    if (!expiries.length) {
+        console.log(`Session saved for ${url.origin} (session cookies, no expiry recorded).`);
+        console.log(`TDA_AUTH_STATUS saved ${url.origin}`);
+        return;
+    }
+    const soonest = new Date(Math.min(...expiries) * 1000);
+    const expired = soonest.getTime() < Date.now();
+    console.log(`Session saved for ${url.origin}; ${expired ? 'expired' : 'expires'} ${soonest.toISOString()}.`);
+    console.log(`TDA_AUTH_STATUS ${expired ? 'expired' : 'saved'} ${url.origin} ${soonest.toISOString()}`);
+}
+// ── main ─────────────────────────────────────────────────────────────────────
+async function main() {
+    const [, , subcommand, urlArg] = process.argv;
+    if (!subcommand || !urlArg || !['capture', 'login', 'status'].includes(subcommand)) {
+        printUsage();
         process.exit(1);
     }
-    const seed = {
-        cookies: verifiedSnapshot.cookies,
-        ...(Object.keys(verifiedSnapshot.localStorage).length && { localStorage: verifiedSnapshot.localStorage }),
-        ...(Object.keys(verifiedSnapshot.sessionStorage).length && { sessionStorage: verifiedSnapshot.sessionStorage }),
-    };
-    const savedPath = saveStoredAuth(url.href, seed);
-    console.log('');
-    console.log(`✓ Trigger: ${trigger === 'closed' ? 'browser closed' : 'Enter pressed'}`);
-    console.log(`✓ Captured ${verifiedSnapshot.cookies.length} cookies, ${Object.keys(verifiedSnapshot.localStorage).length} localStorage entries, ${Object.keys(verifiedSnapshot.sessionStorage).length} sessionStorage entries`);
-    console.log(`✓ Final URL: ${verifiedSnapshot.finalUrl}`);
-    console.log(`✓ Saved to: ${savedPath}`);
-    console.log('');
-    console.log(`▌TheDesignAgent▐ will now auto-apply this session for any URL on ${url.origin}.`);
-    console.log(`To re-capture (after expiry or logout), run this command again.`);
-    process.exit(0);
+    let url;
+    try {
+        url = new URL(urlArg);
+    }
+    catch {
+        fail(`invalid URL: ${urlArg}`);
+    }
+    if (subcommand === 'status')
+        return status(url);
+    if (subcommand === 'login')
+        return login(url);
+    return capture(url);
 }
-main().catch(err => {
-    console.error('auth-capture failed:', err instanceof Error ? err.message : err);
-    process.exit(1);
-});
+main().catch(err => fail('auth command crashed', [err instanceof Error ? err.message : String(err)]));

package/dist/auth-store.d.ts

@@ -1,5 +1,6 @@
 import type { AuthSeed } from './screenshot.js';
 export declare const AUTH_STORE_DIR: string;
+export declare const BROWSER_PROFILE_DIR: string;
 export declare function authFilePath(url: string): string;
 export declare function loadStoredAuth(url: string): AuthSeed | null;
 export declare function saveStoredAuth(url: string, seed: AuthSeed): string;

package/dist/auth-store.js

@@ -1,7 +1,9 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+// Saved sessions are live login cookies: keep them readable by the owner only.
 export const AUTH_STORE_DIR = join(homedir(), '.thedesignagent', 'auth');
+export const BROWSER_PROFILE_DIR = join(homedir(), '.thedesignagent', 'browser-profile');
 function safeFilename(origin) {
     return origin.replace(/^https?:\/\//, '').replace(/[^a-z0-9.-]/gi, '_') + '.json';
 }
@@ -20,8 +22,10 @@ export function loadStoredAuth(url) {
     }
 }
 export function saveStoredAuth(url, seed) {
-    mkdirSync(AUTH_STORE_DIR, { recursive: true });
+    mkdirSync(AUTH_STORE_DIR, { recursive: true, mode: 0o700 });
+    chmodSync(AUTH_STORE_DIR, 0o700);
     const path = authFilePath(url);
-    writeFileSync(path, JSON.stringify(seed, null, 2));
+    writeFileSync(path, JSON.stringify(seed, null, 2), { mode: 0o600 });
+    chmodSync(path, 0o600);
     return path;
 }

package/dist/index.js

@@ -24,6 +24,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import Anthropic from '@anthropic-ai/sdk';
 import { z } from 'zod';
+import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { captureScreenshot } from './screenshot.js';
 import { loadStoredAuth } from './auth-store.js';
@@ -111,13 +112,24 @@ async function runFallback(task, artifact, codebaseContext) {
         ? `\n\n## Codebase Context\n${codebaseContext.slice(0, 3000)}`
         : '';
     const userMessage = `## Task\n${task}\n\n## Artifact to Evaluate\n${artifact}${contextSection}\n\nReturn ONLY valid JSON matching the schema in the system prompt.`;
+    // Opus 5.5 always thinks: thinking shares max_tokens, and the reply is not
+    // content[0]. `fallbacks` (not yet in the SDK types) re-runs a safety
+    // classifier decline on Anthropic's recommended model within the same call.
     const response = await client.messages.create({
-        model: 'claude-opus-4-7',
-        max_tokens: 4000,
+        model: 'claude-opus-5-5',
+        max_tokens: 16000,
+        output_config: { effort: 'medium' },
         system: FALLBACK_SYSTEM_PROMPT,
         messages: [{ role: 'user', content: userMessage }],
-    });
-    const text = response.content[0].type === 'text' ? response.content[0].text : '';
+        fallbacks: 'default',
+    }, { headers: { 'anthropic-beta': 'server-side-fallback-2026-07-01' } });
+    if (response.stop_reason === 'refusal') {
+        throw new Error('Fallback Claude declined the request');
+    }
+    const text = response.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('');
     const jsonStr = text.replace(/^```(?:json)?\n?/m, '').replace(/\n?```$/m, '').trim();
     try {
         const parsed = JSON.parse(jsonStr);
@@ -218,43 +230,43 @@ async function tryCaptureScreenshot(url, authSeed) {
         return { screenshotError, authSeedSource: source };
     }
 }
-function suggestedAuthCmd(renderUrl) {
-    try {
-        const origin = new URL(renderUrl).origin;
-        const authCapturePath = join(dirname(process.argv[1]), 'auth-capture.js');
-        return `node ${authCapturePath} capture ${origin}`;
-    }
-    catch {
-        return 'thedesignagent-auth capture <your-app-url>';
-    }
+// The login recipe a repo can provide (written by the plugin's setup flow).
+// It prints either a URL that logs in when opened or an AuthSeed JSON.
+const LOGIN_RECIPE = '.thedesignagent-login.mjs';
+// Run the auth CLI that ships alongside this server, so its version always matches.
+// Pass the page being reviewed, not just the origin: many apps 404 or
+// redirect at the root, and the session is saved per origin either way.
+function authCmd(sub, pageUrl) {
+    const authCapturePath = join(dirname(process.argv[1]), 'auth-capture.js');
+    return `node "${authCapturePath}" ${sub} ${pageUrl}`;
 }
 function buildAuthRequiredFooter(renderUrl, capture) {
     const { screenshotPath, finalUrl, authSeedSource } = capture;
-    const expired = authSeedSource === 'stored';
-    const stateLine = expired
-        ? `A saved session for this origin existed but appears expired.`
-        : `No saved session for this origin yet.`;
+    const origin = (() => { try {
+        return new URL(renderUrl).origin;
+    }
+    catch {
+        return renderUrl;
+    } })();
+    const stateLine = authSeedSource === 'stored'
+        ? `A saved session for ${origin} existed but has expired.`
+        : `No saved session for ${origin} yet.`;
+    const hasRecipe = existsSync(join(process.cwd(), LOGIN_RECIPE));
     const lines = [
         `---`,
-        `🛑 ▌TheDesignAgent▐ — ACTION REQUIRED: page is behind authentication`,
+        `🛑 ▌TheDesignAgent▐ — page is behind login. No review ran and no credits were charged.`,
         ``,
-        `The visual eval ran against a login page, not the target screen. The findings above describe the login form and should be DISCARDED.`,
-        ``,
-        `${stateLine} The user must run this exact command in their own terminal:`,
-        ``,
-        `   ${suggestedAuthCmd(renderUrl)}`,
+        stateLine,
         ``,
         `WHAT TO DO NEXT:`,
-        `1. Surface the command above to the user verbatim.`,
-        `2. Tell them: a Chrome window will open — log in normally, then close it (or press Enter in the terminal).`,
-        `3. Wait for them to confirm they've run it.`,
-        `4. Then retry this visual call with the same render_url. Auth will be auto-applied.`,
-        ``,
-        `WHAT NOT TO DO:`,
-        `- Do not search the app's source for auth keys, JWT names, or localStorage tokens.`,
-        `- Do not attempt to construct auth_seed manually — it almost always fails (HttpOnly cookies are invisible to code search).`,
-        `- Do not run the capture command yourself in the background — it needs the user's interactive login.`,
     ];
+    if (hasRecipe) {
+        lines.push(`1. This repo has a login recipe. Run it (from the repo root):`, `     node ${LOGIN_RECIPE} | ${authCmd('login', renderUrl)}`, `2. When it prints TDA_AUTH_SAVED, retry this Visual call with the same render_url.`, `3. If it prints TDA_AUTH_FAILED, fall back to the manual capture below.`, ``, `Manual capture (fallback):`);
+    }
+    lines.push(`${hasRecipe ? '' : '1. '}Run this yourself, in the background (it opens a browser window for the user):`, `     ${authCmd('capture', renderUrl)}`, `   Tell the user: "A browser window opened at ${origin}. Log in there; it saves and closes by itself."`, `   Wait for the command to finish. It prints TDA_AUTH_SAVED when done (or TDA_AUTH_FAILED with a reason; it gives up after 10 minutes).`, `${hasRecipe ? '' : '2. '}Then retry this Visual call once with the same render_url. The session is applied automatically.`, ``, `WHAT NOT TO DO:`, `- Do not search the app's source for auth keys, JWT names, or localStorage tokens.`, `- Do not construct auth_seed by hand. HttpOnly cookies are invisible to code search, so it almost always fails.`);
+    if (!hasRecipe) {
+        lines.push(``, `To make this automatic next time, the plugin's setup flow can write a ${LOGIN_RECIPE} for this repo.`);
+    }
     if (finalUrl) {
         lines.push(``, `(Diagnostics: redirected to ${finalUrl})`);
     }
@@ -418,6 +430,12 @@ async function handleVisualCall(args) {
     log('info', 'pipeline_call', `tool=visual project_id=${args.project_id ?? 'none'} task_len=${args.task.length} render_url=${args.render_url ?? 'none'}`);
     const capture = await tryCaptureScreenshot(args.render_url, args.auth_seed);
     const { screenshot } = capture;
+    // Landed on a login page: stop before the pipeline. Evaluating the login
+    // form would cost credits and produce findings the agent must discard.
+    if (capture.authRequired && args.render_url) {
+        log('info', 'visual_auth_required', `render_url=${args.render_url} final_url=${capture.finalUrl ?? 'unknown'}`);
+        return { content: [{ type: 'text', text: buildAuthRequiredFooter(args.render_url, capture) }] };
+    }
     try {
         const response = await fetch(`${API_BASE}/visual`, {
             method: 'POST',
@@ -516,7 +534,7 @@ const evalInputSchema = {
     repo_hash: z.string().optional().describe('SHA256 of git remote origin URL (fallback if no .thedesignagent)'),
     codebase_context: z.string().optional().describe('Optional surrounding code context'),
 };
-const server = new McpServer({ name: 'TheDesignAgent', version: '0.2.5' });
+const server = new McpServer({ name: 'TheDesignAgent', version: '0.3.1' });
 server.registerTool('Discover', {
     description: `Get a build brief calibrated to your project, persona, and the specific screen you're building.
 
@@ -567,7 +585,7 @@ Call for visual design review after building. TheDesignAgent scores across three
 
 If render_url is provided, the MCP server takes a real screenshot via headless Chrome and the pipeline runs Vision-based analysis. Otherwise it falls back to text analysis of the artifact code.
 
-AUTH-GATED PAGES: If the page is behind login, this tool will detect the redirect and return an auth-required response with a one-line command for the user to run (\`thedesignagent-auth capture <origin>\`). When you receive this response: STOP, surface that exact command to the user, and ask them to retry once they've run it. DO NOT investigate the app's auth scheme. DO NOT attempt to populate auth_seed by grepping for tokens or localStorage keys. The capture command handles all of that automatically; trying to construct auth_seed yourself wastes the user's time and usually doesn't work.
+AUTH-GATED PAGES: If the page is behind login, this tool stops before evaluating (no credits charged) and returns the exact commands to save a session: a repo login recipe (.thedesignagent-login.mjs) when one exists, otherwise a browser capture you run in the background while the user logs in (it saves and closes by itself). Follow those instructions, then retry once. DO NOT investigate the app's auth scheme or populate auth_seed by grepping for tokens or localStorage keys; that wastes the user's time and usually doesn't work.
 
 Screenshots are saved to ~/.thedesignagent/screenshots/ (24h TTL) so you can open them to see exactly what was evaluated.
 

package/dist/screenshot.d.ts

@@ -7,6 +7,7 @@ export interface AuthSeedCookie {
     httpOnly?: boolean;
     secure?: boolean;
     sameSite?: 'Strict' | 'Lax' | 'None';
+    expires?: number;
 }
 export interface AuthSeed {
     cookies?: AuthSeedCookie[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thedesignagent/mcp",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "MCP server for TheDesignAgent — UX and visual judgment layer for agent-generated UI",
   "license": "MIT",
   "type": "module",
@@ -35,7 +35,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.36.0",
+    "@anthropic-ai/sdk": "^0.92.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "puppeteer-core": "^23.11.1",
     "zod": "^3.22.0"