@vellumai/cli 0.10.0 → 0.10.1-dev.202606240206.7c2bca6

package/src/commands/client.ts

@@ -54,9 +54,12 @@ import {
   getPlatformUrl,
   getWebUrl,
   readPlatformToken,
+  savePlatformToken,
+  clearPlatformToken,
 } from "../lib/platform-client";
 import { tuiLog } from "../lib/tui-log";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
+import { probePort } from "../lib/port-probe.js";
 
 const SUPPORTED_INTERFACES = ["cli", "web"] as const;
 type SupportedInterface = (typeof SUPPORTED_INTERFACES)[number];
@@ -101,8 +104,10 @@ export function parseArgs(): ParsedArgs {
   const { envVars: cliFlagVars, remaining: argsWithoutFlags } =
     parseFeatureFlagArgs(process.argv.slice(3));
   const flagEnvVars = { ...readAmbientFlagEnvVars(), ...cliFlagVars };
-  const disablePlatformAmbient = process.env.VELLUM_DISABLE_PLATFORM?.trim().toLowerCase();
-  let disablePlatform = disablePlatformAmbient === "true" || disablePlatformAmbient === "1";
+  const disablePlatformAmbient =
+    process.env.VELLUM_DISABLE_PLATFORM?.trim().toLowerCase();
+  let disablePlatform =
+    disablePlatformAmbient === "true" || disablePlatformAmbient === "1";
   const args = argsWithoutFlags;
 
   // Build parsedFlagOverrides from the extracted env vars:
@@ -389,6 +394,31 @@ const HATCH_PATTERN = /^(?:\/assistant)?\/__local\/hatch$/;
 const RETIRE_PATTERN = /^(?:\/assistant)?\/__local\/retire$/;
 const GUARDIAN_TOKEN_PATTERN =
   /^(?:\/assistant)?\/__local\/guardian-token\/([^/]+)$/;
+const PLATFORM_SESSION_PATTERN =
+  /^(?:\/assistant)?\/__local\/platform-session$/;
+
+// The loopback platform session token. Persisted via the same store the CLI
+// uses (so `vellum client` restarts and CLI logins stay in sync), cached here
+// to keep it off the per-request proxy path. Set only after the SPA validates
+// the loopback `state`, so an unsolicited /callback can't fixate a session.
+let platformSessionToken: string | null | undefined;
+function currentPlatformToken(): string | null {
+  if (platformSessionToken === undefined) {
+    platformSessionToken = readPlatformToken();
+  }
+  return platformSessionToken;
+}
+
+// Whether to attach the platform credential to a proxied request. Only
+// same-origin (SPA) traffic qualifies — a cross-site page must not be able to
+// use the local proxy as a confused deputy for authenticated platform calls.
+// Cross-origin fetches always send an Origin; `Sec-Fetch-Site` is a belt-and-
+// braces check for browsers that send it.
+function isSameOriginRequest(req: Request): boolean {
+  if (!originIsAllowed(req.headers.get("origin") ?? undefined)) return false;
+  const site = req.headers.get("sec-fetch-site");
+  return !site || site === "same-origin" || site === "none";
+}
 
 function getEnvRecord(): Record<string, string> {
   const result: Record<string, string> = {};
@@ -418,6 +448,7 @@ async function handleLocalEndpoints(
     HATCH_PATTERN.test(pathname) ||
     RETIRE_PATTERN.test(pathname) ||
     GUARDIAN_TOKEN_PATTERN.test(pathname) ||
+    PLATFORM_SESSION_PATTERN.test(pathname) ||
     parseGatewayUrl(pathname).match;
 
   if (!isLocalRoute) return null;
@@ -435,6 +466,33 @@ async function handleLocalEndpoints(
     return Response.json({ error: "Forbidden" }, { status: 403 });
   }
 
+  // Platform session: the SPA hands over the loopback token here (after it has
+  // validated the `state` nonce) so the proxy below can authenticate to the
+  // platform. The browser never holds a session cookie.
+  if (PLATFORM_SESSION_PATTERN.test(pathname)) {
+    if (req.method === "DELETE") {
+      clearPlatformToken();
+      platformSessionToken = null;
+      return Response.json({ ok: true });
+    }
+    if (req.method === "POST") {
+      const body = (await req.json().catch(() => null)) as {
+        token?: unknown;
+      } | null;
+      const token = body?.token;
+      if (typeof token !== "string" || !/^[A-Za-z0-9]+$/.test(token)) {
+        return Response.json(
+          { ok: false, error: "Invalid token" },
+          { status: 400 },
+        );
+      }
+      savePlatformToken(token);
+      platformSessionToken = token;
+      return Response.json({ ok: true });
+    }
+    return new Response(null, { status: 405 });
+  }
+
   // Lockfile
   if (LOCKFILE_PATTERN.test(pathname)) {
     if (req.method === "GET") {
@@ -658,6 +716,106 @@ function getBaseDir(): string {
   return path.resolve(import.meta.dir, "..", "..", "..");
 }
 
+// Just the slice of a Bun server `fetchHandler` needs — matches the structural
+// arg `handleLocalEndpoints` accepts, so Bun's `Server` is assignable to it.
+type RequestPeerServer = {
+  requestIP(req: Request): { address: string } | null;
+};
+
+const WEB_PORT_SCAN_LIMIT = 50;
+
+type WebFetchHandler = (
+  req: Request,
+  server: RequestPeerServer,
+) => Promise<Response>;
+
+function isAddrInUse(err: unknown): boolean {
+  const e = err as { code?: string; message?: string } | undefined;
+  return (
+    e?.code === "EADDRINUSE" ||
+    /EADDRINUSE|address already in use/i.test(e?.message ?? "")
+  );
+}
+
+// Bind one loopback family; returns the server, or null when the port is in
+// use. Server type is inferred from `Bun.serve` (avoids a generic mismatch).
+function tryBindLoopback(
+  port: number,
+  hostname: string,
+  fetchHandler: WebFetchHandler,
+) {
+  try {
+    return Bun.serve({ port, hostname, fetch: fetchHandler });
+  } catch (err) {
+    if (isAddrInUse(err)) return null;
+    throw err;
+  }
+}
+
+/**
+ * Bind the local web server on BOTH loopback families (`127.0.0.1` and `::1`)
+ * so the app can be reached at `http://localhost:<port>` regardless of whether
+ * the browser resolves `localhost` to IPv4 or IPv6 — matching the host the
+ * platform hardcodes in its loopback login callback.
+ *
+ * IPv4 is mandatory. IPv6 is best-effort: if `::1` is already taken (e.g. the
+ * local platform's `vel up` edge-proxy owns `[::]:<port>`), the port is
+ * contested and we advance — otherwise `localhost` would resolve to that other
+ * server. If IPv6 is simply unavailable on the host, we proceed IPv4-only.
+ *
+ * Never binds wildcard interfaces (`0.0.0.0`/`::`): the server exposes
+ * `/__local/*` control endpoints, so it must stay loopback-only.
+ */
+function serveLoopback(preferredPort: number, fetchHandler: WebFetchHandler) {
+  for (
+    let port = preferredPort;
+    port < preferredPort + WEB_PORT_SCAN_LIMIT;
+    port++
+  ) {
+    const primary = tryBindLoopback(port, "127.0.0.1", fetchHandler);
+    if (!primary) continue;
+
+    try {
+      const secondary = Bun.serve({
+        port,
+        hostname: "::1",
+        fetch: fetchHandler,
+      });
+      return { port, servers: [primary, secondary] };
+    } catch (err) {
+      if (isAddrInUse(err)) {
+        // `::1` is contested (e.g. `vel up`) — move ports so `localhost`
+        // doesn't resolve to that other server.
+        primary.stop(true);
+        continue;
+      }
+      // IPv6 unavailable (e.g. EADDRNOTAVAIL) — IPv4-only is acceptable since
+      // `localhost` then resolves to 127.0.0.1 anyway.
+      return { port, servers: [primary] };
+    }
+  }
+  throw new Error(
+    `Could not bind a free loopback port in [${preferredPort}, ${preferredPort + WEB_PORT_SCAN_LIMIT - 1}]`,
+  );
+}
+
+/**
+ * Find the first port at/above `preferred` with nothing listening on either
+ * loopback family. Used for the Vite dev server, which binds the port itself
+ * (via the `PORT` env). Connect-probe based, so there's a small TOCTOU window
+ * before Vite binds — acceptable for dev.
+ */
+async function findFreeDualLoopbackPort(preferred: number): Promise<number> {
+  for (let port = preferred; port < preferred + WEB_PORT_SCAN_LIMIT; port++) {
+    const [busyV4, busyV6] = await Promise.all([
+      probePort(port, "127.0.0.1"),
+      probePort(port, "::1"),
+    ]);
+    if (!busyV4 && !busyV6) return port;
+  }
+  return preferred;
+}
+
 async function runWebInterface(
   flagEnvVars: Record<string, string>,
   parsedFlagOverrides: Record<string, boolean | string>,
@@ -699,120 +857,131 @@ async function runWebInterface(
     `<script>window.__VELLUM_CONFIG__=${configJson}${flagOverridesSnippet}</script></head>`,
   );
 
-  const server = Bun.serve({
-    port: 3000,
-    hostname: "127.0.0.1",
-    fetch: async (req) => {
-      const url = new URL(req.url);
-      const { pathname } = url;
+  const fetchHandler: WebFetchHandler = async (req, server) => {
+    const url = new URL(req.url);
+    const { pathname } = url;
 
-      if (pathname === "/" || pathname === "/assistant") {
-        return Response.redirect(SPA_BASE, 302);
-      }
+    if (pathname === "/" || pathname === "/assistant") {
+      return Response.redirect(SPA_BASE, 302);
+    }
 
-      // Loopback auth: the platform redirects here after login with
-      // ?state=...&session_token=... — forward into the SPA.
-      if (pathname === "/callback") {
-        return Response.redirect(
-          `/account/platform-callback${url.search}`,
-          302,
-        );
-      }
+    // Loopback auth: the platform redirects here after login with
+    // ?state=...&session_token=... — forward into the SPA, which validates the
+    // `state` nonce before registering the token via /__local/platform-session.
+    if (pathname === "/callback") {
+      return Response.redirect(`/account/platform-callback${url.search}`, 302);
+    }
 
-      // Expose environment config to the SPA.
-      if (pathname === "/assistant/__config" || pathname === "/__config") {
-        return new Response(configJson, {
-          headers: { "Content-Type": "application/json" },
-        });
-      }
+    // Expose environment config to the SPA.
+    if (pathname === "/assistant/__config" || pathname === "/__config") {
+      return new Response(configJson, {
+        headers: { "Content-Type": "application/json" },
+      });
+    }
 
-      // __local endpoints for local-mode (lockfile, hatch, retire, guardian-token, gateway-proxy).
-      const localResponse = await handleLocalEndpoints(req, url, server);
-      if (localResponse) return localResponse;
-
-      // Reverse-proxy platform API requests.
-      if (
-        pathname.startsWith("/v1/") ||
-        pathname.startsWith("/_allauth/") ||
-        pathname.startsWith("/accounts/")
-      ) {
-        const target = new URL(pathname + url.search, platformUrl);
-        const headers = new Headers(req.headers);
-        headers.set("Host", new URL(platformUrl).host);
-        headers.delete("Origin");
-        headers.delete("Referer");
-
-        // Forward the session token — the loopback flow stores it in
-        // the browser cookie jar for localhost, but the platform backend
-        // expects it on its own domain. Set both the Cookie (for Django
-        // session middleware / allauth) and X-Session-Token (for DRF
-        // views that accept header-based auth).
-        const sessionToken = /sessionid=([^;]+)/.exec(
-          req.headers.get("Cookie") ?? "",
-        )?.[1];
+    // __local endpoints for local-mode (lockfile, hatch, retire, guardian-token, gateway-proxy).
+    const localResponse = await handleLocalEndpoints(req, url, server);
+    if (localResponse) return localResponse;
+
+    // Reverse-proxy platform API requests.
+    if (
+      pathname.startsWith("/v1/") ||
+      pathname.startsWith("/_allauth/") ||
+      pathname.startsWith("/accounts/")
+    ) {
+      const target = new URL(pathname + url.search, platformUrl);
+      const headers = new Headers(req.headers);
+      headers.set("Host", new URL(platformUrl).host);
+      headers.delete("Origin");
+      headers.delete("Referer");
+
+      // The DRF API authenticates by header (X-Session-Token); the allauth /
+      // accounts session endpoints need the Django session cookie.
+      const isApiRequest = pathname.startsWith("/v1/");
+
+      // Authenticate with the loopback session token the SPA registered. Only
+      // same-origin SPA traffic gets the credential — never a cross-site caller.
+      const sessionToken = isSameOriginRequest(req)
+        ? currentPlatformToken()
+        : null;
+      if (isApiRequest) {
+        // Header-only auth for the DRF API. Sending a `sessionid` cookie would
+        // engage Django's SessionAuthentication, which enforces CSRF — and the
+        // proxy strips Origin/Referer above, so the CSRF Referer check would
+        // reject every unsafe (POST/PUT/PATCH) request. Drop any browser cookie
+        // (localhost jar) so it can't re-engage that path.
+        headers.delete("Cookie");
         if (sessionToken) {
-          headers.set(
-            "Cookie",
-            `sessionid=${sessionToken}; __Secure-sessionid=${sessionToken}`,
-          );
           headers.set("X-Session-Token", sessionToken);
         }
-
-        try {
-          const hasBody = req.method !== "GET" && req.method !== "HEAD";
-          const body = hasBody ? await req.arrayBuffer() : undefined;
-          const proxyRes = await loopbackSafeFetch(target.toString(), {
-            method: req.method,
-            headers,
-            body,
-            redirect: "manual",
-          });
-          const resHeaders = new Headers(proxyRes.headers);
-          resHeaders.delete("transfer-encoding");
-          return new Response(proxyRes.body, {
-            status: proxyRes.status,
-            statusText: proxyRes.statusText,
-            headers: resHeaders,
-          });
-        } catch (err) {
-          return new Response(
-            JSON.stringify({ error: `Platform proxy error: ${err}` }),
-            { status: 502, headers: { "Content-Type": "application/json" } },
-          );
-        }
+      } else if (sessionToken) {
+        // allauth / accounts: the platform expects the Django session cookie.
+        headers.set(
+          "Cookie",
+          `sessionid=${sessionToken}; __Secure-sessionid=${sessionToken}`,
+        );
+        headers.set("X-Session-Token", sessionToken);
       }
 
-      if (pathname.startsWith(SPA_BASE)) {
-        const relPath = pathname.slice(SPA_BASE.length);
-        if (relPath) {
-          const filePath = path.join(distDir, relPath);
-          const file = Bun.file(filePath);
-          if (await file.exists()) {
-            return new Response(file);
-          }
-        }
-        return new Response(indexHtml, {
-          headers: { "Content-Type": "text/html; charset=utf-8" },
+      try {
+        const hasBody = req.method !== "GET" && req.method !== "HEAD";
+        const body = hasBody ? await req.arrayBuffer() : undefined;
+        const proxyRes = await loopbackSafeFetch(target.toString(), {
+          method: req.method,
+          headers,
+          body,
+          redirect: "manual",
         });
+        const resHeaders = new Headers(proxyRes.headers);
+        resHeaders.delete("transfer-encoding");
+        return new Response(proxyRes.body, {
+          status: proxyRes.status,
+          statusText: proxyRes.statusText,
+          headers: resHeaders,
+        });
+      } catch (err) {
+        return new Response(
+          JSON.stringify({ error: `Platform proxy error: ${err}` }),
+          { status: 502, headers: { "Content-Type": "application/json" } },
+        );
       }
+    }
 
-      // SPA fallback for /account/* routes (login, callback, etc.)
-      if (pathname.startsWith("/account/")) {
-        return new Response(indexHtml, {
-          headers: { "Content-Type": "text/html; charset=utf-8" },
-        });
+    if (pathname.startsWith(SPA_BASE)) {
+      const relPath = pathname.slice(SPA_BASE.length);
+      if (relPath) {
+        const filePath = path.join(distDir, relPath);
+        const file = Bun.file(filePath);
+        if (await file.exists()) {
+          return new Response(file);
+        }
       }
+      return new Response(indexHtml, {
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
 
-      return new Response("Not Found", { status: 404 });
-    },
-  });
+    // SPA fallback for /account/* routes (login, callback, etc.)
+    if (pathname.startsWith("/account/")) {
+      return new Response(indexHtml, {
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
 
-  console.log(
-    `Vellum web interface: http://${server.hostname}:${server.port}${SPA_BASE}`,
-  );
+    return new Response("Not Found", { status: 404 });
+  };
+
+  const { port, servers } = serveLoopback(3000, fetchHandler);
+  if (port !== 3000) {
+    console.log(`Port 3000 in use; using ${port}.`);
+  }
+  // Advertise `localhost` (not `127.0.0.1`) so the app origin matches the host
+  // the platform hardcodes in its loopback callback. We bind both loopback
+  // families above so `localhost` reaches us whichever one it resolves to.
+  console.log(`Vellum web interface: http://localhost:${port}${SPA_BASE}`);
 
   const shutdown = (): void => {
-    server.stop();
+    for (const server of servers) server.stop();
     process.exit(0);
   };
   process.on("SIGINT", shutdown);
@@ -834,6 +1003,14 @@ async function runViteDevServer(
     viteFlagVars[`VITE_${envName}`] = value;
   }
 
+  // Auto-pick a free port (Vite uses strictPort) so a running `vel up` stack
+  // on :3000 doesn't wedge dev. The loopback callback port follows
+  // window.location.port, so a non-3000 port propagates automatically.
+  const port = await findFreeDualLoopbackPort(3000);
+  if (port !== 3000) {
+    console.log(`Port 3000 in use; using ${port}.`);
+  }
+
   const child = spawn("bun", ["run", "dev"], {
     cwd: webSourceDir,
     stdio: "inherit",
@@ -846,7 +1023,7 @@ async function runViteDevServer(
       API_PROXY_TARGET: platformUrl,
       VELLUM_WEB_URL: getWebUrl(),
       VELLUM_PLATFORM_URL: platformUrl,
-      PORT: "3000",
+      PORT: String(port),
     },
   });
 

package/src/commands/exec.ts

@@ -1,6 +1,6 @@
 import { spawn } from "child_process";
 
-import { resolveAssistant, resolveCloud } from "../lib/assistant-config";
+import { resolveAssistant } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
 import type { ServiceName } from "../lib/docker";
 import { execAppleContainer } from "../lib/exec-apple-container";
@@ -153,7 +153,7 @@ export async function exec(): Promise<void> {
     process.exit(1);
   }
 
-  const cloud = resolveCloud(entry);
+  const cloud = entry.cloud;
 
   if (cloud === "local") {
     const child = spawn(command[0], command.slice(1), { stdio: "inherit" });

package/src/commands/flags.ts

@@ -92,7 +92,7 @@ function printHelp(): void {
     "  $ vellum flags                                              # list flags for active assistant",
   );
   console.log(
-    "  $ vellum flags get query-complexity-routing                  # inspect one flag",
+    "  $ vellum flags get voice-mode                                 # inspect one flag",
   );
   console.log(
     "  $ vellum flags set voice-mode true                           # enable a flag",

package/src/commands/logs.ts

@@ -7,7 +7,6 @@ import { join } from "path";
 import {
   extractHostFromUrl,
   resolveAssistant,
-  resolveCloud,
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
@@ -589,7 +588,7 @@ export async function logs(): Promise<void> {
     process.exit(1);
   }
 
-  const cloud = resolveCloud(entry);
+  const cloud = entry.cloud;
 
   switch (cloud) {
     case "local":

package/src/commands/ps.ts

@@ -10,7 +10,6 @@ import {
   getDaemonPidPath,
   loadAllAssistants,
   lookupAssistantByIdentifier,
-  resolveCloud,
   type AssistantEntry,
 } from "../lib/assistant-config";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
@@ -381,7 +380,7 @@ async function getDockerProcesses(entry: AssistantEntry): Promise<TableRow[]> {
 }
 
 async function showAssistantProcesses(entry: AssistantEntry): Promise<void> {
-  const cloud = resolveCloud(entry);
+  const cloud = entry.cloud;
 
   console.log(`Processes for ${formatAssistantReference(entry)} (${cloud}):\n`);
 

package/src/commands/retire.ts

@@ -9,7 +9,6 @@ import {
   loadAllAssistants,
   lookupAssistantByIdentifier,
   removeAssistantEntry,
-  resolveCloud,
   type AssistantEntry,
 } from "../lib/assistant-config.js";
 import { parseAssistantTargetArg } from "../lib/assistant-target-args.js";
@@ -249,7 +248,7 @@ async function retireInner(): Promise<void> {
   const entry = lookup.entry;
   const assistantId = entry.assistantId;
   const source = parsed.source;
-  const cloud = resolveCloud(entry);
+  const cloud = entry.cloud;
 
   if (cloud === "paired") {
     // A remote assistant paired from another machine. Retiring tears the

package/src/commands/roadmap.ts

@@ -27,7 +27,7 @@ function printUsage(): void {
   console.log("  $ vellum roadmap get my-feature-slug");
   console.log('  $ vellum roadmap create --title "Add dark mode"');
   console.log(
-    '  $ vellum roadmap update my-feature --status planned --tag integrations',
+    "  $ vellum roadmap update my-feature --status planned --tag integrations",
   );
   console.log("  $ vellum roadmap upvote my-feature-slug");
 }
@@ -59,8 +59,8 @@ function requireSlug(args: string[], command: string): string {
   return slug;
 }
 
-// eslint-disable-next-line no-control-regex
-const ANSI_RE = /[\x00-\x08\x0b-\x1f\x7f]|\x1b(?:\[[0-9;]*[A-Za-z]|\].*?(?:\x07|\x1b\\))/g;
+const ANSI_RE =
+  /[\x00-\x08\x0b-\x1f\x7f]|\x1b(?:\[[0-9;]*[A-Za-z]|\].*?(?:\x07|\x1b\\))/g;
 function sanitize(text: string): string {
   return text.replace(ANSI_RE, "");
 }
@@ -96,10 +96,7 @@ async function apiFetch(
   });
 }
 
-async function handleError(
-  response: Response,
-  action: string,
-): Promise<never> {
+async function handleError(response: Response, action: string): Promise<never> {
   const text = await response.text().catch(() => "");
   console.error(`Failed to ${action} (${response.status}): ${text}`);
   process.exit(1);
@@ -169,9 +166,10 @@ async function roadmapList(args: string[]): Promise<void> {
 
   for (const item of data.items) {
     const upvoted = item.viewer_upvoted ? " (upvoted)" : "";
-    const tags = item.tags.length > 0
-      ? ` [${item.tags.map((t) => sanitize(t.slug)).join(", ")}]`
-      : "";
+    const tags =
+      item.tags.length > 0
+        ? ` [${item.tags.map((t) => sanitize(t.slug)).join(", ")}]`
+        : "";
     console.log(
       `  ${sanitize(item.title)}  ▲${item.upvote_count}${upvoted}  💬${item.comment_count}  ${item.status}${tags}`,
     );

package/src/commands/rollback.ts

@@ -2,7 +2,6 @@ import {
   findAssistantByName,
   getActiveAssistant,
   loadAllAssistants,
-  resolveCloud,
   saveAssistantEntry,
   type AssistantEntry,
 } from "../lib/assistant-config";
@@ -208,7 +207,7 @@ async function rollbackPlatformViaEndpoint(
 export async function rollback(): Promise<void> {
   const { name, version } = parseArgs();
   const entry = resolveTargetAssistant(name);
-  const cloud = resolveCloud(entry);
+  const cloud = entry.cloud;
 
   if (cloud === "apple-container") {
     console.error(

package/src/commands/ssh.ts

@@ -3,7 +3,6 @@ import { spawn } from "child_process";
 import {
   extractHostFromUrl,
   resolveAssistant,
-  resolveCloud,
 } from "../lib/assistant-config";
 import { dockerResourceNames } from "../lib/docker";
 import { getPlatformUrl, readPlatformToken } from "../lib/platform-client";
@@ -47,7 +46,7 @@ export async function ssh(): Promise<void> {
     process.exit(1);
   }
 
-  const cloud = resolveCloud(entry);
+  const cloud = entry.cloud;
 
   if (cloud === "local") {
     console.error(