rivet-design 0.27.0 → 0.27.1

package/dist/services/TelemetryService.js

@@ -14,7 +14,16 @@ const failureReason_1 = require("../utils/failureReason");
 const proxy_1 = require("../config/proxy");
 const MCPVariantsTelemetry_1 = require("./MCPVariantsTelemetry");
 const errorMessage_1 = require("../utils/errorMessage");
+const serverUnavailable_1 = require("../cli/serverUnavailable");
 const log = (0, logger_1.createLogger)('TelemetryService');
+const serverUnavailableReasonProperties = (error) => {
+    const reason = typeof error === 'object' && error !== null
+        ? Reflect.get(error, 'serverUnavailableReason')
+        : undefined;
+    return (0, serverUnavailable_1.isServerUnavailableReason)(reason)
+        ? { server_unavailable_reason: reason }
+        : {};
+};
 const KNOWN_MCP_EDITORS = new Set([
     'cursor',
     'codex',
@@ -61,8 +70,15 @@ class TelemetryService {
         this.track(`library_${data.operation}_${data.outcome}`, {
             duration_ms: data.durationMs,
             ...(0, failureReason_1.failureReasonCodeProperties)(data.error),
+            ...serverUnavailableReasonProperties(data.error),
         });
     }
+    trackRequestRejected(reason) {
+        if (this.reportedRequestRejections.has(reason))
+            return;
+        this.reportedRequestRejections.add(reason);
+        this.track('server_request_rejected', { reason });
+    }
     hashTelemetryValue(value) {
         return (0, crypto_1.createHash)('sha256')
             .update(value)
@@ -74,6 +90,7 @@ class TelemetryService {
     defaultSource;
     editor;
     identifiedAccounts = new Set();
+    reportedRequestRejections = new Set();
     constructor(options = true) {
         const opts = typeof options === 'boolean' ? { enabled: options } : options;
         this.isEnabled = (opts.enabled ?? true) && (0, telemetryPolicy_1.getTelemetryMode)() !== 'off';
@@ -682,6 +699,7 @@ class TelemetryService {
             has_port: data.hasPort,
             port: data.port,
             duration_ms: data.durationMs,
+            static_entry_source: data.staticEntrySource,
             source: 'mcp',
         });
     }
@@ -698,6 +716,7 @@ class TelemetryService {
             exit_code: data.exitCode,
             term_signal: data.signal,
             missing_deps: data.missingDeps,
+            static_entry_source: data.staticEntrySource,
             ...(0, failureReason_1.failureReasonProperties)(data.error),
             source: 'mcp',
         });

package/dist/services/VariantHistoryService.d.ts

@@ -3,6 +3,7 @@ import type { GuidanceDocument } from '../types/guidance';
 import { type ReferenceImage } from './referenceImages';
 import { type VariantReference } from '../types/variant-reference';
 import type { VariantHistoryStatus, VariantHistoryKind, PersistVariantPreview, VariantServeSpec, VariantDesignSource, VariantDeployment, VariantCanvasDeployment, VariantHistoryManifest } from '../types/variant-history';
+import type { DirectionRef } from '../types/direction-ref';
 export type { VariantHistoryStatus, VariantHistoryKind, VariantHistoryPreview, PersistVariantPreview, VariantTreePointer, VariantBasePointer, DevServerRecipe, VariantServeSpec, VariantHistoryArtifact, VariantDesignSource, VariantDeployment, VariantCanvasDeployment, VariantHistoryManifest, VariantHistorySessionFile, } from '../types/variant-history';
 import type { BundleMetadataStore } from '../storage/library/BundleMetadataStore';
 import { TreeStore } from './TreeStore';
@@ -13,6 +14,7 @@ export interface PersistVariantArgs {
     sessionId: string;
     variantId: string;
     requestId?: string;
+    directionRef?: DirectionRef;
     label: string;
     brief: string;
     references?: VariantReference[];
@@ -116,6 +118,12 @@ export declare class VariantHistoryService {
         label?: string;
         runLabel?: string;
     }): Promise<void>;
+    assignDirectionRef(args: {
+        projectPath: string;
+        sessionId: string;
+        variantId: string;
+        directionRef: DirectionRef;
+    }): Promise<void>;
     renameRun(args: {
         projectPath: string;
         sessionId: string;

package/dist/services/VariantHistoryService.js

@@ -203,6 +203,7 @@ class VariantHistoryService {
         let preservedDestinationPath;
         let preservedCreatedAt;
         let preservedRequestId;
+        let preservedDirectionRef;
         let preservedReferences;
         let preservedPreviewRoutes;
         let preservedTree;
@@ -219,6 +220,7 @@ class VariantHistoryService {
                 });
             preservedCreatedAt = prior.createdAt;
             preservedRequestId = prior.requestId;
+            preservedDirectionRef = prior.directionRef;
             preservedReferences = prior.references;
             preservedPreviewRoutes = prior.previewRoutes;
             preservedTree = prior.tree;
@@ -363,6 +365,9 @@ class VariantHistoryService {
             ...((args.requestId ?? preservedRequestId)
                 ? { requestId: args.requestId ?? preservedRequestId }
                 : {}),
+            ...((preservedDirectionRef ?? args.directionRef)
+                ? { directionRef: preservedDirectionRef ?? args.directionRef }
+                : {}),
             label: args.label,
             brief: args.brief,
             references: (0, variant_reference_1.mergeVariantReferences)(references),
@@ -527,6 +532,41 @@ class VariantHistoryService {
             manifest,
         });
     }
+    async assignDirectionRef(args) {
+        assertSafeId(args.sessionId, 'sessionId');
+        assertSafeId(args.variantId, 'variantId');
+        const bundle = this.bundleFor(args.projectPath);
+        if (bundle) {
+            bundle.updateVariant({
+                ...args,
+                update: (manifest) => {
+                    manifest.directionRef ??= args.directionRef;
+                },
+            });
+            return;
+        }
+        const manifestPath = path_1.default.join(this.variantDir(args.projectPath, args.sessionId, args.variantId), MANIFEST_FILENAME);
+        let manifest;
+        try {
+            const raw = await promises_1.default.readFile(manifestPath, 'utf8');
+            manifest = JSON.parse(raw);
+        }
+        catch (err) {
+            const code = (0, errnoCode_1.errnoCode)(err);
+            if (code !== 'ENOENT') {
+                log.warn(`assignDirectionRef: manifest read failed at ${manifestPath} (session ${args.sessionId} variant ${args.variantId})`, err);
+            }
+            return;
+        }
+        if (manifest.directionRef)
+            return;
+        manifest.directionRef = args.directionRef;
+        await writeManifestFile(manifestPath, manifest);
+        await this.projectManifestToIndex({
+            projectPath: args.projectPath,
+            manifest,
+        });
+    }
     async renameRun(args) {
         const entries = await this.listVariants({ projectPath: args.projectPath });
         const targets = entries.filter((entry) => {

package/dist/services/WorktreeManager.d.ts

@@ -23,6 +23,7 @@ export declare class WorktreeManager {
     createWorktrees(sessionId: string, count: number, instanceKeyPrefix?: string): Promise<string[]>;
     forkWorktreesFrom(sourceWorktreePath: string, sessionId: string, count: number, instanceKeyPrefix?: string): Promise<string[]>;
     getDiff(worktreePath: string): Promise<string>;
+    getChangedFiles(worktreePath: string): Promise<string[]>;
     getFreePort(): Promise<number>;
     findFreePortFrom(startPort: number, scanWindow?: number): Promise<number>;
     releasePort(port: number): void;

package/dist/services/WorktreeManager.js

@@ -276,6 +276,18 @@ class WorktreeManager {
         await git.raw(['add', '--intent-to-add', '.']).catch(() => { });
         return git.diff(['--binary', '--full-index', 'HEAD']);
     }
+    async getChangedFiles(worktreePath) {
+        const git = (0, simple_git_1.simpleGit)(worktreePath, GIT_OPTS);
+        await git.raw(['add', '--intent-to-add', '.']).catch(() => { });
+        const names = await git.raw([
+            'diff',
+            '--name-only',
+            '--diff-filter=d',
+            '-z',
+            'HEAD',
+        ]);
+        return names.split('\0').filter(Boolean);
+    }
     getFreePort() {
         return new Promise((resolve, reject) => {
             const server = net_1.default.createServer();

package/dist/services/createAgentVariantsOrchestrator.js

@@ -1,6 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createAgentVariantsOrchestrator = exports.withVariantsSessionReplayLinking = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
 const index_core_1 = require("../index-core");
 const agent_variants_1 = require("../agent-variants");
 const devServerCommand_1 = require("../utils/devServerCommand");
@@ -69,11 +74,13 @@ const createAgentVariantsOrchestrator = (options) => {
                         targetPath: projectPath,
                         entryPath: options.staticEntry,
                     }).entryPath;
-                    log.info(`Resolved env for variants session ${sessionId}: static/${entryPath}`);
+                    const hasEntry = options.staticEntry !== undefined ||
+                        fs_1.default.existsSync(path_1.default.join(projectPath, entryPath));
+                    log.info(`Resolved env for variants session ${sessionId}: static/${hasEntry ? entryPath : '(no entry page)'}`);
                     return {
                         projectPath,
                         framework,
-                        entryPath,
+                        ...(hasEntry ? { entryPath } : {}),
                     };
                 }
                 const packageManager = await detection.detectPackageManager(projectPath);

package/dist/services/directionRefs.d.ts

@@ -0,0 +1,21 @@
+import type { DirectionAddress, DirectionCandidate, DirectionRef, DirectionResolution, DirectionSearchAddress } from '../types/direction-ref';
+import type { VariantHistoryManifest, VariantHistoryStatus } from '../types/variant-history';
+export declare const isDirectionActive: (status: VariantHistoryStatus) => boolean;
+type DirectionRefSource = {
+    manifest: Pick<VariantHistoryManifest, 'sessionId' | 'variantId' | 'label' | 'createdAt' | 'directionRef'>;
+};
+export declare const slugifyDirectionLabel: (label: string) => string;
+export declare const nextDirectionRef: (args: {
+    label: string;
+    taken: ReadonlySet<string>;
+}) => DirectionRef;
+export declare const withDirectionRefs: <Entry extends DirectionRefSource>(entries: readonly Entry[]) => Array<Entry & {
+    directionRef: DirectionRef;
+}>;
+export declare const parseDirectionAddress: (raw: string) => DirectionAddress | null;
+export declare const resolveDirectionAddress: (args: {
+    address: DirectionSearchAddress;
+    candidates: readonly DirectionCandidate[];
+}) => DirectionResolution;
+export {};
+//# sourceMappingURL=directionRefs.d.ts.map

package/dist/services/directionRefs.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDirectionAddress = exports.parseDirectionAddress = exports.withDirectionRefs = exports.nextDirectionRef = exports.slugifyDirectionLabel = exports.isDirectionActive = void 0;
+const SLUG_MAX_LENGTH = 40;
+const EMPTY_LABEL_SLUG = 'direction';
+const LAST_KEYWORD = 'last';
+const FIRST_COLLISION_SUFFIX = 2;
+const MIN_VARIANT_ID_PREFIX_LENGTH = 4;
+const MAX_UNKNOWN_CANDIDATES = 10;
+const TOKEN_PATTERN = /^[A-Za-z0-9_-]+$/;
+const INACTIVE_STATUSES = new Set([
+    'removed',
+    'cancelled',
+]);
+const isDirectionActive = (status) => !INACTIVE_STATUSES.has(status);
+exports.isDirectionActive = isDirectionActive;
+const slugifyDirectionLabel = (label) => {
+    const slug = label
+        .normalize('NFKD')
+        .replace(/\p{M}/gu, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    if (!slug)
+        return EMPTY_LABEL_SLUG;
+    if (slug.length <= SLUG_MAX_LENGTH)
+        return slug;
+    const boundary = slug.lastIndexOf('-', SLUG_MAX_LENGTH);
+    return slug.slice(0, boundary > 0 ? boundary : SLUG_MAX_LENGTH);
+};
+exports.slugifyDirectionLabel = slugifyDirectionLabel;
+const nextDirectionRef = (args) => {
+    const slug = (0, exports.slugifyDirectionLabel)(args.label);
+    const isTaken = (candidate) => candidate === LAST_KEYWORD || args.taken.has(candidate);
+    let candidate = slug;
+    for (let suffix = FIRST_COLLISION_SUFFIX; isTaken(candidate); suffix++)
+        candidate = `${slug}-${suffix}`;
+    return candidate;
+};
+exports.nextDirectionRef = nextDirectionRef;
+const directionKey = (manifest) => `${manifest.sessionId}:${manifest.variantId}`;
+const byCreation = (a, b) => a.manifest.createdAt.localeCompare(b.manifest.createdAt) ||
+    a.manifest.sessionId.localeCompare(b.manifest.sessionId) ||
+    a.manifest.variantId.localeCompare(b.manifest.variantId);
+const withDirectionRefs = (entries) => {
+    const taken = new Set(entries.flatMap(({ manifest }) => manifest.directionRef ? [manifest.directionRef] : []));
+    const legacyRefs = new Map();
+    const legacyRefOf = (manifest) => {
+        const key = directionKey(manifest);
+        const known = legacyRefs.get(key);
+        if (known)
+            return known;
+        const directionRef = (0, exports.nextDirectionRef)({ label: manifest.label, taken });
+        taken.add(directionRef);
+        legacyRefs.set(key, directionRef);
+        return directionRef;
+    };
+    for (const { manifest } of [...entries].sort(byCreation))
+        if (!manifest.directionRef)
+            legacyRefOf(manifest);
+    return entries.map((entry) => ({
+        ...entry,
+        directionRef: entry.manifest.directionRef ?? legacyRefOf(entry.manifest),
+    }));
+};
+exports.withDirectionRefs = withDirectionRefs;
+const parseDirectionIds = (raw) => {
+    const projectSeparator = raw.indexOf('/');
+    const projectId = projectSeparator === -1 ? undefined : raw.slice(0, projectSeparator);
+    const direction = projectSeparator === -1 ? raw : raw.slice(projectSeparator + 1);
+    if (projectSeparator !== -1 && (!projectId || direction.includes('/')))
+        return null;
+    const variantSeparator = direction.indexOf(':');
+    if (variantSeparator <= 0 || variantSeparator === direction.length - 1)
+        return null;
+    if (direction.indexOf(':', variantSeparator + 1) !== -1)
+        return null;
+    const sessionId = direction.slice(0, variantSeparator).trim();
+    const variantId = direction.slice(variantSeparator + 1).trim();
+    if (!sessionId || !variantId)
+        return null;
+    return {
+        kind: 'ids',
+        ...(projectId ? { projectId } : {}),
+        sessionId,
+        variantId,
+    };
+};
+const parseDirectionAddress = (raw) => {
+    const value = raw.trim();
+    if (value.toLowerCase() === LAST_KEYWORD)
+        return { kind: 'last' };
+    if (value.includes(':') || value.includes('/'))
+        return parseDirectionIds(value);
+    return TOKEN_PATTERN.test(value) ? { kind: 'token', token: value } : null;
+};
+exports.parseDirectionAddress = parseDirectionAddress;
+const newestFirst = (a, b) => b.createdAt.localeCompare(a.createdAt);
+const notFound = (args) => {
+    const candidates = args.newest.slice(0, MAX_UNKNOWN_CANDIDATES);
+    const knownRefs = candidates.map((candidate) => candidate.directionRef);
+    const knownRefsSentence = knownRefs.length > 0 ? ` Known refs: ${knownRefs.join(', ')}.` : '';
+    return {
+        isResolved: false,
+        code: 'WORK_ITEM_NOT_FOUND',
+        message: `No direction matches "${args.input}".${knownRefsSentence}`,
+        candidates,
+    };
+};
+const resolveToken = (args) => {
+    const needle = args.token.toLowerCase();
+    const exact = args.newest.filter((candidate) => candidate.directionRef.toLowerCase() === needle);
+    const prefixed = needle.length >= MIN_VARIANT_ID_PREFIX_LENGTH
+        ? args.newest.filter((candidate) => candidate.variantId.toLowerCase().startsWith(needle))
+        : [];
+    const matches = exact.length > 0 ? exact : prefixed;
+    if (matches.length === 1)
+        return { isResolved: true, direction: matches[0] };
+    if (matches.length === 0)
+        return notFound({ input: args.token, newest: args.newest });
+    return {
+        isResolved: false,
+        code: 'DIRECTION_AMBIGUOUS',
+        message: `"${args.token}" matches ${matches.length} directions: ${matches
+            .map((candidate) => candidate.directionRef)
+            .join(', ')}.`,
+        candidates: matches,
+    };
+};
+const resolveDirectionAddress = (args) => {
+    const newest = [...args.candidates].sort(newestFirst);
+    switch (args.address.kind) {
+        case 'last': {
+            const direction = newest.find((candidate) => (0, exports.isDirectionActive)(candidate.status));
+            return direction
+                ? { isResolved: true, direction }
+                : notFound({ input: LAST_KEYWORD, newest });
+        }
+        case 'token':
+            return resolveToken({ token: args.address.token, newest });
+        default: {
+            const unhandled = args.address;
+            return unhandled;
+        }
+    }
+};
+exports.resolveDirectionAddress = resolveDirectionAddress;
+//# sourceMappingURL=directionRefs.js.map

package/dist/services/projectDirections.d.ts

@@ -0,0 +1,22 @@
+import type { ProjectLibrary } from './ProjectLibrary';
+import type { VariantHistoryEntry, VariantHistoryService } from './VariantHistoryService';
+import type { DirectionRef, DirectionResolution, DirectionSearchAddress } from '../types/direction-ref';
+export type ProjectDirectionSource = {
+    kind: 'library';
+    library: ProjectLibrary;
+    projectId: string;
+} | {
+    kind: 'history';
+    history: VariantHistoryService;
+    projectPath: string;
+};
+export type ProjectDirection = VariantHistoryEntry & {
+    projectPath: string;
+    directionRef: DirectionRef;
+};
+export declare const listProjectDirections: (source: ProjectDirectionSource) => Promise<ProjectDirection[]>;
+export declare const resolveProjectDirection: (args: {
+    source: ProjectDirectionSource;
+    address: DirectionSearchAddress;
+}) => Promise<DirectionResolution>;
+//# sourceMappingURL=projectDirections.d.ts.map

package/dist/services/projectDirections.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveProjectDirection = exports.listProjectDirections = void 0;
+const directionRefs_1 = require("./directionRefs");
+const historyRoots_1 = require("./historyRoots");
+const listSourceEntries = async (source) => {
+    switch (source.kind) {
+        case 'library':
+            return source.library.listVariants(source.projectId, {
+                isRemovedIncluded: true,
+            });
+        case 'history':
+            return (await Promise.all([
+                source.projectPath,
+                ...(0, historyRoots_1.nestedFreshSessionWorkdirs)(source.projectPath),
+            ].map(async (projectPath) => (await source.history.listVariants({ projectPath })).map((entry) => ({ ...entry, projectPath }))))).flat();
+        default: {
+            const unhandled = source;
+            return unhandled;
+        }
+    }
+};
+const listProjectDirections = async (source) => (0, directionRefs_1.withDirectionRefs)(await listSourceEntries(source));
+exports.listProjectDirections = listProjectDirections;
+const directionCandidateOf = (direction) => ({
+    directionRef: direction.directionRef,
+    sessionId: direction.manifest.sessionId,
+    variantId: direction.manifest.variantId,
+    label: direction.manifest.label,
+    status: direction.manifest.status,
+    createdAt: direction.manifest.createdAt,
+});
+const resolveProjectDirection = async (args) => (0, directionRefs_1.resolveDirectionAddress)({
+    address: args.address,
+    candidates: (await (0, exports.listProjectDirections)(args.source)).map(directionCandidateOf),
+});
+exports.resolveProjectDirection = resolveProjectDirection;
+//# sourceMappingURL=projectDirections.js.map

package/dist/types/direction-ref.d.ts

@@ -0,0 +1,36 @@
+import type { VariantHistoryStatus } from './variant-history';
+export type DirectionRef = string & {
+    readonly __brand: 'DirectionRef';
+};
+export type DirectionAddress = {
+    kind: 'ids';
+    projectId?: string;
+    sessionId: string;
+    variantId: string;
+} | {
+    kind: 'token';
+    token: string;
+} | {
+    kind: 'last';
+};
+export type DirectionSearchAddress = Exclude<DirectionAddress, {
+    kind: 'ids';
+}>;
+export interface DirectionCandidate {
+    directionRef: DirectionRef;
+    sessionId: string;
+    variantId: string;
+    label: string;
+    status: VariantHistoryStatus;
+    createdAt: string;
+}
+export type DirectionResolution = {
+    isResolved: true;
+    direction: DirectionCandidate;
+} | {
+    isResolved: false;
+    code: 'WORK_ITEM_NOT_FOUND' | 'DIRECTION_AMBIGUOUS';
+    message: string;
+    candidates: DirectionCandidate[];
+};
+//# sourceMappingURL=direction-ref.d.ts.map

package/dist/types/direction-ref.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=direction-ref.js.map

package/dist/types/variant-history.d.ts

@@ -1,3 +1,4 @@
+import type { DirectionRef } from './direction-ref';
 import type { VariantReference } from './variant-reference';
 export type { VariantReference } from './variant-reference';
 export type VariantHistoryStatus = 'completed' | 'committed' | 'rejected' | 'cancelled' | 'removed';
@@ -91,6 +92,7 @@ export interface VariantHistoryManifest {
     variantId: string;
     sessionId: string;
     requestId?: string;
+    directionRef?: DirectionRef;
     label: string;
     brief: string;
     references?: VariantReference[];
@@ -120,7 +122,7 @@ export interface VariantHistoryManifest {
     deployments?: VariantDeployment[];
     runtime?: import('../agent-variants/contracts').WorkerRuntimeInfo;
 }
-export type VariantHistoryRow = Pick<VariantHistoryManifest, 'sessionId' | 'variantId' | 'requestId' | 'label' | 'brief' | 'references' | 'previewRoutes' | 'runLabel' | 'projectKind' | 'status' | 'createdAt' | 'statusChangedAt' | 'changedFilesCount' | 'preview' | 'artifact' | 'parentVariant' | 'serve' | 'runtime'> & {
+export type VariantHistoryRow = Pick<VariantHistoryManifest, 'sessionId' | 'variantId' | 'requestId' | 'directionRef' | 'label' | 'brief' | 'references' | 'previewRoutes' | 'runLabel' | 'projectKind' | 'status' | 'createdAt' | 'statusChangedAt' | 'changedFilesCount' | 'preview' | 'artifact' | 'parentVariant' | 'serve' | 'runtime'> & {
     kind: VariantHistoryKind;
     hasStaticPreview: boolean;
     hasTree: boolean;

package/dist/utils/skills/cli-guidance.js

@@ -28,7 +28,7 @@ exports.CLI_GUIDANCE_BODY = `Rivet helps you **explore multiple design direction
 
 Use these independently exposed tools for their named purposes:
 
-- \`rivet_explore_designs\` starts directions with \`project\`, \`instruction\`, \`runLabel\`, and one authored \`briefs\` entry per direction. Use \`baseDirectionId: "sessionId:variantId"\` to vary a result.
+- \`rivet_explore_designs\` starts directions with \`project\`, \`instruction\`, \`runLabel\`, and one authored \`briefs\` entry per direction. Use \`baseDirectionId\` with a direction's \`directionRef\` (for example \`"warm-editorial-green"\`) or \`"sessionId:variantId"\` to vary a result.
 - \`rivet_get_exploration\` reads progress and results with \`project\`. Add \`sessionId\`, \`variantId\`, \`includeHistory\`, or the start response's \`workId\` for recorded context receipts.
 - \`rivet_cancel_exploration\` cancels the named \`project\` and \`sessionId\` only when the user asks.
 - \`rivet_find_references\` searches retained titles, text, notes, and analysis with \`query\`, optional \`sourceId\`, and optional \`limit\`. Its \`saved_text\` ranking is lexical. It does not start workers, create an index, or perform semantic model search.
@@ -95,12 +95,13 @@ The export returns \`{checks:[{id,status:"pass"|"fail"|"blocked",priority:"high"
 - \`rivet open [--project <path>] [--agent claude|codex|cursor] [--rivet-port N] [--user-port N] [--framework nextjs|vite|cra|remix|svelte|static] [--entry <path>] [--no-browser] [--no-git]\` — start or attach the project's editor server (idempotent; returns \`editorUrl\`). It detects the app, attaches to an already-running dev server, or starts one from the app's standard \`dev\`/\`start\`/\`serve\`/\`storybook\` script when possible. Follow the browser behavior above for interactive work.
   - **Attach, don't rebuild.** If the user's dev server is already running (including Storybook — component-library teams often run only Storybook), pass \`--user-port <port>\` to attach directly: this skips detection and never starts a second server. Auto-detection scans common ports (3000, 5173, 6006, …), but an explicit \`--user-port\` is always the most reliable path — when in doubt, ask the user which port their app is on, or start the dev server yourself first and pass its port.
   - **Rivet never installs dependencies.** If \`open\` fails because the app's start command failed, the error carries the exact command and its output. YOU own the fix: diagnose the output, run the project's install yourself if dependencies are missing, or start the dev server yourself — then re-run \`rivet open --user-port <port>\`. Do not retry \`rivet open\` unchanged expecting a different result.
-- \`rivet variants start --project <path> --instruction <text> [--run-label <text>] [--briefs <json>] [--count N] [--fidelity low|medium|high] [--element <selector>] [--files <json>] [--fresh] [--profile auto|off] [--context-images <json>] [--reference-pages <json>] [--reference-videos <json>] [--target <sessionId>:<variantId>] [--worker-provider claude|codex|cursor] [--worker-model <id>]\` — explore design directions. For every start, including fresh apps and \`--target\` requests, agent invocations MUST pass an AI-authored 1–3 word batch label through \`rivet_explore_designs\` \`runLabel\` or CLI \`--run-label\`, plus one AI-authored brief per direction; \`briefs.length\` sets the count. Fresh starts use the same host-authored briefs and batch label; Rivet prepares reference context for the workers without calling a planning model. Use \`--files\` for already-known project paths and \`--target\` to Vary an existing direction. Returns a \`workId\` and \`nextAction\` after workspace provisioning.
+- \`rivet variants start --project <path> --instruction <text> [--run-label <text>] [--briefs <json>] [--count N] [--fidelity low|medium|high] [--element <selector>] [--files <json>] [--fresh] [--profile auto|off] [--context-images <json>] [--reference-pages <json>] [--reference-videos <json>] [--target <directionRef>|<sessionId>:<variantId>] [--worker-provider claude|codex|cursor] [--worker-model <id>]\` — explore design directions. For every start, including fresh apps and \`--target\` requests, agent invocations MUST pass an AI-authored 1–3 word batch label through \`rivet_explore_designs\` \`runLabel\` or CLI \`--run-label\`, plus one AI-authored brief per direction; \`briefs.length\` sets the count. Fresh starts use the same host-authored briefs and batch label; Rivet prepares reference context for the workers without calling a planning model. Use \`--files\` for already-known project paths and \`--target\` to Vary an existing direction. Returns a \`workId\` and \`nextAction\` after workspace provisioning.
 - \`rivet variants complete <workId> --project <path> [--session <sessionId>] [--status succeeded|failed|cancelled] [--output <json>] [--error <message>]\` — report one host-agent work item complete after you edit its assigned workspace. Static artifacts are read from disk; do not send them through \`--output\`.
 - \`rivet wait <workId> --project <path> [--timeout <seconds>]\` — bounded block until a work id settles (exit 5 on timeout; re-issue or check status).
 - \`rivet status --project <path> [--watch]\` — session, resolved runner, active run, and the variants snapshot. \`--watch\` streams NDJSON.
 - \`rivet variants status --project <path>\` / \`rivet variants list --project <path> [--history]\` — inspect live or past directions.
 - \`rivet variants get <projectId>/<sessionId>:<variantId> [--detail]\` — resolve a copied direction from any working directory through the local project library, even when its editor is closed. The default response is compact metadata and an artifact path; add \`--detail\` for the full diff, file list, and design notes.
+- \`rivet variants get <directionRef>|last --project <path> [--detail]\` — resolve a direction by the short \`directionRef\` shown in status, history, and \`nextAction\` work items (for example \`warm-editorial-green\`), or the newest direction with \`last\`. Refs never change once assigned. An ambiguous or unknown ref fails with \`DIRECTION_AMBIGUOUS\` or \`WORK_ITEM_NOT_FOUND\` and lists the candidate refs in \`error.details.candidates\`.
 - \`rivet variants cancel <sessionId> --project <path>\` — cancel a running variants session.
 - \`rivet evidence capture --url <url>\` — rendered design evidence (root variables, element styles, fonts) for a reference URL.
 - \`rivet reference fetch <url>\` — Pinterest / Are.na reference data via the user's connected account. Accepts full pin/board URLs and \`pin.it\` share links. Pinterest images are downloaded into \`.rivet/references/\` and returned as absolute paths (\`data.images\`, plus \`local_path\` per pin) — view them directly and pass them to variants via \`--context-images\` instead of relaying URLs. If Pinterest returns \`status: not_connected\`, present the returned \`authUrl\` to the user and retry after they authorize. On failure the error message says exactly what to tell the user (e.g. save the pin to a board first).
@@ -125,7 +126,7 @@ Existing app, using CLI commands when MCP is unavailable. With MCP use \`rivet_g
 
 Fresh 0-to-1: with MCP use \`rivet_explore_designs\` with \`fresh: true\` after reading \`rivet_get_design_context\`. For the CLI flow, create or use an empty directory and run \`rivet open --project <path> ...\`. Resolve the selected saved instructions with \`rivet context resolve\`, then author a batch label and one distinct brief per direction from the user's request, supplied references, and saved instructions. Include concrete section, layout, typography, and interaction choices in each brief's notes. Run \`rivet variants start --project <path> --fresh --instruction "build a SaaS landing page" --run-label "Landing layouts" --briefs '<json>' ...\`, omitting \`--count\` because the briefs set the count. Rivet uses those briefs directly without a hosted planning call. Pass local reference images via \`--context-images '["/abs/path.png"]'\` (\`rivet_explore_designs\` \`contextImages\`) — Rivet copies them into the run context and every worker views them natively. Pass reference page URLs via \`--reference-pages '["https://example.com"]'\` (\`referencePages\`) — Rivet renders each page server-side for design evidence + a screenshot; never capture evidence or screenshot pages yourself. Pass local reference videos via \`--reference-videos '["/abs/clip.mp4"]'\` (\`referenceVideos\`) — Rivet samples keyframes server-side; never run ffmpeg yourself. Never substitute a prose description of media you can pass directly.
 
-Vary an existing direction: with MCP read \`rivet_get_exploration\` and pass \`baseDirectionId: "sessionId:variantId"\` to \`rivet_explore_designs\`. For the CLI flow, after status/list gives you \`sessionId\` and \`variantId\`, author a batch label and two distinct delta briefs by default, then run \`rivet variants start --project <path> --target <sessionId>:<variantId> --instruction "make this calmer" --run-label "Calmer direction" --briefs '<json>' ...\`. Include \`--files '["src/known-target.tsx"]'\` when the relevant files are already known. Explicit briefs/counts remain authoritative.
+Vary an existing direction: with MCP read \`rivet_get_exploration\` and pass the direction's \`directionRef\` as \`baseDirectionId\` to \`rivet_explore_designs\`. For the CLI flow, after status/list gives you its \`directionRef\`, author a batch label and two distinct delta briefs by default, then run \`rivet variants start --project <path> --target <directionRef> --instruction "make this calmer" --run-label "Calmer direction" --briefs '<json>' ...\`. Include \`--files '["src/known-target.tsx"]'\` when the relevant files are already known. Explicit briefs/counts remain authoritative.
 
 Rivet owns orchestration; the host agent owns implementation. Do not wait for Rivet to spawn a separate agent. When \`rivet variants start\`, \`rivet status\`, \`rivet_explore_designs\`, or \`rivet_get_exploration\` returns \`nextAction.action="complete_host_variant_work"\`, complete those work items from the current host session. Follow the returned parallelism strategy: direct work stays in the current host; native delegation can be required even for one item with a requested model. Spawn one native worker per delegated workspace in the same turn, and have each worker report its own completion immediately via its \`completeCommand\` (or \`rivet_complete_variant_work\`) — a variant's completion must never wait for its siblings.
 

package/dist/utils/subprocessEnvironment.d.ts

@@ -1,5 +1,5 @@
 type ProviderPurpose = 'claude' | 'codex' | 'cursor' | 'verifier';
-type ChildPurpose = ProviderPurpose | 'devServer' | 'packageManager' | 'staticPreview' | 'profileMemory' | 'git' | 'desktop';
+type ChildPurpose = ProviderPurpose | 'devServer' | 'packageManager' | 'profileMemory' | 'git' | 'desktop';
 type SubprocessPurpose = ChildPurpose | 'rivetRuntime';
 export declare const subprocessEnvironment: (purpose: SubprocessPurpose, inherited?: NodeJS.ProcessEnv) => NodeJS.ProcessEnv;
 export {};

package/dist/utils/subprocessEnvironment.js

@@ -178,7 +178,6 @@ const CHILD_ALLOWLISTS = {
         ],
         prefixes: [],
     },
-    staticPreview: { names: SYSTEM_VARIABLES, prefixes: [] },
     profileMemory: { names: SYSTEM_VARIABLES, prefixes: [] },
 };
 const childAllowlists = Object.values(CHILD_ALLOWLISTS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rivet-design",
-  "version": "0.27.0",
+  "version": "0.27.1",
   "description": "Local visual web development tool with AI-powered code modification",
   "main": "dist/index.js",
   "workspaces": [
@@ -120,7 +120,7 @@
     "eslint": "^9.36.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^5.2.0",
+    "eslint-plugin-react-hooks": "^7.1.1",
     "globals": "^17.14.0",
     "husky": "^9.1.7",
     "jest": "^30.1.3",
@@ -212,5 +212,5 @@
   "rivetPlugin": {
     "toolContract": "intent-v2"
   },
-  "gitHead": "3efd8a49dc50fdc302b9b2152238a2b79d3e899e"
+  "gitHead": "4ee9afdfb73764212502fcaa1b21335ad89ab889"
 }