[youknowriad]

Related issues

• Related to STU-2562 (behavior pass, PR 9: live preview and agent refresh)

How AI was used in this PR

Claude Code implemented the change against the rebuild reference (workspace.tsx, use-preview-navigation.ts, refresh-browser.ts), wrote the tests, ran a targeted eval, and checked the Live preview in studio ui in light and dark with an isolated config and a fake Live connection. Riad reviewed the behavior and asked for the end-of-run reload to be dropped.

Proposed Changes

• The preview follows a chat's Live environment. A chat switched to Live used to lose its preview. It now shows the connected WordPress.com site, so you see the site the agent is working on. Local-only tools stay out of the way there: no annotations, no WP Admin/Database/Design system shortcuts or auto-login, no Start/Stop, Share or Site settings. Publish stays, and Open in browser opens the live address. Switching back to Local returns to the local page you were on.
• The agent reloads the preview when it means to. A new refresh_browser tool lets the agent reload the in-app preview mid-run, after a change that alters what the site renders. The preview no longer reloads on its own at the end of every run, whatever you were doing, so this is now the only agent-driven reload, as in the rebuild. The tool exists only when a Studio UI is attached: terminal studio code sessions and studio mcp never see it.
• WP Admin is left alone, locally and on Live. A reload the agent asks for never lands on a WP Admin page you're on, so unsaved edits in the editor survive, now on the live site too.

Testing Instructions

Run npm run cli:build:ui && node apps/cli/dist/cli/main.mjs ui --no-open (or the Desktop app) with a local site connected to a WordPress.com site.

1. In a chat on that site, open + › Work on live site: the preview shows the live site and its address. Annotate, Start/Stop and Share are gone; Publish stays. Clicking the address field opens no shortcuts. In a narrow window, the More menu holds Back, Forward, Reload preview and Open in browser only.
2. Type a path in the address field: it loads on the live site. Switch back to Local: the local preview returns at its own page.
3. Stop the local site while the chat is on Live: the live preview stays.
4. On a local chat, ask for a change: the preview reloads when the agent calls refresh_browser, not when the turn ends.
5. Open WP Admin in the preview, then ask for a change: the editor isn't reloaded under you.
6. Repeat 1 in light and dark.

Evals: npm run eval -- --filter-pattern "asking for a site leaves a working new site" passes. The eval runner attaches no UI, so refresh_browser isn't registered there and its prompt is unchanged; the tool is covered by unit tests on both ends.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

🤖 Generated with Claude Code

[chubes4]

I had removed the refresh_browser tool in #5171. This feels like something that the app should handle instead of the agent. The challenge is knowing when the refresh is needed.

[wpmobilebot]

📊 Performance Test Results

Comparing 15d58ee vs trunk

app-size

Metric	trunk	15d58ee	Diff	Change
App Size (Mac)	945.67 MB	943.25 MB	2.43 MB	🟢 -0.3%

site-editor

Metric	trunk	15d58ee	Diff	Change
load	1176 ms	1232 ms	+56 ms	🔴 4.8%

site-startup

Metric	trunk	15d58ee	Diff	Change
siteCreation	6491 ms	6514 ms	+23 ms	⚪ 0.0%
siteStartup	2875 ms	2875 ms	0 ms	⚪ 0.0%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[youknowriad]

Yes, and for me that was a regression. the preview was reloading constantly as I was chatting with the agent and it was disorienting.

[chubes4]

Could we fine-tune the timing of the refresh rather than handing it back to the agent?

Call it after a change that alters what the site renders (content, settings, theme, plugins).

I'm hoping to move this directive into code. It also reduces branching between the app and the CLI, since it is only needed when the app is open.

[youknowriad]

I don't know how to do that without too much complexity. I'd rather keep things simple for now. I understand the need to be more and more deterministic but I think we should balance that with the complexity of our tools and their interdependencies. The tools become way too specific if we go in this direction.

[youknowriad]

One potential thing we could that (and that we had at some point in the past) is make the agent create "artifacts" which are like generic checkpoints, and the app/mcp... whatever consumer of the agent can decide what to do for these artifacts. For me that keeps a clean separation between agent knowledge and app feedback

[chubes4]

Yeah, I went overboard with the reloads, sorry about that. I agree the complexity can balloon. I tried a few approaches and went with something minimal instead. If you want to punt removing refresh_browser for now, that makes sense to me.

Using artifacts could be interesting, but it shouldn't be the agent's responsibility to set them, or we will have the same problem as refresh_browser.

One idea that I considered was using metadata provided by the tools so the app would know when it needs to refresh based on which tools were used. This seems like the most promising direction for a long term solution to me.

[youknowriad]

One idea that I considered was using metadata provided by the tools so the app would know when it needs to refresh based on which tools were used. This seems like the most promising direction for a long term solution to me.

I like that, the problem I see though is that some of our tools are too broad (like wp cli), which wp CLI tool is going to need a refresh is very hard to define. Same for any broad tool like wpcom_request ...

[youknowriad]

I'm merging this PR for now and we can see how we can improve that over time.