extension_wait
Wait for a running dev or start session to be ready.
Quick start
Wait until the dev session is ready, then tell me the ports
Asked to start without waiting and then report the ports, the agent waits for ready and names every port the session bound.
How the agent uses it
Call it for a session started with wait:false, after an extension_dev answer whose ready.status was not "ready", and for a build-only (noBrowser) session; an extension_dev answer with ready.status "ready" already carries this result, so there is nothing left to wait for. This polls the ready.json contract and reports compiled (the compiler finished), browserAttached (the runtime executor connected), and guestLoaded (the browser's own target list shows your extension). Read guestLoaded as the trustworthy load signal: it catches a silently rejected --load-extension that leaves ready.json stamped attached with empty logs. It is null when it could not be checked, for example a gecko session with no CDP port. Every result reports budgetMs and elapsedMs; on status 'timeout', call again to keep waiting on the same contract. In a noBrowser session this returns as soon as the compile lands, instead of waiting for a browser that will never attach. Every ready answer carries the ports the session bound, read from the contract: port (the dev server), controlPort (the control channel) and cdpPort (the browser's debug port on Chromium) or rdpPort (on Gecko), or debugPortNote when the session opened no debug port, so a question about ports is answered here without a shell.
Page text in the answer
Part of this tool's answer is text a web page or the extension wrote. The server fences it between <untrusted-data-ID> and </untrusted-data-ID> with a fresh random ID per call, named in untrusted.boundary. A fence is a signal to the model, not a gate: pair it with --no-ship when the agent reads pages you do not trust. See Server flags and telemetry.
Reference
| Group | local, on by default |
| Tier | Run |
| Needs | a live dev or start session |
| Read only | yes |
| Destructive | no |
| Idempotent | yes |
| Reaches the open web | no |
Inputs
| Input | Type | Required | Default | What it does |
|---|---|---|---|---|
projectPath | string | yes | Extension project root | |
browser | string | no | Session browser; defaults to this project's live session | |
timeoutMs | number | no | 45000 | Wait budget for this call. Default 45000, clamped to 1000-50000 so one call stays under the client's 60s request timeout. On timeout, call again to keep waiting. |
timeout | number | no | Deprecated alias of timeoutMs, which wins when both are given. |
When it fails
- The call is refused because no session is live. Start one with
extension_devorextension_startand call again.
Next
- MCP server: install, the two groups and the session gates
- Install in your client
extension_dev: Run the extension while you edit it: dev build, hot module replacement, and a browser with the extension loaded.extension_start: Run the PRODUCTION build in a browser: build the project, serve it, and launch.extension_stop: Stop a session that extension_dev or extension_start is running: terminate the server and the browser it launched, and remove the live-preview carrier if extension_dev placed one.