@vellumai/cli 0.8.12 → 0.9.0-dev.202606162243.4268db3

package/src/commands/nginx-ingress.ts

@@ -0,0 +1,291 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import {
+  formatAssistantLookupError,
+  lookupAssistantByIdentifier,
+  resolveAssistant,
+} from "../lib/assistant-config.js";
+import type { AssistantEntry } from "../lib/assistant-config.js";
+import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
+import { GATEWAY_PORT } from "../lib/constants.js";
+import {
+  formatFeatureFlagGateMessage,
+  isAssistantFeatureFlagEnabled,
+  WEB_REMOTE_INGRESS_FLAG,
+} from "../lib/feature-flags.js";
+import { waitForDaemonReady } from "../lib/http-client.js";
+import {
+  DEFAULT_NGINX_INGRESS_PORT,
+  findWebDistDir,
+  getIngressPaths,
+  getIngressPid,
+  getNginxIngressPort,
+  getNginxVersion,
+  isIngressRunning,
+  resolveTunnelTargetPort,
+  startIngressNginx,
+  stopIngressNginx,
+} from "../lib/nginx-ingress.js";
+
+const READY_TIMEOUT_MS = 5_000;
+
+function printHelp(): void {
+  console.log("Usage: vellum nginx-ingress <subcommand> [<name>] [options]");
+  console.log("");
+  console.log(
+    "Manage the nginx web edge that serves the SPA and fronts the gateway",
+  );
+  console.log(
+    "for remote web access: browser → tunnel (TLS) → nginx@127.0.0.1.",
+  );
+  console.log("While nginx ingress is running, `vellum tunnel` targets it.");
+  console.log("");
+  console.log("Subcommands:");
+  console.log("  up       Generate the nginx config and start the proxy");
+  console.log("  down     Stop the proxy");
+  console.log("  status   Show whether the proxy is running and where");
+  console.log("");
+  console.log("Arguments:");
+  console.log(
+    "  <name>   Name of the assistant (defaults to active or only local)",
+  );
+  console.log("");
+  console.log("Options:");
+  console.log("  --help, -h   Show this help");
+  console.log("");
+  console.log("Environment:");
+  console.log(
+    `  VELLUM_NGINX_INGRESS_PORT   nginx ingress loopback listen port (default ${DEFAULT_NGINX_INGRESS_PORT})`,
+  );
+  console.log("  NGINX_BIN             Path to the nginx binary");
+  console.log("");
+  console.log("Examples:");
+  console.log("  $ vellum nginx-ingress up");
+  console.log("  $ vellum nginx-ingress status");
+  console.log("  $ vellum nginx-ingress down my-assistant");
+  console.log("");
+  console.log("Feature flags:");
+  console.log(
+    `  ${WEB_REMOTE_INGRESS_FLAG} must be enabled to start nginx ingress`,
+  );
+}
+
+interface NginxIngressTarget {
+  assistantId?: string;
+  workspaceDir: string;
+  gatewayPort: number;
+}
+
+function parsePortFromUrl(url: unknown): number | undefined {
+  if (typeof url !== "string" || !url.trim()) return undefined;
+  try {
+    const port = Number(new URL(url).port);
+    return Number.isInteger(port) && port > 0 && port <= 65535
+      ? port
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveEntryGatewayPort(entry: AssistantEntry | undefined): number {
+  return (
+    parsePortFromUrl(entry?.localUrl) ??
+    parsePortFromUrl(entry?.runtimeUrl) ??
+    GATEWAY_PORT
+  );
+}
+
+/**
+ * Resolve which assistant nginx ingress fronts. Multi-instance hatches allocate
+ * per-assistant gateway ports and workspaces, so both must come from the
+ * resolved entry's resources. Entries without resources still record their
+ * reachable gateway URL, so derive the port from localUrl/runtimeUrl before
+ * falling back to the legacy default. Explicit names go through the shared
+ * identifier lookup (see cli/AGENTS.md "Assistant targeting convention") so
+ * display names resolve and ambiguous matches fail loudly.
+ */
+export function resolveNginxIngressTarget(
+  assistantName: string | null,
+): NginxIngressTarget {
+  let entry: AssistantEntry | undefined;
+  if (assistantName) {
+    const result = lookupAssistantByIdentifier(assistantName);
+    if (result.status !== "found") {
+      throw new Error(formatAssistantLookupError(assistantName, result));
+    }
+    entry = result.entry;
+  } else {
+    entry = resolveAssistant() ?? undefined;
+  }
+  if (entry?.resources) {
+    return {
+      assistantId: entry.assistantId,
+      workspaceDir: join(entry.resources.instanceDir, ".vellum", "workspace"),
+      gatewayPort: entry.resources.gatewayPort,
+    };
+  }
+  return {
+    assistantId: entry?.assistantId,
+    workspaceDir:
+      process.env.VELLUM_WORKSPACE_DIR?.trim() ||
+      join(homedir(), ".vellum", "workspace"),
+    gatewayPort: resolveEntryGatewayPort(entry),
+  };
+}
+
+async function assertWebRemoteIngressEnabled(
+  target: NginxIngressTarget,
+): Promise<void> {
+  if (!target.assistantId) {
+    throw new Error(formatFeatureFlagGateMessage(WEB_REMOTE_INGRESS_FLAG));
+  }
+
+  let enabled: boolean;
+  try {
+    enabled = await isAssistantFeatureFlagEnabled(
+      target.assistantId,
+      WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl: `http://127.0.0.1:${target.gatewayPort}` },
+    );
+  } catch (err) {
+    throw new Error(
+      `Could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` feature flag. Is the assistant running? Try \`vellum wake\` and retry. ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+
+  if (!enabled) {
+    throw new Error(formatFeatureFlagGateMessage(WEB_REMOTE_INGRESS_FLAG));
+  }
+}
+
+async function up(target: NginxIngressTarget): Promise<void> {
+  const { workspaceDir, gatewayPort } = target;
+  const listenPort = getNginxIngressPort();
+
+  await assertWebRemoteIngressEnabled(target);
+
+  const version = getNginxVersion();
+  if (!version) {
+    console.error("Error: nginx is not installed.");
+    console.error("");
+    console.error("Install nginx:");
+    console.error("  macOS:  brew install nginx");
+    console.error("  Linux:  sudo apt install nginx");
+    console.error("");
+    console.error(
+      "Or point NGINX_BIN at an existing binary: NGINX_BIN=/path/to/nginx",
+    );
+    process.exit(1);
+  }
+
+  if (isIngressRunning(workspaceDir)) {
+    console.log("nginx ingress is already running.");
+    await status(target);
+    return;
+  }
+
+  const webDistDir = findWebDistDir();
+  if (!webDistDir) {
+    console.error(
+      "Error: unable to locate built web assets for remote web ingress.",
+    );
+    console.error("");
+    console.error("Build the SPA first:");
+    console.error("  cd apps/web && VITE_PLATFORM_MODE=false bun run build");
+    console.error("");
+    console.error(
+      "Or install @vellumai/web so its packaged dist directory is available.",
+    );
+    process.exit(1);
+  }
+
+  console.log(`Using ${version}`);
+  console.log(
+    `Starting nginx ingress on 127.0.0.1:${listenPort} → web ${webDistDir} + gateway 127.0.0.1:${gatewayPort}...`,
+  );
+
+  const child = startIngressNginx({
+    workspaceDir,
+    gatewayPort,
+    listenPort,
+    remoteWebIngress: { webDistDir },
+  });
+  child.unref();
+
+  // /healthz proxies through nginx to the gateway, so a 200 proves the whole
+  // ingress → gateway path works.
+  const ready = await waitForDaemonReady(listenPort, READY_TIMEOUT_MS);
+  if (!ready) {
+    const { logPath } = getIngressPaths(workspaceDir);
+    await stopIngressNginx(workspaceDir);
+    console.error(
+      `Error: nginx ingress did not become reachable on 127.0.0.1:${listenPort}.`,
+    );
+    console.error(`Check the nginx log: ${logPath}`);
+    process.exit(1);
+  }
+
+  console.log("");
+  console.log(`nginx ingress running: http://127.0.0.1:${listenPort}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(
+    "  vellum tunnel --provider ngrok   # tunnel now targets nginx ingress",
+  );
+  console.log("  vellum nginx-ingress down        # stop the proxy");
+}
+
+async function down(target: NginxIngressTarget): Promise<void> {
+  const stopped = await stopIngressNginx(target.workspaceDir);
+  if (!stopped && isIngressRunning(target.workspaceDir)) {
+    console.error("Error: nginx ingress is still running; could not stop it.");
+    process.exit(1);
+  }
+  console.log(
+    stopped ? "nginx ingress stopped." : "nginx ingress is not running.",
+  );
+}
+
+async function status(target: NginxIngressTarget): Promise<void> {
+  const { workspaceDir, gatewayPort } = target;
+  const { confPath, logPath } = getIngressPaths(workspaceDir);
+  const pid = getIngressPid(workspaceDir);
+  if (pid === null) {
+    console.log("nginx ingress: not running");
+    return;
+  }
+  const { port } = resolveTunnelTargetPort(workspaceDir, gatewayPort);
+  console.log("nginx ingress: running");
+  console.log(`  PID:     ${pid}`);
+  console.log(`  Listen:  http://127.0.0.1:${port}`);
+  console.log(`  Gateway: http://127.0.0.1:${gatewayPort}`);
+  console.log(`  Config:  ${confPath}`);
+  console.log(`  Log:     ${logPath}`);
+}
+
+export async function nginxIngress(): Promise<void> {
+  const args = process.argv.slice(3);
+  const sub = args[0];
+
+  if (!sub || sub === "--help" || sub === "-h") {
+    printHelp();
+    process.exit(sub ? 0 : 1);
+  }
+
+  // Joins all remaining positionals so unquoted multi-word display names
+  // resolve as one identifier (cli/AGENTS.md "Assistant targeting convention").
+  const assistantName = parseAssistantTargetArg(args.slice(1));
+  const target = resolveNginxIngressTarget(assistantName ?? null);
+
+  if (sub === "up") return up(target);
+  if (sub === "down") return down(target);
+  if (sub === "status") return status(target);
+
+  console.error(`Error: Unknown subcommand '${sub}'.`);
+  console.error("Run 'vellum nginx-ingress --help' for usage.");
+  process.exit(1);
+}

package/src/commands/rollback.ts

@@ -2,7 +2,6 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
-  normalizeVersion,
   resolveCloud,
   saveAssistantEntry,
   type AssistantEntry,
@@ -403,11 +402,6 @@ export async function rollback(): Promise<void> {
           networkName: res.network,
         },
         previousContainerInfo: entry.containerInfo,
-        // Cleared (not preserved) when the rolled-back-to version is unknown
-        version:
-          previousVersion !== "unknown"
-            ? normalizeVersion(previousVersion)
-            : undefined,
         // Clear the backup path — it belonged to the upgrade we just rolled back
         preUpgradeBackupPath: undefined,
         previousDbMigrationVersion: undefined,

package/src/commands/sleep.ts

@@ -7,6 +7,7 @@ import {
 } from "../lib/assistant-config.js";
 import type { AssistantEntry } from "../lib/assistant-config.js";
 import { dockerResourceNames, sleepContainers } from "../lib/docker.js";
+import { stopIngressNginx } from "../lib/nginx-ingress.js";
 import { isProcessAlive, stopProcessByPidFile } from "../lib/process";
 
 const ACTIVE_CALL_LEASES_FILE = "active-call-leases.json";
@@ -134,9 +135,18 @@ export async function sleep(): Promise<void> {
     }
   }
 
+  // Stop assistant — use a generous timeout. On SIGTERM the daemon runs a
+  // WAL checkpoint before exiting, which can take several seconds on a
+  // multi-GB database. The default 2s grace in stopProcess() would SIGKILL a
+  // healthy daemon mid-checkpoint, forcing a costly multi-minute WAL recovery
+  // on the next start. The timeout is only a SIGKILL ceiling — stopProcess
+  // returns as soon as the process exits, so this adds no delay in the common
+  // case and only applies when the daemon is genuinely wedged.
   const assistantStopped = await stopProcessByPidFile(
     assistantPidFile,
     "assistant",
+    undefined,
+    120_000,
   );
   if (!assistantStopped) {
     console.log("Assistant is not running.");
@@ -157,4 +167,11 @@ export async function sleep(): Promise<void> {
   } else {
     console.log("Gateway stopped.");
   }
+
+  // Stop the nginx ingress if one is fronting this gateway — otherwise it
+  // keeps running against a dead upstream and serves 502s.
+  const ingressStopped = await stopIngressNginx(join(vellumDir, "workspace"));
+  if (ingressStopped) {
+    console.log("nginx ingress stopped.");
+  }
 }

package/src/commands/teleport.ts

@@ -391,9 +391,8 @@ async function exportFromAssistant(
     // daemon, the CLI is updated separately).
     let sourceRuntimeVersion: string;
     try {
-      const identity = await callRuntimeWithAuthRetry(
-        entry,
-        async (token) => localRuntimeIdentity(entry, token),
+      const identity = await callRuntimeWithAuthRetry(entry, async (token) =>
+        localRuntimeIdentity(entry, token),
       );
       sourceRuntimeVersion = identity.version;
     } catch (err) {
@@ -427,16 +426,13 @@ async function exportFromAssistant(
     let jobId: string;
     let accessToken: string;
     try {
-      const result = await callRuntimeWithAuthRetry(
-        entry,
-        async (token) => {
-          const r = await localRuntimeExportToGcs(entry, token, {
-            uploadUrl,
-            description: "teleport export",
-          });
-          return { jobId: r.jobId, token };
-        },
-      );
+      const result = await callRuntimeWithAuthRetry(entry, async (token) => {
+        const r = await localRuntimeExportToGcs(entry, token, {
+          uploadUrl,
+          description: "teleport export",
+        });
+        return { jobId: r.jobId, token };
+      });
       jobId = result.jobId;
       accessToken = result.token;
     } catch (err) {
@@ -734,9 +730,8 @@ async function importToAssistant(
     // target can't actually load) whenever the two drift apart.
     let targetRuntimeVersion: string;
     try {
-      const identity = await callRuntimeWithAuthRetry(
-        entry,
-        (token) => localRuntimeIdentity(entry, token),
+      const identity = await callRuntimeWithAuthRetry(entry, (token) =>
+        localRuntimeIdentity(entry, token),
       );
       targetRuntimeVersion = identity.version;
     } catch (err) {
@@ -779,15 +774,12 @@ async function importToAssistant(
     let jobId: string;
     let accessToken: string;
     try {
-      const result = await callRuntimeWithAuthRetry(
-        entry,
-        async (token) => {
-          const r = await localRuntimeImportFromGcs(entry, token, {
-            bundleUrl,
-          });
-          return { jobId: r.jobId, token };
-        },
-      );
+      const result = await callRuntimeWithAuthRetry(entry, async (token) => {
+        const r = await localRuntimeImportFromGcs(entry, token, {
+          bundleUrl,
+        });
+        return { jobId: r.jobId, token };
+      });
       jobId = result.jobId;
       accessToken = result.token;
     } catch (err) {
@@ -910,17 +902,12 @@ export async function resolveOrHatchTarget(
 
   if (targetEnv === "docker") {
     const beforeIds = new Set(loadAllAssistants().map((e) => e.assistantId));
-    await hatchDocker(
-      "vellum",
-      false,
-      targetName ?? null,
-      false,
-      {},
-      {},
-      {
-        setupProviderCredentials: false,
-      },
-    );
+    await hatchDocker({
+      species: "vellum",
+      detached: false,
+      name: targetName ?? null,
+      setupProviderCredentials: false,
+    });
     const entry = targetName
       ? findAssistantByName(targetName)
       : (loadAllAssistants().find((e) => !beforeIds.has(e.assistantId)) ??

package/src/commands/tunnel.ts

@@ -1,7 +1,12 @@
 import { join } from "path";
 
-import { resolveAssistant } from "../lib/assistant-config";
+import { resolveAssistant, type AssistantEntry } from "../lib/assistant-config";
 import { runCloudflareTunnel } from "../lib/cloudflare-tunnel.js";
+import { GATEWAY_PORT } from "../lib/constants.js";
+import {
+  isAssistantFeatureFlagEnabled,
+  WEB_REMOTE_INGRESS_FLAG,
+} from "../lib/feature-flags.js";
 import { runNgrokTunnel } from "../lib/ngrok";
 
 const VALID_PROVIDERS = ["vellum", "ngrok", "cloudflare", "tailscale"] as const;
@@ -88,6 +93,46 @@ function parseArgs(): TunnelArgs {
   return { assistantName, provider };
 }
 
+function parsePortFromUrl(url: unknown): number | undefined {
+  if (typeof url !== "string" || !url.trim()) return undefined;
+  try {
+    const port = Number(new URL(url).port);
+    return Number.isInteger(port) && port > 0 && port <= 65535
+      ? port
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveEntryGatewayPort(entry: AssistantEntry): number {
+  return (
+    entry.resources?.gatewayPort ??
+    parsePortFromUrl(entry.localUrl) ??
+    parsePortFromUrl(entry.runtimeUrl) ??
+    GATEWAY_PORT
+  );
+}
+
+async function shouldPreferNginxIngress(
+  assistantId: string,
+  gatewayPort: number,
+): Promise<boolean> {
+  try {
+    return await isAssistantFeatureFlagEnabled(
+      assistantId,
+      WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl: `http://127.0.0.1:${gatewayPort}` },
+    );
+  } catch (err) {
+    throw new Error(
+      `Could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` feature flag before starting the tunnel. Is the assistant running? Try \`vellum wake\` and retry. ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+}
+
 export async function tunnel(): Promise<void> {
   const { assistantName, provider } = parseArgs();
 
@@ -104,21 +149,34 @@ export async function tunnel(): Promise<void> {
     process.exit(1);
   }
 
+  const resources = entry.resources;
+  const gatewayPort = resolveEntryGatewayPort(entry);
+  const baseTunnelOpts = {
+    port: gatewayPort,
+    ...(resources
+      ? { workspaceDir: join(resources.instanceDir, ".vellum", "workspace") }
+      : {}),
+  };
+
   if (provider === "ngrok") {
-    await runNgrokTunnel();
+    await runNgrokTunnel({
+      ...baseTunnelOpts,
+      preferNginxIngress: await shouldPreferNginxIngress(
+        entry.assistantId,
+        gatewayPort,
+      ),
+    });
     return;
   }
 
   if (provider === "cloudflare") {
-    const resources = entry.resources;
-    await runCloudflareTunnel(
-      resources
-        ? {
-            port: resources.gatewayPort,
-            workspaceDir: join(resources.instanceDir, ".vellum", "workspace"),
-          }
-        : {},
-    );
+    await runCloudflareTunnel({
+      ...baseTunnelOpts,
+      preferNginxIngress: await shouldPreferNginxIngress(
+        entry.assistantId,
+        gatewayPort,
+      ),
+    });
     return;
   }
 

package/src/commands/upgrade.ts

@@ -6,7 +6,6 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
-  normalizeVersion,
   resolveCloud,
   saveAssistantEntry,
   type AssistantEntry,
@@ -496,7 +495,6 @@ async function upgradeDocker(
       previousContainerInfo: entry.containerInfo,
       previousDbMigrationVersion: preMigrationState.dbVersion,
       previousWorkspaceMigrationId: preMigrationState.lastWorkspaceMigrationId,
-      version: normalizeVersion(versionTag),
       // Preserve the backup path so `vellum rollback` can restore it later
       preUpgradeBackupPath: backupPath ?? undefined,
     };

package/src/commands/wake.ts

@@ -9,7 +9,6 @@ import {
 import { dockerResourceNames, wakeContainers } from "../lib/docker.js";
 import {
   leaseGuardianToken,
-  loadGuardianToken,
   resetGuardianBootstrap,
   seedGuardianTokenFromSiblingEnv,
 } from "../lib/guardian-token.js";
@@ -43,7 +42,7 @@ export async function wake(): Promise<void> {
       "  --foreground   Run assistant in foreground with logs printed to terminal",
     );
     console.log(
-      "  --repair-guardian  Re-provision the guardian token if missing (resets the\n" +
+      "  --repair-guardian  Force-re-provision the guardian token (resets the\n" +
         "                     gateway bootstrap and re-leases — REVOKES other device-bound\n" +
         "                     tokens, so only use deliberately, never from auto-repair)",
     );
@@ -238,8 +237,11 @@ export async function wake(): Promise<void> {
     console.log("   Seeded guardian token from sibling environment.");
   }
 
-  // Last-resort recovery (explicit `--repair-guardian` only): if no guardian
-  // token exists for this env even after sibling seeding, re-provision one. The
+  // Last-resort recovery (explicit `--repair-guardian` only): force a
+  // re-provision. Token health can't be judged locally — a connect can 401
+  // off a token whose local expiry looks fine (revoked, mis-seeded, wrong
+  // principal) — and the user explicitly confirmed the destructive repair,
+  // so guessing "looks healthy, skip" just recreates the no-op loop. The
   // single-use bootstrap secret may already be spent — a prior connect can
   // lease a token that's then lost, or the gateway marks the secret consumed
   // before the client persists it — which otherwise bricks connect into a
@@ -248,7 +250,7 @@ export async function wake(): Promise<void> {
   // by the lockfile secret — mirrors the macOS client's forceReBootstrap), then
   // re-lease. Gated behind the flag because the re-lease revokes other
   // device-bound tokens; it must never run from the automatic repair path.
-  if (repairGuardian && !loadGuardianToken(entry.assistantId)) {
+  if (repairGuardian) {
     const loopbackUrl = `http://127.0.0.1:${resources.gatewayPort}`;
     const maxAttempts = 3;
     for (let attempt = 1; attempt <= maxAttempts; attempt++) {