@vellumai/cli 0.10.0-dev.202606230105.081b3b9 → 0.10.0-dev.202606230530.bc0f32e

package/node_modules/@vellumai/local-mode/src/__tests__/loopback-auth.test.ts

@@ -69,6 +69,32 @@ describe("isActiveAssistant", () => {
     expect(isActiveAssistant([lockfilePath], "active")).toBe(true);
   });
 
+  test("returns true for the sole assistant when activeAssistant is empty", () => {
+    const dir = makeTempDir();
+    const lockfilePath = path.join(dir, "lockfile.json");
+    fs.writeFileSync(
+      lockfilePath,
+      JSON.stringify({
+        assistants: [{ assistantId: "only" }],
+        activeAssistant: null,
+      }),
+    );
+    expect(isActiveAssistant([lockfilePath], "only")).toBe(true);
+  });
+
+  test("returns true for the sole assistant when activeAssistant is stale", () => {
+    const dir = makeTempDir();
+    const lockfilePath = path.join(dir, "lockfile.json");
+    fs.writeFileSync(
+      lockfilePath,
+      JSON.stringify({
+        assistants: [{ assistantId: "only" }],
+        activeAssistant: "missing",
+      }),
+    );
+    expect(isActiveAssistant([lockfilePath], "only")).toBe(true);
+  });
+
   test("returns false for a non-active assistant", () => {
     const dir = makeTempDir();
     const lockfilePath = path.join(dir, "lockfile.json");

package/node_modules/@vellumai/local-mode/src/lockfile.ts

@@ -94,8 +94,15 @@ export function isActiveAssistant(
 ): boolean {
   for (const candidate of lockfilePaths) {
     try {
-      const data = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<string, unknown>;
-      return data.activeAssistant === assistantId;
+      const data = JSON.parse(fs.readFileSync(candidate, "utf-8")) as Record<
+        string,
+        unknown
+      >;
+      if (data.activeAssistant === assistantId) return true;
+      const assistants = data.assistants;
+      if (!Array.isArray(assistants) || assistants.length !== 1) return false;
+      const [onlyAssistant] = assistants as Array<Record<string, unknown>>;
+      return onlyAssistant?.assistantId === assistantId;
     } catch {
       continue;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.0-dev.202606230105.081b3b9",
+  "version": "0.10.0-dev.202606230530.bc0f32e",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

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,118 @@ 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];
-        if (sessionToken) {
-          headers.set(
-            "Cookie",
-            `sessionid=${sessionToken}; __Secure-sessionid=${sessionToken}`,
-          );
-          headers.set("X-Session-Token", sessionToken);
-        }
+    // __local endpoints for local-mode (lockfile, hatch, retire, guardian-token, gateway-proxy).
+    const localResponse = await handleLocalEndpoints(req, url, server);
+    if (localResponse) return localResponse;
 
-        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" } },
-          );
-        }
+    // 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");
+
+      // Authenticate with the loopback session token the SPA registered. The
+      // platform expects it both as the Django session cookie and as
+      // X-Session-Token (for DRF views that accept header-based auth). Only
+      // same-origin SPA traffic gets the credential — never a cross-site caller.
+      const sessionToken = isSameOriginRequest(req)
+        ? currentPlatformToken()
+        : null;
+      if (sessionToken) {
+        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 +990,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 +1010,7 @@ async function runViteDevServer(
       API_PROXY_TARGET: platformUrl,
       VELLUM_WEB_URL: getWebUrl(),
       VELLUM_PLATFORM_URL: platformUrl,
-      PORT: "3000",
+      PORT: String(port),
     },
   });
 

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",