Unverified Commit a86d36b5 authored by vercel[bot]'s avatar vercel[bot] Committed by GitHub

Add experimental.agentHmrBatching: hold HMR during an agent's multi-step edit

An AI coding agent edits in many small steps, so the dev server compiles and
pushes an HMR update per step and the browser preview walks through every
half-finished intermediate state. The compile errors from those states land in
the browser's error overlay, in front of a person, instead of going back to the
agent that can still fix them.

This adds an agent-scoped batch. While one is open, every HMR message that would
change what the browser renders is held instead of delivered, so the preview
stays on the last output that compiled. Closing the batch waits for the
compilation to settle and then either flushes the held messages as one coalesced
update, or — when the code does not compile — leaves the preview alone and
returns the errors to the caller, keeping the queue so the next clean compile
releases it.

Batches are opened and closed with three new MCP tools (begin_hmr_batch,
end_hmr_batch, get_hmr_batch_status), registered only when the flag is set. With
no batch open, every message takes exactly the path it took before.
Co-Authored-By: 's avatarJude Gao <32973745+gaojude@users.noreply.github.com>
parent 30e73d2d
---
title: agentHmrBatching
description: Let an AI coding agent group a multi-step edit into a single HMR update, and receive compile errors itself instead of showing them in the browser.
version: experimental
---
An AI coding agent edits a project in many small steps: rename a component, then
update its call sites, then add the prop it now needs. Each write is a file
change, so the dev server compiles it and pushes an HMR update, and the preview
in the browser walks through every intermediate state — including the ones that
only make sense half-finished. Meanwhile the compile errors from those states
land in the browser's error overlay, in front of a person, rather than going back
to the agent that can still fix them.
`experimental.agentHmrBatching` lets the agent group those steps into one update.
```js filename="next.config.js"
module.exports = {
experimental: {
// Batches are opened and closed through MCP tools, so the MCP server has to
// be enabled too (it is, by default).
mcpServer: true,
agentHmrBatching: true,
},
}
```
## How it works
The agent wraps a multi-step edit in a batch:
1. `begin_hmr_batch` — from here on, every HMR message that would change what the
browser is rendering is held back instead of delivered, so the preview keeps
showing the last output that compiled.
2. The agent writes as many files as the change needs. The dev server compiles
each write as usual; only the delivery to the browser waits.
3. `end_hmr_batch` — waits for the compilation to settle, then either:
- **`status: "flushed"`** — the code compiles. The held messages are delivered
as one coalesced update, so the preview goes straight from the last good
state to the new one without rendering anything in between.
- **`status: "withheld"`** — the code does not compile. Nothing is delivered,
the preview stays on the last good state, and the errors are returned in the
tool result. They are the agent's to fix; the held updates stay queued and
are delivered once the code compiles again.
`get_hmr_batch_status` reports whether a batch is open, how much it is holding,
and the errors from the most recent compilation.
With no batch open, HMR behaves exactly as it does with this option off.
## Reading an `end_hmr_batch` result
| Field | Meaning |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | `flushed`, `withheld`, or `no-batch`. |
| `compiled` | Whether a compile result was observed at all. When `false`, an empty `errors` means the edit never reached the bundler — not that it is valid. |
| `errors` | Compilation errors as of the end of the batch. |
| `heldMessageCount` | How many HMR messages the batch was holding when it closed. |
| `previewPreserved` | `false` if the batch held so many messages that they had to be released early, so the preview did briefly move. |
| `timedOut` | The batch was closed by the dev server because it stayed open past its timeout, not by the agent. |
## Good to know
- A batch has a timeout (30 seconds by default, set per batch with `timeoutMs`).
An agent that exits without closing its batch does not leave the preview frozen:
the dev server closes it and releases the held updates.
- Batches do not nest. Opening one while another is open returns the open batch.
- Batching holds back HMR pushes to already-connected clients. It does not freeze
the server: a reload or a new navigation during a batch renders the current
state of the code, half-finished or not.
...@@ -311,6 +311,7 @@ export const experimentalSchema = { ...@@ -311,6 +311,7 @@ export const experimentalSchema = {
proxyTimeout: z.number().gte(0).optional(), proxyTimeout: z.number().gte(0).optional(),
rootParams: z.boolean().optional(), rootParams: z.boolean().optional(),
mcpServer: z.boolean().optional(), mcpServer: z.boolean().optional(),
agentHmrBatching: z.boolean().optional(),
removeUncaughtErrorAndRejectionListeners: z.boolean().optional(), removeUncaughtErrorAndRejectionListeners: z.boolean().optional(),
validateRSCRequestHeaders: z.boolean().optional(), validateRSCRequestHeaders: z.boolean().optional(),
scrollRestoration: z.boolean().optional(), scrollRestoration: z.boolean().optional(),
......
...@@ -1463,6 +1463,24 @@ export interface ExperimentalConfig { ...@@ -1463,6 +1463,24 @@ export interface ExperimentalConfig {
*/ */
mcpServer?: boolean mcpServer?: boolean
/**
* Let an AI coding agent group a multi-step edit into a single HMR update.
*
* While a batch is open, the dev server holds back every HMR message that
* would change what the browser is rendering, so the preview keeps showing
* the last output that compiled instead of walking through each half-finished
* intermediate step. Closing the batch either delivers the held messages as
* one update, or — if the code does not compile — leaves the preview alone
* and hands the errors back to the agent.
*
* Batches are opened and closed through the `begin_hmr_batch` /
* `end_hmr_batch` MCP tools, so this also requires `mcpServer`. With no batch
* open, HMR behaves exactly as it does with this option off.
*
* @default false
*/
agentHmrBatching?: boolean
/** /**
* Acquires a lockfile at `<distDir>/lock` when starting `next dev` or `next * Acquires a lockfile at `<distDir>/lock` when starting `next dev` or `next
* build`. Failing to acquire the lock causes the process to exit with an * build`. Failing to acquire the lock causes the process to exit with an
...@@ -2336,6 +2354,7 @@ export const defaultConfig = Object.freeze({ ...@@ -2336,6 +2354,7 @@ export const defaultConfig = Object.freeze({
proxyClientMaxBodySize: 10_485_760, // 10MB proxyClientMaxBodySize: 10_485_760, // 10MB
hideLogsAfterAbort: false, hideLogsAfterAbort: false,
mcpServer: true, mcpServer: true,
agentHmrBatching: false,
turbopackFileSystemCacheForDev: true, turbopackFileSystemCacheForDev: true,
turbopackFileSystemCacheForBuild: true, turbopackFileSystemCacheForBuild: true,
turbopackInferModuleSideEffects: true, turbopackInferModuleSideEffects: true,
......
This diff is collapsed.
This diff is collapsed.
...@@ -30,6 +30,7 @@ import type { HmrMessageSentToBrowser } from './hot-reloader-types' ...@@ -30,6 +30,7 @@ import type { HmrMessageSentToBrowser } from './hot-reloader-types'
import { HMR_MESSAGE_SENT_TO_BROWSER } from './hot-reloader-types' import { HMR_MESSAGE_SENT_TO_BROWSER } from './hot-reloader-types'
import { devIndicatorServerState } from './dev-indicator-server-state' import { devIndicatorServerState } from './dev-indicator-server-state'
import { createBinaryHmrMessageData } from './messages' import { createBinaryHmrMessageData } from './messages'
import { getAgentHmrBatchController } from './agent-hmr-batch'
import type { NextConfigComplete } from '../config-shared' import type { NextConfigComplete } from '../config-shared'
import { import {
getRequestInsightsSnapshot, getRequestInsightsSnapshot,
...@@ -82,6 +83,13 @@ export class WebpackHotMiddleware { ...@@ -82,6 +83,13 @@ export class WebpackHotMiddleware {
private middlewareLatestStats: { ts: number; stats: webpack.Stats } | null = private middlewareLatestStats: { ts: number; stats: webpack.Stats } | null =
null null
private serverLatestStats: { ts: number; stats: webpack.Stats } | null = null private serverLatestStats: { ts: number; stats: webpack.Stats } | null = null
/**
* Agent-scoped HMR batching. Inert unless an agent has opened a batch; see
* `./agent-hmr-batch.ts`.
*/
private agentHmrBatch = getAgentHmrBatchController()
/** Compilers whose invalidation has not finished compiling yet. */
private invalidatedCompilers = new Set<number>()
constructor( constructor(
compilers: webpack.Compiler[], compilers: webpack.Compiler[],
...@@ -90,6 +98,22 @@ export class WebpackHotMiddleware { ...@@ -90,6 +98,22 @@ export class WebpackHotMiddleware {
private config: NextConfigComplete, private config: NextConfigComplete,
private devToolsConfig: DevToolsConfig private devToolsConfig: DevToolsConfig
) { ) {
this.agentHmrBatch.configure({
enabled: config.experimental.agentHmrBatching === true,
isCompiling: () => this.invalidatedCompilers.size > 0,
})
// Separate taps, so that tracking "is a compilation in flight" cannot
// change the early-return conditions the publishing handlers below rely on.
compilers.forEach((compiler, index) => {
compiler.hooks.invalid.tap('agent-hmr-batch', () => {
this.invalidatedCompilers.add(index)
})
compiler.hooks.done.tap('agent-hmr-batch', () => {
this.invalidatedCompilers.delete(index)
})
})
compilers[0].hooks.invalid.tap( compilers[0].hooks.invalid.tap(
'webpack-hot-middleware', 'webpack-hot-middleware',
this.onClientInvalid this.onClientInvalid
...@@ -258,12 +282,20 @@ export class WebpackHotMiddleware { ...@@ -258,12 +282,20 @@ export class WebpackHotMiddleware {
return return
} }
for (const wsClient of [ const deliver = () => {
...this.clientsWithoutHtmlRequestId, for (const wsClient of [
...this.clientsByHtmlRequestId.values(), ...this.clientsWithoutHtmlRequestId,
]) { ...this.clientsByHtmlRequestId.values(),
this.publishToClient(wsClient, message) ]) {
this.publishToClient(wsClient, message)
}
} }
if (this.agentHmrBatch.intercept(message, deliver)) {
return
}
deliver()
} }
publishToLegacyClients = (message: HmrMessageSentToBrowser) => { publishToLegacyClients = (message: HmrMessageSentToBrowser) => {
......
...@@ -137,6 +137,7 @@ import { ...@@ -137,6 +137,7 @@ import {
} from '../lib/trace/request-insights' } from '../lib/trace/request-insights'
import { resolvePathToRoute } from '../mcp/tools/utils/resolve-path-to-route' import { resolvePathToRoute } from '../mcp/tools/utils/resolve-path-to-route'
import { handleErrorStateResponse } from '../mcp/tools/get-errors' import { handleErrorStateResponse } from '../mcp/tools/get-errors'
import { getAgentHmrBatchController } from './agent-hmr-batch'
import { handlePageMetadataResponse } from '../mcp/tools/get-page-metadata' import { handlePageMetadataResponse } from '../mcp/tools/get-page-metadata'
import { setStackFrameResolver } from '../mcp/tools/utils/format-errors' import { setStackFrameResolver } from '../mcp/tools/utils/format-errors'
import { recordMcpTelemetry } from '../mcp/mcp-telemetry-tracker' import { recordMcpTelemetry } from '../mcp/mcp-telemetry-tracker'
...@@ -823,6 +824,21 @@ export async function createHotReloaderTurbopack( ...@@ -823,6 +824,21 @@ export async function createHotReloaderTurbopack(
let updateInProgress = false let updateInProgress = false
let pendingServerComponentChanges = false let pendingServerComponentChanges = false
// Agent-scoped HMR batching. Inert unless an agent has opened a batch
// through the MCP tools, which are only registered when the experimental
// flag is set. See `./agent-hmr-batch.ts`.
const agentHmrBatch = getAgentHmrBatchController()
agentHmrBatch.configure({
enabled: nextConfig.experimental.agentHmrBatching === true,
isCompiling: () => updateInProgress,
})
// The per-client message and update queues below already hold everything a
// compilation produced, so a batch flush re-drives that flush rather than
// duplicating the queue.
const disposeAgentHmrBatchResume = agentHmrBatch.onResume(() => {
sendEnqueuedMessages()
})
function sendServerComponentChanges() { function sendServerComponentChanges() {
sendHmr('server-component-changes', { sendHmr('server-component-changes', {
type: HMR_MESSAGE_SENT_TO_BROWSER.SERVER_COMPONENT_CHANGES, type: HMR_MESSAGE_SENT_TO_BROWSER.SERVER_COMPONENT_CHANGES,
...@@ -857,6 +873,13 @@ export async function createHotReloaderTurbopack( ...@@ -857,6 +873,13 @@ export async function createHotReloaderTurbopack(
return return
} }
if (agentHmrBatch.isHolding()) {
// An agent is mid-edit. Leave the messages queued so the browser keeps
// rendering the last output that compiled; closing the batch calls back
// into here to deliver them.
return
}
for (const client of [ for (const client of [
...clientsWithoutHtmlRequestId, ...clientsWithoutHtmlRequestId,
...clientsByHtmlRequestId.values(), ...clientsByHtmlRequestId.values(),
...@@ -1613,14 +1636,22 @@ export async function createHotReloaderTurbopack( ...@@ -1613,14 +1636,22 @@ export async function createHotReloaderTurbopack(
}, },
send(action) { send(action) {
const payload = JSON.stringify(action) const deliver = () => {
const payload = JSON.stringify(action)
for (const client of [ for (const client of [
...clientsWithoutHtmlRequestId, ...clientsWithoutHtmlRequestId,
...clientsByHtmlRequestId.values(), ...clientsByHtmlRequestId.values(),
]) { ]) {
client.send(payload) client.send(payload)
}
}
if (agentHmrBatch.intercept(action, deliver)) {
return
} }
deliver()
}, },
getServerComponentsHmrRefreshHash() { getServerComponentsHmrRefreshHash() {
...@@ -1970,6 +2001,8 @@ export async function createHotReloaderTurbopack( ...@@ -1970,6 +2001,8 @@ export async function createHotReloaderTurbopack(
// Report MCP telemetry if MCP server is enabled // Report MCP telemetry if MCP server is enabled
recordMcpTelemetry(opts.telemetry) recordMcpTelemetry(opts.telemetry)
disposeAgentHmrBatchResume()
for (const wsClient of [ for (const wsClient of [
...clientsWithoutHtmlRequestId, ...clientsWithoutHtmlRequestId,
...clientsByHtmlRequestId.values(), ...clientsByHtmlRequestId.values(),
...@@ -2054,27 +2087,52 @@ export async function createHotReloaderTurbopack( ...@@ -2054,27 +2087,52 @@ export async function createHotReloaderTurbopack(
addToErrorsMap(errors, currentTopLevelIssues) addToErrorsMap(errors, currentTopLevelIssues)
addErrors(errors, currentEntryIssues) addErrors(errors, currentEntryIssues)
for (const client of [ // Report the current version without advancing it: a completed
...clientsWithoutHtmlRequestId, // compilation is not itself an edit, and this hash is not consumed by
...clientsByHtmlRequestId.values(), // the Turbopack client. Read here rather than inside the send below,
]) { // so that a send an agent batch defers still reports the hash of the
const state = clientStates.get(client) // compilation it belongs to.
if (!state) { const hash = String(hmrHash)
continue
const sendBuiltToClients = () => {
for (const client of [
...clientsWithoutHtmlRequestId,
...clientsByHtmlRequestId.values(),
]) {
const state = clientStates.get(client)
if (!state) {
continue
}
const clientErrors = new Map(errors)
addErrors(clientErrors, state.clientIssues)
sendToClient(client, {
type: HMR_MESSAGE_SENT_TO_BROWSER.BUILT,
hash,
errors: [...clientErrors.values()],
warnings: [],
})
} }
}
const clientErrors = new Map(errors) // The whole fan-out is one unit as far as a batch is concerned: it
addErrors(clientErrors, state.clientIssues) // is one compilation's result, and the errors on it are what the
// batch hands back to the agent that caused them. Client-specific
sendToClient(client, { // issues are left out of that summary; they are added per client
type: HMR_MESSAGE_SENT_TO_BROWSER.BUILT, // when the message is actually delivered.
// Report the current version without advancing it: a completed if (
// compilation is not itself an edit, and this hash is not !agentHmrBatch.intercept(
// consumed by the Turbopack client. {
hash: String(hmrHash), type: HMR_MESSAGE_SENT_TO_BROWSER.BUILT,
errors: [...clientErrors.values()], hash,
warnings: [], errors: [...errors.values()],
}) warnings: [],
},
sendBuiltToClients
)
) {
sendBuiltToClients()
} }
if (hmrEventHappened) { if (hmrEventHappened) {
......
...@@ -8,6 +8,8 @@ import { registerGetRoutesTool } from './tools/get-routes' ...@@ -8,6 +8,8 @@ import { registerGetRoutesTool } from './tools/get-routes'
import { registerGetCompilationIssuesTool } from './tools/get-compilation-issues' import { registerGetCompilationIssuesTool } from './tools/get-compilation-issues'
import { registerCompileRouteTool } from './tools/compile-route' import { registerCompileRouteTool } from './tools/compile-route'
import { registerGetRequestInsightsTool } from './tools/get-request-insights' import { registerGetRequestInsightsTool } from './tools/get-request-insights'
import { registerHmrBatchTools } from './tools/hmr-batch'
import { getAgentHmrBatchController } from '../dev/agent-hmr-batch'
import type { HmrMessageSentToBrowser } from '../dev/hot-reloader-types' import type { HmrMessageSentToBrowser } from '../dev/hot-reloader-types'
import type { NextConfigComplete } from '../config-shared' import type { NextConfigComplete } from '../config-shared'
import type { Project } from '../../build/swc/types' import type { Project } from '../../build/swc/types'
...@@ -66,6 +68,10 @@ export const getOrCreateMcpServer = (options: McpServerOptions) => { ...@@ -66,6 +68,10 @@ export const getOrCreateMcpServer = (options: McpServerOptions) => {
}) })
registerGetRequestInsightsTool(mcpServer) registerGetRequestInsightsTool(mcpServer)
if (options.nextConfig.experimental.agentHmrBatching) {
registerHmrBatchTools(mcpServer, getAgentHmrBatchController)
}
if (options.getTurbopackProject) { if (options.getTurbopackProject) {
registerGetCompilationIssuesTool(mcpServer, options.getTurbopackProject) registerGetCompilationIssuesTool(mcpServer, options.getTurbopackProject)
} }
......
/**
* MCP tools for agent-scoped HMR batching.
*
* These are the only way to open and close a batch, and they are registered
* only when `experimental.agentHmrBatching` is set. See
* `../../dev/agent-hmr-batch.ts` for what a batch actually does.
*
* The intended shape of an agent's turn is:
*
* begin_hmr_batch → write files → end_hmr_batch
*
* with `end_hmr_batch` being the thing that reports whether the edit compiles.
* That is the point of the batch: the errors go to the agent that can still
* fix them, while the human watching the preview never sees the intermediate
* states.
*/
import type { McpServer } from 'next/dist/compiled/@modelcontextprotocol/sdk/server/mcp'
import z from 'next/dist/compiled/zod'
import { mcpTelemetryTracker } from '../mcp-telemetry-tracker'
import {
type AgentHmrBatchController,
DEFAULT_BATCH_TIMEOUT_MS,
MAX_BATCH_TIMEOUT_MS,
MIN_BATCH_TIMEOUT_MS,
} from '../../dev/agent-hmr-batch'
function json(value: unknown, isError?: boolean) {
return {
...(isError ? { isError: true } : null),
content: [{ type: 'text' as const, text: JSON.stringify(value) }],
}
}
export function registerHmrBatchTools(
server: McpServer,
getController: () => AgentHmrBatchController
) {
server.registerTool(
'begin_hmr_batch',
{
description:
'Open an HMR batch before making a multi-step edit. While the batch is open the dev server ' +
'holds back every HMR update, so the browser preview keeps rendering the last output that ' +
'compiled instead of flickering through each intermediate step. Always close it with ' +
'end_hmr_batch, which reports whether the finished edit compiles. ' +
'Batches do not nest: if one is already open this returns that batch instead of opening another.',
inputSchema: {
timeoutMs: z
.number()
.int()
.describe(
'How long the batch may stay open before the dev server closes it on its own, in ' +
`milliseconds (default ${DEFAULT_BATCH_TIMEOUT_MS}, clamped to ` +
`${MIN_BATCH_TIMEOUT_MS}–${MAX_BATCH_TIMEOUT_MS}). This is a safety net for an agent ` +
'that exits without closing its batch; it is not a deadline to plan edits around.'
)
.optional(),
},
},
async ({ timeoutMs }) => {
mcpTelemetryTracker.recordToolCall('mcp/begin_hmr_batch')
const result = getController().begin({ timeoutMs })
if (result.status === 'disabled') {
return json(
{
error:
'Agent HMR batching is not enabled. Set `experimental.agentHmrBatching: true` in next.config.js.',
},
true
)
}
return json(result)
}
)
server.registerTool(
'end_hmr_batch',
{
description:
'Close the HMR batch opened by begin_hmr_batch. Waits for the compilation triggered by the ' +
'edit to settle, then either delivers the held updates to the browser as a single update ' +
'(status "flushed") or, when the edit does not compile, leaves the preview on the last good ' +
'state and returns the errors (status "withheld"). A "withheld" result means the errors are ' +
'yours to fix: the held updates are still queued and are delivered once the code compiles ' +
'again. `compiled: false` means no compilation was observed at all, so an empty error list ' +
'says nothing about whether the code is valid.',
inputSchema: {},
},
async () => {
mcpTelemetryTracker.recordToolCall('mcp/end_hmr_batch')
const result = await getController().end()
if (result.status === 'disabled') {
return json(
{
error:
'Agent HMR batching is not enabled. Set `experimental.agentHmrBatching: true` in next.config.js.',
},
true
)
}
return json(result)
}
)
server.registerTool(
'get_hmr_batch_status',
{
description:
'Report whether an HMR batch is open, how many HMR messages it is holding back, and the ' +
'errors from the most recent compilation. Useful for recovering after losing track of ' +
'batch state, and for checking whether updates are still queued behind a failed batch.',
inputSchema: {},
},
async () => {
mcpTelemetryTracker.recordToolCall('mcp/get_hmr_batch_status')
return json(getController().status())
}
)
}
...@@ -281,6 +281,9 @@ export type McpToolName = ...@@ -281,6 +281,9 @@ export type McpToolName =
| 'mcp/get_server_action_by_id' | 'mcp/get_server_action_by_id'
| 'mcp/get_compilation_issues' | 'mcp/get_compilation_issues'
| 'mcp/compile_route' | 'mcp/compile_route'
| 'mcp/begin_hmr_batch'
| 'mcp/end_hmr_batch'
| 'mcp/get_hmr_batch_status'
export type EventMcpToolUsage = { export type EventMcpToolUsage = {
toolName: McpToolName toolName: McpToolName
......
...@@ -82,6 +82,9 @@ describe('MCP Telemetry Events', () => { ...@@ -82,6 +82,9 @@ describe('MCP Telemetry Events', () => {
'mcp/get_server_action_by_id', 'mcp/get_server_action_by_id',
'mcp/get_compilation_issues', 'mcp/get_compilation_issues',
'mcp/compile_route', 'mcp/compile_route',
'mcp/begin_hmr_batch',
'mcp/end_hmr_batch',
'mcp/get_hmr_batch_status',
] ]
const usages = allTools.map((tool, index) => ({ const usages = allTools.map((tool, index) => ({
...@@ -91,7 +94,7 @@ describe('MCP Telemetry Events', () => { ...@@ -91,7 +94,7 @@ describe('MCP Telemetry Events', () => {
const events = eventMcpToolUsage(usages) const events = eventMcpToolUsage(usages)
expect(events).toHaveLength(9) expect(events).toHaveLength(allTools.length)
events.forEach((event, index) => { events.forEach((event, index) => {
expect(event.eventName).toBe(EVENT_MCP_TOOL_USAGE) expect(event.eventName).toBe(EVENT_MCP_TOOL_USAGE)
......
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
import { message } from './message'
export default function Page() {
return <p id="message">{message}</p>
}
module.exports = {
experimental: {
mcpServer: true,
agentHmrBatching: true,
},
}
/**
* Agent-scoped HMR batching, end to end against a real dev server.
*
* The reproduction these tests encode: an agent making a multi-step edit
* produces one HMR update per step, so the browser preview walks through every
* half-finished intermediate state, and compile errors land in the browser's
* error overlay rather than in the hands of the agent that caused them.
*/
import path from 'path'
import { nextTestSetup } from 'e2e-utils'
import { retry, waitForNoRedbox } from 'next-test-utils'
describe('mcp-server agent HMR batching', () => {
const { next, skipped } = nextTestSetup({
files: path.join(__dirname, 'fixtures', 'hmr-batch-app'),
})
if (skipped) {
return
}
async function callMcp(method: string, params: object) {
const response = await fetch(`${next.url}/_next/mcp`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json, text/event-stream',
},
body: JSON.stringify({
jsonrpc: '2.0',
id: 'hmr-batch',
method,
params,
}),
})
const text = await response.text()
const match = text.match(/data: ({.*})/s)
expect(match).toBeTruthy()
return JSON.parse(match![1]).result
}
async function callTool(name: string, args: object = {}) {
const result = await callMcp('tools/call', { name, arguments: args })
return JSON.parse(result?.content?.[0]?.text)
}
type BatchStatus = {
enabled: boolean
open: boolean
batchId: string | null
heldMessageCount: number
heldMessageTypes: Record<string, number>
pendingFromPreviousBatch: number
errors: Array<{ message: string }>
}
const getStatus = (): Promise<BatchStatus> => callTool('get_hmr_batch_status')
/** How many compilations this batch has held so far. */
const builtCount = (status: BatchStatus) => status.heldMessageTypes.built ?? 0
async function setMessage(value: string) {
await next.patchFile(
'app/message.ts',
`export const message = '${value}'\n`
)
}
/**
* Writes a file and waits until the dev server has finished compiling it and
* the open batch has held the result. Waiting on the batch's own accounting
* rather than on a timeout is what makes "the preview did not move" a real
* assertion instead of a race.
*/
async function editAndAwaitHeldCompile(write: () => Promise<void>) {
const before = builtCount(await getStatus())
await write()
let status: BatchStatus
await retry(async () => {
status = await getStatus()
expect(builtCount(status)).toBeGreaterThan(before)
}, 30_000)
return status!
}
const readMessage = (browser: Awaited<ReturnType<typeof next.browser>>) =>
browser.elementByCss('#message').text()
afterEach(async () => {
// Leave no batch open for the next test, whatever happened in this one.
const status = await getStatus()
if (status.open) {
await callTool('end_hmr_batch')
}
})
it('exposes the batch tools when experimental.agentHmrBatching is on', async () => {
const { tools } = await callMcp('tools/list', {})
const names = tools.map((tool: { name: string }) => tool.name)
expect(names).toContain('begin_hmr_batch')
expect(names).toContain('end_hmr_batch')
expect(names).toContain('get_hmr_batch_status')
expect(await getStatus()).toMatchObject({
enabled: true,
open: false,
batchId: null,
})
})
it('changes nothing about HMR while no batch is open', async () => {
await setMessage('no-batch-before')
const browser = await next.browser('/')
await retry(async () => {
expect(await readMessage(browser)).toBe('no-batch-before')
}, 15_000)
await setMessage('no-batch-after')
await retry(async () => {
expect(await readMessage(browser)).toBe('no-batch-after')
}, 15_000)
})
it('keeps the preview on the last good state for the length of a batch', async () => {
await setMessage('before-batch')
const browser = await next.browser('/')
await retry(async () => {
expect(await readMessage(browser)).toBe('before-batch')
}, 15_000)
const begun = await callTool('begin_hmr_batch')
expect(begun).toMatchObject({ status: 'opened' })
// A multi-step edit: three separate writes, each compiled by the dev
// server, none of them shown.
for (const step of ['step-1', 'step-2', 'step-3']) {
await editAndAwaitHeldCompile(() => setMessage(step))
expect(await readMessage(browser)).toBe('before-batch')
}
const status = await getStatus()
expect(status.open).toBe(true)
expect(status.batchId).toBe(begun.batchId)
expect(status.heldMessageCount).toBeGreaterThan(0)
const ended = await callTool('end_hmr_batch')
expect(ended).toMatchObject({
status: 'flushed',
batchId: begun.batchId,
compiled: true,
errors: [],
previewPreserved: true,
})
// One jump, from the state before the batch straight to the final one.
await retry(async () => {
expect(await readMessage(browser)).toBe('step-3')
}, 15_000)
})
it('hands compile errors to the agent and leaves the preview alone', async () => {
await setMessage('last-good')
const browser = await next.browser('/')
await retry(async () => {
expect(await readMessage(browser)).toBe('last-good')
}, 15_000)
expect(await callTool('begin_hmr_batch')).toMatchObject({
status: 'opened',
})
await editAndAwaitHeldCompile(async () => {
await next.patchFile(
'app/message.ts',
`import { missing } from './does-not-exist'\n` +
`export const message = missing\n`
)
})
const ended = await callTool('end_hmr_batch')
expect(ended.status).toBe('withheld')
expect(ended.compiled).toBe(true)
expect(ended.errors.length).toBeGreaterThan(0)
expect(
ended.errors.map((error: { message: string }) => error.message).join('\n')
).toContain('does-not-exist')
// The error went to the agent, not to the human watching the preview.
expect(await readMessage(browser)).toBe('last-good')
await waitForNoRedbox(browser)
// The held updates were not thrown away: fixing the code releases them.
await setMessage('after-fix')
await retry(async () => {
expect(await readMessage(browser)).toBe('after-fix')
}, 15_000)
})
it('does not nest batches', async () => {
const first = await callTool('begin_hmr_batch')
expect(first.status).toBe('opened')
const second = await callTool('begin_hmr_batch')
expect(second).toMatchObject({
status: 'already-open',
batchId: first.batchId,
})
const ended = await callTool('end_hmr_batch')
expect(ended.batchId).toBe(first.batchId)
expect(await callTool('end_hmr_batch')).toMatchObject({
status: 'no-batch',
})
})
})
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