rivet-design 0.11.11 → 0.11.13

package/dist/mcp/server.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.startMCPServer = exports.createRivetMcp = exports.buildStaticPreviewRefineResponse = exports.collectStaticPreviewRefineTargetInstructions = exports.buildVariantRequestBatchResponse = exports.buildMixedVariantBatchResponse = exports.startParentProcessMonitor = exports.configureMcpStdioLogging = void 0;
+exports.startMCPServer = exports.createRivetMcp = exports.buildLeasedVariantResponse = exports.buildStaticPreviewRefineResponse = exports.collectStaticPreviewRefineTargetInstructions = exports.buildApplyChangesResponse = exports.buildNoPendingChangesResponse = exports.resolveLeasePickupRequestId = exports.buildVariantRequestBatchResponse = exports.buildMixedVariantBatchResponse = exports.startParentProcessMonitor = exports.buildVisualEditorWatchAction = exports.configureMcpStdioLogging = void 0;
 const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
 const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
 const v3_1 = require("zod/v3");
@@ -99,6 +99,17 @@ async function stopChildProcess(child, timeoutMs = DEV_SERVER_STOP_TIMEOUT_MS) {
     }
     await waitForExit;
 }
+/** Builds the required host-agent action that keeps a visual editor session listening. */
+const buildVisualEditorWatchAction = (sessionId, timing = 'immediate') => ({
+    tool: 'watch_for_changes',
+    arguments: { sessionId },
+    required: true,
+    timing,
+    loopUntil: 'close_visual_editor',
+    onTimeout: 'call_again',
+    afterHandlingChanges: 'call_again',
+});
+exports.buildVisualEditorWatchAction = buildVisualEditorWatchAction;
 const DEV_SERVER_STOP_TIMEOUT_MS = 5000;
 const PARENT_PROCESS_MONITOR_INTERVAL_MS = 2000;
 const SUPERSEDED_CHANGES_MESSAGE = 'Queued changes were superseded by newer user input. Call watch_for_changes again.';
@@ -403,22 +414,68 @@ const requestHasResolvedReferences = (request) => request.changes.some((c) => c.
     Array.isArray(c.resolvedReferences) &&
     c.resolvedReferences.length > 0);
 const VARIANT_REQUEST_GUIDE = 'This batch is a Rivet variant request — do NOT edit files directly. ' +
-    'The pending change is a single CommentChangeItem with `variantRequest.count`. ' +
+    'The pending change is a single CommentChangeItem; `variantRequest.count` is only the editor\'s default placeholder count — YOU own the real number. Decide how many directions to generate from the user\'s `instruction` text (honor an explicit ask like "give me 5"; otherwise default to 3-4). ' +
     "Derive the structured `start_variants.target` from the comment's `element` using this priority: " +
     '(a) `{ type: "file", ref: filePaths[0] }` when `filePaths.length === 1`; otherwise ' +
-    '(b) `{ type: "selector", ref: `[data-rivet-id="${rivetId}"]` }` when `rivetId` is present, then ' +
-    '(c) `{ type: "selector", ref: `#${id}` }` when `id` has no whitespace, then ' +
-    '(d) `{ type: "selector", ref: xpath }`, then ' +
-    '(e) `{ type: "selector", ref: `.${token}` }` for a single-token `className`. ' +
+    '(b) `{ type: "element", ref: `[data-rivet-id="${rivetId}"]` }` when `rivetId` is present, then ' +
+    '(c) `{ type: "element", ref: `#${id}` }` when `id` has no whitespace, then ' +
+    '(d) `{ type: "element", ref: xpath }`, then ' +
+    '(e) `{ type: "element", ref: `.${token}` }` for a single-token `className`. ' +
+    'When you set a `target` from the comment\'s `element`, scope each variant\'s change to THAT element and its immediate section/card — do not restyle the rest of the page. ' +
     'If the comment has imageCount > 0, inspect the following image content items before calling `start_variants`; pass each image through `userContext` as `{ transport: "upload", dataUrl, label: "Reference image N", userIntent: "Inline variant visual reference" }` when your client exposes a data URL, or pass concise visual observations as `{ transport: "text", content, label: "Reference image observations", userIntent: "Inline variant visual reference" }` when it does not. ' +
-    'Then call `start_variants` with `{ mode: "existing", prompt: instruction, count: variantRequest.count, target, userContext }`. Do NOT use the older `propose_variants` chain for this path. `start_variants` returns leased work items; generate each variant in its worktree and call `report_variant_complete` for each leased item. ' +
+    'Then call `start_variants` with `{ mode: "existing", prompt: instruction, target, userContext, requestId, briefs }`, passing this batch\'s `requestId` through verbatim so the editor can map its loading placeholders to the new cards. Set the count by supplying `briefs` (one distinct `{ label, body }` per variant — `briefs.length` is the count, and each card is named by what it changes); the editor seeds a few placeholders and reconciles to however many you actually generate. Do NOT use the older `propose_variants` chain for this path. ' +
+    'ACCUMULATION: when a variants session is already live for this project, calling `start_variants` again does NOT discard it — Rivet APPENDS the new directions to that same active session (they show up alongside the existing ones), so just call `start_variants` per Vary; never try to reuse a prior sessionId or worry about orphaning earlier variants. ' +
+    '`start_variants` returns leased work items; generate each variant in its worktree and call `report_variant_complete` for each leased item. ' +
     'After the user picks a variant via `commit_variant`, STOP and tell the user their variant has been committed.';
 const VARIANT_MIXED_BATCH_GUIDE = 'Mixed batch rejected: a `variantRequest` comment must be the only item in its batch. ' +
     'Ask the user to send the variant request on its own (clear other pending changes first) and retry.';
-const STATIC_PREVIEW_REFINE_GUIDE = 'STATIC_PREVIEW_REFINE_GUIDE: These changes target a static_preview variant. ' +
-    'Do NOT edit base project files. Group changes by staticPreviewTarget, then call ' +
-    "`continue_variants(action:'refine_variant', variantId, instruction)` once per distinct target with that group's combined instruction. " +
-    'Regenerate each variant HTML, then call `report_variant_complete` for each leased refine work item with output.html containing the full updated static HTML.';
+// Shared preamble for both static-preview refine guides (fork vs in-place).
+// Keeps the STATIC_PREVIEW_REFINE_GUIDE marker, the lease call, and the
+// targetElement scoping rule consistent across both flows.
+const STATIC_PREVIEW_REFINE_GUIDE_PREAMBLE = 'STATIC_PREVIEW_REFINE_GUIDE: These changes target static_preview variant(s). ' +
+    'Do NOT edit base project files. ' +
+    "Lease ONLY this batch's work items: call `continue_variants({ action: 'request_work', workItemIds: <the response.workItemIds array> })`. " +
+    'Passing workItemIds (rather than a bare requestedLeaseCount) keeps concurrent runs from leasing each other\'s work, so several batches can be handled in parallel. ' +
+    'When input.targetElement is present it is the specific element the user selected (match it in the HTML by tagName/className/id/textContent): ' +
+    'scope the change to THAT element and its immediate section/card — do not restyle the rest of the page. ';
+// "Vary" flow: the server forked N NEW sibling variants; the original is left
+// untouched and each fork gets a synthesized parent+change name.
+const STATIC_PREVIEW_FORK_GUIDE = STATIC_PREVIEW_REFINE_GUIDE_PREAMBLE +
+    'Do NOT overwrite the original variant. ' +
+    'The server has already created the requested number of NEW sibling variants per target — each is a fresh ' +
+    'static_preview work item seeded from the source variant (input.currentHtml) plus your instruction (input.instruction). ' +
+    'For each leased static_preview work item, generate a NEW variation of input.currentHtml that applies input.instruction. ' +
+    'Then call `report_variant_complete` with output.html containing the full updated static HTML, ' +
+    'AND a synthesized `title` (≤ 6 words) + one-sentence `description` that combine the parent variant ' +
+    '(input.sourceLabel / input.sourceBody) with the change (input.instruction) — e.g. "Icon grid — red hover". ' +
+    'Each leased item becomes its own new variant card; the original variant is left unchanged.';
+// "Apply" flow: the server created a single in-place refinement work item that
+// UPDATES THE SAME variant — it is NOT a new sibling, so the variant keeps its
+// existing name and no synthesized title/description is reported.
+const STATIC_PREVIEW_INPLACE_REFINE_GUIDE = STATIC_PREVIEW_REFINE_GUIDE_PREAMBLE +
+    'The server has created an IN-PLACE refinement work item that UPDATES THE SAME variant per target — ' +
+    'it is NOT a new sibling. Lease it, then edit input.currentHtml to apply input.instruction, ' +
+    'preserving everything else. ' +
+    'Then call `report_variant_complete` with output.html containing the full updated static HTML. ' +
+    'Do NOT pass a new `title`/`description` — the variant keeps its existing name. ' +
+    'The edited HTML replaces the existing variant in place.';
+/**
+ * Pick the guide that matches what the server actually did with this batch:
+ * a "Vary" target carries a `count` (the server forked N siblings), while a
+ * plain "Apply" has no count (the server created one in-place refinement that
+ * overwrites the source). A mixed batch falls back to the fork guide, whose
+ * lease+report steps still cover the count-bearing targets.
+ */
+const selectStaticPreviewRefineGuide = (targetInstructions) => targetInstructions.some(({ count }) => count != null)
+    ? STATIC_PREVIEW_FORK_GUIDE
+    : STATIC_PREVIEW_INPLACE_REFINE_GUIDE;
+const buildLeasePayloadFields = (lease) => ({
+    leaseId: lease.leaseId,
+    requestId: lease.requestId,
+    kind: lease.kind,
+    mergedRequestIds: lease.mergedRequestIds,
+    mergedFrom: lease.mergedFrom,
+});
 const buildSupersededChangesResponse = () => ({
     content: [
         {
@@ -451,11 +508,12 @@ const buildMixedVariantBatchResponse = (rejectedRequest) => {
     };
 };
 exports.buildMixedVariantBatchResponse = buildMixedVariantBatchResponse;
-const buildVariantRequestBatchResponse = (consumedRequest) => {
-    if (!consumedRequest) {
+const buildVariantRequestBatchResponse = (intent, lease) => {
+    if (!intent) {
         return buildSupersededChangesResponse();
     }
-    const { changes, imageContent } = (0, changeBatchClassification_1.extractImages)(consumedRequest.changes);
+    const { changes, imageContent } = (0, changeBatchClassification_1.extractImages)(intent.changes);
+    const requestId = intent.agentRunId ?? intent.traceId;
     return {
         content: [
             {
@@ -464,7 +522,10 @@ const buildVariantRequestBatchResponse = (consumedRequest) => {
                     hasChanges: true,
                     kind: 'variant_request',
                     changes,
-                    sourceFiles: consumedRequest.sourceFiles,
+                    sourceFiles: intent.sourceFiles,
+                    ...(requestId ? { requestId } : {}),
+                    ...(intent.target ? { target: intent.target } : {}),
+                    ...(lease ? buildLeasePayloadFields(lease) : {}),
                     applyGuide: VARIANT_REQUEST_GUIDE,
                 }),
             },
@@ -473,10 +534,71 @@ const buildVariantRequestBatchResponse = (consumedRequest) => {
     };
 };
 exports.buildVariantRequestBatchResponse = buildVariantRequestBatchResponse;
+/**
+ * Resolves whether `watch_for_changes` / `get_pending_changes` should pass
+ * `requestId` into lease pickup. requestId is only for idempotent re-poll of
+ * the same in-flight lease — omit it after ack so FIFO can pick the next batch.
+ */
+const resolveLeasePickupRequestId = (args) => args.refresh_git || args.ack_batch ? undefined : args.requestId;
+exports.resolveLeasePickupRequestId = resolveLeasePickupRequestId;
+/**
+ * Builds a poll response for an empty apply queue.
+ */
+const buildNoPendingChangesResponse = (params = {}) => ({
+    content: [
+        {
+            type: 'text',
+            text: JSON.stringify({
+                hasChanges: false,
+                ...(params.message ? { message: params.message } : {}),
+                ...(params.devServerHealth !== undefined
+                    ? { devServerHealth: params.devServerHealth }
+                    : {}),
+                ...(params.pendingVariantRequests !== undefined
+                    ? { pendingVariantRequests: params.pendingVariantRequests }
+                    : {}),
+            }),
+        },
+    ],
+});
+exports.buildNoPendingChangesResponse = buildNoPendingChangesResponse;
+/**
+ * Builds a poll response for a normal apply batch.
+ */
+const buildApplyChangesResponse = (params) => {
+    const { changes, imageContent } = (0, changeBatchClassification_1.extractImages)(params.intent.changes);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    hasChanges: true,
+                    kind: 'apply',
+                    changes,
+                    sourceFiles: params.intent.sourceFiles,
+                    ...(params.intent.target ? { target: params.intent.target } : {}),
+                    ...(params.intent.worktreePath
+                        ? { worktreePath: params.intent.worktreePath }
+                        : {}),
+                    ...(params.lease ? buildLeasePayloadFields(params.lease) : {}),
+                    applyGuide: buildApplyGuide(params.intent.worktreePath, requestHasResolvedReferences(params.intent)),
+                    ...(params.pendingVariantRequests !== undefined
+                        ? { pendingVariantRequests: params.pendingVariantRequests }
+                        : {}),
+                }),
+            },
+            ...imageContent,
+        ],
+    };
+};
+exports.buildApplyChangesResponse = buildApplyChangesResponse;
 const staticPreviewTargetKey = (target) => `${target.sessionId}:${target.variantId}`;
 const getCommentStaticPreviewTarget = (comment, fallbackTarget) => comment.staticPreviewTarget ?? fallbackTarget;
 const collectStaticPreviewRefineTargetInstructions = (request) => {
     const groups = new Map();
+    // Per-request correlation id: each Vary/Apply is dispatched as its own batch,
+    // so the batch's agentRunId (or traceId) uniquely identifies this UI request.
+    const requestId = request.agentRunId ?? request.traceId;
     for (const change of request.changes) {
         if (change.kind !== 'comment')
             continue;
@@ -484,21 +606,29 @@ const collectStaticPreviewRefineTargetInstructions = (request) => {
         if (!target)
             continue;
         const key = staticPreviewTargetKey(target);
+        const count = change.variantRequest?.count;
         const existing = groups.get(key);
         if (existing) {
             existing.instruction = `${existing.instruction}\n\n${change.instruction}`;
+            if (count != null) {
+                existing.count = Math.max(existing.count ?? 0, count);
+            }
+            existing.element = existing.element ?? change.element;
         }
         else {
             groups.set(key, {
                 target,
                 instruction: change.instruction,
+                ...(count != null ? { count } : {}),
+                element: change.element,
+                ...(requestId ? { requestId } : {}),
             });
         }
     }
     return [...groups.values()];
 };
 exports.collectStaticPreviewRefineTargetInstructions = collectStaticPreviewRefineTargetInstructions;
-const buildStaticPreviewRefineResponse = (consumedRequest) => {
+const buildStaticPreviewRefineResponse = (consumedRequest, droppedRefinements = [], createdWorkItemIds = [], lease) => {
     if (!consumedRequest) {
         return buildSupersededChangesResponse();
     }
@@ -516,7 +646,19 @@ const buildStaticPreviewRefineResponse = (consumedRequest) => {
                     sourceFiles: consumedRequest.sourceFiles,
                     staticPreviewTarget: consumedRequest.staticPreviewTarget,
                     staticPreviewTargets,
-                    applyGuide: STATIC_PREVIEW_REFINE_GUIDE,
+                    ...(lease ? buildLeasePayloadFields(lease) : {}),
+                    applyGuide: selectStaticPreviewRefineGuide(targetInstructions),
+                    // The exact work items THIS batch created. Lease ONLY these (pass them
+                    // as `workItemIds` to request_work) so concurrent runs each pick up
+                    // their own batch instead of one greedily leasing everything.
+                    ...(createdWorkItemIds.length > 0 ? { workItemIds: createdWorkItemIds } : {}),
+                    // In-place refinements the server could not apply (the variant was
+                    // already sent / no longer editable). Surfaced structurally so the
+                    // agent knows the instruction was NOT applied, instead of the poll
+                    // throwing and losing the already-consumed batch.
+                    ...(droppedRefinements.length > 0
+                        ? { rejectedRefinements: droppedRefinements }
+                        : {}),
                 }),
             },
             ...imageContent,
@@ -524,6 +666,23 @@ const buildStaticPreviewRefineResponse = (consumedRequest) => {
     };
 };
 exports.buildStaticPreviewRefineResponse = buildStaticPreviewRefineResponse;
+/**
+ * Build the MCP response for a leased variant batch.
+ */
+const buildLeasedVariantResponse = (params) => {
+    const intent = params.lease.intent;
+    if (params.isFreshStaticPreviewVariantRequestBatch(intent)) {
+        return params.withPendingVariantRequests(params.handleStaticPreviewRefineBatch(intent, params.lease));
+    }
+    if ((0, changeBatchClassification_1.isSingleVariantRequestBatch)(intent)) {
+        return params.withPendingVariantRequests((0, exports.buildVariantRequestBatchResponse)(intent, params.lease));
+    }
+    if ((0, changeBatchClassification_1.isStaticPreviewRefineBatch)(intent)) {
+        return params.withPendingVariantRequests(params.handleStaticPreviewRefineBatch(intent, params.lease));
+    }
+    return params.withPendingVariantRequests((0, exports.buildVariantRequestBatchResponse)(intent, params.lease));
+};
+exports.buildLeasedVariantResponse = buildLeasedVariantResponse;
 /**
  * Builds the fully configured Rivet MCP server (tools, auth gating, session
  * bridge, telemetry) without binding it to a transport. Shared by the stdio
@@ -559,6 +718,94 @@ const createRivetMcp = (options) => {
         bridge,
         telemetry,
     });
+    /**
+     * Resolve a variants sessionId to its projectContext kind, swallowing the
+     * `SESSION_NOT_FOUND` throw for unknown/expired sessions so classification can
+     * fall back to the default path.
+     */
+    const resolveSessionKind = (sessionId) => {
+        try {
+            return agentVariantsOrchestrator.getProjectContext(sessionId).kind;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    /**
+     * A `variant_request` ("generate N variants") on a FRESH static-preview
+     * variant has no file-backed worktree to code_gen against: the inline preview
+     * HTML is gitignored and never lands in a `git worktree` clone, so the default
+     * `mode:"existing"` guide would send the agent to edit files that don't exist.
+     * Reroute it through the static-preview refine flow, which operates on the
+     * variant's inline HTML.
+     */
+    const isFreshStaticPreviewVariantRequestBatch = (intent) => (0, changeBatchClassification_1.isFreshStaticPreviewVariantRequest)(intent, resolveSessionKind, (sid, vid) => agentVariantsOrchestrator.isStaticPreviewVariant(sid, vid));
+    /**
+     * Kick off static-preview refinement work items for a leased batch.
+     */
+    const handleStaticPreviewRefineBatch = (intent, lease) => {
+        const consumedRequest = (0, changeBatchClassification_1.withDerivedStaticPreviewTargets)(intent);
+        let droppedRefinements = [];
+        let createdWorkItemIds = [];
+        if (consumedRequest) {
+            const targetInstructions = (0, exports.collectStaticPreviewRefineTargetInstructions)(consumedRequest);
+            const sessionId = targetInstructions[0]?.target.sessionId;
+            if (sessionId) {
+                ({ droppedRefinements, createdWorkItemIds } =
+                    agentVariantsOrchestrator.beginStaticPreviewRefinements({
+                        sessionId,
+                        targets: targetInstructions.map(({ target, instruction, count, element, requestId }) => ({
+                            variantId: target.variantId,
+                            instruction,
+                            count,
+                            element,
+                            requestId,
+                        })),
+                    }));
+            }
+        }
+        return (0, exports.buildStaticPreviewRefineResponse)(consumedRequest, droppedRefinements, createdWorkItemIds, lease);
+    };
+    /** Complete an apply lease and refresh git status in the Rivet UI. */
+    const handleApplyAck = (sessionId, args) => {
+        const leaseId = args.leaseId ?? bridge.findActiveApplyLease()?.leaseId ?? undefined;
+        if (leaseId) {
+            const ackResult = bridge.ackBatch({
+                leaseId,
+                requestId: args.requestId,
+            });
+            if (ackResult.kind === 'apply' && ackResult.mergedRequestIds.length > 0) {
+                telemetry.trackMCPChangeAcked({
+                    channel: 'apply',
+                    leaseId,
+                    requestId: args.requestId ?? ackResult.mergedRequestIds[0],
+                    changeCount: ackResult.mergedRequestIds.length,
+                    sessionId,
+                });
+            }
+        }
+        handleRefreshGit(sessionId);
+        bridge.setStatus('READY');
+    };
+    /** Release a variant lease after the agent finishes the batch. */
+    const handleVariantAck = (args) => {
+        if (!args.leaseId) {
+            return;
+        }
+        const ackResult = bridge.ackBatch({
+            leaseId: args.leaseId,
+            requestId: args.requestId,
+        });
+        if (ackResult.kind === 'variant' && ackResult.mergedRequestIds.length > 0) {
+            telemetry.trackMCPChangeAcked({
+                channel: 'variant',
+                leaseId: args.leaseId,
+                requestId: args.requestId ?? ackResult.mergedRequestIds[0],
+                changeCount: ackResult.mergedRequestIds.length,
+                sessionId: bridge.getSessionId() ?? undefined,
+            });
+        }
+    };
     /** Complete the active run correlation and refresh git status in the Rivet UI. */
     const handleRefreshGit = (sessionId) => {
         const activeRunCorrelation = bridge.completeActiveRunCorrelation();
@@ -575,12 +822,11 @@ const createRivetMcp = (options) => {
         bridge.reportFeedback('__RIVET_REFRESH_GIT__');
     };
     /**
-     * Start tracking an MCP apply run after intent pickup.
+     * Start tracking an MCP apply run after a batch is leased.
      */
-    const beginApplyingRun = (intent, sessionId) => {
+    const beginApplyingRun = (intent, sessionId, _lease) => {
         bridge.setStatus('APPLYING');
         const { newRun, orphanedRun } = bridge.startApplyingRun(intent);
-        bridge.clearPending();
         trackChangesQueuedFromIntent(intent, bridge, telemetry, sessionId);
         if (orphanedRun) {
             trackOrphanedMCPRun(telemetry, sessionId, orphanedRun);
@@ -595,6 +841,66 @@ const createRivetMcp = (options) => {
             source: 'mcp',
         });
     };
+    /**
+     * Lease and route the next batch from the unified bridge pipeline.
+     */
+    const leaseAndRouteBatch = (sessionId, requestId) => {
+        while (true) {
+            const applyHead = bridge.getPendingChanges();
+            if (!applyHead || !(0, changeBatchClassification_1.isMixedVariantBatch)(applyHead)) {
+                break;
+            }
+            const rejectedRequest = bridge.rejectMixedVariantRequestBatch(applyHead);
+            return withPendingVariantRequests((0, exports.buildMixedVariantBatchResponse)(rejectedRequest));
+        }
+        const lease = bridge.leaseBatch(requestId);
+        if (!lease) {
+            return null;
+        }
+        telemetry.trackMCPChangeLeased({
+            channel: lease.kind,
+            leaseId: lease.leaseId,
+            requestId: lease.requestId,
+            changeCount: lease.mergedFrom,
+            sessionId,
+        });
+        if (lease.kind === 'variant') {
+            return (0, exports.buildLeasedVariantResponse)({
+                lease,
+                isFreshStaticPreviewVariantRequestBatch,
+                handleStaticPreviewRefineBatch,
+                withPendingVariantRequests,
+            });
+        }
+        beginApplyingRun(lease.intent, sessionId, lease);
+        return (0, exports.buildApplyChangesResponse)({
+            intent: lease.intent,
+            lease,
+            pendingVariantRequests: bridge.pendingVariantRequestCount(),
+        });
+    };
+    /**
+     * Stamp the live variant-request FIFO depth onto a built change response's
+     * first text block as `pendingVariantRequests`. Read from the bridge AFTER
+     * any batch was consumed, so the count reflects how many MORE batches are
+     * still queued (`> 0` ⇒ the agent should keep draining via
+     * watch_for_changes / get_pending_changes). Non-JSON text blocks pass through
+     * unchanged. Mutates and returns the same response object for convenience.
+     */
+    const withPendingVariantRequests = (response) => {
+        const head = response.content[0];
+        if (head?.type !== 'text')
+            return response;
+        try {
+            const parsed = JSON.parse(head.text);
+            parsed.pendingVariantRequests = bridge.pendingVariantRequestCount();
+            head.text = JSON.stringify(parsed);
+        }
+        catch {
+            // Not a JSON payload — leave it untouched.
+        }
+        return response;
+    };
     // Tailor the sign-in instructions to the user's stored credentials so the
     // agent is told to sign in up front (rather than after an AUTH_REQUIRED
     // failure). A synchronous disk read is enough: the presence of an access or
@@ -892,7 +1198,7 @@ const createRivetMcp = (options) => {
             .string()
             .describe('The session ID returned by open_visual_editor'),
     };
-    guardedMcp.tool('open_visual_editor', 'Start a Rivet visual editing session. Pass projectPath directly; framework is optional and will be detected when omitted. If the response has opened: false, follow the nextStep/nextAction instructions to recover. Once opened, follow the next_step instructions exactly.', openEditorArgs, async (args) => {
+    guardedMcp.tool('open_visual_editor', 'Start a Rivet visual editing session. Pass projectPath directly; framework is optional and will be detected when omitted. If the response has opened: false, follow the nextStep/nextAction instructions to recover. If opened: true, the response includes nextAction { tool: "watch_for_changes", ... }; host agents must call it immediately and keep that loop active until the user stops or closes the editor.', openEditorArgs, async (args) => {
         if (bridge.isActive()) {
             return {
                 content: [
@@ -1398,26 +1704,14 @@ const createRivetMcp = (options) => {
                         startupModeSelection,
                         requestedStartupMode,
                         isGitEnabled: isGitEnabledForSession,
-                        next_step: mcpEditor === 'cursor' ||
-                            mcpEditor === 'codex' ||
-                            mcpEditor === 'claude-desktop'
-                            ? `Rivet is open. Tell the user: "Rivet is ready — make your visual changes and click '${sendButtonLabel}'." Then call watch_for_changes({ sessionId: "${sessionId}" }) to wait for their changes. After applying, STOP and ask the user if they want to keep watching or go back to normal prompting.`
-                            : `Rivet is open. Tell the user: "Rivet is ready — make your visual changes and click '${sendButtonLabel}'."
-
-IMPORTANT — Start a background monitor so you automatically detect when the user sends changes. Use the Monitor tool:
-  description: "Rivet changes"
-  persistent: true
-  command: while sleep 2; do if curl -sf http://localhost:${rivetPort}/api/mcp/status | grep -q '"hasPendingIntent":true'; then echo "Rivet: user sent changes - call get_pending_changes to apply"; exit 0; fi; done
-
-When the monitor notifies you, call get_pending_changes({ sessionId: "${sessionId}" }) to retrieve the changes and apply them. After applying, restart the monitor to watch for the next round. You are also free to handle other requests while the monitor runs.
-
-If the Monitor tool is not available, call watch_for_changes({ sessionId: "${sessionId}" }) instead to block until the user sends changes.`,
+                        nextAction: (0, exports.buildVisualEditorWatchAction)(sessionId),
+                        next_step: `Rivet is open. Tell the user: "Rivet is ready — make your visual changes and click '${sendButtonLabel}'." Then immediately call watch_for_changes({ sessionId: "${sessionId}" }) and keep the watch loop active until the user stops or closes the editor. If watch_for_changes times out, call it again. After handling a batch, call it again; for hosts with background workers, dispatch static-preview variant/refine batches and re-watch immediately, and for hosts without background workers, process the scoped batch inline before re-watching.`,
                     }),
                 },
             ],
         };
     });
-    guardedMcp.tool('watch_for_changes', `Block until the user clicks "${sendButtonLabel}" in Rivet, then return their changes. If it times out (hasChanges: false), call it again to keep waiting. When hasChanges: true, apply the changes, then STOP and ask the user: "Want me to keep watching for more Rivet changes, or go back to normal prompting?"`, {
+    guardedMcp.tool('watch_for_changes', `Required visual-editor watch loop. Call immediately after a successful open_visual_editor response, or after a start_variants response that includes editorNextAction/visualEditor. It blocks until the user sends a change batch, then returns a leased payload with leaseId and kind. After editing files (apply) call watch_for_changes again with refresh_git: true and the leaseId to release the lease and refresh git. After variant batches call watch_for_changes with ack_batch: true and the leaseId. If it times out (hasChanges: false), call it again to keep waiting.`, {
         sessionId: v3_1.z
             .string()
             .describe('The session ID returned by open_visual_editor'),
@@ -1434,7 +1728,19 @@ If the Monitor tool is not available, call watch_for_changes({ sessionId: "${ses
         refresh_git: v3_1.z
             .boolean()
             .optional()
-            .describe('Set to true after writing files to trigger a git status refresh in the Rivet UI'),
+            .describe('After completing an apply lease: set true with leaseId to ack the lease and trigger a git status refresh in the Rivet UI'),
+        ack_batch: v3_1.z
+            .boolean()
+            .optional()
+            .describe('After completing a variant lease: set true with leaseId to release the leased batch'),
+        leaseId: v3_1.z
+            .string()
+            .optional()
+            .describe('The leaseId from the batch you just completed'),
+        requestId: v3_1.z
+            .string()
+            .optional()
+            .describe('Optional requestId from the leased batch for idempotent ack'),
     }, async (args) => {
         if (!bridge.isActive() || bridge.getSessionId() !== args.sessionId) {
             return {
@@ -1452,75 +1758,46 @@ If the Monitor tool is not available, call watch_for_changes({ sessionId: "${ses
             bridge.reportFeedback(args.message);
         }
         if (args.refresh_git) {
-            handleRefreshGit(args.sessionId);
+            handleApplyAck(args.sessionId, {
+                leaseId: args.leaseId,
+                requestId: args.requestId,
+            });
+        }
+        if (args.ack_batch) {
+            handleVariantAck({
+                leaseId: args.leaseId,
+                requestId: args.requestId,
+            });
+        }
+        // `handleApplyAck` sets READY so the UI can clear comment markers. Do not
+        // overwrite it synchronously — the UI polls `/api/mcp/status` and needs
+        // one READY observation before the watch loop re-arms.
+        if (!args.refresh_git) {
+            bridge.setStatus('WATCHING');
         }
-        bridge.setStatus('READY');
-        let intent;
         try {
-            intent = await bridge.waitForChanges(timeoutMs);
+            await bridge.waitForChanges(timeoutMs);
         }
         catch {
             const health = bridge.getDevServerHealth();
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({
-                            hasChanges: false,
-                            message: 'Timed out waiting for changes. Call watch_for_changes again to keep waiting.',
-                            devServerHealth: health,
-                        }),
-                    },
-                ],
-            };
-        }
-        if ((0, changeBatchClassification_1.isMixedVariantBatch)(intent)) {
-            const rejectedRequest = bridge.rejectMixedVariantRequestBatch(intent);
-            return (0, exports.buildMixedVariantBatchResponse)(rejectedRequest);
+            return (0, exports.buildNoPendingChangesResponse)({
+                message: 'Timed out waiting for changes. Call watch_for_changes again to keep waiting.',
+                devServerHealth: health,
+                pendingVariantRequests: bridge.pendingVariantRequestCount(),
+            });
         }
-        if ((0, changeBatchClassification_1.isSingleVariantRequestBatch)(intent)) {
-            const consumedRequest = bridge.consumeVariantRequestBatch(intent);
-            return (0, exports.buildVariantRequestBatchResponse)(consumedRequest);
+        const routed = leaseAndRouteBatch(args.sessionId, (0, exports.resolveLeasePickupRequestId)(args));
+        if (routed) {
+            return routed;
         }
-        if ((0, changeBatchClassification_1.isStaticPreviewRefineBatch)(intent)) {
-            const consumedRequest = bridge.consumeStaticPreviewRefineBatch(intent);
-            if (consumedRequest) {
-                const targetInstructions = (0, exports.collectStaticPreviewRefineTargetInstructions)(consumedRequest);
-                const sessionId = targetInstructions[0]?.target.sessionId;
-                if (sessionId) {
-                    agentVariantsOrchestrator.beginStaticPreviewRefinements({
-                        sessionId,
-                        targets: targetInstructions.map(({ target, instruction }) => ({
-                            variantId: target.variantId,
-                            instruction,
-                        })),
-                    });
-                }
-            }
-            return (0, exports.buildStaticPreviewRefineResponse)(consumedRequest);
-        }
-        beginApplyingRun(intent, args.sessionId);
-        const { changes, imageContent } = (0, changeBatchClassification_1.extractImages)(intent.changes);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        hasChanges: true,
-                        changes,
-                        sourceFiles: intent.sourceFiles,
-                        ...(intent.target ? { target: intent.target } : {}),
-                        ...(intent.worktreePath
-                            ? { worktreePath: intent.worktreePath }
-                            : {}),
-                        applyGuide: buildApplyGuide(intent.worktreePath, requestHasResolvedReferences(intent)),
-                    }),
-                },
-                ...imageContent,
-            ],
-        };
+        const health = bridge.getDevServerHealth();
+        return (0, exports.buildNoPendingChangesResponse)({
+            message: 'No pending changes. Call watch_for_changes again to keep waiting.',
+            devServerHealth: health,
+            pendingVariantRequests: bridge.pendingVariantRequestCount(),
+        });
     });
-    guardedMcp.tool('get_pending_changes', `Pick up pending design changes from the Rivet visual editor. Call this when the user asks you to apply Rivet changes (e.g. "apply", "check rivet", "apply changes"). Returns hasChanges: false if no changes are queued yet. Also use this to report feedback to the Rivet UI: pass "message" to share your plan or summarize what you changed, and set refresh_git: true after writing files so the UI reflects the updated git status.`, {
+    guardedMcp.tool('get_pending_changes', `Pick up pending design changes from the Rivet visual editor. Returns a leased batch with leaseId and kind when work is queued. After editing files (apply), call again with refresh_git: true and leaseId to ack and refresh git. After variant batches, call with ack_batch: true and leaseId. Returns hasChanges: false if no changes are queued yet.`, {
         sessionId: v3_1.z
             .string()
             .describe('The session ID returned by open_visual_editor'),
@@ -1531,7 +1808,19 @@ If the Monitor tool is not available, call watch_for_changes({ sessionId: "${ses
         refresh_git: v3_1.z
             .boolean()
             .optional()
-            .describe('Set to true after writing files to trigger a git status refresh in the Rivet UI'),
+            .describe('After completing an apply lease: set true with leaseId to ack and trigger a git status refresh in the Rivet UI'),
+        ack_batch: v3_1.z
+            .boolean()
+            .optional()
+            .describe('After completing a variant lease: set true with leaseId to release the leased batch'),
+        leaseId: v3_1.z
+            .string()
+            .optional()
+            .describe('The leaseId from the batch you just completed'),
+        requestId: v3_1.z
+            .string()
+            .optional()
+            .describe('Optional requestId from the leased batch for idempotent ack'),
     }, async (args) => {
         if (!bridge.isActive() || bridge.getSessionId() !== args.sessionId) {
             return {
@@ -1548,66 +1837,24 @@ If the Monitor tool is not available, call watch_for_changes({ sessionId: "${ses
             bridge.reportFeedback(args.message);
         }
         if (args.refresh_git) {
-            handleRefreshGit(args.sessionId);
-            // Signal the Rivet UI that the round is complete
-            bridge.setStatus('READY');
-        }
-        const intent = bridge.getPendingChanges();
-        if (!intent) {
-            return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify({ hasChanges: false }),
-                    },
-                ],
-            };
-        }
-        if ((0, changeBatchClassification_1.isMixedVariantBatch)(intent)) {
-            const rejectedRequest = bridge.rejectMixedVariantRequestBatch(intent);
-            return (0, exports.buildMixedVariantBatchResponse)(rejectedRequest);
+            handleApplyAck(args.sessionId, {
+                leaseId: args.leaseId,
+                requestId: args.requestId,
+            });
         }
-        if ((0, changeBatchClassification_1.isSingleVariantRequestBatch)(intent)) {
-            const consumedRequest = bridge.consumeVariantRequestBatch(intent);
-            return (0, exports.buildVariantRequestBatchResponse)(consumedRequest);
+        if (args.ack_batch) {
+            handleVariantAck({
+                leaseId: args.leaseId,
+                requestId: args.requestId,
+            });
         }
-        if ((0, changeBatchClassification_1.isStaticPreviewRefineBatch)(intent)) {
-            const consumedRequest = bridge.consumeStaticPreviewRefineBatch(intent);
-            if (consumedRequest) {
-                const targetInstructions = (0, exports.collectStaticPreviewRefineTargetInstructions)(consumedRequest);
-                const sessionId = targetInstructions[0]?.target.sessionId;
-                if (sessionId) {
-                    agentVariantsOrchestrator.beginStaticPreviewRefinements({
-                        sessionId,
-                        targets: targetInstructions.map(({ target, instruction }) => ({
-                            variantId: target.variantId,
-                            instruction,
-                        })),
-                    });
-                }
-            }
-            return (0, exports.buildStaticPreviewRefineResponse)(consumedRequest);
+        const routed = leaseAndRouteBatch(args.sessionId, (0, exports.resolveLeasePickupRequestId)(args));
+        if (routed) {
+            return routed;
         }
-        beginApplyingRun(intent, args.sessionId);
-        const { changes, imageContent } = (0, changeBatchClassification_1.extractImages)(intent.changes);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: JSON.stringify({
-                        hasChanges: true,
-                        changes,
-                        sourceFiles: intent.sourceFiles,
-                        ...(intent.target ? { target: intent.target } : {}),
-                        ...(intent.worktreePath
-                            ? { worktreePath: intent.worktreePath }
-                            : {}),
-                        applyGuide: buildApplyGuide(intent.worktreePath, requestHasResolvedReferences(intent)),
-                    }),
-                },
-                ...imageContent,
-            ],
-        };
+        return (0, exports.buildNoPendingChangesResponse)({
+            pendingVariantRequests: bridge.pendingVariantRequestCount(),
+        });
     });
     guardedMcp.tool('close_visual_editor', 'Stop the Rivet visual editing session and clean up resources. Call this when the user is done making visual changes.', sessionIdArgs, async (args) => {
         if (!bridge.isActive() || bridge.getSessionId() !== args.sessionId) {
@@ -1643,6 +1890,7 @@ If the Monitor tool is not available, call watch_for_changes({ sessionId: "${ses
         leaseOwner: () => 'mcp-server',
         ensureVisualEditorOpen: ensureZeroToOneVisualEditorOpen,
         getProjectPath: () => bridge.getProjectPath(),
+        pendingVariantRequestCount: () => bridge.pendingVariantRequestCount(),
         isVariantSendEnabled: async () => {
             const flags = await (0, evaluateFlags_1.getFeatureFlags)();
             return flags.variantSend.isEnabled;