@vellumai/cli 0.10.11 → 0.10.12-dev.202607242227.e52a30c

package/src/commands/wake.ts

@@ -30,6 +30,15 @@ import {
   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";
 
 export async function wake(): Promise<void> {
   const args = process.argv.slice(3);
@@ -379,6 +388,17 @@ 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.",
@@ -404,3 +424,101 @@ export async function wake(): Promise<void> {
     });
   }
 }
+
+/**
+ * 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 isAssistantFeatureFlagEnabled(
+      assistantId,
+      WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl: `http://127.0.0.1:${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/lib/__tests__/step-runner.test.ts

@@ -33,7 +33,12 @@ describe("buildExecErrorMessage", () => {
   });
 
   it("appends both streams joined by newline when both present", () => {
-    const msg = buildExecErrorMessage("docker", 1, "stderr-line", "stdout-line");
+    const msg = buildExecErrorMessage(
+      "docker",
+      1,
+      "stderr-line",
+      "stdout-line",
+    );
     expect(msg).toBe("docker exited with code 1\nstderr-line\nstdout-line");
   });
 

package/src/lib/__tests__/terminal-session.test.ts

@@ -1,9 +1,6 @@
 import { describe, expect, test } from "bun:test";
 
-import {
-  parseSentinelOutput,
-  stripAnsi,
-} from "../terminal-session.js";
+import { parseSentinelOutput, stripAnsi } from "../terminal-session.js";
 
 const START = "__VELLUM_EXEC_START_1234__";
 const END = "__VELLUM_EXEC_END_1234__";
@@ -132,7 +129,7 @@ describe("parseSentinelOutput", () => {
       START,
       "📤 Resend Email Setup [installed]",
       "  ID: resend-setup",
-      '  Set up and send emails via a user-provided Resend account (BYO email provider)',
+      "  Set up and send emails via a user-provided Resend account (BYO email provider)",
       "",
       "Community registry (1):",
       "",
@@ -151,18 +148,12 @@ describe("parseSentinelOutput", () => {
     const cleaned = "just some random output\nwith no sentinels\n";
     const result = parseSentinelOutput(cleaned, START, END);
     // Falls back to entire output (trimmed)
-    expect(result.output).toBe(
-      "just some random output\nwith no sentinels",
-    );
+    expect(result.output).toBe("just some random output\nwith no sentinels");
     expect(result.exitCode).toBe(0);
   });
 
   test("handles output with only start sentinel (no end)", () => {
-    const cleaned = [
-      START,
-      "partial output",
-      "more output",
-    ].join("\n");
+    const cleaned = [START, "partial output", "more output"].join("\n");
 
     const result = parseSentinelOutput(cleaned, START, END);
     expect(result.output).toBe("partial output\nmore output");
@@ -177,7 +168,7 @@ describe("parseSentinelOutput", () => {
         ` '${END}'; echo '__VELLUM_EXIT_'$__ec; exit $__ec`,
       START,
       "[13:06:38.851] INFO (761 on pod-0): [clawhub] Running clawhub command",
-      '    args: [',
+      "    args: [",
       '      "search",',
       '      "resend-setup",',
       '      "--limit",',

package/src/lib/assistant-config.ts

@@ -18,6 +18,7 @@ import {
 } from "@vellumai/local-mode/contract";
 
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "./constants.js";
+import { crossEnvironmentAssistantHint } from "./environments/detect.js";
 import {
   getDefaultPorts,
   getLockfilePath,
@@ -109,6 +110,9 @@ export type AssistantEntry = Omit<
   /** Loopback URL for same-machine health checks (e.g. `http://127.0.0.1:7831`).
    *  Avoids mDNS resolution issues when the machine checks its own gateway. */
   localUrl?: string;
+  /** Public https ingress URL recorded by `vellum tunnel` providers for this
+   *  instance. The advertised-URL default for remote-web pairing. */
+  ingressUrl?: string;
   bearerToken?: string;
   /** True when this entry was registered via `vellum connect import` (a remote
    *  pairing). Set alongside `cloud: "paired"`; also backs the re-import /
@@ -420,7 +424,7 @@ export function formatAssistantLookupError(
     return `Multiple assistants match '${identifier}': ${matches}. Use the assistant ID to disambiguate.`;
   }
 
-  return `No assistant found with name or ID '${identifier}'.`;
+  return `No assistant found with name or ID '${identifier}'.${crossEnvironmentAssistantHint() ?? ""}`;
 }
 
 export function removeAssistantEntry(assistantId: string): void {
@@ -577,7 +581,9 @@ export function resolveTargetAssistant(nameArg?: string): AssistantEntry {
     if (all.length === 1) return all[0];
 
     if (all.length === 0) {
-      console.error("No assistant found. Run 'vellum hatch' first.");
+      console.error(
+        `No assistant found. Run 'vellum hatch' first.${crossEnvironmentAssistantHint() ?? ""}`,
+      );
     } else {
       console.error(
         `Multiple assistants found. Set an active assistant with 'vellum use <name>'.`,

package/src/lib/cloudflare-tunnel.ts

@@ -1,60 +1,13 @@
 import { execFileSync, spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
 
 import { GATEWAY_PORT } from "./constants.js";
+import {
+  clearIngressUrl,
+  getDefaultWorkspaceDir,
+  saveIngressUrl,
+} from "./ingress-config.js";
 import { resolveTunnelTargetPort } from "./nginx-ingress.js";
 
-// ── Workspace config helpers (mirrors the pattern in ngrok.ts) ───────────────
-
-function getDefaultWorkspaceDir(): string {
-  return (
-    process.env.VELLUM_WORKSPACE_DIR?.trim() ||
-    join(homedir(), ".vellum", "workspace")
-  );
-}
-
-function getConfigPath(workspaceDir: string): string {
-  return join(workspaceDir, "config.json");
-}
-
-function loadRawConfig(workspaceDir: string): Record<string, unknown> {
-  const configPath = getConfigPath(workspaceDir);
-  if (!existsSync(configPath)) return {};
-  return JSON.parse(readFileSync(configPath, "utf-8")) as Record<
-    string,
-    unknown
-  >;
-}
-
-function saveRawConfig(
-  workspaceDir: string,
-  config: Record<string, unknown>,
-): void {
-  const configPath = getConfigPath(workspaceDir);
-  const dir = dirname(configPath);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-}
-
-function saveIngressUrl(workspaceDir: string, publicUrl: string): void {
-  const config = loadRawConfig(workspaceDir);
-  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
-  ingress.publicBaseUrl = publicUrl;
-  ingress.enabled = true;
-  config.ingress = ingress;
-  saveRawConfig(workspaceDir, config);
-}
-
-function clearIngressUrl(workspaceDir: string): void {
-  const config = loadRawConfig(workspaceDir);
-  const ingress = (config.ingress ?? {}) as Record<string, unknown>;
-  delete ingress.publicBaseUrl;
-  config.ingress = ingress;
-  saveRawConfig(workspaceDir, config);
-}
-
 // ── Cloudflare Tunnel ─────────────────────────────────────────────────────────
 
 const CLOUDFLARED_TIMEOUT_MS = 30_000;
@@ -178,6 +131,8 @@ export interface RunCloudflareTunnelOptions {
   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;
 }
 
 export async function runCloudflareTunnel(
@@ -224,7 +179,7 @@ export async function runCloudflareTunnel(
     if (!child.killed) child.kill("SIGTERM");
     if (publicUrl) {
       console.log("\nClearing ingress URL from config...");
-      clearIngressUrl(workspaceDir);
+      clearIngressUrl(workspaceDir, opts.assistantId);
     }
   };
 
@@ -246,7 +201,7 @@ export async function runCloudflareTunnel(
     // Always clear the saved ingress URL when the tunnel process ends so
     // webhook integrations don't keep hitting a dead endpoint.
     if (publicUrl !== undefined) {
-      clearIngressUrl(workspaceDir);
+      clearIngressUrl(workspaceDir, opts.assistantId);
     }
     if (code !== null && code !== 0) {
       console.error(`\ncloudflared exited with code ${code}.`);
@@ -277,7 +232,7 @@ export async function runCloudflareTunnel(
   console.log(`Forwarding to:     localhost:${port}`);
   console.log("");
 
-  saveIngressUrl(workspaceDir, publicUrl);
+  saveIngressUrl(workspaceDir, publicUrl, opts.assistantId);
   console.log("Ingress URL saved to config.");
   console.log("");
   console.log("Press Ctrl+C to stop the tunnel and clear the ingress URL.");

package/src/lib/device-id.ts

@@ -23,9 +23,7 @@ let cached: string | undefined;
 function resolveDeviceIdPaths(): { dir: string; file: string } {
   const env = getCurrentEnvironment();
   const dir =
-    env.name === "production"
-      ? join(homedir(), ".vellum")
-      : getConfigDir(env);
+    env.name === "production" ? join(homedir(), ".vellum") : getConfigDir(env);
   return { dir, file: join(dir, "device.json") };
 }
 

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

@@ -0,0 +1,101 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  crossEnvironmentAssistantHint,
+  detectOtherEnvironmentAssistants,
+} from "../detect.js";
+import { getSeed } from "../resolve.js";
+
+const prod = getSeed("production")!;
+
+/** Create `<XDG_DATA_HOME>/vellum-<env>/assistants/<id>/` for a non-prod env. */
+function seedAssistantDir(dataHome: string, envName: string, id: string): void {
+  mkdirSync(join(dataHome, `vellum-${envName}`, "assistants", id), {
+    recursive: true,
+  });
+}
+
+describe("cross-environment assistant detection", () => {
+  let dataHome: string;
+  let prevXdg: string | undefined;
+  let prevEnv: string | undefined;
+
+  beforeEach(() => {
+    prevXdg = process.env.XDG_DATA_HOME;
+    prevEnv = process.env.VELLUM_ENVIRONMENT;
+    dataHome = mkdtempSync(join(tmpdir(), "cli-detect-xdg-"));
+    process.env.XDG_DATA_HOME = dataHome;
+    // Pin the current env so the hint's "this CLI targets '<env>'" copy and
+    // the current-env skip are deterministic regardless of machine config.
+    process.env.VELLUM_ENVIRONMENT = "production";
+  });
+
+  afterEach(() => {
+    if (prevXdg === undefined) {
+      delete process.env.XDG_DATA_HOME;
+    } else {
+      process.env.XDG_DATA_HOME = prevXdg;
+    }
+    if (prevEnv === undefined) {
+      delete process.env.VELLUM_ENVIRONMENT;
+    } else {
+      process.env.VELLUM_ENVIRONMENT = prevEnv;
+    }
+    rmSync(dataHome, { recursive: true, force: true });
+  });
+
+  test("finds an env whose data dir holds an assistant subdirectory", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    expect(detectOtherEnvironmentAssistants(prod)).toContain("dev");
+  });
+
+  test("reports every other env that holds assistants", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    seedAssistantDir(dataHome, "staging", "staging-bot");
+    const others = detectOtherEnvironmentAssistants(prod);
+    expect(others).toContain("dev");
+    expect(others).toContain("staging");
+  });
+
+  test("skips the current environment even when it holds assistants", () => {
+    // production's own multi-instance dir (no env suffix).
+    mkdirSync(join(dataHome, "vellum", "assistants", "prod-bot"), {
+      recursive: true,
+    });
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("ignores an env dir that holds no assistant subdirectory", () => {
+    mkdirSync(join(dataHome, "vellum-dev", "assistants"), { recursive: true });
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("returns empty when no env data dirs exist", () => {
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+  });
+
+  test("swallows fs errors (data root is a file, not a dir) and returns empty", () => {
+    const filePath = join(dataHome, "not-a-dir");
+    writeFileSync(filePath, "x");
+    process.env.XDG_DATA_HOME = filePath;
+    expect(detectOtherEnvironmentAssistants(prod)).toEqual([]);
+    expect(crossEnvironmentAssistantHint()).toBeNull();
+  });
+
+  test("hint names the env, the current env, and both fixes", () => {
+    seedAssistantDir(dataHome, "dev", "dev-bot");
+    const hint = crossEnvironmentAssistantHint();
+    expect(hint).not.toBeNull();
+    expect(hint).toContain("'dev'");
+    expect(hint).toContain("This CLI targets 'production'");
+    expect(hint).toContain("Install vellum Command");
+    expect(hint).toContain("VELLUM_ENVIRONMENT=dev");
+  });
+
+  test("hint is null when no other env has assistants", () => {
+    expect(crossEnvironmentAssistantHint()).toBeNull();
+  });
+});

package/src/lib/environments/detect.ts

@@ -0,0 +1,79 @@
+import { readdirSync } from "fs";
+
+import { SEEDS, type EnvironmentDefinition } from "@vellumai/environments";
+
+import { getMultiInstanceDir } from "./paths.js";
+import { getCurrentEnvironment } from "./resolve.js";
+
+/**
+ * Names of OTHER environments (every seed except `currentEnv`) whose
+ * multi-instance data dir exists and holds at least one assistant
+ * subdirectory.
+ *
+ * Each environment has its own on-host data layout — see
+ * {@link getMultiInstanceDir}. A user who hatched via a dev/staging desktop
+ * app but runs the production npm CLI (or vice versa) targets a different
+ * layout than the app did, so the assistant the app created is invisible to
+ * this CLI. This cheap filesystem scan surfaces that split so callers can
+ * point the user at the environment that actually holds their assistants.
+ *
+ * Never throws: a missing or unreadable dir just means that environment has no
+ * discoverable assistants, so it is skipped. Returns an empty array on any
+ * error.
+ */
+export function detectOtherEnvironmentAssistants(
+  currentEnv: EnvironmentDefinition,
+): string[] {
+  const found: string[] = [];
+  for (const env of Object.values(SEEDS)) {
+    if (env.name === currentEnv.name) {
+      continue;
+    }
+    try {
+      const hasAssistant = readdirSync(getMultiInstanceDir(env), {
+        withFileTypes: true,
+      }).some((dirent) => dirent.isDirectory());
+      if (hasAssistant) {
+        found.push(env.name);
+      }
+    } catch {
+      // Missing or unreadable dir — this environment has no discoverable
+      // assistants. Skip it.
+    }
+  }
+  return found;
+}
+
+/**
+ * One-line hint appended to "no assistant found" and "gateway unreachable"
+ * errors when another environment's data dir holds assistants. A first-time
+ * user who hatched via a dev/staging desktop app while running the production
+ * npm CLI otherwise gets a bare failure with no clue the two tools target
+ * different environments.
+ *
+ * Returns null when nothing is found so callers can append unconditionally:
+ * `message + (crossEnvironmentAssistantHint() ?? "")`. Detection failure never
+ * propagates — the caller's original error must survive intact.
+ */
+export function crossEnvironmentAssistantHint(): string | null {
+  let currentEnv: EnvironmentDefinition;
+  let others: string[];
+  try {
+    currentEnv = getCurrentEnvironment();
+    others = detectOtherEnvironmentAssistants(currentEnv);
+  } catch {
+    return null;
+  }
+  if (others.length === 0) {
+    return null;
+  }
+
+  const quoted = others.map((name) => `'${name}'`).join(", ");
+  const noun = others.length > 1 ? "environments" : "environment";
+  return (
+    `\n\nFound assistants in the ${quoted} ${noun} (managed by a dev/staging ` +
+    `desktop app). This CLI targets '${currentEnv.name}'. Use the desktop ` +
+    `app's 'Install vellum Command…' menu item to get a matching CLI, or ` +
+    `set VELLUM_ENVIRONMENT=${others[0]}.`
+  );
+}

package/src/lib/flag-args.test.ts

@@ -12,12 +12,7 @@ describe("parseFeatureFlagArgs", () => {
   });
 
   test("multiple flags produce multiple env vars", () => {
-    const result = parseFeatureFlagArgs([
-      "--flag",
-      "a=1",
-      "--flag",
-      "b=0",
-    ]);
+    const result = parseFeatureFlagArgs(["--flag", "a=1", "--flag", "b=0"]);
     expect(result).toEqual({
       envVars: { VELLUM_FLAG_A: "1", VELLUM_FLAG_B: "0" },
       remaining: [],

package/src/lib/guardian-token.ts

@@ -17,10 +17,7 @@ import { platform } from "os";
 import { dirname, join } from "path";
 
 import { SEEDS } from "@vellumai/environments";
-import {
-  guardianTokenPath,
-  resolveConfigDir,
-} from "@vellumai/local-mode";
+import { guardianTokenPath, resolveConfigDir } from "@vellumai/local-mode";
 
 import { getConfigDir } from "./environments/paths.js";
 import { getCurrentEnvironment } from "./environments/resolve.js";
@@ -347,21 +344,24 @@ export async function refreshGuardianToken(
 
     const tokenData = current ?? before;
 
-    const response = await loopbackSafeFetch(`${gatewayUrl}/v1/guardian/refresh`, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${tokenData.accessToken}`,
+    const response = await loopbackSafeFetch(
+      `${gatewayUrl}/v1/guardian/refresh`,
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${tokenData.accessToken}`,
+        },
+        body: JSON.stringify({
+          refreshToken: tokenData.refreshToken,
+          // The refresh token is device-bound; send the device id used at init
+          // (falling back to a fresh computation for tokens persisted before the
+          // field was stored) so the gateway can verify the binding.
+          deviceId: tokenData.deviceId || computeDeviceId(),
+        }),
+        signal: AbortSignal.timeout(REFRESH_FETCH_TIMEOUT_MS),
       },
-      body: JSON.stringify({
-        refreshToken: tokenData.refreshToken,
-        // The refresh token is device-bound; send the device id used at init
-        // (falling back to a fresh computation for tokens persisted before the
-        // field was stored) so the gateway can verify the binding.
-        deviceId: tokenData.deviceId || computeDeviceId(),
-      }),
-      signal: AbortSignal.timeout(REFRESH_FETCH_TIMEOUT_MS),
-    });
+    );
     if (!response.ok) return null;
 
     const json = (await response.json()) as Record<string, unknown>;