@vellumai/cli 0.8.12-staging.2 → 0.9.0-staging.1

package/src/commands/login.ts

@@ -1,19 +1,16 @@
-import { createServer } from "http";
 import { spawn } from "child_process";
 import { randomBytes } from "crypto";
+import { createServer } from "http";
+import type { AddressInfo } from "net";
 
 import {
   getActiveAssistant,
-  resolveAssistant,
   loadAllAssistants,
   removeAssistantEntry,
+  resolveAssistant,
   setActiveAssistant,
 } from "../lib/assistant-config";
 import { computeDeviceId } from "../lib/guardian-token";
-import {
-  fetchAssistantIngressUrl,
-  fetchCurrentVersion,
-} from "../lib/upgrade-lifecycle.js";
 import {
   clearPlatformToken,
   ensureSelfHostedLocalRegistration,
@@ -21,7 +18,6 @@ import {
   fetchOrganizationId,
   fetchPlatformAssistants,
   getPlatformUrl,
-  getWebUrl,
   injectCredentialsIntoAssistant,
   readGatewayCredential,
   readPlatformToken,
@@ -29,6 +25,18 @@ import {
   savePlatformToken,
 } from "../lib/platform-client";
 import { syncCloudAssistants } from "../lib/sync-cloud-assistants";
+import {
+  fetchAssistantIngressUrl,
+  fetchCurrentVersion,
+} from "../lib/upgrade-lifecycle.js";
+import {
+  CALLBACK_PATH,
+  buildAuthorizeUrl,
+  exchangeAccessTokenForSession,
+  exchangeCodeWithWorkos,
+  fetchWorkosClientId,
+  generatePkcePair,
+} from "../lib/workos-pkce";
 
 const LOGIN_TIMEOUT_MS = 120_000; // 2 minutes
 
@@ -41,7 +49,11 @@ function escapeHtml(s: string): string {
     .replace(/'/g, "'");
 }
 
-function renderLoginPage(title: string, subtitle: string, success: boolean): string {
+function renderLoginPage(
+  title: string,
+  subtitle: string,
+  success: boolean,
+): string {
   const checkmarkSvg = `<svg class="icon" viewBox="0 0 56 56" fill="none" xmlns="http://www.w3.org/2000/svg">
       <circle cx="28" cy="28" r="28" fill="var(--positive-bg)"/>
       <path class="check" d="M17 28.5L24.5 36L39 21" stroke="var(--positive-fg)" stroke-width="3.5" stroke-linecap="round" stroke-linejoin="round" fill="none"/>
@@ -175,78 +187,131 @@ function openBrowser(url: string): void {
   child.unref();
 }
 
+export interface LoopbackListener {
+  /** The full `http://127.0.0.1:<port>/auth/callback` redirect URI. */
+  redirectUri: string;
+  /** Resolves with the authorization code once the state-matched callback arrives. */
+  waitForCode: Promise<string>;
+  /** Tear down the server, rejecting any pending waiter with `reason`. */
+  close: (reason?: string) => void;
+}
+
 /**
- * Start a local HTTP server, open the browser to the platform login page,
- * and wait for the platform to redirect back with the session token.
+ * Bind an ephemeral 127.0.0.1 listener and wait for the OAuth redirect.
+ * Exported for tests; production callers go through `workosPkceLogin`.
  */
-function browserLogin(webUrl: string): Promise<string> {
-  return new Promise((resolve, reject) => {
-    const state = randomBytes(32).toString("hex");
+export function startLoopbackListener(
+  expectedState: string,
+): Promise<LoopbackListener> {
+  return new Promise((resolveListener, rejectListener) => {
+    let settle: {
+      resolve: (code: string) => void;
+      reject: (err: Error) => void;
+    };
+    const waitForCode = new Promise<string>((resolve, reject) => {
+      settle = { resolve, reject };
+    });
 
     const server = createServer((req, res) => {
-      const url = new URL(req.url ?? "/", `http://localhost`);
-
-      if (url.pathname !== "/callback") {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (
+        url.pathname !== CALLBACK_PATH ||
+        url.searchParams.get("state") !== expectedState
+      ) {
         res.writeHead(404, { "Content-Type": "text/plain" });
         res.end("Not found");
         return;
       }
 
-      const receivedState = url.searchParams.get("state");
-      const sessionToken = url.searchParams.get("session_token");
-
-      if (receivedState !== state) {
+      const error = url.searchParams.get("error");
+      const code = url.searchParams.get("code");
+      if (error || !code) {
         res.writeHead(400, { "Content-Type": "text/html" });
-        res.end(renderLoginPage("Login Failed", "State mismatch. Please try again.", false));
-        cleanup("State mismatch — possible CSRF attack.");
-        return;
-      }
-
-      if (!sessionToken) {
-        res.writeHead(400, { "Content-Type": "text/html" });
-        res.end(renderLoginPage("Login Failed", "No session token received. Please try again.", false));
-        cleanup("No session token received from platform.");
+        res.end(
+          renderLoginPage(
+            "Login Failed",
+            "Please try again from your terminal.",
+            false,
+          ),
+        );
+        server.close();
+        settle.reject(
+          new Error(
+            `Authentication failed: ${error ?? "no authorization code received"}`,
+          ),
+        );
         return;
       }
 
       res.writeHead(200, { "Content-Type": "text/html" });
-      res.end(renderLoginPage("Login Successful", "You can close this window and return to your terminal.", true));
-      cleanup(null, sessionToken);
-    });
-
-    const timeout = setTimeout(() => {
-      cleanup("Login timed out. Please try again.");
-    }, LOGIN_TIMEOUT_MS);
-
-    function cleanup(error: string | null, token?: string): void {
-      clearTimeout(timeout);
+      res.end(
+        renderLoginPage(
+          "Login Successful",
+          "You can close this window and return to your terminal.",
+          true,
+        ),
+      );
       server.close();
-      if (error) {
-        reject(new Error(error));
-      } else if (token) {
-        resolve(token);
-      } else {
-        reject(new Error("Unknown error during login."));
-      }
-    }
+      settle.resolve(code);
+    });
 
-    server.on("error", (err) => cleanup(err.message));
+    server.on("error", rejectListener);
     server.listen(0, "127.0.0.1", () => {
       const addr = server.address();
       if (!addr || typeof addr === "string") {
-        cleanup("Failed to start local server.");
+        rejectListener(new Error("Failed to start local server."));
         return;
       }
+      const { port } = addr as AddressInfo;
+      resolveListener({
+        redirectUri: `http://127.0.0.1:${port}${CALLBACK_PATH}`,
+        waitForCode,
+        close: (reason?: string) => {
+          server.close();
+          settle.reject(new Error(reason ?? "Login cancelled."));
+        },
+      });
+    });
+  });
+}
+
+/** App-held WorkOS PKCE login */
+async function workosPkceLogin(platformUrl: string): Promise<string> {
+  const clientId = await fetchWorkosClientId(platformUrl);
+  const { verifier, challenge } = generatePkcePair();
+  const state = randomBytes(32).toString("hex");
 
-      const port = addr.port;
-      const returnTo = `/accounts/cli/callback?port=${port}&state=${state}`;
-      const loginUrl = `${webUrl}/account/login?returnTo=${encodeURIComponent(returnTo)}`;
+  const listener = await startLoopbackListener(state);
+  const timeout = setTimeout(() => {
+    listener.close("Login timed out. Please try again.");
+  }, LOGIN_TIMEOUT_MS);
 
-      console.log("Opening browser for login...");
-      console.log(`If the browser doesn't open, visit: ${loginUrl}`);
-      openBrowser(loginUrl);
+  try {
+    const authorizeUrl = buildAuthorizeUrl({
+      clientId,
+      redirectUri: listener.redirectUri,
+      challenge,
+      state,
     });
-  });
+
+    console.log("Opening browser for login...");
+    console.log(`If the browser doesn't open, visit: ${authorizeUrl}`);
+    openBrowser(authorizeUrl);
+
+    const code = await listener.waitForCode;
+    const accessToken = await exchangeCodeWithWorkos({
+      clientId,
+      code,
+      verifier,
+    });
+    return await exchangeAccessTokenForSession(
+      platformUrl,
+      clientId,
+      accessToken,
+    );
+  } finally {
+    clearTimeout(timeout);
+  }
 }
 
 export async function login(): Promise<void> {
@@ -306,11 +371,10 @@ export async function login(): Promise<void> {
     }
   }
 
-  // If no --token flag, use browser-based login
+  // If no --token flag, use app-held WorkOS PKCE login.
   if (!token) {
-    const webUrl = getWebUrl();
     try {
-      token = await browserLogin(webUrl);
+      token = await workosPkceLogin(getPlatformUrl());
     } catch (error) {
       console.error(`❌ ${error instanceof Error ? error.message : error}`);
       process.exit(1);

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.");
+  }
 }