rivet-design 0.9.2 → 0.9.4

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

@@ -1,11 +1,59 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAgentOutput = exports.slugifyPrompt = void 0;
 exports.registerAgentVariantsTools = registerAgentVariantsTools;
+exports.buildQaFailurePrompt = buildQaFailurePrompt;
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
 const contracts_1 = require("./contracts");
 const errors_1 = require("./errors");
+const createZeroToOneTool_1 = require("./createZeroToOneTool");
+Object.defineProperty(exports, "slugifyPrompt", { enumerable: true, get: function () { return createZeroToOneTool_1.slugifyPrompt; } });
+const viteReactTs_1 = require("../../services/templates/viteReactTs");
+const ProjectDetectionService_1 = require("../../services/ProjectDetectionService");
+const SessionStore_1 = require("./SessionStore");
+/**
+ * Coerce `output` to a structured value when an agent (incorrectly) sends a
+ * stringified JSON. The MCP schema accepts `z.unknown()` so the call doesn't
+ * fail validation, but downstream consumers (e.g. `output.html` in
+ * WorktreeOrchestrator) expect an object and silently no-op on strings —
+ * leaving the variant stuck at "not ready" until session expiry.
+ */
+const normalizeAgentOutput = (output) => {
+    if (typeof output !== 'string')
+        return output;
+    try {
+        return JSON.parse(output);
+    }
+    catch {
+        return output;
+    }
+};
+exports.normalizeAgentOutput = normalizeAgentOutput;
+/**
+ * Reject caller-supplied fresh destinations at the generic variants boundary.
+ * Fresh projects must go through `create_zero_to_one_project`, where the
+ * server derives the destination path before delegating to the orchestrator.
+ */
+const validateFreshProjectInput = (args) => {
+    if (args.projectContext?.kind !== 'fresh')
+        return null;
+    return {
+        stage: 'failed',
+        errorCode: 'SCHEMA_VALIDATION_FAILED',
+        message: 'Fresh-project sessions must be started with create_zero_to_one_project so Rivet derives and validates the destination path.',
+    };
+};
 function registerAgentVariantsTools(mcp, deps) {
-    mcp.tool('propose_variants', 'START HERE for any "create variants", "show me N options for X", "explore approaches to X", "build me Y from scratch", or "create a new Z app" request. DO NOT generate variants natively (Task tool, parallel tool calls, or your own creative process). Returns { sessionId, briefWorkItem }. Protocol: 1) call this tool, 2) run the brief work item with your own LLM to generate N briefs, 3) call report_variant_briefs, 3.5) AUTO-OPEN the Rivet editor — call detect_project + open_visual_editor if not already open; the user needs the iframe up to see variants render, do NOT wait for them to ask, 4) SHOW the briefs to the user IN CHAT as a numbered list and ask "look good or want adjustments?" — DO NOT ask which one to pick, 5) wait for user feedback (affirmative → proceed; tweak → bodyOverride or re-brief), 6) call approve_variant_briefs({sessionId, briefIds: [all]}), 7) call continue_variants(action="request_work") to lease all items in parallel (scaffold_base first for fresh-project), 8) run all code-gens IN PARALLEL in their own worktreePath, calling report_variant_complete per item, 9) DO NOT print diffs — instead tell the user the variants are ready and to use the chip at the bottom-center of the Rivet iframe to cycle (prev/next pills) and commit (check button), 10) watch_for_changes (or poll get_pending_changes) — when the user clicks the check, you get a VariantChangeItem on the queue, 11) apply via git apply (diff payload) or copy the worktree (new-project payload). Pass projectContext.kind=fresh with workspacePath for brand-new projects.', contracts_1.proposeVariantsInput, async (args) => {
+    mcp.tool('propose_variants', 'Stage 1 of the legacy variants flow with an in-chat brief approval gate. Prefer `start_variants` for new code paths — it collapses propose + report_briefs + approve + request_work into a single call. Use this only when the agent needs the user to review briefs before generation. Returns { sessionId, briefWorkItem }. Full protocol in the rivet skill.', contracts_1.proposeVariantsInput, async (args) => {
         try {
+            const failure = validateFreshProjectInput(args);
+            if (failure)
+                return jsonResponse(failure);
             const result = deps.orchestrator.propose({
                 sessionId: args.sessionId,
                 prompt: args.prompt,
@@ -13,6 +61,21 @@ function registerAgentVariantsTools(mcp, deps) {
                 target: args.target,
                 projectContext: args.projectContext,
             });
+            if (result.stage === 'awaiting_source_plan') {
+                const out = {
+                    sessionId: result.sessionId,
+                    stage: 'awaiting_source_plan',
+                    sourcePlanWorkItem: {
+                        id: result.sourcePlanWorkItem.id,
+                        kind: 'source_plan',
+                        attempt: result.sourcePlanWorkItem.attempt,
+                        input: result.sourcePlanWorkItem.input,
+                        output_schema: SessionStore_1.SOURCE_PLAN_OUTPUT_SCHEMA,
+                    },
+                    nextAction: 'continue_variants',
+                };
+                return jsonResponse(out);
+            }
             const out = {
                 sessionId: result.sessionId,
                 stage: 'awaiting_briefs',
@@ -21,7 +84,7 @@ function registerAgentVariantsTools(mcp, deps) {
                     kind: 'brief',
                     attempt: result.briefWorkItem.attempt,
                     input: result.briefWorkItem.input,
-                    output_schema: { briefs: 'Array<{briefId, label, body}>' },
+                    output_schema: { briefs: 'Array<{briefId, label: "≤4-word title", body: "ONE sentence ≤12 words"}>' },
                 },
                 nextAction: 'report_variant_briefs',
             };
@@ -31,7 +94,7 @@ function registerAgentVariantsTools(mcp, deps) {
             return errorResponse(err);
         }
     });
-    mcp.tool('report_variant_briefs', 'Agent reports N drafted briefs back to Rivet after running its own LLM call on the brief work item. Transitions the session to awaiting_approval; user reviews briefs in the variants tab.', contracts_1.reportVariantBriefsInput, async (args) => {
+    mcp.tool('report_variant_briefs', 'Report drafted briefs from the leased brief work item. Each brief: label ≤ 4 words, body = exactly ONE sentence ≤ 12 words — a single evocative descriptor, no bullets, no lists, no multi-clause run-ons. Body is shown directly to the user in the variants panel so it must be concise and immediately scannable. On success, transitions to awaiting_approval.', contracts_1.reportVariantBriefsInput, async (args) => {
         try {
             const result = deps.orchestrator.reportBriefs({
                 sessionId: args.sessionId,
@@ -43,6 +106,7 @@ function registerAgentVariantsTools(mcp, deps) {
             const out = {
                 stage: 'awaiting_approval',
                 briefs: result.briefs,
+                approvalPrompt: buildApprovalPrompt(result.briefs),
                 nextAction: 'continue_variants',
             };
             return jsonResponse(out);
@@ -51,8 +115,45 @@ function registerAgentVariantsTools(mcp, deps) {
             return errorResponse(err);
         }
     });
-    mcp.tool('approve_variant_briefs', 'Call AFTER showing the briefs to the user in chat and getting an affirmative ("looks good", "yep", "go") OR refined selections from them. Provide briefIds for ALL the briefs the user wants generated (typically all of them). Each approved brief gets a parallel code-gen work item — Rivet provisions one isolated worktree per item. Advance via continue_variants(action="request_work") to lease and run them in parallel. For tweak-with-feedback, use the selections form with bodyOverride per brief.', contracts_1.approveVariantBriefsInput, async (args) => {
+    mcp.tool('report_source_plan', 'Report the consolidated source plan for a leased source_plan work item. Combines URL/role classification, source research findings, browser-extracted DESIGN.md per design_source URL, and the static_preview vs vite_app execution decision. Choose vite_app when the request needs large local assets (e.g. GLB models), model-viewer, Three.js, route structure, package dependencies, or files under public/; choose static_preview for self-contained HTML/CSS/JS prototypes. If the requirement is ambiguous, set executionPlan.userQuestion instead of guessing — Rivet will surface it as a clarification blocker at approve time. Reports unlock the brief work item for source-grounded fresh-project sessions.', contracts_1.reportSourcePlanInput, async (args) => {
+        try {
+            const result = deps.orchestrator.reportSourcePlan({
+                sessionId: args.sessionId,
+                workItemId: args.workItemId,
+                leaseId: args.leaseId,
+                attempt: args.attempt,
+                sourcePlan: args.sourcePlan,
+            });
+            const plan = args.sourcePlan.executionPlan;
+            const out = {
+                stage: 'awaiting_briefs',
+                briefWorkItem: {
+                    id: result.briefWorkItem.id,
+                    kind: 'brief',
+                    attempt: result.briefWorkItem.attempt,
+                    input: result.briefWorkItem.input,
+                    output_schema: {
+                        briefs: 'Array<{briefId, label: "≤4-word title", body: "ONE sentence ≤12 words"}>',
+                    },
+                },
+                executionPlan: {
+                    mode: plan.mode,
+                    confidence: plan.confidence,
+                    reason: plan.reason,
+                    assetCount: plan.assetPlan?.length ?? 0,
+                    runtimeRequirementCount: plan.runtimeRequirements?.length ?? 0,
+                },
+                nextAction: 'report_variant_briefs',
+            };
+            return jsonResponse(out);
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    mcp.tool('approve_variant_briefs', 'Call AFTER showing the briefs to the user in chat and getting an affirmative ("looks good", "yep", "go") OR refined selections from them. Set confirmedByUser=true when the user approves. Only use bypassRequestedByUser=true (with bypassReason) if the user explicitly asks to bypass confirmation. Provide briefIds for ALL the briefs the user wants generated (typically all of them). Each approved brief gets a parallel code-gen work item — Rivet provisions one isolated worktree per item. Advance via continue_variants(action="request_work") to lease and run them in parallel. For tweak-with-feedback, use the selections form with bodyOverride per brief.', contracts_1.approveVariantBriefsInput, async (args) => {
         try {
+            assertExplicitUserConfirmation('approve_variant_briefs', args, 'approve variant briefs');
             const selections = args.selections ??
                 (args.briefIds ?? []).map((briefId) => ({ briefId }));
             if (selections.length === 0) {
@@ -75,8 +176,9 @@ function registerAgentVariantsTools(mcp, deps) {
             return errorResponse(err);
         }
     });
-    mcp.tool('commit_variant', "Call AFTER all variants have been generated AND you've shown each variant's diff/changes to the user in chat AND the user has picked one. Pass the variantId (the workItemId of the chosen variant). Rivet looks up that variant's captured diff and enqueues it onto the existing pending-changes channel — call get_pending_changes next to retrieve and apply. Idempotent on (sessionId, variantId).", contracts_1.commitVariantInput, async (args) => {
+    mcp.tool('commit_variant', "Call AFTER all variants have been generated AND you've shown each variant's diff/changes to the user in chat AND the user has picked one. Set confirmedByUser=true when the user confirms the pick. Only use bypassRequestedByUser=true (with bypassReason) if the user explicitly asks to bypass confirmation. Pass the variantId (the workItemId of the chosen variant). Rivet looks up that variant's captured diff and enqueues it onto the existing pending-changes channel — call get_pending_changes next to retrieve and apply. Idempotent on (sessionId, variantId).", contracts_1.commitVariantInput, async (args) => {
         try {
+            assertExplicitUserConfirmation('commit_variant', args, 'commit a variant');
             const result = await deps.orchestrator.commitVariant({
                 sessionId: args.sessionId,
                 variantId: args.variantId,
@@ -86,6 +188,8 @@ function registerAgentVariantsTools(mcp, deps) {
                 enqueued: result.enqueued,
                 duplicate: result.duplicate,
                 changedFilesCount: result.changedFilesCount,
+                payloadKind: result.payloadKind,
+                destinationPath: result.destinationPath,
             };
             return jsonResponse(out);
         }
@@ -93,7 +197,7 @@ function registerAgentVariantsTools(mcp, deps) {
             return errorResponse(err);
         }
     });
-    mcp.tool('continue_variants', 'Long-poll/state-pump the variants flow. action=check returns immediately; action=wait blocks up to ~5min for a state change; action=request_work asks for a lease on ready work items.', contracts_1.continueVariantsInput, async (args) => {
+    mcp.tool('continue_variants', 'Long-poll/state-pump the variants flow. action=check returns immediately; action=wait blocks up to ~5min for state changes; action=request_work leases ready work items (source_research, static_preview, or code_gen depending on stage). static_preview is for fresh zero-to-one sessions and should return {html, css?, js?} so Rivet can show fast visual previews before Vite/code generation finishes.', contracts_1.continueVariantsInput, async (args) => {
         try {
             const stage = deps.orchestrator.getStage(args.sessionId);
             if (stage === 'awaiting_briefs') {
@@ -102,24 +206,35 @@ function registerAgentVariantsTools(mcp, deps) {
                 throw new errors_1.AgentVariantsError('INVALID_STAGE_ACTION', 'Run the brief work item and call report_variant_briefs before continue_variants');
             }
             if (stage === 'awaiting_approval') {
+                const briefs = deps.orchestrator.getBriefs(args.sessionId);
                 return jsonResponse({
                     stage: 'awaiting_approval',
-                    briefs: deps.orchestrator.getBriefs(args.sessionId),
+                    briefs,
+                    approvalPrompt: buildApprovalPrompt(briefs),
                 });
             }
-            if (stage === 'work_items_ready' &&
-                args.action === 'request_work') {
+            if (args.action === 'request_work' &&
+                (stage === 'awaiting_source_plan' ||
+                    stage === 'work_items_ready' ||
+                    stage === 'waiting_for_results')) {
+                // SessionStore.requestWork accepts both stages and expires stale
+                // leases before issuing new ones, so this also recycles wedged
+                // variants whose leases expired while the session was already in
+                // waiting_for_results.
                 const lease = deps.orchestrator.requestWork({
                     sessionId: args.sessionId,
                     leaseOwner: deps.leaseOwner(),
                     requestedLeaseCount: args.requestedLeaseCount,
                 });
-                return jsonResponse({
-                    stage: 'work_items_ready',
+                const postLeaseStage = deps.orchestrator.getStage(args.sessionId);
+                const leasePayload = {
                     leaseId: lease.leaseId,
                     leaseTtlMs: lease.leaseTtlMs,
                     leasedWorkItems: lease.leasedWorkItems,
-                });
+                };
+                return jsonResponse(postLeaseStage === 'awaiting_source_plan'
+                    ? { stage: 'awaiting_source_plan', ...leasePayload }
+                    : { stage: 'work_items_ready', ...leasePayload });
             }
             if (stage === 'work_items_ready' || stage === 'waiting_for_results') {
                 return jsonResponse({
@@ -127,17 +242,36 @@ function registerAgentVariantsTools(mcp, deps) {
                     progress: deps.orchestrator.getProgress(args.sessionId),
                 });
             }
+            if (stage === 'awaiting_source_plan') {
+                return jsonResponse({
+                    stage: 'awaiting_source_plan',
+                    progress: deps.orchestrator.getProgress(args.sessionId),
+                });
+            }
             // Terminal stages
-            return jsonResponse({
-                stage,
-                summary: deps.orchestrator.getSummary(args.sessionId),
-            });
+            {
+                const summary = deps.orchestrator.getSummary(args.sessionId);
+                const variants = deps.orchestrator.getVariants(args.sessionId);
+                const previewUrls = variants
+                    .filter((v) => v.preview?.kind === 'static_artifact')
+                    .map((v) => ({
+                    label: v.label,
+                    url: v.preview.url,
+                }));
+                const qaSurfacing = buildQaSurfacing(variants);
+                return jsonResponse({
+                    stage,
+                    summary,
+                    ...(previewUrls.length > 0 ? { previewUrls } : {}),
+                    ...qaSurfacing,
+                });
+            }
         }
         catch (err) {
             return errorResponse(err);
         }
     });
-    mcp.tool('report_variant_complete', "Agent reports per-variant code-gen status: running (heartbeat), succeeded, failed, or cancelled. Requires a valid leaseId and matching attempt obtained from continue_variants(action='request_work').", contracts_1.reportVariantCompleteInput, async (args) => {
+    mcp.tool('report_variant_complete', "Agent reports per-work-item status: running (heartbeat), succeeded, failed, or cancelled. Requires a valid leaseId and matching attempt obtained from continue_variants(action='request_work'). For benchmark instrumentation, agents can optionally include tokensIn, tokensOut, and model in the call so Rivet can record cost per variant.", contracts_1.reportVariantCompleteInput, async (args) => {
         try {
             const result = await deps.orchestrator.reportComplete({
                 sessionId: args.sessionId,
@@ -145,17 +279,31 @@ function registerAgentVariantsTools(mcp, deps) {
                 leaseId: args.leaseId,
                 attempt: args.attempt,
                 status: args.status,
-                output: args.output,
+                output: (0, exports.normalizeAgentOutput)(args.output),
                 error: args.error,
+                tokensIn: args.tokensIn,
+                tokensOut: args.tokensOut,
+                model: args.model,
             });
             let out;
             if (result.stage === 'ready' ||
                 result.stage === 'degraded' ||
                 result.stage === 'failed' ||
                 result.stage === 'cancelled') {
+                const summary = result.summary ?? deps.orchestrator.getSummary(args.sessionId);
+                const variants = deps.orchestrator.getVariants(args.sessionId);
+                const previewUrls = variants
+                    .filter((v) => v.preview?.kind === 'static_artifact')
+                    .map((v) => ({
+                    label: v.label,
+                    url: v.preview.url,
+                }));
+                const qaSurfacing = buildQaSurfacing(variants);
                 out = {
                     stage: result.stage,
-                    summary: result.summary ?? deps.orchestrator.getSummary(args.sessionId),
+                    summary,
+                    ...(previewUrls.length > 0 ? { previewUrls } : {}),
+                    ...qaSurfacing,
                 };
             }
             else {
@@ -186,6 +334,39 @@ function registerAgentVariantsTools(mcp, deps) {
             return errorResponse(err);
         }
     });
+    mcp.tool('start_variants', 'Single-call kickoff for variants exploration. Spawns N variant worktrees, opens the visual editor, and returns a lease + worktreePaths — no follow-up detect_project / open_visual_editor / continue_variants needed. Pass `briefs` (one per variant) so each card has a distinct name and description; omitting them stubs every variant with the user prompt verbatim. `briefs.length` sets the count. mode="existing" for existing projects, "zero_to_one" for prompt-only fresh projects. For source-grounded fresh projects (inspiration URLs / custom design context) use create_zero_to_one_project instead. Full protocol in the rivet skill.', contracts_1.startVariantsInput, async (args) => {
+        try {
+            if (args.mode === 'zero_to_one') {
+                const out = await handleStartVariantsZeroToOne(args, deps);
+                return jsonResponse(out);
+            }
+            const out = await handleStartVariantsExisting(args, deps);
+            return jsonResponse(out);
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
+    mcp.tool('cancel_variant', 'Cancel a single variant within an in-flight session without affecting its siblings. Called by the Rivet UI when the user clicks the cancel button on a variant card. Marks the variant cancelled and releases its lease; sibling variants continue. Idempotent on terminal states (already cancelled / succeeded / failed returns alreadyTerminal=true with the actual finalStatus). Per-variant worktree teardown happens at session commit/cancel time. Distinct from cancel_variants (plural), which kills the entire session.', contracts_1.cancelVariantInput, async (args) => {
+        try {
+            const result = await deps.orchestrator.cancelVariant({
+                sessionId: args.sessionId,
+                variantId: args.variantId,
+                reason: args.reason,
+            });
+            const out = {
+                sessionId: result.sessionId,
+                variantId: result.variantId,
+                finalStatus: result.finalStatus,
+                sessionStage: result.sessionStage,
+                alreadyTerminal: result.alreadyTerminal,
+            };
+            return jsonResponse(out);
+        }
+        catch (err) {
+            return errorResponse(err);
+        }
+    });
 }
 // --- Helpers --------------------------------------------------------------
 // Return type is left implicit so the MCP SDK's overload selection picks the
@@ -218,4 +399,255 @@ function errorResponse(err) {
         isError: true,
     };
 }
+function assertExplicitUserConfirmation(toolName, confirmation, actionLabel) {
+    if (confirmation.confirmedByUser) {
+        return;
+    }
+    if (confirmation.bypassRequestedByUser &&
+        confirmation.bypassReason?.trim().length) {
+        return;
+    }
+    throw new errors_1.AgentVariantsError('MISSING_REQUIRED_INPUT', `${toolName} requires explicit user confirmation to ${actionLabel}. Set confirmedByUser=true after user confirmation, or set bypassRequestedByUser=true with bypassReason when the user explicitly asks to bypass.`);
+}
+function buildApprovalPrompt(briefs) {
+    const formattedBriefs = briefs
+        .map((brief, index) => `${index + 1}. name: ${brief.label}\n   description: ${brief.body}`)
+        .join('\n');
+    return (`Review these variant briefs:\n${formattedBriefs}\n\n` +
+        'Do these look good, or do you want any adjustments before I proceed?');
+}
+/**
+ * Compose the QA surfacing block (`qaPrompt`, `qa[]`) attached to terminal
+ * tool responses. Returns an empty object when no variant has a recorded
+ * QA verdict so existing-project flows (which never trigger preview QA)
+ * remain a no-op.
+ *
+ * Exported indirectly via the orchestrator's terminal tool responses so
+ * the calling agent can show the user a concrete retry/continue/cancel
+ * choice when one or more variants fail QA.
+ */
+function buildQaSurfacing(variants) {
+    const withQa = variants.filter((v) => Boolean(v.qa) && v.qa.status !== 'not_run');
+    if (withQa.length === 0)
+        return {};
+    const qaEntries = withQa.map((v) => ({
+        workItemId: v.workItemId,
+        label: v.label,
+        qa: v.qa,
+    }));
+    const failures = withQa.filter((v) => v.qa.status === 'failed');
+    if (failures.length === 0) {
+        return { qa: qaEntries };
+    }
+    return {
+        qa: qaEntries,
+        qaPrompt: buildQaFailurePrompt(failures.map((v) => ({ label: v.label, qa: v.qa })), withQa.length - failures.length),
+    };
+}
+/**
+ * User-facing prompt template for QA failures. Lists each failed variant
+ * with its summary + first asset/console issue, then asks the user
+ * whether to retry, continue with healthy variants, or cancel. Kept as
+ * data (not a log line) so the calling agent can present the choice
+ * directly to the human.
+ */
+function buildQaFailurePrompt(failures, healthyCount) {
+    if (failures.length === 0) {
+        return '';
+    }
+    const lines = failures.map((failure) => {
+        const firstIssue = failure.qa.issues[0];
+        const issueDetail = firstIssue
+            ? ` (${describeIssue(firstIssue.kind)}: ${firstIssue.detail}${firstIssue.message ? ` — ${firstIssue.message}` : ''})`
+            : '';
+        return `• ${failure.label}: ${failure.qa.summary}${issueDetail}`;
+    });
+    const healthyLine = healthyCount > 0
+        ? `\n\n${healthyCount} other variant${healthyCount === 1 ? '' : 's'} passed QA and can still be committed.`
+        : '';
+    const intro = failures.length === 1
+        ? '1 variant failed QA:'
+        : `${failures.length} variants failed QA:`;
+    return `${intro}\n${lines.join('\n')}${healthyLine}\n\nWould you like to retry the failed variant${failures.length === 1 ? '' : 's'}, continue with healthy variants only, or cancel?`;
+}
+const describeIssue = (kind) => {
+    switch (kind) {
+        case 'asset_load_failed':
+            return 'asset load failed';
+        case 'console_error':
+            return 'console/runtime error';
+        case 'preview_unavailable':
+            return 'preview unavailable';
+    }
+};
+/**
+ * Handle the zero-to-one branch of `start_variants`. Mirrors the
+ * destination-derivation, framework validation, and visual-editor
+ * auto-open behavior of `create_zero_to_one_project`, but skips the
+ * source-research / inspiration-extraction path. Source-grounded fresh
+ * projects must continue to use `create_zero_to_one_project`.
+ */
+async function handleStartVariantsZeroToOne(args, deps) {
+    const framework = args.framework ?? 'vite';
+    if (framework !== 'vite') {
+        return {
+            stage: 'failed',
+            errorCode: 'UNSUPPORTED_FRAMEWORK',
+            message: `start_variants(mode='zero_to_one') only supports framework='vite'; got '${framework}'.`,
+        };
+    }
+    const homedir = deps.homedir ?? os_1.default.homedir;
+    const destinationParent = args.destinationParent ?? homedir();
+    if (!path_1.default.isAbsolute(destinationParent)) {
+        return {
+            stage: 'failed',
+            errorCode: 'SCHEMA_VALIDATION_FAILED',
+            message: `destinationParent must be absolute; got '${destinationParent}'.`,
+        };
+    }
+    const slug = (0, createZeroToOneTool_1.slugifyPrompt)(args.prompt);
+    const destinationPath = path_1.default.join(destinationParent, slug);
+    if (!(0, viteReactTs_1.isDestinationEmpty)(destinationPath)) {
+        return {
+            stage: 'failed',
+            errorCode: 'DESTINATION_NOT_EMPTY',
+            message: `Destination '${destinationPath}' is not empty.`,
+        };
+    }
+    const hasSourceContext = args.sourceContext &&
+        ((args.sourceContext.sourceUrls?.length ?? 0) > 0 ||
+            (args.sourceContext.sourceArtifacts?.length ?? 0) > 0 ||
+            Boolean(args.sourceContext.sourceIntent) ||
+            Boolean(args.sourceContext.artifact));
+    if (hasSourceContext) {
+        return {
+            stage: 'failed',
+            errorCode: 'INVALID_STAGE_ACTION',
+            message: "start_variants(mode='zero_to_one') cannot run source-grounded sessions. " +
+                'Use create_zero_to_one_project for inspiration URLs / source artifacts so the source_plan flow can run.',
+        };
+    }
+    fs_1.default.mkdirSync(destinationParent, { recursive: true });
+    const projectContext = {
+        kind: 'fresh',
+        workspacePath: destinationPath,
+        framework: 'vite',
+    };
+    const visualEditor = deps.ensureVisualEditorOpen
+        ? await deps.ensureVisualEditorOpen({
+            projectPath: destinationPath,
+            framework: 'vite',
+        })
+        : undefined;
+    const result = await deps.orchestrator.startUnified({
+        prompt: args.prompt,
+        count: args.count,
+        target: args.target,
+        projectContext,
+        leaseOwner: deps.leaseOwner(),
+        briefs: args.briefs,
+    });
+    return assembleStartVariantsResponse({
+        mode: 'zero_to_one',
+        result,
+        destinationPath,
+        visualEditor,
+    });
+}
+/**
+ * Handle the existing-project branch of `start_variants`. Detects the
+ * project's framework server-side (cwd or the provided projectPath) so
+ * the agent doesn't need a separate detect_project call, auto-opens the
+ * visual editor on the resolved projectPath, and leases all variant
+ * work items so they're ready to code in the same response.
+ */
+async function handleStartVariantsExisting(args, deps) {
+    const projectPath = args.projectPath ?? process.cwd();
+    if (!path_1.default.isAbsolute(projectPath)) {
+        return {
+            stage: 'failed',
+            errorCode: 'SCHEMA_VALIDATION_FAILED',
+            message: `projectPath must be absolute; got '${projectPath}'.`,
+        };
+    }
+    let framework;
+    try {
+        framework = new ProjectDetectionService_1.ProjectDetectionService().detectFramework(projectPath);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : 'Unknown detection error';
+        return {
+            stage: 'failed',
+            errorCode: 'SCHEMA_VALIDATION_FAILED',
+            message: `Could not detect project at '${projectPath}': ${msg}. Ensure it has a package.json, or pass projectPath explicitly.`,
+        };
+    }
+    // ensureVisualEditorOpen is typed for framework='vite' (matches the
+    // zero-to-one entry point), but it works against any projectPath. For
+    // existing projects with non-vite frameworks, the agent can still open
+    // the editor itself via the standalone open_visual_editor tool.
+    const visualEditor = deps.ensureVisualEditorOpen && framework === 'vite'
+        ? await deps.ensureVisualEditorOpen({
+            projectPath,
+            framework: 'vite',
+        })
+        : undefined;
+    const result = await deps.orchestrator.startUnified({
+        prompt: args.prompt,
+        count: args.count,
+        target: args.target,
+        leaseOwner: deps.leaseOwner(),
+        briefs: args.briefs,
+    });
+    return assembleStartVariantsResponse({
+        mode: 'existing',
+        result,
+        project: { projectPath, framework },
+        visualEditor,
+    });
+}
+/**
+ * Build the StartVariantsOutput from a startUnified result + the lease
+ * info it surfaced. Pairs each variant in the original `variants` list
+ * with its `leasedWorkItems[]` entry from requestWork so the agent sees
+ * one consistent per-variant object with everything it needs.
+ */
+function assembleStartVariantsResponse(args) {
+    const { result } = args;
+    if (result.leaseId === undefined ||
+        result.leaseTtlMs === undefined ||
+        result.leasedWorkItems === undefined) {
+        return {
+            stage: 'failed',
+            errorCode: 'INVALID_STAGE_ACTION',
+            message: 'start_variants expected a lease to be issued by startUnified but none was returned.',
+        };
+    }
+    const itemById = new Map(result.leasedWorkItems.map((item) => [item.id, item]));
+    const variants = [];
+    for (const v of result.variants) {
+        const workItem = itemById.get(v.variantId);
+        if (!workItem) {
+            return {
+                stage: 'failed',
+                errorCode: 'INVALID_STAGE_ACTION',
+                message: `start_variants leased fewer items than variants — missing workItem for ${v.variantId}.`,
+            };
+        }
+        variants.push({ ...v, workItem });
+    }
+    return {
+        sessionId: result.sessionId,
+        stage: 'work_items_ready',
+        mode: args.mode,
+        leaseId: result.leaseId,
+        leaseTtlMs: result.leaseTtlMs,
+        variants,
+        scaffoldBaseWorkItemId: result.scaffoldBaseWorkItemId,
+        ...(args.destinationPath ? { destinationPath: args.destinationPath } : {}),
+        ...(args.visualEditor ? { visualEditor: args.visualEditor } : {}),
+        ...(args.project ? { project: args.project } : {}),
+        nextAction: 'report_variant_complete',
+    };
+}
 //# sourceMappingURL=tools.js.map