rivet-design 0.12.4 → 0.13.1

package/dist/routes/agentVariants.js

@@ -9,18 +9,23 @@ const path_1 = __importDefault(require("path"));
 const express_1 = require("express");
 const v3_1 = require("zod/v3");
 const logger_1 = require("../utils/logger");
-const agent_variants_1 = require("../mcp/agent-variants");
-const contracts_1 = require("../mcp/agent-variants/contracts");
+const agent_variants_1 = require("../agent-variants");
+const contracts_1 = require("../agent-variants/contracts");
 const changeBatchClassification_1 = require("../mcp/changeBatchClassification");
 const createAgentVariantsOrchestrator_1 = require("../services/createAgentVariantsOrchestrator");
 const VariantHistoryService_1 = require("../services/VariantHistoryService");
 const PrototypeDeployService_1 = require("../services/PrototypeDeployService");
 const HistoryReplayService_1 = require("../services/HistoryReplayService");
-const runLabel_1 = require("../mcp/agent-variants/runLabel");
+const runLabel_1 = require("../agent-variants/runLabel");
 const evaluateFlags_1 = require("../config/evaluateFlags");
 const featureFlagUserKey_1 = require("../config/featureFlagUserKey");
 const variantSessionStart_1 = require("../utils/variantSessionStart");
+const inlineStartTracker_1 = require("./inlineStartTracker");
+const loopback_1 = require("../utils/loopback");
+const preview_bridge_1 = require("../proxy-middleware/preview-bridge");
 const log = (0, logger_1.createLogger)('AgentVariantsRouter');
+const DIRECTION_TITLE_MAX_WORDS = 5;
+const DIRECTION_SUBTITLE_MAX_WORDS = 10;
 /**
  * Public CDN hosts agent-generated previews are allowed to load code/assets
  * from. We don't control which CDN the agent emits: p5.js, three.js, and
@@ -61,16 +66,32 @@ const PREVIEW_CDN_HOSTS = [
  * without widening blast radius, and the per-CDN allowlist above goes away.
  * Until that migration lands, broadening PREVIEW_CDN_HOSTS is the stopgap.
  */
-const STATIC_PREVIEW_CSP = [
-    "default-src 'self' data: blob:",
-    `script-src 'self' 'unsafe-inline' blob: ${PREVIEW_CDN_HOSTS}`,
-    `style-src 'self' 'unsafe-inline' ${PREVIEW_CDN_HOSTS}`,
-    "img-src 'self' data: blob: https:",
-    `font-src 'self' data: ${PREVIEW_CDN_HOSTS}`,
-    `connect-src 'self' blob: ${PREVIEW_CDN_HOSTS}`,
-    "frame-ancestors 'self'",
-    "base-uri 'self'",
-].join('; ');
+/**
+ * CSP for agent-generated static previews. Previews are served same-origin on
+ * the isolated preview port, so `'self'` resolves to the preview document's own
+ * origin and its sibling assets (CSS/JS/GLB/textures) load normally.
+ *
+ * `frame-ancestors` must also allow the editor origin: with the isolated
+ * preview origin the editor lives on a different origin than the preview, so
+ * `'self'` alone would block the editor from framing the variant preview
+ * (`frame-ancestors 'self' → refused to connect`). See
+ * docs/preview-target-addressing-design.md.
+ */
+const buildStaticPreviewCsp = (parentFrameOrigin) => {
+    const frameAncestors = parentFrameOrigin
+        ? `'self' ${parentFrameOrigin}`
+        : "'self'";
+    return [
+        "default-src 'self' data: blob:",
+        `script-src 'self' 'unsafe-inline' blob: ${PREVIEW_CDN_HOSTS}`,
+        `style-src 'self' 'unsafe-inline' ${PREVIEW_CDN_HOSTS}`,
+        "img-src 'self' data: blob: https:",
+        `font-src 'self' data: ${PREVIEW_CDN_HOSTS}`,
+        `connect-src 'self' blob: ${PREVIEW_CDN_HOSTS}`,
+        `frame-ancestors ${frameAncestors}`,
+        "base-uri 'self'",
+    ].join('; ');
+};
 const previewPortBody = v3_1.z.object({
     variantId: v3_1.z.string().min(1).nullable(),
 });
@@ -120,6 +141,73 @@ const commentReferenceItemSchema = v3_1.z.object({
     label: v3_1.z.string().min(1),
     origin: v3_1.z.enum(['live', 'history']),
 });
+const inlineVariantTargetSchema = v3_1.z.object({
+    kind: v3_1.z.literal('variant'),
+    sessionId: v3_1.z.string().min(1),
+    variantId: v3_1.z.string().min(1),
+});
+const inlineStaticPreviewTargetSchema = v3_1.z.object({
+    kind: v3_1.z.literal('static_preview'),
+    sessionId: v3_1.z.string().min(1),
+    variantId: v3_1.z.string().min(1),
+});
+const inlineVariantBriefSchema = contracts_1.startVariantsBriefContent.superRefine((brief, context) => {
+    const titleWordCount = brief.label.trim().split(/\s+/).length;
+    const subtitleWordCount = brief.body.trim().split(/\s+/).length;
+    if (titleWordCount > DIRECTION_TITLE_MAX_WORDS) {
+        context.addIssue({
+            code: v3_1.z.ZodIssueCode.custom,
+            path: ['label'],
+            message: 'direction titles must contain at most 5 words',
+        });
+    }
+    if (subtitleWordCount > DIRECTION_SUBTITLE_MAX_WORDS) {
+        context.addIssue({
+            code: v3_1.z.ZodIssueCode.custom,
+            path: ['body'],
+            message: 'direction subtitles must contain at most 10 words',
+        });
+    }
+});
+const inlineVariantRequestSchema = v3_1.z
+    .object({
+    count: v3_1.z.number().int().min(contracts_1.VARIANT_COUNT_MIN).max(contracts_1.VARIANT_COUNT_MAX),
+    mode: v3_1.z.enum(['existing', 'zero_to_one']).optional(),
+    briefs: v3_1.z
+        .array(inlineVariantBriefSchema)
+        .min(contracts_1.VARIANT_COUNT_MIN)
+        .max(contracts_1.VARIANT_COUNT_MAX)
+        .optional(),
+})
+    .superRefine((request, context) => {
+    if (request.briefs && request.briefs.length !== request.count) {
+        context.addIssue({
+            code: v3_1.z.ZodIssueCode.custom,
+            path: ['briefs'],
+            message: 'briefs length must match count',
+        });
+    }
+    if (request.briefs) {
+        const labels = request.briefs.map((brief) => brief.label.trim().toLowerCase().replace(/\s+/g, ' '));
+        if (new Set(labels).size !== labels.length) {
+            context.addIssue({
+                code: v3_1.z.ZodIssueCode.custom,
+                path: ['briefs'],
+                message: 'brief labels must be distinct',
+            });
+        }
+    }
+});
+const inlineInitiatorSchema = v3_1.z
+    .discriminatedUnion('kind', [
+    v3_1.z.object({ kind: v3_1.z.literal('human') }),
+    v3_1.z.object({
+        kind: v3_1.z.literal('agent'),
+        agent: v3_1.z.enum(['claude', 'codex', 'cursor', 'unknown']),
+        model: v3_1.z.string().max(200).optional(),
+    }),
+])
+    .optional();
 const inlineVariantBody = v3_1.z.object({
     changes: v3_1.z
         .array(v3_1.z
@@ -130,17 +218,15 @@ const inlineVariantBody = v3_1.z.object({
         instruction: v3_1.z.string().min(1),
         images: v3_1.z.array(v3_1.z.string()).optional(),
         references: v3_1.z.array(commentReferenceItemSchema).max(8).optional(),
-        variantRequest: v3_1.z.object({
-            count: v3_1.z
-                .number()
-                .int()
-                .min(contracts_1.VARIANT_COUNT_MIN)
-                .max(contracts_1.VARIANT_COUNT_MAX),
-        }),
+        variantRequest: inlineVariantRequestSchema,
     })
         .passthrough())
         .min(1),
     sourceFiles: v3_1.z.array(v3_1.z.string()).optional(),
+    /** Vary on an existing variant: attaches to the active session. */
+    target: inlineVariantTargetSchema.optional(),
+    /** Vary on an HTML-only static preview: forks it via the refine flow. */
+    staticPreviewTarget: inlineStaticPreviewTargetSchema.optional(),
     telemetryContext: v3_1.z
         .object({
         browserSessionId: v3_1.z.string().optional(),
@@ -149,6 +235,19 @@ const inlineVariantBody = v3_1.z.object({
         .optional(),
     traceId: v3_1.z.string().optional(),
     agentRunId: v3_1.z.string().optional(),
+    initiator: inlineInitiatorSchema,
+});
+const hostVariantCompleteBody = v3_1.z.object({
+    status: v3_1.z.enum(['succeeded', 'failed', 'cancelled']).default('succeeded'),
+    output: v3_1.z.unknown().optional(),
+    error: v3_1.z
+        .object({
+        code: v3_1.z.string().min(1),
+        message: v3_1.z.string().min(1),
+    })
+        .optional(),
+    title: v3_1.z.string().min(1).max(120).optional(),
+    description: v3_1.z.string().min(1).max(400).optional(),
 });
 // Shared by the active-session and history rename routes. Trim first so a
 // whitespace-only title is rejected, and cap the length so an over-long label
@@ -200,19 +299,18 @@ const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => {
  */
 const getVariantShareTitle = (manifest) => {
     const title = [manifest.label, manifest.brief, manifest.sessionPrompt].find((candidate) => candidate.trim().length > 0);
-    return ((0, PrototypeDeployService_1.normalizePrototypeShareTitle)(title) ??
-        VARIANT_SHARE_TITLE_FALLBACK);
+    return (0, PrototypeDeployService_1.normalizePrototypeShareTitle)(title) ?? VARIANT_SHARE_TITLE_FALLBACK;
 };
 /**
  * Selects the run prompt for a public canvas share, with a stable fallback.
  */
 const getCanvasShareTitle = (sessionPrompt) => {
-    return ((0, PrototypeDeployService_1.normalizePrototypeShareTitle)(sessionPrompt) ??
-        CANVAS_SHARE_TITLE_FALLBACK);
+    return ((0, PrototypeDeployService_1.normalizePrototypeShareTitle)(sessionPrompt) ?? CANVAS_SHARE_TITLE_FALLBACK);
 };
 const CANVAS_IFRAME_SANDBOX = 'allow-scripts allow-forms allow-popups';
 const RIVET_SOCIAL_IMAGE_URL = 'https://rivet.design/images/rivet-social.png';
 const RIVET_DEFAULT_SHARE_DESCRIPTION = 'Built with Rivet — the visual editor for design';
+const UNSUPPORTED_PROTOTYPE_DEPLOY_MESSAGE = "This prototype can't be deployed — only buildable app directions or static previews are supported.";
 /**
  * Render a public canvas page that puts every deployed direction in one shareable view.
  */
@@ -444,7 +542,7 @@ const stampWatcherLiveness = (snapshot, liveness, pendingVariantRequestCount, ac
     };
 };
 exports.stampWatcherLiveness = stampWatcherLiveness;
-const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHistoryOverride, deployServiceOverride, variantRunService, historyReplayOverride) => {
+const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHistoryOverride, deployServiceOverride, variantRunService, historyReplayOverride, previewBridge, inlineStartTrackerOverride) => {
     const router = (0, express_1.Router)();
     // `agent_variants.*` events from this router (preview switches, active-project
     // transitions) must carry the browser's PostHog $session_id to link to a
@@ -467,7 +565,19 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 ? (port) => bridge.switchPreviewPort(port)
                 : undefined,
         });
-    let isInlineVariantRequestStarting = false;
+    const inlineStartTracker = inlineStartTrackerOverride ?? (0, inlineStartTracker_1.createInlineStartTracker)();
+    const touchActiveVariantSession = () => {
+        orchestrator.touchActiveSession?.();
+    };
+    const touchVariantSession = (sessionId) => {
+        orchestrator.touchSession?.(sessionId);
+    };
+    router.use('/variants', (req, _res, next) => {
+        if ((0, loopback_1.isLoopbackAddress)(req.socket.remoteAddress)) {
+            touchActiveVariantSession();
+        }
+        next();
+    });
     /**
      * Stamp the live watcher liveness onto a snapshot before it leaves the server.
      * The `typeof` guards keep partial bridge mocks (and a missing bridge) from
@@ -566,6 +676,31 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         });
         return true;
     };
+    /**
+     * Resolve the saved app directory a deploy build should run from.
+     */
+    const resolveDeployableAppDir = async (args) => {
+        const manifest = args.variant.manifest;
+        if (manifest.projectKind === 'fresh' &&
+            manifest.artifact.kind === 'project') {
+            return path_1.default.join(args.variant.variantDir, 'files');
+        }
+        if (manifest.projectKind !== 'existing' ||
+            !manifest.tree ||
+            manifest.serve?.kind !== 'dev-server') {
+            return null;
+        }
+        const cacheDir = await variantHistory.store.extractToCache({
+            projectPath: args.projectPath,
+            treeSha: manifest.tree.treeSha,
+            commitish: manifest.tree.ref,
+        });
+        const appDir = resolvePathWithinRoot(cacheDir, manifest.serve.recipe.cwd);
+        if (!appDir || !node_fs_1.default.existsSync(path_1.default.join(appDir, 'package.json'))) {
+            return null;
+        }
+        return appDir;
+    };
     /**
      * Deploy one persisted variant and append the returned public URL to history.
      */
@@ -594,18 +729,20 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             // — upload files/ directly, no build needed.
             result = await deployService.deployStatic(filesDir, { title });
         }
-        else if (args.variant.manifest.projectKind === 'fresh' &&
-            args.variant.manifest.artifact.kind === 'project') {
-            // Buildable fresh Vite app — compile then upload.
-            result = await deployService.deploy(filesDir, { title });
-        }
         else {
-            return {
-                ok: false,
-                status: 422,
-                errorCode: 'RUNTIME_VALIDATION_FAILED',
-                message: "This prototype can't be deployed — only fresh app directions or static previews are supported.",
-            };
+            const appDir = await resolveDeployableAppDir({
+                projectPath: args.projectPath,
+                variant: args.variant,
+            });
+            if (!appDir) {
+                return {
+                    ok: false,
+                    status: 422,
+                    errorCode: 'RUNTIME_VALIDATION_FAILED',
+                    message: UNSUPPORTED_PROTOTYPE_DEPLOY_MESSAGE,
+                };
+            }
+            result = await deployService.deploy(appDir, { title });
         }
         const deployment = {
             deployId: result.deployId,
@@ -646,13 +783,37 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             });
             return;
         }
+        // Resolve a variant target that points at an HTML-only static preview:
+        // those requests fork through the refine flow rather than code-gen (a
+        // static preview has no worktree to edit). Gate on the TRUE work-item kind
+        // — never on HTML presence or the client's claim: an existing-project
+        // `code_gen` variant materialized as a static preview serves HTML and
+        // displays as `static_artifact`, but owns a worktree and MUST fork via the
+        // code_gen path (the static fork would reject it with VARIANT_NOT_EDITABLE).
+        const batchTarget = parsed.data.target;
+        const claimedStaticTarget = parsed.data.staticPreviewTarget ??
+            (batchTarget
+                ? {
+                    kind: 'static_preview',
+                    sessionId: batchTarget.sessionId,
+                    variantId: batchTarget.variantId,
+                }
+                : undefined);
+        const staticPreviewTarget = claimedStaticTarget &&
+            orchestrator.getVariantWorkItemKind(claimedStaticTarget.sessionId, claimedStaticTarget.variantId) === 'static_preview'
+            ? claimedStaticTarget
+            : undefined;
         const request = {
             changes: parsed.data.changes,
             sourceFiles: parsed.data.sourceFiles ?? [],
+            target: batchTarget,
+            staticPreviewTarget,
             telemetryContext: parsed.data.telemetryContext,
             traceId: parsed.data.traceId,
             agentRunId: parsed.data.agentRunId,
+            initiator: parsed.data.initiator,
         };
+        bridge?.updateTelemetryContext(request.telemetryContext);
         if ((0, changeBatchClassification_1.isMixedVariantBatch)(request) || !(0, changeBatchClassification_1.isSingleVariantRequestBatch)(request)) {
             res.status(400).json({
                 error: 'Invalid inline variants batch',
@@ -662,18 +823,63 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             return;
         }
         const activeVariantsSession = orchestrator.buildActiveSnapshot();
-        if ((0, variantSessionStart_1.isVariantSessionStartBlocked)(activeVariantsSession) ||
-            isInlineVariantRequestStarting) {
+        // A targeted request attaches to the active session as a new concurrent
+        // run — allowed while a session is live, but only against the CURRENTLY
+        // active session (mirrors the queue-changes intake guards).
+        const effectiveTarget = batchTarget ?? staticPreviewTarget;
+        if (effectiveTarget &&
+            activeVariantsSession.active === true &&
+            effectiveTarget.sessionId !== activeVariantsSession.sessionId) {
+            res.status(400).json({
+                error: 'Stale variant target',
+                details: 'The targeted variants session is not the active one. Refresh the editor and retry.',
+                reason: 'stale_target',
+            });
+            return;
+        }
+        if (!effectiveTarget &&
+            (0, variantSessionStart_1.isVariantSessionStartBlocked)(activeVariantsSession)) {
+            const stage = activeVariantsSession.active === true
+                ? activeVariantsSession.stage
+                : undefined;
+            const sessionId = activeVariantsSession.active === true
+                ? activeVariantsSession.sessionId
+                : undefined;
             res.status(400).json({
                 error: 'Variants session already active',
-                details: 'Finish or cancel the running variants session before submitting another variant request.',
+                // Name the blocker so callers are not flying blind, and never
+                // recommend cancel as remediation: cancelling to unblock destroys
+                // the user's in-progress work. Only a human should decide that.
+                details: `A variants session is active${sessionId
+                    ? ` (session ${sessionId}${stage ? `, stage ${stage}` : ''})`
+                    : ''}. Wait for it to settle (poll status), target it with --target to refine it, or ask the user before cancelling anything.`,
                 reason: 'active_session',
             });
             return;
         }
-        isInlineVariantRequestStarting = true;
+        if (!effectiveTarget && inlineStartTracker.isStarting()) {
+            res.status(400).json({
+                error: 'Variants start already in progress',
+                details: 'A variants start for this project is still being processed (provisioning can take a while) — status reports it as `variants.starting`. Poll status until the session registers or the start settles, then retry. Do not cancel anything.',
+                reason: 'start_in_flight',
+            });
+            return;
+        }
+        if (!effectiveTarget) {
+            inlineStartTracker.begin();
+        }
         try {
-            const result = await variantRunService.startElementVariants(request);
+            const isStaticPreviewFork = Boolean(staticPreviewTarget);
+            if (isStaticPreviewFork && !variantRunService.refineStaticPreviewBatch) {
+                res.status(503).json({
+                    error: 'Static preview refinement unavailable',
+                    reason: 'inline_variants_unavailable',
+                });
+                return;
+            }
+            const result = isStaticPreviewFork
+                ? await variantRunService.refineStaticPreviewBatch(request)
+                : await variantRunService.startElementVariants(request);
             if (!result.success) {
                 res.status(500).json({
                     error: result.error ?? 'Inline variants run failed',
@@ -691,13 +897,62 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             });
         }
         finally {
-            isInlineVariantRequestStarting = false;
+            if (!effectiveTarget) {
+                inlineStartTracker.end();
+            }
+        }
+    });
+    router.post('/variants/:sessionId/work/:workItemId/complete', async (req, res) => {
+        if (rejectNonLocalRequest(req, res))
+            return;
+        if (!variantRunService) {
+            res.status(503).json({
+                error: 'Variants unavailable',
+                reason: 'variants_unavailable',
+            });
+            return;
+        }
+        const parsed = hostVariantCompleteBody.safeParse(req.body);
+        if (!parsed.success) {
+            res.status(400).json({
+                error: 'Invalid host work completion payload',
+                details: parsed.error.flatten(),
+            });
+            return;
+        }
+        try {
+            const result = await variantRunService.completeHostWork({
+                sessionId: req.params.sessionId,
+                workItemId: req.params.workItemId,
+                status: parsed.data.status,
+                ...(parsed.data.output !== undefined
+                    ? { output: parsed.data.output }
+                    : {}),
+                ...(parsed.data.error ? { error: parsed.data.error } : {}),
+                ...(parsed.data.title ? { title: parsed.data.title } : {}),
+                ...(parsed.data.description
+                    ? { description: parsed.data.description }
+                    : {}),
+            });
+            res.status(200).json(result);
+        }
+        catch (err) {
+            const status = err instanceof agent_variants_1.AgentVariantsError ? 400 : 500;
+            res.status(status).json({
+                error: err instanceof Error ? err.message : 'Host work completion failed',
+                reason: err instanceof agent_variants_1.AgentVariantsError
+                    ? err.code
+                    : 'host_work_completion_failed',
+            });
         }
     });
     router.get('/variants/active', (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
-        res.json(stampLiveness(orchestrator.buildActiveSnapshot()));
+        res.json(stampLiveness({
+            ...orchestrator.buildActiveSnapshot(),
+            starting: inlineStartTracker.isStarting(),
+        }));
     });
     /**
      * Server-Sent Events stream for the iframe chip. Pushes a fresh
@@ -725,7 +980,13 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         // so the initial state and every subscribed update carry them.
         const writeSnapshot = (snapshot) => {
             try {
-                res.write(`data: ${JSON.stringify(stampLiveness(snapshot))}\n\n`);
+                const activeSnapshot = snapshot && typeof snapshot === 'object'
+                    ? {
+                        ...snapshot,
+                        starting: inlineStartTracker.isStarting(),
+                    }
+                    : snapshot;
+                res.write(`data: ${JSON.stringify(stampLiveness(activeSnapshot))}\n\n`);
             }
             catch (err) {
                 log.warn('SSE write failed (client likely disconnected)', err);
@@ -748,6 +1009,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
         const releaseUiClient = orchestrator.registerUiClient();
         const heartbeat = setInterval(() => {
             try {
+                touchActiveVariantSession();
                 res.write(': heartbeat\n\n');
             }
             catch {
@@ -799,7 +1061,11 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             return;
         }
         try {
-            const entries = (await Promise.all(resolveHistoryProjectPaths({ projectPath }).map((historyProjectPath) => variantHistory.listVariants({
+            const entries = (await Promise.all(resolveHistoryProjectPaths({ projectPath }).map((historyProjectPath) => 
+            // Reads the SQLite metadata index when it's usable and falls
+            // back to the manifest walk otherwise — same entries, faster
+            // list. Detail/preview routes stay manifest/file-backed.
+            variantHistory.listVariantsFromIndex({
                 projectPath: historyProjectPath,
                 status: statusParam,
             })))).flat();
@@ -827,6 +1093,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                     runLabel: entry.manifest.runLabel ??
                         (0, runLabel_1.deriveRunLabel)(entry.manifest.sessionPrompt),
                     kind: manifestKind(entry.manifest),
+                    projectKind: entry.manifest.projectKind,
                     status: entry.manifest.status,
                     createdAt: entry.manifest.createdAt,
                     statusChangedAt: entry.manifest.statusChangedAt,
@@ -834,6 +1101,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                     hasStaticPreview: entry.hasStaticPreview,
                     preview: entry.manifest.preview,
                     artifact: entry.manifest.artifact,
+                    parentVariant: entry.manifest.parentVariant,
                     // Tree-store fields (absent on legacy entries): `serve` tells the
                     // panel how a tree-backed entry previews (static → history preview
                     // route; dev-server → the replay run route), `hasTree` marks the
@@ -850,23 +1118,29 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
     // Mirror the live static route's split: the HTML document and its sibling
     // assets are served by separate handlers, so the preview CSP is attached
     // structurally (document only) rather than via a runtime content-type branch.
-    router.get('/variants/history/:sessionId/:variantId/preview', async (req, res) => serveHistoryPreview(req, res, variantHistory, resolveProjectPath, resolveHistoryProjectPaths, { isDocument: true }));
+    router.get('/variants/history/:sessionId/:variantId/preview', async (req, res) => serveHistoryPreview(req, res, variantHistory, resolveProjectPath, resolveHistoryProjectPaths, { isDocument: true }, previewBridge));
     router.get('/variants/history/:sessionId/:variantId/preview/{*assetPath}', async (req, res) => serveHistoryPreview(req, res, variantHistory, resolveProjectPath, resolveHistoryProjectPaths, { isDocument: false }));
-    // Stop the active history replay (if any). Registered before the
+    // Stop history replay servers. Registered before the
     // parameterized history routes purely for clarity — method+arity keep it
     // unambiguous either way.
     router.post('/variants/history/replay/stop', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
             return;
-        await historyReplay.stop();
+        const sessionId = typeof req.query.sessionId === 'string' ? req.query.sessionId : null;
+        const variantId = typeof req.query.variantId === 'string' ? req.query.variantId : null;
+        if (sessionId && variantId) {
+            await historyReplay.stop({ sessionId, variantId });
+        }
+        else {
+            await historyReplay.stop();
+        }
         res.json({ stopped: true });
     });
     /**
      * Boot a past dev-server variant from its tree-store ref: materialize the
      * exact tree, overlay runtime (.env / node_modules), start the persisted
-     * serve recipe, and retarget the preview proxy at the new port. LRU=1 —
-     * running a second variant stops the first. See
-     * docs/variant-history-tree-store-design.md.
+     * serve recipe, and optionally retarget the main preview proxy at the new
+     * port. See docs/variant-history-tree-store-design.md.
      */
     router.post('/variants/history/:sessionId/:variantId/run', async (req, res) => {
         if (rejectNonLocalRequest(req, res))
@@ -898,6 +1172,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 projectPath: found.projectPath,
                 sessionId,
                 variantId,
+                retargetProxy: req.query.targetAddressed !== '1',
             });
             res.json(result);
         }
@@ -991,6 +1266,7 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
             });
             return;
         }
+        touchVariantSession(sessionId);
         try {
             if (!parsed.data.variantId) {
                 variantsTelemetry?.trackAgentVariantsPreviewSwitchStarted({
@@ -1229,20 +1505,29 @@ const createAgentVariantsRouter = (orchestrator, bridge, telemetry, variantHisto
                 res.redirect(301, req.originalUrl + '/');
                 return;
             }
-            const finalHtml = hasAssets
+            const withBaseHref = hasAssets
                 ? injectBaseHref(html, 
                 // Trailing slash is required so `./avatar.glb` resolves to
                 // `.../static/<vid>/avatar.glb`, not `.../static/avatar.glb`.
                 `/api/variants/${encodeURIComponent(sessionId)}/static/${encodeURIComponent(variantId)}/`)
                 : html;
+            // In embedded mode the visual editor drives this iframe over the preview
+            // bridge; without the injected listener, selecting/commenting on the
+            // variant times out (`Preview bridge timed out`) and the comment input
+            // never opens. Mirror the base static route (`routes/static.ts`).
+            const finalHtml = previewBridge?.isEnabled
+                ? (0, preview_bridge_1.injectPreviewBridge)(withBaseHref, {
+                    expectedParentOrigin: previewBridge.expectedParentOrigin,
+                })
+                : withBaseHref;
             // Constrain the blast radius of agent-generated scripts. See
-            // STATIC_PREVIEW_CSP for the policy and the isolated-origin migration
+            // buildStaticPreviewCsp for the policy and the isolated-origin migration
             // that will eventually let us drop the per-CDN allowlist.
             res
                 .status(200)
                 .type('html')
                 .set('Cache-Control', 'no-store')
-                .set('Content-Security-Policy', STATIC_PREVIEW_CSP)
+                .set('Content-Security-Policy', buildStaticPreviewCsp(previewBridge?.expectedParentOrigin))
                 .set('X-Content-Type-Options', 'nosniff')
                 .send(finalHtml);
         }
@@ -1828,7 +2113,7 @@ exports.createAgentVariantsRouter = createAgentVariantsRouter;
  * preview CSP; sibling assets (css/js/images) carry none, since a CSP header is
  * only load-bearing on the document that fetches sub-resources.
  */
-const serveHistoryPreview = async (req, res, variantHistory, resolveProjectPath, resolveHistoryProjectPaths, { isDocument }) => {
+const serveHistoryPreview = async (req, res, variantHistory, resolveProjectPath, resolveHistoryProjectPaths, { isDocument }, previewBridge) => {
     if (rejectNonLocalRequest(req, res))
         return;
     const invalidRawAssetPath = getInvalidRawHistoryPreviewAssetPath(req);
@@ -1891,8 +2176,17 @@ const serveHistoryPreview = async (req, res, variantHistory, resolveProjectPath,
         // blanking out where the live preview rendered.
         if (isDocument) {
             res
-                .set('Content-Security-Policy', STATIC_PREVIEW_CSP)
+                .set('Content-Security-Policy', buildStaticPreviewCsp(previewBridge?.expectedParentOrigin))
                 .set('X-Content-Type-Options', 'nosniff');
+            // Embedded mode drives this snapshot iframe over the preview bridge; the
+            // listener must be present or selecting/commenting on a past variant
+            // times out (`Preview bridge timed out`). Matches the live static route.
+            if (previewBridge?.isEnabled) {
+                res.send((0, preview_bridge_1.injectPreviewBridge)(file.body.toString('utf8'), {
+                    expectedParentOrigin: previewBridge.expectedParentOrigin,
+                }));
+                return;
+            }
         }
         res.send(file.body);
     }
@@ -1932,9 +2226,23 @@ const getInvalidRawHistoryPreviewAssetPath = (req) => {
     }
     return null;
 };
+/**
+ * Resolve a child path while rejecting paths that escape the intended root.
+ */
+const resolvePathWithinRoot = (rootPath, childPath) => {
+    const absolutePath = path_1.default.resolve(rootPath, childPath);
+    const relativePath = path_1.default.relative(rootPath, absolutePath);
+    if (relativePath === '' ||
+        (relativePath.length > 0 &&
+            !relativePath.startsWith('..') &&
+            !path_1.default.isAbsolute(relativePath))) {
+        return absolutePath;
+    }
+    return null;
+};
 function rejectNonLocalRequest(req, res) {
     const remoteAddress = req.socket.remoteAddress;
-    if (isLoopbackAddress(remoteAddress))
+    if ((0, loopback_1.isLoopbackAddress)(remoteAddress))
         return false;
     res.status(403).json({
         errorCode: 'RUNTIME_VALIDATION_FAILED',
@@ -1942,13 +2250,6 @@ function rejectNonLocalRequest(req, res) {
     });
     return true;
 }
-function isLoopbackAddress(remoteAddress) {
-    if (!remoteAddress)
-        return false;
-    return (remoteAddress === '127.0.0.1' ||
-        remoteAddress === '::1' ||
-        remoteAddress.startsWith('::ffff:127.'));
-}
 function stateForSession(orchestrator, sessionId) {
     const stage = orchestrator.getStage(sessionId);
     const briefs = orchestrator.getBriefs(sessionId);