rivet-design 0.10.8 → 0.11.0

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

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ERROR_CODES = exports.getVariantInput = exports.listPastVariantsInput = exports.variantHistoryStatusSchema = exports.startVariantsInput = exports.startVariantsBriefContent = exports.startVariantsMode = exports.cancelVariantInput = exports.cancelVariantsInput = exports.extractInspirationContextInput = exports.reportVariantCompleteInput = exports.reportVariantCompleteStatus = exports.continueVariantsInput = exports.continueVariantsAction = exports.commitVariantInput = exports.approveVariantBriefsInput = exports.reportSourcePlanInput = exports.sourcePlanArtifactSchema = exports.reportVariantBriefsInput = exports.proposeVariantsInput = exports.runLabelSchema = exports.VARIANT_COUNT_MAX = exports.VARIANT_COUNT_MIN = exports.briefSchema = exports.targetSchema = exports.VARIANT_ARTIFACT_KINDS = exports.projectContextSchema = exports.projectContextFresh = exports.executionCapabilityPlanSchema = exports.assetPlanEntrySchema = exports.executionConfidenceSchema = exports.executionModeSchema = exports.sourceContextInputSchema = exports.sourceContextArtifactSchema = exports.sourceRoleEntrySchema = exports.sourceRoleSchema = exports.sourceArtifactInputSchema = exports.sourceArtifactKindSchema = exports.designContextEntrySchema = exports.sourceIntentArtifactSchema = exports.sourceIntentEntrySchema = exports.sourceIntentConfidenceSchema = exports.sourceIntentRoleSchema = exports.projectContextExisting = exports.WORK_ITEM_STATUSES = exports.WORK_ITEM_KINDS = exports.TERMINAL_STAGES = exports.STAGES = void 0;
+exports.ERROR_CODES = exports.getVariantInput = exports.captureDesignEvidenceInput = exports.listPastVariantsInput = exports.variantHistoryStatusSchema = exports.startVariantsInput = exports.startVariantsBriefContent = exports.startVariantsMode = exports.cancelVariantInput = exports.cancelVariantsInput = exports.reportVariantCompleteInput = exports.reportVariantCompleteStatus = exports.continueVariantsInput = exports.continueVariantsAction = exports.commitVariantInput = exports.approveVariantBriefsInput = exports.reportSourcePlanInput = exports.sourcePlanArtifactSchema = exports.reportVariantBriefsInput = exports.proposeVariantsInput = exports.runLabelSchema = exports.VARIANT_COUNT_MAX = exports.VARIANT_COUNT_MIN = exports.variantWorkItemContextSchema = exports.briefSchema = exports.targetSchema = exports.VARIANT_ARTIFACT_KINDS = exports.projectContextInputSchema = exports.projectContextSchema = exports.projectContextFresh = exports.projectContextExisting = exports.variantContextBundleSchema = exports.executionCapabilityPlanSchema = exports.assetPlanEntrySchema = exports.executionConfidenceSchema = exports.executionModeSchema = exports.variantContextBindingSchema = exports.rivetMetadataSchema = exports.sourcePlanActionOptionSchema = exports.rivetContextActionSchema = exports.rivetContextActionKindSchema = exports.storedUserContextSourceRecordSchema = exports.rawUserContextSourceSchema = exports.rawUserContextInputSchema = exports.sourceRoleSchema = exports.designContextEntrySchema = exports.WORK_ITEM_STATUSES = exports.WORK_ITEM_KINDS = exports.TERMINAL_STAGES = exports.STAGES = void 0;
 const v3_1 = require("zod/v3");
 const errors_1 = require("./errors");
 Object.defineProperty(exports, "ERROR_CODES", { enumerable: true, get: function () { return errors_1.ERROR_CODES; } });
-const inspirationDesignContext_1 = require("./inspirationDesignContext");
+const sourceContext_1 = require("./sourceContext");
 // --- Stages ---------------------------------------------------------------
 exports.STAGES = [
     'awaiting_source_plan',
@@ -41,49 +41,16 @@ exports.WORK_ITEM_STATUSES = [
     'cancelled',
 ];
 // --- Project context ------------------------------------------------------
-exports.projectContextExisting = v3_1.z.object({
-    kind: v3_1.z.literal('existing'),
-});
 const DESIGN_CONTEXT_MARKDOWN_MAX_LENGTH = 50_000;
 const DESIGN_CONTEXT_SLUG_MAX_LENGTH = 120;
 const SOURCE_URL_MAX_LENGTH = 2_048;
-const SOURCE_ARTIFACT_LABEL_MAX_LENGTH = 80;
-const SOURCE_ARTIFACT_CONTENT_MAX_LENGTH = 8_000;
 const SOURCE_FINDING_MAX_LENGTH = 400;
 const SOURCE_LIST_MAX_ITEMS = 24;
-const SOURCE_SCREENSHOT_MAX_ITEMS = 16;
-// --- Source intent ---------------------------------------------------------
-exports.sourceIntentRoleSchema = v3_1.z.enum([
-    'design_source',
-    'interaction_reference',
-    'asset_source',
-    'content_reference',
-    'other',
-]);
-exports.sourceIntentConfidenceSchema = v3_1.z.enum(['low', 'medium', 'high']);
-/**
- * One classified source in the agent's `sourceIntent`. Identified by exactly
- * one of:
- *  - `url`: an inspiration URL the user provided
- *  - `imageRef`: a stable per-session reference of the form `image:<index>`
- *    pointing at an image-kind entry in `sourceArtifacts` (visualBrief or
- *    screenshotNotes). Indexed over image-kind artifacts only, so the ref
- *    survives reordering of text-only artifacts.
- */
-exports.sourceIntentEntrySchema = v3_1.z
-    .object({
-    url: v3_1.z.string().min(1).max(SOURCE_URL_MAX_LENGTH).optional(),
-    imageRef: v3_1.z.string().min(1).max(64).optional(),
-    role: exports.sourceIntentRoleSchema,
-    confidence: exports.sourceIntentConfidenceSchema,
-    reason: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH),
-})
-    .refine((entry) => Boolean(entry.url) !== Boolean(entry.imageRef), {
-    message: 'sourceIntent entry must specify exactly one of `url` or `imageRef`.',
-});
-exports.sourceIntentArtifactSchema = v3_1.z.object({
-    sources: v3_1.z.array(exports.sourceIntentEntrySchema).min(1).max(SOURCE_LIST_MAX_ITEMS),
-});
+const USER_CONTEXT_LABEL_MAX_LENGTH = 80;
+const USER_CONTEXT_TEXT_MAX_LENGTH = 50_000;
+const USER_CONTEXT_PATH_MAX_LENGTH = 2_048;
+const USER_CONTEXT_UPLOAD_DATA_URL_MAX_LENGTH = 70_000_000;
+// --- Design context --------------------------------------------------------
 exports.designContextEntrySchema = v3_1.z.discriminatedUnion('kind', [
     v3_1.z.object({
         kind: v3_1.z.literal('slug'),
@@ -95,69 +62,232 @@ exports.designContextEntrySchema = v3_1.z.discriminatedUnion('kind', [
         label: v3_1.z.string().min(1).max(60),
     }),
 ]);
-exports.sourceArtifactKindSchema = v3_1.z.enum([
-    'urlText',
-    'siteBrief',
-    'visualBrief',
-    'screenshotNotes',
-    'motionBrief',
-]);
-exports.sourceArtifactInputSchema = v3_1.z.object({
-    kind: exports.sourceArtifactKindSchema,
-    label: v3_1.z.string().min(1).max(SOURCE_ARTIFACT_LABEL_MAX_LENGTH),
-    content: v3_1.z.string().min(1).max(SOURCE_ARTIFACT_CONTENT_MAX_LENGTH),
-});
+/**
+ * Role a raw source plays in `design_system` action metadata. Retained because
+ * `rivetMetadataSchema` references it; the legacy summary-first
+ * `sourceContext`/`sourceIntent` intake shapes that also used it are gone.
+ */
 exports.sourceRoleSchema = v3_1.z.enum([
     'primary',
     'inspiration',
     'competitor',
 ]);
-exports.sourceRoleEntrySchema = v3_1.z.object({
-    url: v3_1.z.string().min(1).max(SOURCE_URL_MAX_LENGTH),
-    role: exports.sourceRoleSchema,
-    rationale: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
-});
-exports.sourceContextArtifactSchema = v3_1.z.object({
-    sourceFindings: v3_1.z
-        .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
-        .min(1)
-        .max(SOURCE_LIST_MAX_ITEMS),
-    sectionInventory: v3_1.z
-        .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
-        .min(1)
-        .max(SOURCE_LIST_MAX_ITEMS),
-    visualObservations: v3_1.z
-        .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
-        .min(1)
-        .max(SOURCE_LIST_MAX_ITEMS),
-    sourceRoles: v3_1.z.array(exports.sourceRoleEntrySchema).min(1).max(SOURCE_LIST_MAX_ITEMS),
-    qualityBar: v3_1.z
-        .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
-        .min(1)
-        .max(SOURCE_LIST_MAX_ITEMS),
-    screenshotReferences: v3_1.z
-        .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
-        .max(SOURCE_SCREENSHOT_MAX_ITEMS)
-        .optional(),
-    risks: v3_1.z
-        .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
-        .max(SOURCE_LIST_MAX_ITEMS)
+// --- Native user context ---------------------------------------------------
+exports.rawUserContextInputSchema = v3_1.z.discriminatedUnion('transport', [
+    v3_1.z.object({
+        transport: v3_1.z.literal('url'),
+        url: v3_1.z.string().min(1).max(SOURCE_URL_MAX_LENGTH),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+    v3_1.z.object({
+        transport: v3_1.z.literal('file_path'),
+        path: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH),
+        mimeType: v3_1.z.string().min(1).max(120).optional(),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+    v3_1.z.object({
+        transport: v3_1.z.literal('upload'),
+        dataUrl: v3_1.z.string().min(1).max(USER_CONTEXT_UPLOAD_DATA_URL_MAX_LENGTH),
+        filename: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+    v3_1.z.object({
+        transport: v3_1.z.literal('directory_path'),
+        path: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+    v3_1.z.object({
+        transport: v3_1.z.literal('text'),
+        content: v3_1.z.string().min(1).max(USER_CONTEXT_TEXT_MAX_LENGTH),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+]);
+exports.rawUserContextSourceSchema = v3_1.z.discriminatedUnion('transport', [
+    v3_1.z.object({
+        id: v3_1.z.string().min(1),
+        transport: v3_1.z.literal('prompt'),
+        path: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH),
+    }),
+    v3_1.z.object({
+        id: v3_1.z.string().min(1),
+        transport: v3_1.z.literal('url'),
+        url: v3_1.z.string().min(1).max(SOURCE_URL_MAX_LENGTH),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+    v3_1.z.object({
+        id: v3_1.z.string().min(1),
+        transport: v3_1.z.literal('file'),
+        path: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH),
+        mimeType: v3_1.z.string().min(1).max(120).optional(),
+        originalFilename: v3_1.z
+            .string()
+            .min(1)
+            .max(USER_CONTEXT_LABEL_MAX_LENGTH)
+            .optional(),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+    v3_1.z.object({
+        id: v3_1.z.string().min(1),
+        transport: v3_1.z.literal('directory'),
+        path: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+    v3_1.z.object({
+        id: v3_1.z.string().min(1),
+        transport: v3_1.z.literal('text'),
+        path: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH),
+        label: v3_1.z.string().min(1).max(USER_CONTEXT_LABEL_MAX_LENGTH).optional(),
+        userIntent: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
+    }),
+]);
+exports.storedUserContextSourceRecordSchema = v3_1.z.object({
+    source: exports.rawUserContextSourceSchema,
+    storage: v3_1.z
+        .object({
+        sizeBytes: v3_1.z.number().int().nonnegative().optional(),
+        sha256: v3_1.z.string().min(1).optional(),
+        originalFilename: v3_1.z.string().min(1).optional(),
+    })
         .optional(),
 });
-exports.sourceContextInputSchema = v3_1.z.object({
-    sourceUrls: v3_1.z
-        .array(v3_1.z.string().min(1).max(SOURCE_URL_MAX_LENGTH))
+exports.rivetContextActionKindSchema = v3_1.z.enum([
+    'extract_design_system',
+    'describe_motion',
+]);
+exports.rivetContextActionSchema = v3_1.z.object({
+    id: v3_1.z.string().min(1),
+    kind: exports.rivetContextActionKindSchema,
+    sourceIds: v3_1.z.array(v3_1.z.string().min(1)).max(SOURCE_LIST_MAX_ITEMS),
+    reason: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH),
+    outputMetadataIds: v3_1.z
+        .array(v3_1.z.string().min(1))
         .max(SOURCE_LIST_MAX_ITEMS)
         .optional(),
-    preserveBrand: v3_1.z.boolean().optional(),
-    sourceArtifacts: v3_1.z
-        .array(exports.sourceArtifactInputSchema)
+});
+exports.sourcePlanActionOptionSchema = v3_1.z.object({
+    kind: exports.rivetContextActionKindSchema,
+    sourceTransports: v3_1.z
+        .array(v3_1.z.enum(['prompt', 'url', 'file', 'directory', 'text']))
+        .min(1)
+        .max(SOURCE_LIST_MAX_ITEMS),
+    capability: v3_1.z.enum(['extract_inspiration_context', 'rivet_describe_motion']),
+    produces: v3_1.z.enum(['design_system', 'motion_guidance']),
+    instructions: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH),
+});
+const rivetMetadataBaseSchema = v3_1.z.object({
+    id: v3_1.z.string().min(1),
+    sourceIds: v3_1.z.array(v3_1.z.string().min(1)).max(SOURCE_LIST_MAX_ITEMS),
+    actionId: v3_1.z.string().min(1).optional(),
+    producedBy: v3_1.z.enum(['rivet', 'agent', 'browser', 'skill']),
+    path: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH).optional(),
+    warnings: v3_1.z
+        .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
         .max(SOURCE_LIST_MAX_ITEMS)
         .optional(),
-    artifact: exports.sourceContextArtifactSchema.optional(),
-    sourceIntent: exports.sourceIntentArtifactSchema.optional(),
-    designDecision: v3_1.z.enum(['let_rivet_choose', 'go_custom']).optional(),
 });
+exports.rivetMetadataSchema = v3_1.z.discriminatedUnion('kind', [
+    rivetMetadataBaseSchema.extend({
+        kind: v3_1.z.literal('design_system'),
+        data: v3_1.z.object({
+            designMarkdown: v3_1.z
+                .string()
+                .min(1)
+                .max(DESIGN_CONTEXT_MARKDOWN_MAX_LENGTH)
+                .optional(),
+            /**
+             * Provenance for the design system: `captured` = derived from rendered
+             * browser evidence (e.g. `capture_design_evidence`); `partial` = some
+             * evidence, gaps filled by inference; `inferred` = no rendered evidence
+             * (static fetch / native inspection only). Keeps DESIGN.md honest about
+             * extracted-vs-guessed values.
+             */
+            evidenceStatus: v3_1.z.enum(['captured', 'partial', 'inferred']).optional(),
+            sourceFindings: v3_1.z
+                .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
+                .min(1)
+                .max(SOURCE_LIST_MAX_ITEMS),
+            sectionInventory: v3_1.z
+                .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
+                .min(1)
+                .max(SOURCE_LIST_MAX_ITEMS),
+            visualObservations: v3_1.z
+                .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
+                .min(1)
+                .max(SOURCE_LIST_MAX_ITEMS),
+            sourceRoles: v3_1.z
+                .array(v3_1.z.object({
+                sourceId: v3_1.z.string().min(1),
+                role: exports.sourceRoleSchema,
+                rationale: v3_1.z
+                    .string()
+                    .min(1)
+                    .max(SOURCE_FINDING_MAX_LENGTH)
+                    .optional(),
+            }))
+                .min(1)
+                .max(SOURCE_LIST_MAX_ITEMS),
+            qualityBar: v3_1.z
+                .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
+                .min(1)
+                .max(SOURCE_LIST_MAX_ITEMS),
+            risks: v3_1.z
+                .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
+                .max(SOURCE_LIST_MAX_ITEMS)
+                .optional(),
+        }),
+    }),
+    rivetMetadataBaseSchema.extend({
+        kind: v3_1.z.literal('motion_guidance'),
+        data: v3_1.z.object({
+            motionMarkdown: v3_1.z
+                .string()
+                .min(1)
+                .max(DESIGN_CONTEXT_MARKDOWN_MAX_LENGTH)
+                .optional(),
+            notes: v3_1.z
+                .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
+                .min(1)
+                .max(SOURCE_LIST_MAX_ITEMS),
+            timings: v3_1.z
+                .array(v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH))
+                .max(SOURCE_LIST_MAX_ITEMS)
+                .optional(),
+        }),
+    }),
+]);
+exports.variantContextBindingSchema = v3_1.z.discriminatedUnion('kind', [
+    v3_1.z.object({
+        kind: v3_1.z.literal('global'),
+        sourceIds: v3_1.z.array(v3_1.z.string().min(1)).max(SOURCE_LIST_MAX_ITEMS),
+        actionIds: v3_1.z.array(v3_1.z.string().min(1)).max(SOURCE_LIST_MAX_ITEMS),
+        metadataIds: v3_1.z
+            .array(v3_1.z.string().min(1))
+            .max(SOURCE_LIST_MAX_ITEMS)
+            .optional(),
+    }),
+    v3_1.z.object({
+        kind: v3_1.z.literal('slot'),
+        slotIndex: v3_1.z
+            .number()
+            .int()
+            .nonnegative()
+            .max(SOURCE_LIST_MAX_ITEMS - 1),
+        sourceIds: v3_1.z.array(v3_1.z.string().min(1)).max(SOURCE_LIST_MAX_ITEMS),
+        actionIds: v3_1.z.array(v3_1.z.string().min(1)).max(SOURCE_LIST_MAX_ITEMS),
+        metadataIds: v3_1.z
+            .array(v3_1.z.string().min(1))
+            .max(SOURCE_LIST_MAX_ITEMS)
+            .optional(),
+    }),
+]);
 // --- Execution capability planning ---------------------------------------
 exports.executionModeSchema = v3_1.z.enum(['static_preview', 'vite_app']);
 exports.executionConfidenceSchema = v3_1.z.enum(['low', 'medium', 'high']);
@@ -187,6 +317,30 @@ exports.executionCapabilityPlanSchema = v3_1.z.object({
         .optional(),
     userQuestion: v3_1.z.string().min(1).max(SOURCE_FINDING_MAX_LENGTH).optional(),
 });
+exports.variantContextBundleSchema = v3_1.z.object({
+    version: v3_1.z.literal(1),
+    sessionId: v3_1.z.string().min(1),
+    contextBundlePath: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH),
+    userContext: v3_1.z
+        .array(exports.rawUserContextSourceSchema)
+        .min(1)
+        .max(SOURCE_LIST_MAX_ITEMS + 1),
+    rivetActions: v3_1.z.array(exports.rivetContextActionSchema).max(SOURCE_LIST_MAX_ITEMS),
+    rivetMetadata: v3_1.z.array(exports.rivetMetadataSchema).max(SOURCE_LIST_MAX_ITEMS),
+    bindings: v3_1.z.array(exports.variantContextBindingSchema).optional(),
+    executionPlan: exports.executionCapabilityPlanSchema.optional(),
+});
+exports.projectContextExisting = v3_1.z.object({
+    kind: v3_1.z.literal('existing'),
+    /** Absolute project path requested for this existing-project run. Present
+     *  when callers target a nested project inside a larger git worktree. */
+    projectPath: v3_1.z.string().min(1).optional(),
+    /** Optional design context supplied by agents/benchmarks for existing
+     *  project runs with visual references. Surfaced as DesignMD artifacts and
+     *  available to QA gates, but does not trigger a source-plan stage. */
+    designContext: v3_1.z.array(exports.designContextEntrySchema).optional(),
+    variantContext: exports.variantContextBundleSchema.optional(),
+});
 exports.projectContextFresh = v3_1.z.object({
     kind: v3_1.z.literal('fresh'),
     /** Where the generated subproject's files live (e.g.
@@ -206,7 +360,7 @@ exports.projectContextFresh = v3_1.z.object({
      *  markdown; markdown entries are written directly as `DESIGN.md`. The
      *  order matches code-gen variant slot order. */
     designContext: v3_1.z.array(exports.designContextEntrySchema).optional(),
-    sourceContext: exports.sourceContextInputSchema.optional(),
+    variantContext: exports.variantContextBundleSchema.optional(),
     /** Agent-supplied execution plan from `report_source_plan`. Drives the
      *  generation routing decision at approve() time: `static_preview` keeps
      *  the lightweight HTML-only path; `vite_app` provisions a real Vite
@@ -217,6 +371,16 @@ exports.projectContextSchema = v3_1.z.discriminatedUnion('kind', [
     exports.projectContextExisting,
     exports.projectContextFresh,
 ]);
+const projectContextExistingInput = exports.projectContextExisting.omit({
+    variantContext: true,
+});
+const projectContextFreshInput = exports.projectContextFresh.omit({
+    variantContext: true,
+});
+exports.projectContextInputSchema = v3_1.z.discriminatedUnion('kind', [
+    projectContextExistingInput,
+    projectContextFreshInput,
+]);
 // --- Variant session artifacts -------------------------------------------
 /**
  * Kinds of supporting artifact a variants session can surface to the UI.
@@ -256,12 +420,21 @@ exports.briefSchema = v3_1.z.object({
     visualReferenceUrl: v3_1.z
         .string()
         .url()
-        .refine((url) => (0, inspirationDesignContext_1.validateInspirationUrl)(url).ok, {
+        .refine((url) => (0, sourceContext_1.validateInspirationUrl)(url).ok, {
         message: 'visualReferenceUrl must be an HTTP(S) URL that does not target local or private networks',
     })
         .optional()
         .describe('Optional HTTP(S) inspiration URL. Subject to SSRF guard — must not resolve to local or private network targets.'),
 });
+exports.variantWorkItemContextSchema = v3_1.z.object({
+    contextBundlePath: v3_1.z.string().min(1).max(USER_CONTEXT_PATH_MAX_LENGTH),
+    userContext: v3_1.z
+        .array(exports.rawUserContextSourceSchema)
+        .max(SOURCE_LIST_MAX_ITEMS + 1),
+    rivetMetadata: v3_1.z.array(exports.rivetMetadataSchema).max(SOURCE_LIST_MAX_ITEMS),
+    brief: exports.briefSchema,
+    executionMode: exports.executionModeSchema.optional(),
+});
 // --- Tool I/O — propose_variants ------------------------------------------
 /**
  * Inclusive bounds for the number of variants a single propose_variants run
@@ -290,7 +463,7 @@ exports.proposeVariantsInput = {
         .max(exports.VARIANT_COUNT_MAX)
         .optional(),
     target: exports.targetSchema.optional(),
-    projectContext: exports.projectContextSchema.optional(),
+    projectContext: exports.projectContextInputSchema.optional(),
     runLabel: exports.runLabelSchema,
 };
 // --- Tool I/O — report_variant_briefs -------------------------------------
@@ -300,38 +473,25 @@ exports.reportVariantBriefsInput = {
     attempt: v3_1.z.number().int().nonnegative(),
     leaseId: v3_1.z.string().optional(),
     briefs: v3_1.z.array(exports.briefSchema).min(1).max(8),
+    bindings: v3_1.z.array(exports.variantContextBindingSchema).max(8).optional(),
 };
 // --- Tool I/O — report_source_plan ----------------------------------------
 /**
- * One agent-extracted DESIGN.md, keyed by exactly one of:
- *  - `url`: the inspiration URL the agent fetched via browser extraction
- *  - `imageRef`: a stable `image:<index>` reference matching an image-kind
- *    entry in the session's `sourceArtifacts` (see `buildImageRefs` in
- *    SessionStore for index semantics)
- */
-const browserDesignContextSchema = v3_1.z
-    .object({
-    url: v3_1.z.string().min(1).max(SOURCE_URL_MAX_LENGTH).optional(),
-    imageRef: v3_1.z.string().min(1).max(64).optional(),
-    label: v3_1.z.string().min(1).max(60),
-    markdown: v3_1.z.string().min(1).max(DESIGN_CONTEXT_MARKDOWN_MAX_LENGTH),
-})
-    .refine((entry) => Boolean(entry.url) !== Boolean(entry.imageRef), {
-    message: 'designContexts entry must specify exactly one of `url` or `imageRef`.',
-});
-/**
- * Consolidated planning artifact reported by the agent in a single tool call.
- * Combines URL/role classification, research findings, browser-extracted
- * DESIGN.md per design_source URL, and the static_preview vs vite_app
- * execution decision. Replaces the prior `report_source_intent` +
- * `report_source_context` round-trips so source-grounded sessions only need
- * one planning hop before briefs.
+ * Canonical planning artifact reported by the agent in a single tool call.
+ * The agent inspects raw `userContext` natively, selects Rivet actions from
+ * `input.availableActions`, and reports the additive metadata those actions
+ * produce plus the static_preview vs vite_app execution decision. `actions`
+ * and `metadata` are required (each reported action must produce its matching
+ * metadata kind); `bindings` is optional and scopes context per variant slot.
+ * The legacy summary-first fields (`sourceIntent`, `sourceContext`,
+ * `designContexts`) are intentionally absent — derived guidance now comes
+ * from action metadata.
  */
 exports.sourcePlanArtifactSchema = v3_1.z.object({
-    sourceIntent: exports.sourceIntentArtifactSchema,
-    sourceContext: exports.sourceContextArtifactSchema,
-    designContexts: v3_1.z
-        .array(browserDesignContextSchema)
+    actions: v3_1.z.array(exports.rivetContextActionSchema).max(SOURCE_LIST_MAX_ITEMS),
+    metadata: v3_1.z.array(exports.rivetMetadataSchema).max(SOURCE_LIST_MAX_ITEMS),
+    bindings: v3_1.z
+        .array(exports.variantContextBindingSchema)
         .max(SOURCE_LIST_MAX_ITEMS)
         .optional(),
     executionPlan: exports.executionCapabilityPlanSchema,
@@ -407,32 +567,6 @@ exports.reportVariantCompleteInput = {
     tokensOut: v3_1.z.number().int().nonnegative().optional(),
     model: v3_1.z.string().optional(),
 };
-// --- Tool I/O — extract_inspiration_context ------------------------------
-/**
- * Stateless inspiration-extraction kickoff. Agents call this before
- * `start_variants(mode='zero_to_one')` when the user provides inspiration
- * URLs or other source artifacts, then pass the returned `designContext`
- * (and optional `sourceContext` echo) into `start_variants`.
- */
-exports.extractInspirationContextInput = {
-    prompt: v3_1.z.string().min(1),
-    count: v3_1.z.number().int().min(exports.VARIANT_COUNT_MIN).max(exports.VARIANT_COUNT_MAX),
-    urls: v3_1.z
-        .array(v3_1.z.string().min(1).max(SOURCE_URL_MAX_LENGTH))
-        .max(SOURCE_LIST_MAX_ITEMS)
-        .optional(),
-    preserveBrand: v3_1.z.boolean().optional(),
-    sourceArtifacts: v3_1.z
-        .array(exports.sourceArtifactInputSchema)
-        .max(SOURCE_LIST_MAX_ITEMS)
-        .optional(),
-    /** When true, bypass any cache entry and force a fresh fetch + extract. */
-    forceRefresh: v3_1.z.boolean().optional(),
-    /** Caller-supplied correlation id, echoed into telemetry so this stateless
-     *  extraction can be tied to the subsequent `start_variants` call (which
-     *  accepts the same field) even though no session exists yet. */
-    clientRequestId: v3_1.z.string().optional(),
-};
 // --- Tool I/O — cancel_variants -------------------------------------------
 exports.cancelVariantsInput = {
     sessionId: v3_1.z.string().min(1),
@@ -488,14 +622,20 @@ exports.startVariantsInput = {
      *  server's current working directory. Used to detect framework and
      *  auto-open the visual editor without a separate detect_project call. */
     projectPath: v3_1.z.string().optional(),
-    /** Zero-to-one only: per-variant-slot design context produced upstream by
-     *  `extract_inspiration_context`. Threaded into the fresh worktree as
-     *  DESIGN.md per slot. Slot order matches variant order. */
+    /** Per-variant-slot design context (slug entries resolve bundled catalog
+     *  markdown; markdown entries are written directly as DESIGN.md). Slot order
+     *  matches variant order. */
     designContext: v3_1.z.array(exports.designContextEntrySchema).optional(),
-    /** Zero-to-one only: optional source-context metadata (inspiration URLs,
-     *  preserveBrand flag, sourceArtifacts). Forwarded to the worktree
-     *  scaffold so SOURCE_CONTEXT.md is written. */
-    sourceContext: exports.sourceContextInputSchema.optional(),
+    /** Optional raw sources attached by the caller — inspiration URLs, local
+     *  images/videos, uploaded image data URLs, directories, or pasted text.
+     *  Rivet stores these as
+     *  read-only user context (the variant context bundle) and, for fresh
+     *  source-grounded runs, lets source planning decide what metadata actions
+     *  to derive. The sole source-intake field. */
+    userContext: v3_1.z
+        .array(exports.rawUserContextInputSchema)
+        .max(SOURCE_LIST_MAX_ITEMS)
+        .optional(),
     clientRequestId: v3_1.z.string().optional(),
 };
 // --- Tool I/O — list_past_variants / get_variant ------------------------
@@ -512,6 +652,24 @@ exports.listPastVariantsInput = {
     limit: v3_1.z.number().int().min(1).max(500).optional(),
     status: exports.variantHistoryStatusSchema.optional(),
 };
+// --- Tool I/O — capture_design_evidence ----------------------------------
+// Renders a reference URL on a remote browser (via the proxy / browser agent)
+// and returns DESIGN.md-shaped markdown derived from rendered DOM + resolved
+// computed styles. The source-plan agent calls this for URL sources before
+// reporting design_system, so the system is extracted rather than inferred.
+exports.captureDesignEvidenceInput = {
+    /** Correlation only; safe to omit. */
+    sessionId: v3_1.z.string().min(1).optional(),
+    /** The reference URL to render. */
+    url: v3_1.z.string().url(),
+    /** Optional viewport override; defaults to desktop 1440x1000. */
+    viewport: v3_1.z
+        .object({
+        width: v3_1.z.number().int().min(320).max(3840),
+        height: v3_1.z.number().int().min(320).max(2160),
+    })
+        .optional(),
+};
 exports.getVariantInput = {
     projectPath: v3_1.z.string().optional(),
     sessionId: v3_1.z.string().min(1),