@vellumai/cli 0.11.2 → 0.11.3-staging.2

package/src/commands/wake.ts

@@ -29,16 +29,7 @@ import {
   startLocalDaemon,
   startGateway,
 } from "../lib/local";
-import { maybeStartNgrokTunnel } from "../lib/ngrok";
-import {
-  isAssistantFeatureFlagEnabled,
-  WEB_REMOTE_INGRESS_FLAG,
-} from "../lib/feature-flags.js";
-import { loadRawConfig } from "../lib/ingress-config.js";
-import {
-  isIngressRunning,
-  startRemoteWebIngress,
-} from "../lib/nginx-ingress.js";
+import { restoreTunnelEdgeAndAutoTunnel } from "../lib/tunnel-edge.js";
 
 export async function wake(): Promise<void> {
   const args = process.argv.slice(3);
@@ -377,9 +368,11 @@ export async function wake(): Promise<void> {
     }
   }
 
-  // Auto-start ngrok if webhook integrations (e.g. Telegram) are configured.
+  // Restore the nginx edge and point the webhook auto-tunnel at it. Non-fatal:
+  // a down edge is a degraded remote-web/webhook path, not a broken assistant.
   const workspaceDir = join(resources.instanceDir, ".vellum", "workspace");
-  const ngrokChild = await maybeStartNgrokTunnel(
+  const ngrokChild = await restoreTunnelEdgeAndAutoTunnel(
+    entry.assistantId,
     resources.gatewayPort,
     workspaceDir,
   );
@@ -388,17 +381,6 @@ export async function wake(): Promise<void> {
     writeFileSync(ngrokPidFile, String(ngrokChild.pid));
   }
 
-  // Restore the nginx web ingress edge when the workspace config still wants
-  // it. A TLS-terminating front (tailscale serve / tunnel) persists across
-  // restarts and keeps proxying to the edge's loopback port, but the edge has
-  // a manual lifecycle — so a routine restart otherwise leaves the self-hosted
-  // remote-web path dead (502 / blank page) until someone runs it back up.
-  await restoreWebIngressIfEnabled(
-    entry.assistantId,
-    resources.gatewayPort,
-    workspaceDir,
-  );
-
   if (daemonMigrationsFailed) {
     console.log(
       "Assistant database migrations FAILED — DB-backed routes will return 503 until the assistant is restarted. Check the daemon logs.",
@@ -424,143 +406,3 @@ export async function wake(): Promise<void> {
     });
   }
 }
-
-/**
- * Retry policy for the flag probe that gates the web-ingress restore. The
- * gateway has typically been up for milliseconds at this point and answers
- * `503 {"status":"starting"}` (or refuses connections) until its startup
- * completes, so a single probe races it. Mutable so tests can shrink the
- * window.
- */
-export const WEB_INGRESS_FLAG_RETRY = {
-  attempts: 15,
-  intervalMs: 2_000,
-};
-
-/**
- * Probe the `web-remote-ingress` flag, riding out the gateway's startup
- * window: transient failures retry on an interval until the attempt budget is
- * spent, then the last error propagates to the caller's warn path.
- */
-async function verifyWebIngressFlagWithRetry(
-  assistantId: string,
-  gatewayPort: number,
-): Promise<boolean> {
-  let lastError: unknown;
-  for (let attempt = 1; attempt <= WEB_INGRESS_FLAG_RETRY.attempts; attempt++) {
-    try {
-      return await isAssistantFeatureFlagEnabled(
-        assistantId,
-        WEB_REMOTE_INGRESS_FLAG,
-        { runtimeUrl: `http://127.0.0.1:${gatewayPort}` },
-      );
-    } catch (err) {
-      lastError = err;
-      if (attempt === 1) {
-        console.log(
-          "   Waiting for the gateway before restoring the web ingress edge...",
-        );
-      }
-      if (attempt < WEB_INGRESS_FLAG_RETRY.attempts) {
-        await new Promise((resolve) =>
-          setTimeout(resolve, WEB_INGRESS_FLAG_RETRY.intervalMs),
-        );
-      }
-    }
-  }
-  throw lastError;
-}
-
-/**
- * Bring the nginx web ingress edge back up after a wake when the workspace
- * config still wants it. Only restores when ingress is explicitly enabled with
- * a saved public URL and the `web-remote-ingress` flag is on — the edge is
- * pointless without the flag, so a disabled flag skips quietly with a hint.
- *
- * Reads the same workspace config the edge serves. Any failure to restore
- * warns with the manual `vellum nginx-ingress up` command and never fails the
- * wake — a down edge is a degraded remote-web path, not a broken assistant.
- */
-async function restoreWebIngressIfEnabled(
-  assistantId: string,
-  gatewayPort: number,
-  workspaceDir: string,
-): Promise<void> {
-  const config = loadRawConfig(workspaceDir);
-  const ingress = config.ingress as
-    | { enabled?: unknown; publicBaseUrl?: unknown }
-    | undefined;
-  const enabled = ingress?.enabled === true;
-  const publicBaseUrl =
-    typeof ingress?.publicBaseUrl === "string"
-      ? ingress.publicBaseUrl.trim()
-      : "";
-  if (!enabled || !publicBaseUrl) {
-    return;
-  }
-
-  // The edge already survived (or was manually brought back) — nothing to do.
-  if (isIngressRunning(workspaceDir)) {
-    return;
-  }
-
-  let flagEnabled: boolean;
-  try {
-    flagEnabled = await verifyWebIngressFlagWithRetry(assistantId, gatewayPort);
-  } catch (err) {
-    console.warn(
-      `   Could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` flag to restore the web ingress edge; leaving it down. Bring it up manually with \`vellum nginx-ingress up\`. ${
-        err instanceof Error ? err.message : String(err)
-      }`,
-    );
-    return;
-  }
-  if (!flagEnabled) {
-    console.log(
-      `   Web ingress edge not restored: the \`${WEB_REMOTE_INGRESS_FLAG}\` flag is off. Enable it and run \`vellum nginx-ingress up\` to serve remote web access.`,
-    );
-    return;
-  }
-
-  try {
-    const result = await startRemoteWebIngress({
-      workspaceDir,
-      gatewayPort,
-      onStarting: ({ listenPort }) => {
-        console.log(
-          `Restoring web ingress edge on 127.0.0.1:${listenPort} (ingress.enabled)...`,
-        );
-      },
-    });
-    switch (result.status) {
-      case "started":
-        console.log(
-          `   Web ingress edge running: http://127.0.0.1:${result.listenPort}`,
-        );
-        break;
-      case "already-running":
-        break;
-      case "nginx-missing":
-        console.warn(
-          "   Could not restore the web ingress edge: nginx is not installed. Bring it up manually with `vellum nginx-ingress up`.",
-        );
-        break;
-      case "web-dist-missing":
-        console.warn(
-          "   Could not restore the web ingress edge: built web assets were not found. Bring it up manually with `vellum nginx-ingress up`.",
-        );
-        break;
-      case "unreachable":
-        console.warn(
-          `   Web ingress edge did not become reachable on 127.0.0.1:${result.listenPort}; check ${result.logPath}. Bring it up manually with \`vellum nginx-ingress up\`.`,
-        );
-        break;
-    }
-  } catch (err) {
-    console.warn(
-      `   Failed to restore the web ingress edge: ${
-        err instanceof Error ? err.message : String(err)
-      }. Bring it up manually with \`vellum nginx-ingress up\`.`,
-    );
-  }
-}

package/src/index.ts

@@ -106,7 +106,7 @@ function printHelp(): void {
   console.log("  gateway  Gateway management commands");
   console.log("  hatch    Create a new assistant instance");
   console.log(
-    "  nginx-ingress  Manage the nginx proxy fronting the gateway for web access [beta]",
+    "  nginx-ingress  Manage the nginx edge that `vellum tunnel` fronts [beta]",
   );
   console.log("  logs     View logs from an assistant instance");
   console.log("  login    Log in to the Vellum platform");

package/src/lib/__tests__/local-ces.test.ts

@@ -9,7 +9,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, mock, test } from "bun:test";
 
-import { startCes } from "../local.js";
+import { resolveCesSocketPath, startCes } from "../local.js";
 
 // ---------------------------------------------------------------------------
 // Mocks
@@ -134,4 +134,13 @@ describe("startCes", () => {
     const cesPidFile = join(vellumDir, "ces.pid");
     expect(existsSync(cesPidFile)).toBe(true);
   }, 15_000);
+  test("uses a Windows named pipe for the local CES seam", () => {
+    const resources = {
+      instanceDir: "C:\\Users\\Example\\Vellum\\assistant-123",
+    } as Parameters<typeof resolveCesSocketPath>[0];
+
+    const socketPath = resolveCesSocketPath(resources, "win32");
+    expect(socketPath.startsWith("\\\\.\\pipe\\vellum-ces-")).toBe(true);
+    expect(socketPath).not.toContain("Example");
+  });
 });

package/src/lib/cloudflare-tunnel.ts

@@ -6,7 +6,6 @@ import {
   getDefaultWorkspaceDir,
   saveIngressUrl,
 } from "./ingress-config.js";
-import { resolveTunnelTargetPort } from "./nginx-ingress.js";
 
 // ── Cloudflare Tunnel ─────────────────────────────────────────────────────────
 
@@ -116,7 +115,7 @@ export function waitForCloudflareTunnelUrl(
 /**
  * Run the cloudflared quick-tunnel workflow:
  * 1. Verify cloudflared is installed.
- * 2. Start a quick tunnel pointing at the gateway port.
+ * 2. Start a quick tunnel pointing at the local edge port.
  * 3. Parse the public URL from cloudflared output.
  * 4. Persist the URL to the workspace config as the ingress base URL.
  * 5. Block until the process exits or the user presses Ctrl+C.
@@ -125,12 +124,10 @@ export function waitForCloudflareTunnelUrl(
  * No Cloudflare account is required — quick tunnels are free and ephemeral.
  */
 export interface RunCloudflareTunnelOptions {
-  /** Gateway port to forward. Defaults to the global GATEWAY_PORT. */
+  /** Local edge port to forward. Defaults to the global GATEWAY_PORT. */
   port?: number;
   /** Workspace directory for config read/write. Defaults to ~/.vellum/workspace. */
   workspaceDir?: string;
-  /** Prefer nginx ingress over the gateway port when it is running. */
-  preferNginxIngress?: boolean;
   /** Lockfile entry to mirror the ingress URL onto (`ingressUrl`). */
   assistantId?: string;
 }
@@ -156,17 +153,7 @@ export async function runCloudflareTunnel(
   console.log(`Using ${version}`);
 
   const workspaceDir = opts.workspaceDir ?? getDefaultWorkspaceDir();
-  const gatewayPort = opts.port ?? GATEWAY_PORT;
-  const { port, viaIngress } = resolveTunnelTargetPort(
-    workspaceDir,
-    gatewayPort,
-    { preferNginxIngress: opts.preferNginxIngress === true },
-  );
-  if (viaIngress) {
-    console.log(
-      `nginx ingress detected — tunneling to it on 127.0.0.1:${port}.`,
-    );
-  }
+  const port = opts.port ?? GATEWAY_PORT;
 
   console.log(`Starting cloudflared quick tunnel to localhost:${port}...`);
   console.log("No Cloudflare account required — quick tunnels are free.");

package/src/lib/environments/__tests__/paths.test.ts

@@ -37,6 +37,7 @@ afterAll(() => {
 // mock.module() calls above.
 const {
   getConfigDir,
+  getConfigDirs,
   getDefaultPorts,
   getLockfilePath,
   getLockfilePaths,
@@ -57,7 +58,7 @@ const dev: EnvironmentDefinition = {
   webUrl: "https://dev-assistant.vellum.ai",
 };
 
-const XDG_ENV_VARS = ["XDG_DATA_HOME", "XDG_CONFIG_HOME"] as const;
+const XDG_ENV_VARS = ["XDG_DATA_HOME", "XDG_CONFIG_HOME", "APPDATA"] as const;
 
 describe("path helpers", () => {
   let savedEnv: Record<string, string | undefined>;
@@ -81,6 +82,24 @@ describe("path helpers", () => {
   });
 
   describe("getConfigDir", () => {
+    test("Windows keeps XDG config as a legacy read location", () => {
+      const descriptor = Object.getOwnPropertyDescriptor(process, "platform")!;
+      try {
+        Object.defineProperty(process, "platform", {
+          ...descriptor,
+          value: "win32",
+        });
+        process.env.APPDATA = "C:\\AppData";
+        process.env.XDG_CONFIG_HOME = "D:\\Legacy";
+        expect(getConfigDirs(dev)).toEqual([
+          "C:\\AppData\\vellum-dev",
+          "D:\\Legacy\\vellum-dev",
+        ]);
+      } finally {
+        Object.defineProperty(process, "platform", descriptor);
+      }
+    });
+
     test("production returns ~/.config/vellum/", () => {
       expect(getConfigDir(prod)).toBe(join(TEST_HOME, ".config", "vellum"));
     });

package/src/lib/environments/paths.ts

@@ -2,18 +2,14 @@ import { homedir } from "os";
 import { join } from "path";
 
 import type { EnvironmentDefinition, PortMap } from "@vellumai/environments";
-
-const PRODUCTION_ENVIRONMENT_NAME = "production";
-
-/**
- * Production lockfile filenames in priority order. The current name is
- * `.vellum.lock.json`; `.vellum.lockfile.json` is the legacy name kept for
- * backward compatibility with installs that predate the rename.
- */
-const PRODUCTION_LOCKFILE_NAMES = [
-  ".vellum.lock.json",
-  ".vellum.lockfile.json",
-] as const;
+import {
+  resolveAssistantsDir,
+  resolveConfigDirPaths,
+  resolveLockfilePaths,
+  resolveLogDir,
+  resolveRuntimeDir,
+  type LocalPathOptions,
+} from "@vellumai/local-mode";
 
 const DEFAULT_PORTS: Readonly<PortMap> = {
   daemon: 7821,
@@ -30,11 +26,11 @@ const DEFAULT_PORTS: Readonly<PortMap> = {
  * non-production environments use `$XDG_CONFIG_HOME/vellum-<env>/`.
  */
 export function getConfigDir(env: EnvironmentDefinition): string {
-  if (env.configDirOverride) return env.configDirOverride;
-  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
-    return join(xdgConfigHome(), "vellum");
-  }
-  return join(xdgConfigHome(), `vellum-${env.name}`);
+  return getConfigDirs(env)[0]!;
+}
+
+export function getConfigDirs(env: EnvironmentDefinition): string[] {
+  return resolveConfigDirPaths(process.env, localPathOptions(env));
 }
 
 /**
@@ -56,12 +52,7 @@ export function getConfigDir(env: EnvironmentDefinition): string {
  * both production and non-production environments.
  */
 export function getLockfilePaths(env: EnvironmentDefinition): string[] {
-  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
-    const dir = env.lockfileDirOverride ?? homedir();
-    return PRODUCTION_LOCKFILE_NAMES.map((name) => join(dir, name));
-  }
-  const dir = env.lockfileDirOverride ?? getConfigDir(env);
-  return [join(dir, "lockfile.json")];
+  return resolveLockfilePaths(process.env, localPathOptions(env));
 }
 
 /**
@@ -79,10 +70,7 @@ export function getLockfilePath(env: EnvironmentDefinition): string {
  * `~/.local/share/vellum-<env>/assistants/`.
  */
 export function getMultiInstanceDir(env: EnvironmentDefinition): string {
-  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
-    return join(xdgDataHome(), "vellum", "assistants");
-  }
-  return join(xdgDataHome(), `vellum-${env.name}`, "assistants");
+  return resolveAssistantsDir(process.env, localPathOptions(env));
 }
 
 /**
@@ -104,10 +92,11 @@ export function getDefaultPorts(env: EnvironmentDefinition): PortMap {
  * use `~/.local/share/vellum-<env>/`.
  */
 export function getStateDir(env: EnvironmentDefinition): string {
-  if (env.name === PRODUCTION_ENVIRONMENT_NAME) {
-    return join(xdgDataHome(), "vellum");
-  }
-  return join(xdgDataHome(), `vellum-${env.name}`);
+  return resolveRuntimeDir(process.env, localPathOptions(env));
+}
+
+export function getLogDir(env: EnvironmentDefinition): string {
+  return resolveLogDir(process.env, localPathOptions(env));
 }
 
 /**
@@ -133,18 +122,17 @@ export function getInputHistoryPath(): string {
 export const ASSISTANT_INTERNAL_PORT = DEFAULT_PORTS.daemon;
 export const GATEWAY_INTERNAL_PORT = DEFAULT_PORTS.gateway;
 
-function xdgDataHome(): string {
-  return (
-    process.env.XDG_DATA_HOME?.trim() || join(homedir(), ".local", "share")
-  );
-}
-
-function xdgConfigHome(): string {
-  return process.env.XDG_CONFIG_HOME?.trim() || join(homedir(), ".config");
-}
-
 function xdgStateHome(): string {
   return (
     process.env.XDG_STATE_HOME?.trim() || join(homedir(), ".local", "state")
   );
 }
+
+function localPathOptions(env: EnvironmentDefinition): LocalPathOptions {
+  return {
+    homeDir: homedir(),
+    environmentName: env.name,
+    configDirOverride: env.configDirOverride,
+    lockfileDirOverride: env.lockfileDirOverride,
+  };
+}

package/src/lib/environments/resolve.ts

@@ -4,6 +4,7 @@ import { dirname } from "path";
 import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
 import {
   defaultEnvironmentFilePath,
+  defaultEnvironmentFilePaths,
   readDefaultEnvironment as readPersistedDefaultEnvironment,
 } from "@vellumai/local-mode";
 
@@ -30,11 +31,12 @@ export function writeDefaultEnvironment(name: string): void {
  * Remove the persisted default environment file, falling back to production.
  */
 export function clearDefaultEnvironment(): void {
-  const filePath = defaultEnvironmentFilePath(process.env);
-  try {
-    unlinkSync(filePath);
-  } catch {
-    // Already absent — nothing to do.
+  for (const filePath of defaultEnvironmentFilePaths(process.env)) {
+    try {
+      unlinkSync(filePath);
+    } catch {
+      // Already absent.
+    }
   }
 }
 

package/src/lib/guardian-token.ts

@@ -17,27 +17,21 @@ import { platform } from "os";
 import { dirname, join } from "path";
 
 import { SEEDS } from "@vellumai/environments";
-import { guardianTokenPath, resolveConfigDir } from "@vellumai/local-mode";
-
-import { getConfigDir } from "./environments/paths.js";
+import {
+  guardianTokenPath,
+  isConfidentialRefreshUrl,
+  resolveConfigDir,
+  saveGuardianToken as writeGuardianToken,
+  type GuardianTokenData,
+} from "@vellumai/local-mode";
+
+import { getConfigDir, getConfigDirs } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
 import { loopbackSafeFetch } from "./loopback-fetch.js";
 
 const DEVICE_ID_SALT = "vellum-assistant-host-id";
 
-export interface GuardianTokenData {
-  guardianPrincipalId: string;
-  accessToken: string;
-  /** ISO date string or epoch-ms number as returned by the gateway. */
-  accessTokenExpiresAt: string | number;
-  refreshToken: string;
-  /** ISO date string or epoch-ms number as returned by the gateway. */
-  refreshTokenExpiresAt: string | number;
-  refreshAfter: string;
-  isNew: boolean;
-  deviceId: string;
-  leasedAt: string;
-}
+export type { GuardianTokenData };
 
 function getGuardianTokenPath(assistantId: string): string {
   // Resolve via the shared @vellumai/local-mode resolver — the same one every
@@ -165,28 +159,24 @@ export function computeDeviceId(): string {
 export function loadGuardianToken(
   assistantId: string,
 ): GuardianTokenData | null {
-  const tokenPath = getGuardianTokenPath(assistantId);
-  try {
-    const raw = readFileSync(tokenPath, "utf-8");
-    return JSON.parse(raw) as GuardianTokenData;
-  } catch {
-    return null;
+  for (const dir of getConfigDirs(getCurrentEnvironment())) {
+    try {
+      const raw = readFileSync(guardianTokenPath(dir, assistantId), "utf-8");
+      return JSON.parse(raw) as GuardianTokenData;
+    } catch {
+      // Try the next compatible location.
+    }
   }
+  return null;
 }
 
 export function saveGuardianToken(
   assistantId: string,
   data: GuardianTokenData,
 ): void {
-  const tokenPath = getGuardianTokenPath(assistantId);
-  const dir = dirname(tokenPath);
-  if (!existsSync(dir)) {
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-  }
-  writeFileSync(tokenPath, JSON.stringify(data, null, 2) + "\n", {
-    mode: 0o600,
-  });
-  chmodSync(tokenPath, 0o600);
+  // Delegates to the shared @vellumai/local-mode writer (0700 dir, 0600 file)
+  // with the same env-resolved config dir the path resolver above uses.
+  writeGuardianToken(resolveConfigDir(process.env), assistantId, data);
 }
 
 /** Abort the refresh POST if the gateway is slow/unreachable (it's now on the
@@ -256,37 +246,6 @@ function releaseRefreshLock(lockPath: string): void {
  * process already rotated it while we waited, we return that fresh token
  * instead of replaying our now-stale refresh token.
  */
-/**
- * The guardian refresh token is long-lived and replayable, so we only transmit
- * it over a confidential channel: HTTPS, or a loopback host (local dev, or a
- * same-host reverse proxy / tunnel agent). Refreshing against a non-loopback
- * plaintext `http://` URL is refused — an on-path attacker could otherwise
- * capture the refresh token and rotate it into fresh credentials.
- *
- * A user-chosen malicious `https://` destination is intentionally out of scope:
- * HTTPS protects the channel, and the access token already goes wherever the
- * configured URL points. This guard targets the plaintext-interception vector.
- */
-function isLoopbackHostname(hostname: string): boolean {
-  const h = hostname.toLowerCase();
-  return (
-    h === "localhost" ||
-    h === "::1" ||
-    h === "[::1]" ||
-    h === "0:0:0:0:0:0:0:1" ||
-    /^127(?:\.\d{1,3}){3}$/.test(h)
-  );
-}
-
-function isConfidentialRefreshUrl(gatewayUrl: string): boolean {
-  try {
-    const url = new URL(gatewayUrl);
-    return url.protocol === "https:" || isLoopbackHostname(url.hostname);
-  } catch {
-    return false;
-  }
-}
-
 /**
  * True when a stored guardian token has reached its renewal point — now is
  * at/after `refreshAfter` (preferred) or `accessTokenExpiresAt`. Used to gate
@@ -380,6 +339,7 @@ export async function refreshGuardianToken(
       isNew: false,
       deviceId: tokenData.deviceId,
       leasedAt: new Date().toISOString(),
+      pairedGatewayUrl: tokenData.pairedGatewayUrl,
     };
     saveGuardianToken(assistantId, refreshed);
     return refreshed;

package/src/lib/ingress-config.ts

@@ -85,6 +85,31 @@ export function saveIngressUrl(
   }
 }
 
+/** Persist a reserved ngrok domain under `ingress.ngrok.domain`; null clears it. */
+export function saveNgrokDomain(
+  workspaceDir: string,
+  domain: string | null,
+): void {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
+  if (domain) {
+    ingress.ngrok = { domain };
+  } else {
+    delete ingress.ngrok;
+  }
+  config.ingress = ingress;
+  saveRawConfig(workspaceDir, config);
+}
+
+/** Read the reserved ngrok domain from the workspace config, if saved. */
+export function loadNgrokDomain(workspaceDir: string): string | null {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = config.ingress as Record<string, unknown> | undefined;
+  const ngrok = ingress?.ngrok as Record<string, unknown> | undefined;
+  const domain = ngrok?.domain;
+  return typeof domain === "string" && domain.trim() ? domain : null;
+}
+
 /** Clear the ingress public base URL from the workspace config. */
 export function clearIngressUrl(
   workspaceDir: string,