@trusty-squire/mcp 0.1.17 → 0.2.0

package/dist/bot/agent.js

@@ -8,6 +8,7 @@
 // executor; the prompt is the contract. If a service breaks we tweak the
 // prompt rather than threading service-specific logic through the agent.
 import { rankAndCapInventory, scoreSignupButton } from "./browser.js";
+import { OAUTH_PROVIDERS, extractOAuthScopes, } from "./oauth-providers.js";
 import { saveDebugSnapshot } from "./debug.js";
 import { wasRecentlyPrewarmed, recordPrewarmSuccess } from "./prewarm-cache.js";
 import { pickLLMPair, } from "./llm-client.js";
@@ -47,6 +48,24 @@ const VERIFICATION_EXPECTED_PATTERNS = [
 // their email. Legitimate verification mail almost always lands inside a
 // minute; this catches the fast case without 300s of dead air.
 const VERIFICATION_PROBE_SECONDS = 45;
+// T7: page text that means the post-OAuth API key sits behind a
+// billing / payment-method wall. When the OAuth onboarding loop ends
+// without a key and the page reads like this, the run ends
+// `onboarding_blocked` rather than grep-looping a wall it cannot
+// satisfy (the S3-class trap named in the plan's failure modes).
+const ONBOARDING_PAYWALL_PATTERNS = [
+    "add a payment method",
+    "add a credit card",
+    "add credit card",
+    "payment method required",
+    "a payment method is required",
+    "credit card required",
+    "enter your card",
+    "enter your payment",
+    "enter payment details",
+    "upgrade your plan to",
+    "start your paid plan",
+];
 // S3: does this post-submit page text indicate the service genuinely
 // expects the user to confirm via email? Drives whether the bot polls the
 // full verification timeout or runs only a short probe. Exported so the
@@ -253,12 +272,72 @@ export function isOauthOnlyChooser(inventory) {
     const hasEmailOption = inventory.some((e) => scoreSignupButton(`${e.visibleText ?? ""} ${e.ariaLabel ?? ""} ${e.labelText ?? ""}`) > 0);
     return !hasEmailOption;
 }
-export function parsePostVerifyStep(raw) {
+// Find a "Sign in with <provider>" affordance in the page inventory —
+// the entry point for the OAuth-first path (T6/T13). Three signals, in
+// confidence order — derived from a live sweep where the text-only
+// heuristic missed real buttons:
+//   1. href — an <a> whose link routes through the provider's OAuth
+//      endpoint (/identity/login/google, /auth/github/callback, …).
+//      Unambiguous: a marketing link to policies.google.com does not.
+//   2. iconLabel — an icon-only button with no text at all, named only
+//      by a descendant <img alt="Google"> / <svg><title> (Mistral).
+//   3. text + an auth verb — "Continue with Google", "Sign up with
+//      GitHub". The auth verb is what keeps a bare "Google" nav link
+//      or "Google's Privacy Policy" out.
+// Returns null when the page has no such affordance — the planner then
+// falls back to form-fill. Exported for unit testing.
+export function findOAuthButton(inventory, provider) {
+    const keyword = OAUTH_PROVIDERS[provider].buttonKeyword;
+    const keywordRe = new RegExp(`\\b${keyword}\\b`);
+    const hrefRe = new RegExp(`(?:login|signin|sign-in|auth|oauth|connect|sso)[/_-]*${keyword}` +
+        `|${keyword}[/_-]*(?:login|signin|auth|oauth|connect)`, "i");
+    for (const e of inventory) {
+        const isButtonish = e.tag === "button" ||
+            e.tag === "a" ||
+            e.role === "button" ||
+            e.type === "submit" ||
+            e.type === "button";
+        if (!isButtonish)
+            continue;
+        // 1. An <a> whose href routes through the provider's OAuth endpoint.
+        const href = (e.href ?? "").toLowerCase();
+        if (href.length > 0 && hrefRe.test(href))
+            return e;
+        // 2. Icon-only button — named only by a descendant img/svg.
+        if (keywordRe.test((e.iconLabel ?? "").toLowerCase()))
+            return e;
+        // 3. Visible text / accessible label naming the provider + an
+        //    auth verb. The auth verb requirement rejects nav and policy
+        //    links that merely mention the provider.
+        const text = `${e.visibleText ?? ""} ${e.ariaLabel ?? ""} ${e.labelText ?? ""}`
+            .toLowerCase()
+            .replace(/\s+/g, " ")
+            .trim();
+        if (!keywordRe.test(text))
+            continue;
+        if (/\b(sign|signup|signin|continue|log ?in|connect|auth)\b/.test(text)) {
+            return e;
+        }
+    }
+    return null;
+}
+// Parse a post-verify step. When `allowedSelectors` is supplied, a
+// `click`/`fill` selector that is not in the page inventory is a
+// parse-time rejection — the same DOM-grounding F3 gave the signup
+// planner (parseSignupPlan). It stops the post-OAuth onboarding
+// planner from inventing CSS selectors that never resolve, which was
+// the dominant onboarding-navigation failure mode.
+export function parsePostVerifyStep(raw, allowedSelectors) {
     const obj = extractJsonObject(raw);
     const kind = obj["kind"];
     // `reason` is required by the schema but advisory; default it so a
     // model omitting it doesn't trip a retry on an otherwise-valid step.
     const reason = typeof obj["reason"] === "string" ? obj["reason"] : "";
+    const checkSelector = (selector, context) => {
+        if (allowedSelectors !== undefined && !allowedSelectors.has(selector)) {
+            throw new Error(`${context}: selector ${JSON.stringify(selector)} is not in the page inventory`);
+        }
+    };
     switch (kind) {
         case "done":
             return { kind: "done", reason };
@@ -266,19 +345,21 @@ export function parsePostVerifyStep(raw) {
             return { kind: "extract", reason };
         case "login":
             return { kind: "login", reason };
-        case "click":
-            return {
-                kind: "click",
-                selector: requireString(obj, "selector", "post-verify click step"),
-                reason,
-            };
-        case "fill":
+        case "click": {
+            const selector = requireString(obj, "selector", "post-verify click step");
+            checkSelector(selector, "post-verify click step");
+            return { kind: "click", selector, reason };
+        }
+        case "fill": {
+            const selector = requireString(obj, "selector", "post-verify fill step");
+            checkSelector(selector, "post-verify fill step");
             return {
                 kind: "fill",
-                selector: requireString(obj, "selector", "post-verify fill step"),
+                selector,
                 value: requireString(obj, "value", "post-verify fill step"),
                 reason,
             };
+        }
         case "navigate":
             return {
                 kind: "navigate",
@@ -315,6 +396,22 @@ const CAPTCHA_TOKEN_MARKERS = [
     "g-recaptcha-response",
     "h-captcha-response",
 ];
+// Distinctive service key prefixes. If a *labeled* match's value
+// embeds one of these NOT at its start, the regex straddled glued UI
+// text on a dense dashboard (e.g. Render's API-keys list rendered as
+// "...Name bot-key Menu Key rnd_xxxx" with no separators) — the real
+// key starts at the prefix, so the labeled match is contaminated and
+// must be rejected. A clean labeled key either starts with its prefix
+// (then the prefixed patterns above already caught it) or carries no
+// known prefix at all.
+const EMBEDDED_KEY_PREFIXES = [
+    "rnd_",
+    "phc_",
+    "sk_live_",
+    "sk_test_",
+    "pk_live_",
+    "pk_test_",
+];
 // Pull an API key out of the *visible* page text.
 //
 // Two strategies, in priority order:
@@ -339,6 +436,7 @@ export function extractApiKeyFromText(text) {
         /\bkey-[a-f0-9]{32}\b/, // Mailgun
         /\bphc_[a-zA-Z0-9]{32,}\b/, // PostHog
         /\bSG\.[a-zA-Z0-9_\-]{20,}\.[a-zA-Z0-9_\-]{20,}\b/, // SendGrid
+        /\brnd_[a-zA-Z0-9]{20,}\b/, // Render
     ];
     for (const pattern of prefixed) {
         const match = text.match(pattern);
@@ -366,6 +464,10 @@ export function extractApiKeyFromText(text) {
         const lower = candidate.toLowerCase();
         if (CAPTCHA_TOKEN_MARKERS.some((marker) => lower.includes(marker)))
             continue;
+        // Contaminated: the labeled match straddled glued dashboard text
+        // onto a real key (the key prefix sits mid-candidate, not at 0).
+        if (EMBEDDED_KEY_PREFIXES.some((p) => lower.indexOf(p) > 0))
+            continue;
         return candidate;
     }
     return null;
@@ -523,11 +625,29 @@ export class SignupAgent {
         let progressReplans = 0;
         let emptyPlans = 0;
         let hint;
+        const oauthProvider = task.oauthProvider;
         for (;;) {
             await this.browser.waitForFormReady();
             await saveDebugSnapshot(this.browser, "before-fill");
             const state = await this.browser.getState();
-            const inventory = await this.buildInventory(steps);
+            const inventory = await this.buildInventory(steps, oauthProvider);
+            // T6/T13 — OAuth-first: when an OAuth signup is requested and the
+            // page carries a "Sign in with <provider>" affordance, the OAuth
+            // button unconditionally outranks any form field (a rule, not
+            // score arithmetic — spec refinement). Hand off to the OAuth
+            // consent flow. Absent the affordance, fall through to form-fill.
+            if (oauthProvider !== undefined) {
+                const oauthButton = findOAuthButton(inventory, oauthProvider);
+                const label = OAUTH_PROVIDERS[oauthProvider].label;
+                if (oauthButton !== null) {
+                    steps.push(`OAuth-first: found a ${label} sign-in affordance ` +
+                        `(${JSON.stringify(oauthButton.visibleText ?? oauthButton.ariaLabel ?? label)}) ` +
+                        `— taking the OAuth path`);
+                    return { kind: "oauth", selector: oauthButton.selector };
+                }
+                steps.push(`OAuth-first requested but no ${label} affordance on the page — ` +
+                    `falling back to form-fill`);
+            }
             // OAuth-only: no fillable input AND no button that reads as an
             // email-signup option — nothing to automate (Issue 4).
             if (isOauthOnlyChooser(inventory)) {
@@ -668,9 +788,16 @@ export class SignupAgent {
         }
     }
     // Extract + rank the page's interactive elements (F3 T1/T2).
-    async buildInventory(steps) {
+    // `oauthProvider` keeps that provider's OAuth affordance from being
+    // ranked out of the capped inventory when an OAuth-first signup is
+    // requested (T6/T13). `buttonCap` widens for the post-OAuth
+    // onboarding loop: a dashboard carries far more nav links than a
+    // signup form, and they do not score as signup buttons, so the
+    // default cap would drop the "API Keys"/"Settings" links the
+    // onboarding planner must reach.
+    async buildInventory(steps, oauthProvider, buttonCap = 25) {
         const raw = await this.browser.extractInteractiveElements();
-        const { inventory, buttonsDropped } = rankAndCapInventory(raw);
+        const { inventory, buttonsDropped } = rankAndCapInventory(raw, buttonCap, oauthProvider);
         steps.push(`Inventory: ${inventory.length} element(s)` +
             (buttonsDropped > 0 ? ` (${buttonsDropped} low-ranked button(s) dropped)` : ""));
         return inventory;
@@ -954,6 +1081,11 @@ export class SignupAgent {
                         steps,
                         ...this.resultTail(),
                     };
+                case "oauth":
+                    // T6/T7 — OAuth-first path. runOAuthFlow drives the consent
+                    // handshake and post-OAuth onboarding to its own terminal
+                    // SignupResult; there is no form submit / email verification.
+                    return await this.runOAuthFlow(task, outcome.selector, steps);
                 case "submitted":
                     break;
             }
@@ -993,8 +1125,7 @@ export class SignupAgent {
                                 const maxRounds = task.postVerifyMaxRounds ?? 6;
                                 credentials = await this.postVerifyLoop({
                                     service: task.service,
-                                    email: task.email,
-                                    password,
+                                    credentials: { email: task.email, password },
                                     maxRounds,
                                     steps,
                                 });
@@ -1047,6 +1178,151 @@ export class SignupAgent {
             };
         }
     }
+    // ------------ OAuth-first signup (T6/T7/T13) ------------
+    // Drive an OAuth signup (Google or GitHub) to a terminal
+    // SignupResult. Entered from runSignup when planExecuteWithRetry
+    // found the provider's affordance (T6). Steps: click the button →
+    // walk the consent screens → scope-gate them → drive post-OAuth
+    // onboarding to the API key.
+    //
+    // THE CRITICAL GUARANTEE (D4 / eng-review critical gap): if the flow
+    // lands on the provider's credential form (expired/missing session)
+    // or a security challenge, it hands back `needs_login` and NEVER
+    // types into that form. Driving the provider's login is exactly what
+    // trips its automation detection — and there is no password to give.
+    async runOAuthFlow(task, oauthSelector, steps) {
+        const provider = OAUTH_PROVIDERS[task.oauthProvider ?? "google"];
+        const loginCmd = provider.id === "github"
+            ? "npx @trusty-squire/mcp login --provider=github"
+            : "npx @trusty-squire/mcp login";
+        steps.push(`OAuth: clicking the ${provider.label} sign-in affordance`);
+        await this.browser.startOAuth(oauthSelector);
+        await this.browser.wait(3);
+        await saveDebugSnapshot(this.browser, "oauth-after-click");
+        // Bounded consent walk — handles account-chooser → consent as two
+        // steps without ever spinning. Each iteration re-reads the page.
+        const MAX_OAUTH_NAV = 6;
+        for (let i = 0; i < MAX_OAUTH_NAV; i++) {
+            if (this.browser.oauthPageClosed()) {
+                steps.push(`OAuth: the ${provider.label} window closed — handshake returned to the service`);
+                break;
+            }
+            const url = this.browser.currentUrl();
+            let body;
+            try {
+                body = (await this.browser.extractText()).slice(0, 4000);
+            }
+            catch {
+                // The page is navigating between provider screens — re-read.
+                await this.browser.wait(1);
+                continue;
+            }
+            const authState = provider.classifyAuthState(url, body);
+            steps.push(`OAuth: ${provider.label} auth state = ${authState}`);
+            if (authState === "not_provider")
+                break; // flow left the provider — back on the service
+            if (authState === "challenge") {
+                return this.oauthAbort("needs_login", `${provider.label} interrupted the sign-in with a security challenge ("verify it's you"). ` +
+                    `Re-run \`${loginCmd}\`, clear the challenge in the window, then retry.`, steps);
+            }
+            if (authState === "needs_login") {
+                return this.oauthAbort("needs_login", `the bot's ${provider.label} session is missing or expired — no consent screen was reached. ` +
+                    `Re-run \`${loginCmd}\` to re-establish it, then retry.`, steps);
+            }
+            // authState === "consent". Backstop the page classifier with a
+            // live-DOM check: if the page actually carries a credential
+            // field it is a login form (the text classifier can catch a
+            // login page that says "to continue to <app>"). Hand back —
+            // never type into it.
+            if (await this.oauthLoginFormPresent()) {
+                return this.oauthAbort("needs_login", `landed on a ${provider.label} sign-in form — the session is missing or expired. ` +
+                    `Re-run \`${loginCmd}\`, then retry. The bot will not type into ${provider.label}'s login form.`, steps);
+            }
+            // Genuine consent screen / account chooser — scope-gate it (T7).
+            const scopes = extractOAuthScopes(url);
+            if (scopes === null) {
+                return this.oauthAbort("oauth_consent_needs_review", `reached a ${provider.label} consent screen but could not read its requested scopes ` +
+                    `from the URL — pausing for manual review rather than approving blind.`, steps);
+            }
+            if (!provider.scopesAreBasic(scopes)) {
+                return this.oauthAbort("oauth_consent_needs_review", `the consent screen requests scopes beyond basic identity (${scopes.join(", ")}). ` +
+                    `Approve it manually — the bot only auto-approves basic-identity scopes.`, steps);
+            }
+            steps.push(`OAuth: consent scopes all basic (${scopes.join(", ")}) — auto-approving`);
+            const advanced = await this.browser.advanceOAuthConsent(provider.id);
+            if (!advanced) {
+                return this.oauthAbort("oauth_consent_needs_review", `reached a ${provider.label} consent screen but found no approve control to click — ` +
+                    `approve it manually.`, steps);
+            }
+            await this.browser.wait(3);
+        }
+        // Handshake done — restore the product page (popup flow is a no-op
+        // for same-tab redirects) and drive post-OAuth onboarding.
+        await this.browser.settleAfterOAuth();
+        await this.browser.wait(2);
+        await saveDebugSnapshot(this.browser, "oauth-post-consent");
+        steps.push(`OAuth: signed in via ${provider.label} — driving post-OAuth onboarding to the API key`);
+        let credentials = await this.extractCredentials();
+        if (credentials.api_key === undefined) {
+            credentials = await this.postVerifyLoop({
+                service: task.service,
+                maxRounds: task.postVerifyMaxRounds ?? 8,
+                steps,
+            });
+        }
+        if (credentials.api_key !== undefined) {
+            return {
+                success: true,
+                credentials: { ...credentials },
+                steps,
+                ...this.resultTail(),
+            };
+        }
+        // No API key. Distinguish a billing/card wall (onboarding_blocked)
+        // from a generic navigation miss — never grep-loop a paid wall.
+        const finalText = (await this.browser.extractText().catch(() => "")).toLowerCase();
+        if (ONBOARDING_PAYWALL_PATTERNS.some((p) => finalText.includes(p))) {
+            return {
+                success: false,
+                error: `onboarding_blocked: ${task.service}'s API key sits behind a billing or ` +
+                    `payment-method wall the bot will not cross — finish the signup manually.`,
+                steps,
+                ...this.resultTail(),
+            };
+        }
+        return {
+            success: false,
+            error: `oauth_onboarding_failed: signed in to ${task.service} via ${provider.label} but ` +
+                `could not reach an API key through post-OAuth onboarding.`,
+            steps,
+            ...this.resultTail(),
+        };
+    }
+    // Build a terminal SignupResult for an aborted OAuth run. `prefix`
+    // is the error tag provision-any.ts maps to a tool status
+    // (needs_login, oauth_consent_needs_review).
+    oauthAbort(prefix, detail, steps) {
+        steps.push(`OAuth aborted (${prefix}): ${detail}`);
+        return {
+            success: false,
+            error: `${prefix}: ${detail}`,
+            steps,
+            ...this.resultTail(),
+        };
+    }
+    // Backstop for the critical guarantee (D4): true when the active
+    // provider page carries a credential-entry field — an expired/missing
+    // session dropped the bot on a login form. A genuine consent screen
+    // or account chooser has buttons/tiles only, no text inputs.
+    async oauthLoginFormPresent() {
+        const inv = await this.browser.extractInteractiveElements();
+        return inv.some((e) => e.tag === "input" &&
+            (e.type === "email" ||
+                e.type === "password" ||
+                e.type === "text" ||
+                e.type === "tel" ||
+                e.type === null));
+    }
     // ------------ Claude planner ------------
     async planSignupForm(input) {
         const systemPrompt = `You plan how to fill a web signup form.
@@ -1147,28 +1423,47 @@ ${formatInventory(input.inventory)}`,
         }
         throw lastErr ?? new Error("verification email did not arrive in time");
     }
-    // After verification, drive the browser toward the API key. Each round
-    // asks Claude what to do next given the current page; we stop when
-    // Claude says "done" or when we extract a credential. Bounded by
-    // maxRounds so a confused agent can't burn the whole context window.
+    // Drive the browser toward the API key after the account exists —
+    // used by BOTH the email-verification path and the OAuth path (T9).
+    // Each round asks Claude what to do next given the current page; we
+    // stop when Claude says "done" or when we extract a credential.
+    // Bounded by maxRounds so a confused agent can't burn the context.
+    //
+    // T9 — decoupled from email+password. `credentials` is present only
+    // on the email-verification path, where the loop may need to sign in
+    // with the just-created account (SendPulse). On the OAuth path it is
+    // absent: there is no password, and the Google session already
+    // authenticated the user — a `login` step is then a no-op.
     async postVerifyLoop(args) {
         let credentials = await this.extractCredentials();
         let loginAttempts = 0;
+        const oauth = args.credentials === undefined;
+        // Re-plan hint for the next round — set when an `extract` step
+        // found no key, which means the visible key text is masked /
+        // truncated (the S3-class trap: the planner sees a key-shaped
+        // string and keeps asking to extract it forever).
+        let hint;
         for (let round = 0; round < args.maxRounds; round++) {
             if (credentials.api_key !== undefined || credentials.username !== undefined) {
                 args.steps.push(`Post-verify: credentials found on round ${round}.`);
                 return credentials;
             }
             const state = await this.browser.getState();
+            // DOM-grounded inventory so the planner picks verified selectors
+            // instead of inventing CSS that never resolves. A dashboard has
+            // far more nav links than a signup form, so the button cap is
+            // widened (the "API Keys"/"Settings" links must survive ranking).
+            const inventory = await this.buildInventory(args.steps, undefined, 80);
             let nextStep;
             try {
                 nextStep = await this.planPostVerifyStep({
                     service: args.service,
-                    email: args.email,
-                    password: args.password,
                     round,
                     maxRounds: args.maxRounds,
                     state,
+                    oauth,
+                    inventory,
+                    ...(hint !== undefined ? { hint } : {}),
                 });
             }
             catch (err) {
@@ -1178,9 +1473,20 @@ ${formatInventory(input.inventory)}`,
             args.steps.push(`Post-verify ${round + 1}/${args.maxRounds}: ${nextStep.kind} — ${nextStep.reason}`);
             if (nextStep.kind === "done")
                 break;
+            hint = undefined;
             try {
                 if (nextStep.kind === "extract") {
                     credentials = await this.extractCredentials();
+                    if (credentials.api_key === undefined) {
+                        // The planner saw a key-shaped string but extraction got
+                        // nothing — the on-page key is masked/truncated. Steer the
+                        // next round off `extract` and toward creating a fresh key.
+                        hint =
+                            "Your last 'extract' found NO key — the key text on the page is " +
+                                "masked or truncated (e.g. shows '...' or dots). A masked existing " +
+                                "key cannot be extracted. Click 'Create API Key' / 'New API Key' to " +
+                                "generate a fresh one — its full value is shown once, on creation.";
+                    }
                 }
                 else if (nextStep.kind === "click") {
                     await this.browser.click(nextStep.selector);
@@ -1197,12 +1503,20 @@ ${formatInventory(input.inventory)}`,
                     await this.browser.wait(Math.min(nextStep.seconds, 15));
                 }
                 else if (nextStep.kind === "login") {
-                    if (loginAttempts >= 2) {
+                    if (args.credentials === undefined) {
+                        // OAuth run — no password to give, and the Google session
+                        // already authenticated us. Treat `login` as a no-op note.
+                        args.steps.push("Post-verify: planner asked to log in, but this is an OAuth run — " +
+                            "already authenticated via Google; skipping.");
+                    }
+                    else if (loginAttempts >= 2) {
                         args.steps.push("Post-verify: already attempted login twice — stopping.");
                         break;
                     }
-                    loginAttempts += 1;
-                    await this.loginWithCredentials(args.email, args.password, args.steps);
+                    else {
+                        loginAttempts += 1;
+                        await this.loginWithCredentials(args.credentials.email, args.credentials.password, args.steps);
+                    }
                 }
             }
             catch (err) {
@@ -1253,27 +1567,49 @@ ${formatInventory(input.inventory)}`,
     }
     async planPostVerifyStep(input) {
         const visibleText = (input.state.html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim()).slice(0, 2500);
-        const systemPrompt = `You are driving a headless browser after a SaaS signup verification.
+        const loginGuidance = input.oauth
+            ? `- You are ALREADY signed in via Google — NEVER return {"kind":"login"}. If the page looks like a login wall, return {"kind":"navigate"} to the service's dashboard, or {"kind":"done"}.`
+            : `- If the page is a LOGIN form, or says you must sign in, or you've been signed out, return {"kind":"login"} — the bot signs in with the signup email + password. Do NOT return done on a login wall.`;
+        const systemPrompt = `You are driving a headless browser after a SaaS signup ${input.oauth ? "via Google OAuth" : "verification"}.
 Your goal: surface the user's API key (or any credential — token, secret, app id) so it can be extracted from the page.
 
 You may issue ONE step per turn. Reply with a single JSON object, no prose.
 
+You are given a screenshot and an INVENTORY of the page's interactive
+elements — each line ends with a precise \`selector=\` the bot has
+verified resolves.
+
 Schema:
   {"kind":"done","reason":"why we should stop"}
   {"kind":"extract","reason":"the API key is now visible on this page"}
   {"kind":"login","reason":"the page is a login form / we were signed out"}
-  {"kind":"click","selector":"CSS","reason":"e.g. dismiss onboarding modal / open API keys page"}
-  {"kind":"fill","selector":"CSS","value":"value","reason":"unusual — only for required project-name etc."}
-  {"kind":"navigate","url":"https://...","reason":"e.g. go directly to /settings/api"}
+  {"kind":"click","selector":"<a selector= copied verbatim from the inventory>","reason":"e.g. open the API keys page"}
+  {"kind":"fill","selector":"<a selector= from the inventory>","value":"value","reason":"unusual — only for a required project-name etc."}
+  {"kind":"navigate","url":"https://...","reason":"e.g. go directly to /settings/api-keys"}
   {"kind":"wait","seconds":N,"reason":"page is still loading"}
 
+- CRITICAL: every "selector" in a click/fill step MUST be copied
+  verbatim from a \`selector=\` field in the inventory below. Never
+  invent or guess a selector — one not in the inventory is rejected.
+- If the element you want is NOT in the inventory, use {"kind":"navigate"}
+  to a likely settings URL instead of guessing a selector.
+
 Strategy:
-- If the API key text is visible, return {"kind":"extract"}.
-- If there's a dashboard menu link like "API Keys" / "Tokens" / "Developer", click it.
-- If there's an onboarding modal blocking, dismiss it.
-- If the page is a LOGIN form, or says you must sign in, or you've been signed out, return {"kind":"login"} — the bot signs in with the signup email + password. Do NOT return done on a login wall.
+- If a FULL, untruncated API key is visible, return {"kind":"extract"}.
+- A key shown masked or truncated (with "...", dots, or "•") is NOT
+  extractable — its full value is shown only once, at creation. Do NOT
+  return "extract" for a masked key, and do not return "extract" twice
+  in a row. Instead click "Create API Key" / "New API Key" / "Generate"
+  to make a fresh key, then extract its full value.
+- To reach API keys, prefer a {"kind":"navigate"} straight to the
+  service's API-keys settings URL — note these usually live under the
+  user/ACCOUNT settings, not a project or workspace's settings.
+- Otherwise click a dashboard menu link like "API Keys" / "Tokens" /
+  "Developer" / "Settings" — using its inventory selector.
+- If there's an onboarding modal or a "Skip" link blocking, dismiss it.
+${loginGuidance}
 - If we're on a "verify your phone" / "verify email" wall, return done (we can't solve those).
-- If the page wants the user to create a project before showing keys, fill the minimum and click create.
+- If the page wants the user to create a project/key before showing it, fill the minimum and click create.
 - Round ${input.round + 1} of ${input.maxRounds}. Prefer "done" if you're not making progress.`;
         const userBlocks = [
             { kind: "image", media_type: "image/png", data_base64: input.state.screenshot },
@@ -1285,14 +1621,19 @@ Title: ${input.state.title}
 Round: ${input.round + 1}/${input.maxRounds}
 
 Visible text (truncated):
-${visibleText}`,
+${visibleText}
+
+Interactive element inventory:
+${formatInventory(input.inventory)}${input.hint !== undefined ? `\n\nIMPORTANT — ${input.hint}` : ""}`,
             },
         ];
+        // The planner may only pick click/fill selectors the bot supplied.
+        const allowed = new Set(input.inventory.map((e) => e.selector));
         return this.callLLM({
             system: systemPrompt,
             userBlocks,
             maxTokens: 500,
-            parse: parsePostVerifyStep,
+            parse: (raw) => parsePostVerifyStep(raw, allowed),
         });
     }
     async findSignupLink() {
@@ -1313,13 +1654,29 @@ ${visibleText}`,
         return null;
     }
     async extractCredentials() {
-        // IMPORTANT: pull credentials from the *visible* page text, not the raw
+        // IMPORTANT: pull credentials from the *visible* page, not the raw
         // HTML. Reading from HTML matches anti-bot challenge JS (Cloudflare
-        // Turnstile, hCaptcha) whose challenge tokens look like API keys to a
-        // naive regex.
-        const text = await this.browser.extractText();
+        // Turnstile, hCaptcha) whose challenge tokens look like API keys to
+        // a naive regex.
+        //
+        // Two visible surfaces, in priority order:
+        //   1. Discrete credential candidates — copy-input values and each
+        //      element's own direct text. A key is read whole here, un-glued
+        //      from adjacent buttons; captcha tokens (hidden inputs) are
+        //      excluded by the browser.
+        //   2. The whole visible body text — fallback for a key shown as
+        //      plain prose, accepting that body concatenation can glue
+        //      neighbours (the extractApiKeyFromText guards catch the worst).
         const credentials = {};
-        const apiKey = extractApiKeyFromText(text);
+        let apiKey = null;
+        for (const candidate of await this.browser.extractCredentialCandidates()) {
+            apiKey = extractApiKeyFromText(candidate);
+            if (apiKey !== null)
+                break;
+        }
+        if (apiKey === null) {
+            apiKey = extractApiKeyFromText(await this.browser.extractText());
+        }
         if (apiKey !== null)
             credentials.api_key = apiKey;
         return credentials;