Skills/agent-browser-browserless-openai-signup-smoke/SKILL.md

---
name: agent-browser-browserless-openai-signup-smoke
description: Connect Agent Browser to Browserless or Browser Use CDP and automate OpenAI web flows. Use when Codex needs to (1) smoke-test ChatGPT signup from `chatgpt.com` through email/password/email-verification, or (2) drive an OpenAI OAuth authorize URL through login, email verification, Codex consent, and capture the final `localhost` callback URL. Includes Browserless troubleshooting notes, a Browser Use fallback workflow, and reusable Python helper scripts.
---

# Agent Browser CDP Flows

## Overview

Use this skill for two validated Agent Browser workflows:

- Browserless stealth CDP for ChatGPT signup smoke tests.
- Browser Use cloud browser + Agent Browser CDP attachment for OpenAI OAuth callback capture.

Prefer the Browser Use workflow for the OAuth callback task. It was more stable than Browserless for the final `localhost` redirect.

## Quick Start

### Browserless signup smoke

- Export `BROWSERLESS_TOKEN`.
- Run `python3 skills/agent-browser-browserless-openai-signup-smoke/scripts/openai_signup_smoke.py`.
- Use a non-deliverable but syntactically valid test email such as an `example.com` address.
- Prefer a fresh email alias on each run; reusing the same fake address can route the flow to `log-in/password` instead of the signup password page.
- Stop after the email-verification page unless the user explicitly asks for more.

Example:

```bash
export BROWSERLESS_TOKEN='...'
python3 skills/agent-browser-browserless-openai-signup-smoke/scripts/openai_signup_smoke.py \
  --email 'agent-browser-smoke@example.com' \
  --password 'TempPass!20260315' \
  --output /tmp/openai-signup-smoke.json
```

### Browser Use OAuth callback capture

- Install `browser-use-sdk` in a local environment.
- Export `BROWSER_USE_API_KEY`.
- Run `python3 skills/agent-browser-browserless-openai-signup-smoke/scripts/browseruse_oauth_callback.py` with the OAuth authorize URL, login email, and password.
- Omit `--code` to stop at the email-verification page.
- Add `--code ... --approve-consent` to continue through the Codex consent page and capture the final `localhost` callback URL.

Example: stop at verification

```bash
export BROWSER_USE_API_KEY='...'
python3 skills/agent-browser-browserless-openai-signup-smoke/scripts/browseruse_oauth_callback.py \
  --oauth-url 'https://auth.openai.com/oauth/authorize?...' \
  --email 'user@example.com' \
  --password 'secret' \
  --output /tmp/browseruse-oauth.json
```

Example: capture callback after receiving the email code

```bash
export BROWSER_USE_API_KEY='...'
python3 skills/agent-browser-browserless-openai-signup-smoke/scripts/browseruse_oauth_callback.py \
  --oauth-url 'https://auth.openai.com/oauth/authorize?...' \
  --email 'user@example.com' \
  --password 'secret' \
  --code '123456' \
  --approve-consent \
  --trace-path /tmp/browseruse-oauth-trace.zip \
  --output /tmp/browseruse-oauth.json
```

## Workflow A: Browserless Signup Smoke

1. Build the Browserless stealth websocket URL:
   `wss://production-sfo.browserless.io/chrome/stealth?token=...`
2. Connect Agent Browser to that websocket with a dedicated session name.
3. Open `https://chatgpt.com` and wait briefly for the homepage to stabilize.
4. Click `Sign up for free` with a role-based locator instead of brittle element references.
5. Fill a format-valid test email and submit.
6. Fill a test password and submit.
7. Read back the resulting URL, title, and interactive snapshot.
8. Treat `https://auth.openai.com/email-verification` / `Check your inbox - OpenAI` as a successful smoke-test result.

## Workflow B: Browser Use OAuth Callback Capture

1. Create a Browser Use cloud browser with the SDK.
2. Read `cdp_url` from the Browser Use session, then fetch `/json/version` to get `webSocketDebuggerUrl`.
3. Connect Agent Browser to that websocket URL.
4. Open the OpenAI OAuth authorize URL.
5. Log in with the provided email and password.
6. If no verification code is available yet, stop on `https://auth.openai.com/email-verification`.
7. When a verification code is available, submit it and wait for `https://auth.openai.com/sign-in-with-chatgpt/codex/consent`.
8. Before pressing the consent `Continue` button, route `http://localhost:1455/*` so the callback URL survives even if the upstream app is not listening.
9. Optionally start `agent-browser trace` before the consent click.
10. Click consent `Continue`, then read the full callback URL from the current page URL.

## Expected Observations

- Browserless plain CDP can stall on `Just a moment...`; Browserless stealth is better for signup smoke tests.
- Browser Use’s direct `agent-browser -p browseruse` provider path can fail, while Browser Use SDK session creation plus explicit CDP attachment works.
- Browser Use-backed Agent Browser runs were more stable than Browserless for the OAuth callback flow.
- A successful callback capture can still render a proxy or upstream error page; if the current URL begins with `http://localhost:1455/auth/callback?...`, the callback was captured successfully.
- Reused or stale verification codes show `Incorrect code` on the email-verification page.

See `references/observations.md` for the concrete results captured during testing.

## Troubleshooting

- If the title is `Just a moment...`, reconnect with the Browserless stealth endpoint.
- If Agent Browser falls back to `chrome://new-tab-page/`, discard that run and start a fresh end-to-end session.
- Use fresh verification codes quickly; they expire and cannot be replayed reliably.
- Browser Use browser creation currently accepts `timeout <= 240`.
- If the final page shows `502 Bad Gateway` or `localhost refused to connect`, inspect the current URL before assuming failure.

## Resources

- `scripts/openai_signup_smoke.py` runs the Browserless signup smoke flow and emits a machine-readable summary.
- `scripts/browseruse_oauth_callback.py` creates a Browser Use cloud browser, attaches Agent Browser via CDP, and captures OpenAI OAuth callback URLs.
- `references/observations.md` records the tested Browserless and Browser Use behavior.