rivet-design 0.10.8 → 0.11.0

package/dist/mcp/agent-variants/SessionStore.js

@@ -1,10 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionStore = exports.buildImageRefs = exports.SOURCE_PLAN_OUTPUT_SCHEMA = exports.SCAFFOLD_LEASE_TTL_MS = exports.DEFAULT_LEASE_TTL_MS = void 0;
+exports.SessionStore = exports.buildImageRefs = exports.SOURCE_PLAN_ACTION_OPTIONS = exports.SOURCE_PLAN_OUTPUT_SCHEMA = exports.SCAFFOLD_LEASE_TTL_MS = exports.DEFAULT_LEASE_TTL_MS = void 0;
 const crypto_1 = require("crypto");
 const errors_1 = require("./errors");
 const contracts_1 = require("./contracts");
-const sourceContext_1 = require("./sourceContext");
 const runLabel_1 = require("./runLabel");
 const runPlan_1 = require("./runPlan");
 const DEFAULT_VARIANT_COUNT = 4;
@@ -38,11 +37,27 @@ function descriptorFor(item) {
     };
 }
 exports.SOURCE_PLAN_OUTPUT_SCHEMA = {
-    sourceIntent: "sources: Array<{ url? | imageRef?, role: design_source|interaction_reference|asset_source|content_reference|other, confidence: low|medium|high, reason }> — classify every input source. Each entry keys by EXACTLY ONE of `url` (an inspiration URL the user provided) OR `imageRef` (a stable `image:<index>` reference for an attached-image artifact; the index matches the order of image-kind entries in the session's `sourceArtifacts`, i.e. visualBrief/screenshotNotes). Classify by prompt intent only, no deterministic URL heuristics.",
-    sourceContext: 'sourceFindings, sectionInventory, visualObservations, sourceRoles, qualityBar, screenshotReferences?, risks?',
-    designContexts: 'Array<{ url? | imageRef?, label, markdown }> REQUIRED for every design_source from sourceIntent. Use `url` for browser-extracted DESIGN.md from inspiration URLs; use `imageRef` (the matching `image:<index>` ref) for DESIGN.md you derived from an attached image. For image-derived DESIGN.md, write `Not observed` for sections you cannot determine from the image (commonly Responsive Behavior, full interaction states) rather than inventing values.',
+    actions: "Required Array<{ id, kind: 'extract_design_system'|'describe_motion', sourceIds, reason }> — actions selected after inspecting raw input.userContext and the prompt. Use only kinds listed in input.availableActions. May be empty when no source warrants enrichment.",
+    metadata: "Required Array<{ id, kind: 'design_system'|'motion_guidance', sourceIds, actionId?, producedBy, data }> — additive metadata produced from the reported actions. Every action MUST produce its matching metadata kind (extract_design_system -> design_system, describe_motion -> motion_guidance). For URL-backed design_system, call capture_design_evidence({ sessionId, url }) before report_source_plan and set data.evidenceStatus. For design_system, data may include designMarkdown; otherwise Rivet synthesizes DESIGN.md from the structured observations. For motion_guidance, data may include motionMarkdown plus notes/timings. Raw userContext remains authoritative; metadata is additive shared guidance.",
+    bindings: "Optional Array<{ kind:'global', sourceIds, actionIds, metadataIds? } | { kind:'slot', slotIndex, sourceIds, actionIds, metadataIds? }> — omit for the default global context behavior.",
     executionPlan: "{ mode: 'static_preview' | 'vite_app', confidence: low|medium|high, reason, assetPlan?: Array<{source, destination, referenceAs}>, runtimeRequirements?, userQuestion? } — choose vite_app for large local assets, model-viewer, Three.js, route structure, package deps, or files under public/; assetPlan.source must live under the approved asset root; static_preview for self-contained HTML/CSS/JS prototypes.",
 };
+exports.SOURCE_PLAN_ACTION_OPTIONS = [
+    {
+        kind: 'extract_design_system',
+        sourceTransports: ['url', 'file', 'text'],
+        capability: 'extract_inspiration_context',
+        produces: 'design_system',
+        instructions: 'Inspect visual references natively and use the existing inspiration/design-context extraction path to produce reusable design_system metadata.',
+    },
+    {
+        kind: 'describe_motion',
+        sourceTransports: ['url', 'file'],
+        capability: 'rivet_describe_motion',
+        produces: 'motion_guidance',
+        instructions: 'Inspect interaction references natively and use the Rivet Describe Motion protocol to produce motion_guidance metadata.',
+    },
+];
 /** Returns the completion payload shape required for each leased work item. */
 function outputSchemaFor(kind) {
     switch (kind) {
@@ -88,9 +103,25 @@ const createBriefWorkItem = (args) => ({
         count: args.count,
         target: args.target,
         projectContext: args.projectContext,
+        ...briefWorkItemContext(args.projectContext),
     },
     acceptedReports: [],
 });
+const briefWorkItemContext = (projectContext) => {
+    const bundle = projectContext.variantContext;
+    if (!bundle)
+        return {};
+    return {
+        context: {
+            contextBundlePath: bundle.contextBundlePath,
+            userContext: bundle.userContext,
+            rivetMetadata: bundle.rivetMetadata,
+            ...(projectContext.kind === 'fresh' && projectContext.executionPlan
+                ? { executionMode: projectContext.executionPlan.mode }
+                : {}),
+        },
+    };
+};
 // Source-artifact kinds that represent agent-described attached images.
 // These need their own DESIGN.md slot in the source_plan output, alongside
 // any URL-keyed entries. `siteBrief` / `urlText` are pasted text — they
@@ -118,24 +149,204 @@ const buildImageRefs = (artifacts) => {
 exports.buildImageRefs = buildImageRefs;
 /**
  * Source-grounded fresh sessions require a single `source_plan` planning hop
- * before briefs. The hop fires when there's any source to classify — URLs
- * or attached images. Sessions with the plan already materialized via
- * `artifact` skip straight to `awaiting_briefs`.
+ * before briefs. The hop fires when Rivet has captured a read-only user
+ * context bundle (the sole source-intake surface). The source-plan agent
+ * inspects raw context and reports actions plus metadata.
  */
-const requiresSourcePlan = (projectContext) => {
-    if (projectContext.kind !== 'fresh')
-        return false;
-    const sourceContext = projectContext.sourceContext;
-    if (!sourceContext)
-        return false;
-    const hasUrls = (sourceContext.sourceUrls?.length ?? 0) > 0;
-    const hasImages = (0, exports.buildImageRefs)(sourceContext.sourceArtifacts).length > 0;
-    if (!hasUrls && !hasImages)
-        return false;
-    const hasArtifact = Boolean(sourceContext.artifact);
-    const hasIntent = Boolean(sourceContext.sourceIntent);
-    const hasExecutionPlan = Boolean(projectContext.executionPlan);
-    return !(hasArtifact && hasIntent && hasExecutionPlan);
+const requiresSourcePlan = (projectContext) => projectContext.kind === 'fresh' && Boolean(projectContext.variantContext);
+const listSection = (title, items) => {
+    if (items.length === 0)
+        return [];
+    return [`## ${title}`, '', ...items.map((item) => `- ${item}`), ''];
+};
+const hasSharedSource = (sourceIds, candidateSourceIds) => candidateSourceIds.some((sourceId) => sourceIds.includes(sourceId));
+/**
+ * Formats motion metadata that applies to the same raw sources as the design metadata.
+ */
+const buildMotionGuidanceMarkdown = (sourceIds, metadata) => {
+    const matchingMotion = metadata.filter((entry) => entry.kind === 'motion_guidance' &&
+        hasSharedSource(sourceIds, entry.sourceIds));
+    if (matchingMotion.length === 0)
+        return [];
+    const lines = ['## Motion Guidance', ''];
+    for (const entry of matchingMotion) {
+        if (entry.data.motionMarkdown) {
+            lines.push(entry.data.motionMarkdown.trim(), '');
+            continue;
+        }
+        lines.push(...entry.data.notes.map((item) => `- ${item}`));
+        if (entry.data.timings && entry.data.timings.length > 0) {
+            lines.push('', '### Timings', '');
+            lines.push(...entry.data.timings.map((item) => `- ${item}`));
+        }
+        lines.push('');
+    }
+    return lines;
+};
+/**
+ * Converts design-system metadata into the markdown artifact variant agents consume.
+ */
+const buildDesignMarkdownFromMetadata = (entry, metadata) => {
+    if (entry.data.designMarkdown) {
+        return entry.data.designMarkdown;
+    }
+    const sourceRoleLines = entry.data.sourceRoles.map((role) => role.rationale
+        ? `${role.role}: ${role.sourceId} (${role.rationale})`
+        : `${role.role}: ${role.sourceId}`);
+    const lines = [
+        '# Design System',
+        '',
+        ...listSection('Source Findings', entry.data.sourceFindings),
+        ...listSection('Section Inventory', entry.data.sectionInventory),
+        ...listSection('Visual Observations', entry.data.visualObservations),
+        ...listSection('Source Roles', sourceRoleLines),
+        ...buildMotionGuidanceMarkdown(entry.sourceIds, metadata),
+        ...listSection('Quality Bar', entry.data.qualityBar),
+        ...(entry.data.risks ? listSection('Risks', entry.data.risks) : []),
+    ];
+    return `${lines.join('\n').trim()}\n`;
+};
+/**
+ * Builds design-context entries from action metadata when the report does not provide them directly.
+ */
+const designContextsFromActionMetadata = (metadata) => {
+    if (!metadata)
+        return [];
+    return metadata
+        .filter((entry) => entry.kind === 'design_system')
+        .map((entry, index) => ({
+        label: index === 0 ? 'Design system' : `Design system ${index + 1}`,
+        markdown: buildDesignMarkdownFromMetadata(entry, metadata),
+    }));
+};
+const mergeVariantContext = (args) => {
+    if (!args.bundle)
+        return undefined;
+    const metadata = args.sourcePlan.metadata;
+    const metadataByActionId = new Map();
+    for (const entry of metadata) {
+        if (!entry.actionId)
+            continue;
+        const ids = metadataByActionId.get(entry.actionId) ?? [];
+        ids.push(entry.id);
+        metadataByActionId.set(entry.actionId, ids);
+    }
+    const actions = args.sourcePlan.actions.map((action) => ({
+        ...action,
+        outputMetadataIds: action.outputMetadataIds ?? metadataByActionId.get(action.id),
+    }));
+    return {
+        ...args.bundle,
+        sessionId: args.sessionId,
+        rivetActions: actions,
+        rivetMetadata: metadata,
+        ...(args.sourcePlan.bindings ? { bindings: args.sourcePlan.bindings } : {}),
+        executionPlan: args.sourcePlan.executionPlan,
+    };
+};
+const METADATA_KIND_BY_ACTION_KIND = {
+    extract_design_system: 'design_system',
+    describe_motion: 'motion_guidance',
+};
+/**
+ * Validates the reported source plan's action/metadata invariants:
+ *  - metadata is produced BY actions, so metadata reported with zero actions
+ *    is rejected (it would otherwise build DESIGN.md from an orphaned payload);
+ *  - every metadata entry references real raw-context sources;
+ *  - every reported action produces the metadata kind it claims to.
+ */
+const validateActionMetadataOutputs = (args) => {
+    const actions = args.sourcePlan.actions;
+    const metadata = args.sourcePlan.metadata;
+    // Metadata is produced BY actions. A plan that reports metadata with no
+    // actions has nothing to produce it — reject rather than silently building
+    // design context from an orphaned, otherwise-unvalidated payload.
+    if (actions.length === 0 && metadata.length > 0) {
+        throw new errors_1.AgentVariantsError('SOURCE_CONTEXT_INVALID', 'source_plan reported metadata without any actions; metadata must be produced by a reported action');
+    }
+    const sourceIds = new Set(args.bundle?.userContext.map((source) => source.id) ?? []);
+    // Validate metadata sourceIds independently of `actions` so an empty action
+    // list can never skip the check wholesale.
+    for (const entry of metadata) {
+        const unknownSourceIds = entry.sourceIds.filter((sourceId) => sourceIds.size > 0 && !sourceIds.has(sourceId));
+        if (unknownSourceIds.length > 0) {
+            throw new errors_1.AgentVariantsError('SOURCE_CONTEXT_INVALID', `source_plan metadata ${entry.id} references unknown sourceIds: ${unknownSourceIds.join(', ')}`);
+        }
+    }
+    if (actions.length === 0)
+        return;
+    const metadataById = new Map(metadata.map((entry) => [entry.id, entry]));
+    for (const action of actions) {
+        const unknownSourceIds = action.sourceIds.filter((sourceId) => sourceIds.size > 0 && !sourceIds.has(sourceId));
+        if (unknownSourceIds.length > 0) {
+            throw new errors_1.AgentVariantsError('SOURCE_CONTEXT_INVALID', `source_plan action ${action.id} references unknown sourceIds: ${unknownSourceIds.join(', ')}`);
+        }
+        const expectedMetadataKind = METADATA_KIND_BY_ACTION_KIND[action.kind];
+        const linkedMetadata = [
+            ...metadata.filter((entry) => entry.actionId === action.id),
+            ...(action.outputMetadataIds ?? [])
+                .map((id) => metadataById.get(id))
+                .filter((entry) => Boolean(entry)),
+        ];
+        const hasExpectedMetadata = linkedMetadata.some((entry) => entry.kind === expectedMetadataKind);
+        if (!hasExpectedMetadata) {
+            throw new errors_1.AgentVariantsError('SOURCE_CONTEXT_INVALID', `source_plan action ${action.id} (${action.kind}) must produce ${expectedMetadataKind} metadata`);
+        }
+    }
+};
+const collectSlotBoundIds = (bindings) => {
+    const sourceIds = new Set();
+    const actionIds = new Set();
+    const metadataIds = new Set();
+    for (const binding of bindings ?? []) {
+        if (binding.kind !== 'slot')
+            continue;
+        binding.sourceIds.forEach((id) => sourceIds.add(id));
+        binding.actionIds.forEach((id) => actionIds.add(id));
+        binding.metadataIds?.forEach((id) => metadataIds.add(id));
+    }
+    return { sourceIds, actionIds, metadataIds };
+};
+const collectMatchingIds = (bindings, slotIndex) => {
+    const sourceIds = new Set();
+    const actionIds = new Set();
+    const metadataIds = new Set();
+    for (const binding of bindings ?? []) {
+        if (binding.kind === 'slot' && binding.slotIndex !== slotIndex)
+            continue;
+        binding.sourceIds.forEach((id) => sourceIds.add(id));
+        binding.actionIds.forEach((id) => actionIds.add(id));
+        binding.metadataIds?.forEach((id) => metadataIds.add(id));
+    }
+    return { sourceIds, actionIds, metadataIds };
+};
+const resolveVariantWorkItemContext = (args) => {
+    if (!args.bundle)
+        return undefined;
+    const bindings = args.bundle.bindings;
+    const boundIds = collectSlotBoundIds(bindings);
+    const matchingIds = collectMatchingIds(bindings, args.slotIndex);
+    const userContext = args.bundle.userContext.filter((source) => !boundIds.sourceIds.has(source.id) ||
+        matchingIds.sourceIds.has(source.id));
+    const rivetMetadata = args.bundle.rivetMetadata.filter((metadata) => {
+        const isSlotBound = boundIds.metadataIds.has(metadata.id) ||
+            (metadata.actionId ? boundIds.actionIds.has(metadata.actionId) : false);
+        const isMatching = matchingIds.metadataIds.has(metadata.id) ||
+            (metadata.actionId
+                ? matchingIds.actionIds.has(metadata.actionId)
+                : false);
+        return !isSlotBound || isMatching;
+    });
+    return {
+        contextBundlePath: args.bundle.contextBundlePath,
+        userContext,
+        rivetMetadata,
+        brief: args.brief,
+        ...(args.projectContext.kind === 'fresh' &&
+            args.projectContext.executionPlan
+            ? { executionMode: args.projectContext.executionPlan.mode }
+            : {}),
+    };
 };
 class SessionStore {
     sessions = new Map();
@@ -153,8 +364,8 @@ class SessionStore {
             kind: 'existing',
         };
         const count = clampCount(args.count);
-        const sourceContextForPlan = projectContext.kind === 'fresh'
-            ? projectContext.sourceContext
+        const bundle = projectContext.kind === 'fresh'
+            ? projectContext.variantContext
             : undefined;
         const needsSourcePlan = requiresSourcePlan(projectContext);
         const initialItem = needsSourcePlan
@@ -168,9 +379,14 @@ class SessionStore {
                     prompt: args.prompt,
                     count,
                     target: args.target,
-                    sourceUrls: sourceContextForPlan?.sourceUrls ?? [],
-                    sourceArtifacts: sourceContextForPlan?.sourceArtifacts ?? [],
-                    preserveBrand: sourceContextForPlan?.preserveBrand ?? false,
+                    ...(bundle
+                        ? {
+                            contextBundlePath: bundle.contextBundlePath,
+                            userContext: bundle.userContext,
+                            availableActions: exports.SOURCE_PLAN_ACTION_OPTIONS,
+                            variantSlotCount: count,
+                        }
+                        : {}),
                     projectContext,
                 },
                 acceptedReports: [],
@@ -236,8 +452,25 @@ class SessionStore {
             throw new errors_1.AgentVariantsError('STALE_LEASE', `attempt mismatch: expected ${item.attempt}, got ${args.attempt}`);
         }
         item.status = 'succeeded';
-        item.output = { briefs: args.briefs };
+        item.output = {
+            briefs: args.briefs,
+            ...(args.bindings ? { bindings: args.bindings } : {}),
+        };
         session.briefs = args.briefs;
+        if (args.bindings &&
+            session.projectContext.kind === 'fresh' &&
+            session.projectContext.variantContext) {
+            session.projectContext = {
+                ...session.projectContext,
+                variantContext: {
+                    ...session.projectContext.variantContext,
+                    bindings: [
+                        ...(session.projectContext.variantContext.bindings ?? []),
+                        ...args.bindings,
+                    ],
+                },
+            };
+        }
         session.stage = 'awaiting_approval';
         const result = { briefs: args.briefs };
         session.acceptedFingerprints.set(fp, result);
@@ -262,110 +495,56 @@ class SessionStore {
             throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', `Work item ${args.workItemId} is not a source_plan item`);
         }
         this.validateLease(item, args.leaseId, args.attempt);
-        const { sourceIntent, sourceContext, designContexts, executionPlan } = args.sourcePlan;
-        // Cross-check: every source URL AND every image-derived source on the
-        // session must be classified, and every design_source (URL or image)
-        // must come with a DESIGN.md.
-        const sessionSourceUrls = session.projectContext.kind === 'fresh'
-            ? (session.projectContext.sourceContext?.sourceUrls ?? [])
-            : [];
-        const sessionImageRefs = session.projectContext.kind === 'fresh'
-            ? (0, exports.buildImageRefs)(session.projectContext.sourceContext?.sourceArtifacts)
-            : [];
-        const classifiedUrls = new Set(sourceIntent.sources
-            .map((e) => e.url)
-            .filter((u) => Boolean(u)));
-        const classifiedImageRefs = new Set(sourceIntent.sources
-            .map((e) => e.imageRef)
-            .filter((r) => Boolean(r)));
-        const missingClassification = [
-            ...sessionSourceUrls.filter((url) => !classifiedUrls.has(url)),
-            ...sessionImageRefs.filter((ref) => !classifiedImageRefs.has(ref)),
-        ];
-        if (missingClassification.length > 0) {
-            throw new errors_1.AgentVariantsError('SOURCE_CONTEXT_INVALID', `source_plan missing sourceIntent classification for: ${missingClassification.join(', ')}`);
-        }
-        const designSourceUrls = sourceIntent.sources
-            .filter((entry) => entry.role === 'design_source' && Boolean(entry.url))
-            .map((entry) => entry.url);
-        const designSourceImageRefs = sourceIntent.sources
-            .filter((entry) => entry.role === 'design_source' && Boolean(entry.imageRef))
-            .map((entry) => entry.imageRef);
-        const reportedDesignUrls = new Set((designContexts ?? [])
-            .map((entry) => entry.url)
-            .filter((u) => Boolean(u)));
-        const reportedDesignImageRefs = new Set((designContexts ?? [])
-            .map((entry) => entry.imageRef)
-            .filter((r) => Boolean(r)));
-        const missingDesignContexts = [
-            ...designSourceUrls.filter((url) => !reportedDesignUrls.has(url)),
-            ...designSourceImageRefs.filter((ref) => !reportedDesignImageRefs.has(ref)),
-        ];
-        if (missingDesignContexts.length > 0) {
-            throw new errors_1.AgentVariantsError('SOURCE_CONTEXT_INVALID', `Missing DESIGN.md for design source(s): ${missingDesignContexts.join(', ')}`);
-        }
-        const normalizedArtifact = (0, sourceContext_1.normalizeSourceContextArtifact)(sourceContext);
+        const { executionPlan, actions, metadata, bindings } = args.sourcePlan;
+        // Canonical path: every reported action must produce its matching metadata
+        // kind, and action sourceIds must reference real raw-context sources.
+        validateActionMetadataOutputs({
+            bundle: session.projectContext.kind === 'fresh'
+                ? session.projectContext.variantContext
+                : undefined,
+            sourcePlan: args.sourcePlan,
+        });
         if (session.projectContext.kind === 'fresh') {
-            // Persist one designContext entry PER design_source URL, aligned
-            // to the SOURCE_INTENT design_source order (NOT the agent's
-            // designContexts submission order). Brief fan-out
-            // (provisionFreshWorktrees) reads slot [min(briefIndex, length-1)]
-            // and falls back to slot 0 — a single-source session still ships
-            // one shared markdown, but a multi-source session puts each
-            // design_source's DESIGN.md at a deterministic slot regardless of
-            // how many non-design_source entries the agent classified or the
-            // order it shipped designContexts in. Without this alignment, an
-            // extra interaction_reference URL ahead of a design_source in the
-            // agent's payload would push the wrong DESIGN.md onto variant 0.
-            const designContextByUrl = new Map();
-            const designContextByImageRef = new Map();
-            for (const entry of designContexts ?? []) {
-                const payload = { label: entry.label, markdown: entry.markdown };
-                if (entry.url) {
-                    designContextByUrl.set(entry.url, payload);
-                }
-                else if (entry.imageRef) {
-                    designContextByImageRef.set(entry.imageRef, payload);
-                }
-            }
-            // Persist URL-keyed entries first (preserving the URL design_source
-            // order from sourceIntent), then image-keyed entries (preserving
-            // their design_source order). Brief fan-out reads slot
-            // [min(briefIndex, length-1)] with a slot-0 fallback, so this
-            // ordering puts URL inspirations on the early variant slots when
-            // both URLs and images are present.
-            const alignedDesignContexts = [
-                ...designSourceUrls
-                    .map((url) => designContextByUrl.get(url))
-                    .filter((entry) => Boolean(entry)),
-                ...designSourceImageRefs
-                    .map((ref) => designContextByImageRef.get(ref))
-                    .filter((entry) => Boolean(entry)),
-            ];
+            // Derive DESIGN.md context directly from `design_system` action
+            // metadata. Each entry uses explicit `designMarkdown` when present, or
+            // is synthesized from the structured observations. Brief fan-out
+            // (provisionFreshWorktrees) reads slot [min(briefIndex, length-1)] with
+            // a slot-0 fallback, so a single design system ships one shared markdown
+            // while multiple design systems land on deterministic slots in report
+            // order.
+            const projectDesignContexts = designContextsFromActionMetadata(metadata);
             session.projectContext = {
                 ...session.projectContext,
-                ...(alignedDesignContexts.length > 0
+                ...(projectDesignContexts.length > 0
                     ? {
-                        designContext: alignedDesignContexts.map((entry) => ({
+                        designContext: projectDesignContexts.map((entry) => ({
                             kind: 'markdown',
                             label: entry.label,
                             content: entry.markdown,
                         })),
                     }
                     : {}),
-                sourceContext: {
-                    ...(session.projectContext.sourceContext ?? {}),
-                    sourceIntent,
-                    artifact: normalizedArtifact,
-                },
                 executionPlan,
             };
         }
+        const updatedContext = mergeVariantContext({
+            bundle: session.projectContext.kind === 'fresh'
+                ? session.projectContext.variantContext
+                : undefined,
+            sessionId: session.sessionId,
+            sourcePlan: args.sourcePlan,
+        });
+        if (updatedContext && session.projectContext.kind === 'fresh') {
+            session.projectContext = {
+                ...session.projectContext,
+                variantContext: updatedContext,
+            };
+        }
         item.status = 'succeeded';
         item.output = {
-            sourceIntent,
-            sourceContext: normalizedArtifact,
-            ...(designContexts ? { designContexts } : {}),
+            actions,
+            metadata,
+            ...(bindings ? { bindings } : {}),
             executionPlan,
         };
         item.lease = undefined;
@@ -444,6 +623,20 @@ class SessionStore {
             const visualRef = brief.visualReferenceUrl
                 ? { visualReferenceUrl: brief.visualReferenceUrl }
                 : {};
+            const context = resolveVariantWorkItemContext({
+                // Existing-project sessions also carry a server-owned context bundle
+                // (no source_plan stage), so thread it for both kinds.
+                bundle: session.projectContext.variantContext,
+                projectContext: session.projectContext,
+                brief,
+                slotIndex: briefIndex,
+            });
+            const freshDesignContext = session.projectContext.kind === 'fresh'
+                ? session.projectContext.designContext
+                : undefined;
+            const designContextEntry = freshDesignContext
+                ? freshDesignContext[Math.min(briefIndex, freshDesignContext.length - 1)]
+                : undefined;
             if (wantsStaticPreview) {
                 // Generated + static_preview: HTML is the deliverable. No scaffold or
                 // code_gen — the static_preview item is leased directly.
@@ -459,6 +652,8 @@ class SessionStore {
                         briefBody: sel.bodyOverride ?? brief.body,
                         ...visualRef,
                         projectContext: session.projectContext,
+                        ...(designContextEntry ? { designContextEntry } : {}),
+                        ...(context ? { context } : {}),
                     },
                     acceptedReports: [],
                 };
@@ -475,12 +670,6 @@ class SessionStore {
                 // when the session has fewer designContext entries than variants
                 // (the common case after report_source_plan ships one shared
                 // markdown).
-                const freshDesignContext = session.projectContext.kind === 'fresh'
-                    ? session.projectContext.designContext
-                    : undefined;
-                const designContextEntry = freshDesignContext
-                    ? freshDesignContext[Math.min(briefIndex, freshDesignContext.length - 1)]
-                    : undefined;
                 const codeGenItem = {
                     id: (0, crypto_1.randomUUID)(),
                     kind: 'code_gen',
@@ -495,6 +684,7 @@ class SessionStore {
                         target: session.target,
                         projectContext: session.projectContext,
                         ...(designContextEntry ? { designContextEntry } : {}),
+                        ...(context ? { context } : {}),
                     },
                     acceptedReports: [],
                 };
@@ -636,6 +826,48 @@ class SessionStore {
         session.acceptedFingerprints.set(fp, result);
         return result;
     }
+    /**
+     * Re-open a succeeded variant work item for one aesthetic regeneration.
+     * Consumes the agent's report (validating the lease), then resets the item
+     * to `pending` so it becomes leasable again via `request_work`, stashing the
+     * design critique onto its input so the re-leased descriptor carries the
+     * notes the agent must address before re-reporting.
+     *
+     * The work item never reaches a terminal status, so the session stays in
+     * `waiting_for_results` and never goes terminal off the back of a
+     * design-quality failure. Idempotent on replay via the accepted-fingerprint
+     * cache.
+     */
+    requeueForDesignCritique(args) {
+        const session = this.requireSession(args.sessionId);
+        const fp = fingerprint([
+            'requeueForDesignCritique',
+            args.sessionId,
+            args.workItemId,
+            args.leaseId,
+            args.attempt,
+        ]);
+        const cached = session.acceptedFingerprints.get(fp);
+        if (cached)
+            return cached;
+        this.assertStage(session, ['work_items_ready', 'waiting_for_results']);
+        const item = this.requireWorkItem(session, args.workItemId);
+        this.validateLease(item, args.leaseId, args.attempt);
+        // Reset to pending so request_work re-surfaces it. The re-lease increments
+        // `attempt`, so the regenerated report carries a fresh fingerprint.
+        item.status = 'pending';
+        item.lease = undefined;
+        item.output = undefined;
+        item.error = undefined;
+        const input = (item.input ?? {});
+        item.input = { ...input, designCritique: args.critique };
+        const result = {
+            stage: session.stage,
+            progress: this.progressOf(session),
+        };
+        session.acceptedFingerprints.set(fp, result);
+        return result;
+    }
     /**
      * Creates a refinable HTML work item for a completed static preview variant.
      * The target variant remains the user-facing snapshot; this work item only
@@ -674,6 +906,7 @@ class SessionStore {
                 briefBody: targetInput.briefBody,
                 ...(args.currentHtml ? { currentHtml: args.currentHtml } : {}),
                 projectContext: targetInput.projectContext ?? session.projectContext,
+                ...(targetInput.context ? { context: targetInput.context } : {}),
             },
             acceptedReports: [],
         };