Unverified Commit b2320c04 authored by dan's avatar dan Committed by GitHub

[next-dev-loop] Fix some papercuts (#95153)

Alternative to https://github.com/vercel/next.js/pull/95135.

## Summary

This fixes a bunch of papercuts I discovered by running this skill
repeatedly and analyzing logs:

- Set the min version to
https://github.com/vercel-labs/agent-browser/pull/1483 which fixes
`--wait`.
- Push the agent to read the docs so it doesn't guess browser commands
incorrectly.
- Ask agent to derive session name from CWD so that it doesn't conflict
for git worktrees or same-named directories.
- Explain the daemon warning better so the agent doesn't restart
sessions for no reason.
- The `mcp` prefix was confusing the agent and it was invoking the
commands wrong.
- Add a few more gotchas that the agent often runs into.

## Test Plan

### Harness

I've been running this in an eval that runs a small next project and
navigates around it. The eval penalizes the score if the log shows the
agent stumbling, waiting unnecessarily, getting errors, etc. This
version was most successful so far:

<img width="801" height="78" alt="Screenshot 2026-06-25 at 05 14 43"
src="https://github.com/user-attachments/assets/9c1c8744-2fe9-4c88-ab49-a44966f7515d"
/>

### Real Project

I've also tried it with a real project as a part of CC migration skill.
It started the browser and later was able to talk via MCP and do edits
seemingly without problems. More real testing would be nice — I don't
have much experience with skills.

---------
Co-authored-by: 's avatarJude Gao <jude.gao@vercel.com>
parent be2104ae
...@@ -22,7 +22,9 @@ You verify through two views of the same running app: ...@@ -22,7 +22,9 @@ You verify through two views of the same running app:
`tools/list` for the current surface. `tools/list` for the current surface.
- **`agent-browser`** — a CLI that drives a real Chrome. Knows - **`agent-browser`** — a CLI that drives a real Chrome. Knows
framework-agnostic browser things: DOM, console, network, React framework-agnostic browser things: DOM, console, network, React
fiber, vitals. Run `agent-browser --help` for the current surface. fiber, vitals. Before driving it, run `agent-browser skills get core`
once for the version-matched usage guide — don't guess subcommands
from memory.
The two views cross-check each other. The two views cross-check each other.
...@@ -30,7 +32,8 @@ The two views cross-check each other. ...@@ -30,7 +32,8 @@ The two views cross-check each other.
- Next.js **16.3+** with **Turbopack** — `/_next/mcp` plus the - Next.js **16.3+** with **Turbopack** — `/_next/mcp` plus the
proactive compile check via `get_compilation_issues`. proactive compile check via `get_compilation_issues`.
- `agent-browser` **>= 0.27.0** — when React introspection landed. - `agent-browser` **>= 0.30.1** — React introspection plus `wait --url`
matching full dev-server URLs.
These are hard floors, not soft preferences. If anything is missing, These are hard floors, not soft preferences. If anything is missing,
tell the user how to upgrade and stop. Don't fall back to grepping tell the user how to upgrade and stop. Don't fall back to grepping
...@@ -51,16 +54,20 @@ Once per session, confirm both views are live. ...@@ -51,16 +54,20 @@ Once per session, confirm both views are live.
1. **Open `agent-browser` at the target URL, restoring saved 1. **Open `agent-browser` at the target URL, restoring saved
login state when present.** Build the `open` command from: login state when present.** Build the `open` command from:
- `--session <name>` where `<name>` is the project - `--session <name>` — you'll reuse this exact name on every later
directory basename. `agent-browser` command, so make it unique to this checkout and
stable. Build it from a fixed formula so it never varies between
calls: `"$(basename "$PWD")-$(pwd -P | shasum | cut -c1-8)"`. The
bare basename collides across parallel worktrees or copies.
- `--state ~/.agent-browser/sessions/<name>-default.json` if - `--state ~/.agent-browser/sessions/<name>-default.json` if
that file exists. Omit on first run — a missing path fails that file exists. Omit on first run — a missing path fails
the open. the open.
- `--headed --enable react-devtools`. **If the `agent-browser` - `--headed --enable react-devtools` — always pass both on `open`.
daemon is already running from a previous session**, launch A running daemon won't reapply launch flags, so you will often see
flags like `--headed` are ignored and a warning is printed `⚠ --headed ignored: daemon already running`; that's expected.
(`⚠ --headed ignored: daemon already running`). To change Assuming you always run the daemon with these flags, you can ignore
them, run `agent-browser close` first, then re-open. this warning. Only if you're sure the flags of the running daemon
are wrong, you may run `agent-browser close` first, then re-open.
The browser is the user's. If state was not restored (first The browser is the user's. If state was not restored (first
run, expired session) and the page is gated, the user drives run, expired session) and the page is gated, the user drives
...@@ -69,17 +76,16 @@ Once per session, confirm both views are live. ...@@ -69,17 +76,16 @@ Once per session, confirm both views are live.
open, and `cookies set` on a not-yet-opened session creates a open, and `cookies set` on a not-yet-opened session creates a
sessionless cookie that silently fails to apply. sessionless cookie that silently fails to apply.
2. POST `tools/list` to `/_next/mcp`. Send 2. Probe `/_next/mcp` (`tools/list`) — confirm it's reachable and
`Accept: application/json, text/event-stream`; responses are lists `get_compilation_issues`:
SSE-framed, strip the `data: ` prefix before parsing JSON.
- Unreachable → either `next dev` isn't running, or Next.js is - Unreachable → either `next dev` isn't running, or Next.js is
below 16.3. Check `package.json` to disambiguate, then refuse. below 16.3. Check `package.json` to disambiguate, then refuse.
- `get_compilation_issues` not in the list → Next.js below 16.3. - `get_compilation_issues` not in the list → Next.js below 16.3.
Refuse and tell the user to upgrade. Refuse and tell the user to upgrade.
3. `mcp get_compilation_issues` doubles as a Turbopack probe. 3. `get_compilation_issues` doubles as a Turbopack probe. An error
An error response of `"Turbopack project is not available..."` response of `"Turbopack project is not available..."` means the
means the user is on webpack. Refuse — Turbopack is required. user is on webpack. Refuse — Turbopack is required.
4. `mcp get_routes` → your route map for the rest of the session. 4. `get_routes` → your route map for the rest of the session.
## loop ## loop
...@@ -94,7 +100,7 @@ search doesn't. ...@@ -94,7 +100,7 @@ search doesn't.
Four failure modes. Check each: Four failure modes. Check each:
- **Compiles** — `mcp get_compilation_issues`. - **Compiles** — `get_compilation_issues`.
- **Runs without errors** — `/_next/mcp` (server and bubbled-up - **Runs without errors** — `/_next/mcp` (server and bubbled-up
browser errors both surface here). browser errors both surface here).
- **Behaves as intended** — `agent-browser` drives the page; assert - **Behaves as intended** — `agent-browser` drives the page; assert
...@@ -105,12 +111,38 @@ Four failure modes. Check each: ...@@ -105,12 +111,38 @@ Four failure modes. Check each:
server/client boundary shifts, suspense fallbacks) — DOM asserts server/client boundary shifts, suspense fallbacks) — DOM asserts
alone miss them. alone miss them.
Pick the specific tool from `tools/list` or `agent-browser Pick the specific tool from `tools/list` or the agent-browser
--help` rather than from memory. manual rather than from memory.
## gotchas ## gotchas
- **Every `agent-browser` command must know your session, or it
silently uses a different, empty default browser (blank reads; a
working page looks broken).** Easiest: `export
AGENT_BROWSER_SESSION=<name>` at the top of each shell you run
agent-browser in; then every command there uses it, with no
per-command `--session` flag to repeat.
- **When the two views disagree, suspect the tooling first.** If
`agent-browser` says a route is broken but `/_next/mcp` and the
server say it rendered cleanly, a stale or misdirected browser
session is the likelier cause than a real bug — reconcile the views
before debugging the app.
- Confirming a click or navigation: the page settles a beat later, so
wait with `wait --load networkidle` (no path to get wrong), then
snapshot/read to confirm the page. Avoid `wait --url` unless you pass
the link's exact href — a guessed or placeholder path won't match the
real URL and times out after 25s.
- A blank read, empty snapshot, `about:blank`, or a "no browser
session" error — right after `open` or after a click (even if `open`
reported the page) — is the browser dropping the page (a stale
daemon), not a broken route. Reopen your session at the URL and
re-snapshot; if still blank, run `agent-browser --session <name>
close`, then open again. Don't fall back to `curl`; it bypasses the
browser you're testing.
- React introspection output is stale after navigation. Re-run. - React introspection output is stale after navigation. Re-run.
- `/_next/mcp` replies are SSE — read the JSON off the `data:` line
with `sed -n 's/^data: //p'` (a plain `sed 's/^data: //'` leaves the
`event:` line and the parse fails).
- Non-3000 dev server: read the `next dev` banner; set - Non-3000 dev server: read the `next dev` banner; set
`NEXT_MCP_URL=http://localhost:<port>/_next/mcp`. `NEXT_MCP_URL=http://localhost:<port>/_next/mcp`.
- `get_errors` and `get_page_metadata` need at least one navigation - `get_errors` and `get_page_metadata` need at least one navigation
...@@ -139,9 +171,10 @@ get_compilation_issues Turbopack only; errors on webpack ...@@ -139,9 +171,10 @@ get_compilation_issues Turbopack only; errors on webpack
## teardown ## teardown
Close the `agent-browser` session — `--session` writes state Close the session: `agent-browser --session <name> close` — the same
to disk so the next loop's `--state` restores login. Leave `--session` every command used. `close` writes that session's state to
`next dev` up for the next loop. disk so the next loop's `--state` restores login. Leave `next dev` up
for the next loop.
--- ---
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment