rivet-design 0.19.0 → 0.20.0

package/README.md

@@ -32,6 +32,8 @@ rivet open --project /path/to/app
 
 Rivet opens one shared project library on your computer. Run `rivet open` inside a project to open its editor, or from a non-project directory to browse saved directions across projects. Projects register automatically when opened or created; **Open project…** also lets you choose an existing folder.
 
+While Rivet is running, open `http://localhost:16060` in a browser and sign in with Google to reach the same library. Local development installs use port 16061. Set `RIVET_LIBRARY_PORT` to another port before `rivet open` if the default is occupied. Rivet reports a port conflict instead of moving silently. Opening a browser URL does not start the coordinator after a restart; run `rivet open` to start it.
+
 Saved directions live in project bundles under `~/.rivet/library/production`. Their metadata and self-contained previews remain available when a working folder is missing. Editing still requires that folder. Existing histories are copied only after verification, and their source files are preserved. Switching projects in the browser does not change the project targeted by your terminal or agent.
 
 ## Automatic Updates
@@ -52,13 +54,23 @@ Updated skill and rule files are available on disk immediately. An agent
 session that already loaded them may need its normal restart or reload before
 it uses the refreshed instructions.
 
+At the start of a host-agent conversation that uses Rivet, the agent runs
+`rivet version status` before opening the project. The command reports the
+installed version, latest published version, and update availability without
+changing the installation. The agent shares those versions, runs `rivet update`
+when a release is available, and reports the outcome before continuing. If an
+update fails, the agent reports the failure and can continue with the installed
+CLI. This notice and update flow happens in the host-agent conversation, not
+in the editor.
+
 ## CLI Agent Commands
 
 Rivet's agent-facing commands print one JSON envelope on stdout, write progress to stderr, and do not prompt for input.
 
-For interactive user workflows, run `rivet open` without `--no-browser` so the Rivet UI opens in the browser. Use `--no-browser` only for explicitly unattended automation, headless environments, CI/e2e checks, or when the user explicitly asks not to open a browser; in those cases, report the returned `editorUrl`. Background workers or a background shell command do not make an interactive user request unattended. Always report the returned `editorUrl`; if `browser.action` is `launch_failed`, give the user that link to open manually.
+In Codex within the ChatGPT desktop app or in Claude Code Desktop, use `rivet open --project /path/to/app --no-browser` when the app has an in-app browser that can reach localhost. Open the exact returned `data.editorUrl` in that browser. In Claude Code Desktop, a user may need to select **Open in app** for the link. If the host has no usable in-app browser, run `rivet open` without `--no-browser` to launch the system browser. Always share the returned URL so the user can open it if browser navigation fails.
 
 ```bash
+rivet version status
 rivet open --project /path/to/app
 rivet status --project /path/to/app
 rivet variants start --project /path/to/app --instruction "try three hero layouts" --count 3

package/README.npm.md

@@ -32,6 +32,8 @@ rivet open --project /path/to/app
 
 Rivet opens one shared project library on your computer. Run `rivet open` inside a project to open its editor, or from a non-project directory to browse saved directions across projects. Projects register automatically when opened or created; **Open project…** also lets you choose an existing folder.
 
+While Rivet is running, open `http://localhost:16060` in a browser and sign in with Google to reach the same library. Local development installs use port 16061. Set `RIVET_LIBRARY_PORT` to another port before `rivet open` if the default is occupied. Rivet reports a port conflict instead of moving silently. Opening a browser URL does not start the coordinator after a restart; run `rivet open` to start it.
+
 Saved directions live in project bundles under `~/.rivet/library/production`. Their metadata and self-contained previews remain available when a working folder is missing. Editing still requires that folder. Existing histories are copied only after verification, and their source files are preserved. Switching projects in the browser does not change the project targeted by your terminal or agent.
 
 ## Automatic Updates
@@ -52,13 +54,23 @@ Updated skill and rule files are available on disk immediately. An agent
 session that already loaded them may need its normal restart or reload before
 it uses the refreshed instructions.
 
+At the start of a host-agent conversation that uses Rivet, the agent runs
+`rivet version status` before opening the project. The command reports the
+installed version, latest published version, and update availability without
+changing the installation. The agent shares those versions, runs `rivet update`
+when a release is available, and reports the outcome before continuing. If an
+update fails, the agent reports the failure and can continue with the installed
+CLI. This notice and update flow happens in the host-agent conversation, not
+in the editor.
+
 ## CLI Agent Commands
 
 Rivet's agent-facing commands print one JSON envelope on stdout, write progress to stderr, and do not prompt for input.
 
-For interactive user workflows, run `rivet open` without `--no-browser` so the Rivet UI opens in the browser. Use `--no-browser` only for explicitly unattended automation, headless environments, CI/e2e checks, or when the user explicitly asks not to open a browser; in those cases, report the returned `editorUrl`. Background workers or a background shell command do not make an interactive user request unattended. Always report the returned `editorUrl`; if `browser.action` is `launch_failed`, give the user that link to open manually.
+In Codex within the ChatGPT desktop app or in Claude Code Desktop, use `rivet open --project /path/to/app --no-browser` when the app has an in-app browser that can reach localhost. Open the exact returned `data.editorUrl` in that browser. In Claude Code Desktop, a user may need to select **Open in app** for the link. If the host has no usable in-app browser, run `rivet open` without `--no-browser` to launch the system browser. Always share the returned URL so the user can open it if browser navigation fails.
 
 ```bash
+rivet version status
 rivet open --project /path/to/app
 rivet status --project /path/to/app
 rivet variants start --project /path/to/app --instruction "try three hero layouts" --count 3

package/dist/agent-variants/PreviewRuntime.d.ts

@@ -0,0 +1,100 @@
+import type { ChildProcess } from 'child_process';
+import { type PreviewPackageManager } from '../services/ProjectPackageManager';
+import { type DevServerFailureReason } from '../utils/devServerError';
+import type { ProjectContext } from './contracts';
+import type { ProjectEnvironment, WorktreeManagerLike } from './variant-project-runtime';
+import { type VariantsTelemetry } from './variantsTelemetry';
+export type ResolvedDevServer = {
+    cwd: string;
+    cmd: string;
+    args: string[];
+    env: Record<string, string>;
+    packageManager: PreviewPackageManager;
+};
+export type PreviewFailure = {
+    reason: DevServerFailureReason | 'missing_static_entry' | 'idle_timeout' | 'unknown';
+    portInUse: boolean;
+};
+type PreviewRuntimeDeps = {
+    worktreeManager: WorktreeManagerLike;
+    resolveProjectEnvironment: (sessionId: string) => Promise<ProjectEnvironment>;
+    getProjectContext: (sessionId: string) => ProjectContext;
+    getDependencySignal: (sessionId: string) => AbortSignal | undefined;
+    installDependencies: (worktreePath: string, options?: {
+        workspaceRoot: string;
+        force?: boolean;
+        signal?: AbortSignal;
+    }) => Promise<void>;
+    telemetry: VariantsTelemetry;
+    isSessionLive: (sessionId: string) => boolean;
+    isCleanupStarted: (sessionId: string) => boolean;
+    hasUiClients: () => boolean;
+    changed: () => void;
+    switchPreviewPort?: (port: number | null) => void;
+    setCommittedDevServerHealth?: (port: number | null) => void;
+    startStaticPreviewServer?: (args: {
+        rootPath: string;
+        port: number;
+        host?: string;
+    }) => Promise<ChildProcess>;
+    activeVariantServerIdleTtlMs: number;
+    devServerRestartDelayMs: number;
+};
+export declare class PreviewRuntime {
+    private readonly deps;
+    private readonly sessions;
+    private readonly lingeringCommitted;
+    private readonly committedGenerations;
+    private generation;
+    constructor(deps: PreviewRuntimeDeps);
+    openSession(sessionId: string): void;
+    registerVariant(sessionId: string, workItemId: string, worktreePath: string): void;
+    getPort(sessionId: string, workItemId: string): number | undefined;
+    getRunningVariant(sessionId: string, workItemId: string): {
+        command: ResolvedDevServer;
+        port: number;
+    } | undefined;
+    getFailure(sessionId: string, workItemId: string): PreviewFailure | undefined;
+    setFailure(sessionId: string, workItemId: string, failure: PreviewFailure): void;
+    clearFailure(sessionId: string, workItemId: string): void;
+    touch(sessionId: string): void;
+    startVariant(args: {
+        sessionId: string;
+        workItemId: string;
+        worktreePath: string;
+        isFresh: boolean;
+    }): Promise<number | undefined>;
+    restoreVariant(args: {
+        sessionId: string;
+        workItemId: string;
+        worktreePath: string;
+        isFresh: boolean;
+        isSucceeded: boolean;
+        retryFailed?: boolean;
+    }): Promise<number | undefined>;
+    stopVariantServers(sessionId: string): Promise<number>;
+    startCommitted(args: {
+        sessionId: string;
+        destinationPath: string;
+        mode?: 'vite_app' | 'static_preview';
+    }): Promise<number | undefined>;
+    getCommittedPort(sessionId: string): number | undefined;
+    stopLingeringCommitted(): Promise<void>;
+    closeSession(sessionId: string, reason: 'committed' | 'cancel' | 'shutdown'): Promise<void>;
+    resolveCommand(sessionId: string, worktreePath: string, port: number, isFresh: boolean): Promise<ResolvedDevServer>;
+    private startVariantProcess;
+    private watchVariantProcess;
+    private failVariant;
+    private stopIdleVariants;
+    private resolveRunnableCommand;
+    private resolveStartPort;
+    private resolveExistingProjectCwd;
+    private notifyCommittedPort;
+    private notifyCommittedHealth;
+    private notifyPreviewPort;
+    private clearIdleTimer;
+    private requireSession;
+    private requireVariant;
+}
+export {};
+//# sourceMappingURL=PreviewRuntime.d.ts.map

package/dist/agent-variants/PreviewRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PreviewRuntime.d.ts","sourceRoot":"","sources":["../../src/agent-variants/PreviewRuntime.ts"],"names":[],"mappings":"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"}