@vellumai/cli 0.10.11-dev.202607220859.296f4b0 → 0.10.11-dev.202607220955.d4134f8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.10.11-dev.202607220859.296f4b0",
+  "version": "0.10.11-dev.202607220955.d4134f8",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/pair.test.ts

@@ -931,4 +931,307 @@ describe("pair command", () => {
     expect(errors.join("\n")).toContain("--qr");
     expect(fetchCalled).toBe(false);
   });
+
+  test("--qr with no --url uses the tunnel-saved ingress URL", async () => {
+    const workspaceDir = mkdtempSync(join(tmpdir(), "vellum-pair-ingress-"));
+    // Point the synthesized instance dir at an empty temp XDG root so the
+    // resolution deterministically falls through to VELLUM_WORKSPACE_DIR.
+    const xdgDir = mkdtempSync(join(tmpdir(), "vellum-pair-xdg-"));
+    process.env.XDG_DATA_HOME = xdgDir;
+    writeFileSync(
+      join(workspaceDir, "config.json"),
+      JSON.stringify({
+        ingress: {
+          publicBaseUrl: "https://saved.example.ts.net",
+          enabled: true,
+        },
+      }),
+    );
+    process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+
+    const calls: string[] = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push(url);
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-challenge`) {
+        // The minted challenge must advertise the SAVED ingress URL.
+        expect(JSON.parse(init?.body as string)).toEqual({
+          publicBaseUrl: "https://saved.example.ts.net",
+        });
+        return new Response(
+          JSON.stringify({
+            deviceCode: "device-code",
+            userCode: "ABCD-EFGH",
+            verificationUri: "https://saved.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+            expiresInSeconds: 600,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-verification`) {
+        return new Response(
+          JSON.stringify({
+            status: "approved",
+            verificationUri: "https://saved.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const logs: string[] = [];
+    const logSpy = spyOn(console, "log").mockImplementation(
+      (...a: unknown[]) => {
+        logs.push(a.join(" "));
+      },
+    );
+
+    process.argv = ["bun", "vellum", "pair", "--qr"];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+      delete process.env.VELLUM_WORKSPACE_DIR;
+      delete process.env.XDG_DATA_HOME;
+      rmSync(workspaceDir, { recursive: true, force: true });
+      rmSync(xdgDir, { recursive: true, force: true });
+    }
+
+    expect(calls).toContain(`${LOCAL_URL}/v1/remote-web/pairing-challenge`);
+    const output = logs.join("\n");
+    expect(output).toContain(
+      "Using saved ingress URL https://saved.example.ts.net",
+    );
+    expect(output).toContain(
+      "https://saved.example.ts.net/assistant/pair#device_code=device-code",
+    );
+  });
+
+  test("--url beats the saved ingress URL", async () => {
+    const workspaceDir = mkdtempSync(join(tmpdir(), "vellum-pair-ingress-"));
+    // Point the synthesized instance dir at an empty temp XDG root so the
+    // resolution deterministically falls through to VELLUM_WORKSPACE_DIR.
+    const xdgDir = mkdtempSync(join(tmpdir(), "vellum-pair-xdg-"));
+    process.env.XDG_DATA_HOME = xdgDir;
+    writeFileSync(
+      join(workspaceDir, "config.json"),
+      JSON.stringify({
+        ingress: {
+          publicBaseUrl: "https://saved.example.ts.net",
+          enabled: true,
+        },
+      }),
+    );
+    process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-challenge`) {
+        expect(JSON.parse(init?.body as string)).toEqual({
+          publicBaseUrl: "https://explicit.example.ts.net",
+        });
+        return new Response(
+          JSON.stringify({
+            deviceCode: "device-code",
+            userCode: "ABCD-EFGH",
+            verificationUri: "https://explicit.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+            expiresInSeconds: 600,
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      if (url === `${LOCAL_URL}/v1/remote-web/pairing-verification`) {
+        return new Response(
+          JSON.stringify({
+            status: "approved",
+            verificationUri: "https://explicit.example.ts.net/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      return new Response("not found", { status: 404 });
+    }) as unknown as typeof fetch;
+
+    const logs: string[] = [];
+    const logSpy = spyOn(console, "log").mockImplementation(
+      (...a: unknown[]) => {
+        logs.push(a.join(" "));
+      },
+    );
+
+    process.argv = [
+      "bun",
+      "vellum",
+      "pair",
+      "--qr",
+      "--url",
+      "https://explicit.example.ts.net",
+    ];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+      delete process.env.VELLUM_WORKSPACE_DIR;
+      delete process.env.XDG_DATA_HOME;
+      rmSync(workspaceDir, { recursive: true, force: true });
+      rmSync(xdgDir, { recursive: true, force: true });
+    }
+
+    expect(logs.join("\n")).not.toContain("Using saved ingress URL");
+  });
+
+  test("a non-https saved ingress URL is ignored", async () => {
+    const workspaceDir = mkdtempSync(join(tmpdir(), "vellum-pair-ingress-"));
+    // Point the synthesized instance dir at an empty temp XDG root so the
+    // resolution deterministically falls through to VELLUM_WORKSPACE_DIR.
+    const xdgDir = mkdtempSync(join(tmpdir(), "vellum-pair-xdg-"));
+    process.env.XDG_DATA_HOME = xdgDir;
+    writeFileSync(
+      join(workspaceDir, "config.json"),
+      JSON.stringify({
+        ingress: {
+          publicBaseUrl: "http://insecure.example.com",
+          enabled: true,
+        },
+      }),
+    );
+    process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+
+    const origFetch = globalThis.fetch;
+    let minted = false;
+    globalThis.fetch = (async (url: string) => {
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      minted = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = ["bun", "vellum", "pair", "--qr"];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+      delete process.env.VELLUM_WORKSPACE_DIR;
+      delete process.env.XDG_DATA_HOME;
+      rmSync(workspaceDir, { recursive: true, force: true });
+      rmSync(xdgDir, { recursive: true, force: true });
+    }
+
+    // The saved http URL is skipped, so --qr falls through to the (non-https)
+    // runtime URL and refuses — proving the saved value was not advertised.
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain(RUNTIME_URL);
+    expect(minted).toBe(false);
+  });
+
+  test("a saved ingress URL with ingress disabled is ignored", async () => {
+    const workspaceDir = mkdtempSync(join(tmpdir(), "vellum-pair-ingress-"));
+    // Point the synthesized instance dir at an empty temp XDG root so the
+    // resolution deterministically falls through to VELLUM_WORKSPACE_DIR.
+    const xdgDir = mkdtempSync(join(tmpdir(), "vellum-pair-xdg-"));
+    process.env.XDG_DATA_HOME = xdgDir;
+    writeFileSync(
+      join(workspaceDir, "config.json"),
+      JSON.stringify({
+        ingress: {
+          publicBaseUrl: "https://saved.example.ts.net",
+          enabled: false,
+        },
+      }),
+    );
+    process.env.VELLUM_WORKSPACE_DIR = workspaceDir;
+
+    const origFetch = globalThis.fetch;
+    let minted = false;
+    globalThis.fetch = (async (url: string) => {
+      if (url === `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`) {
+        return new Response(
+          JSON.stringify({
+            flags: [{ key: "web-remote-ingress", enabled: true }],
+          }),
+          { status: 200, headers: { "content-type": "application/json" } },
+        );
+      }
+      minted = true;
+      return new Response("{}", { status: 200 });
+    }) as unknown as typeof fetch;
+
+    const errors: string[] = [];
+    const errSpy = spyOn(console, "error").mockImplementation(
+      (...a: unknown[]) => {
+        errors.push(a.join(" "));
+      },
+    );
+    const exitSpy = spyOn(process, "exit").mockImplementation(((
+      code?: number,
+    ) => {
+      throw new Error(`exit:${code}`);
+    }) as never);
+
+    process.argv = ["bun", "vellum", "pair", "--qr"];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+      delete process.env.VELLUM_WORKSPACE_DIR;
+      delete process.env.XDG_DATA_HOME;
+      rmSync(workspaceDir, { recursive: true, force: true });
+      rmSync(xdgDir, { recursive: true, force: true });
+    }
+
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain(RUNTIME_URL);
+    expect(minted).toBe(false);
+  });
 });

package/src/commands/pair.ts

@@ -10,6 +10,8 @@
  * independent, separately-revocable device (see `vellum unpair`, forthcoming).
  */
 
+import { join } from "node:path";
+
 import { nanoid } from "nanoid";
 // Call `qrcodeTerminal.generate` as a method — the library reads its default
 // error-correction level off `this`, so a destructured import renders nothing.
@@ -33,6 +35,10 @@ import {
   isAssistantFeatureFlagEnabled,
   WEB_REMOTE_INGRESS_FLAG,
 } from "../lib/feature-flags.js";
+import {
+  getDefaultWorkspaceDir,
+  loadIngressUrl,
+} from "../lib/ingress-config.js";
 import { getLocalLanIPv4 } from "../lib/local.js";
 import { isLoopbackUrl, loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
@@ -40,6 +46,45 @@ function assistantDisplayName(entry: AssistantEntry): string {
   return entry.name || entry.assistantName || entry.assistantId;
 }
 
+/**
+ * The tunnel-saved ingress URL, when usable as a remote-web advertised
+ * default: https and non-loopback (the bar `--qr`/`--web` URLs must clear).
+ * Checks the workspaces a tunnel provider may have written: the instance's
+ * own workspace (managed/XDG layouts), then the default workspace (legacy
+ * `~/.vellum/workspace` layouts, where the gateway reads its config).
+ */
+function loadUsableIngressUrl(entry: AssistantEntry): string | null {
+  const candidates = entry.resources
+    ? [
+        join(entry.resources.instanceDir, ".vellum", "workspace"),
+        getDefaultWorkspaceDir(),
+      ]
+    : [getDefaultWorkspaceDir()];
+  for (const workspaceDir of candidates) {
+    let saved: string | null = null;
+    try {
+      saved = loadIngressUrl(workspaceDir);
+    } catch {
+      continue;
+    }
+    if (!saved) {
+      continue;
+    }
+    try {
+      if (new URL(saved).protocol !== "https:") {
+        continue;
+      }
+    } catch {
+      continue;
+    }
+    if (isLoopbackUrl(saved)) {
+      continue;
+    }
+    return saved;
+  }
+  return null;
+}
+
 function printUsage(): void {
   console.log(`vellum pair [beta] - Mint a device-scoped token for another machine
 
@@ -348,17 +393,30 @@ export async function pair(): Promise<void> {
 
   // Mint over loopback (localUrl avoids mDNS for same-machine calls), but
   // advertise a REACHABLE url in the bundle — the loopback url would point the
-  // other machine at its own localhost. Prefer an explicit --url, then the
+  // other machine at its own localhost. Prefer an explicit --url, then (for
+  // the remote-web flows) the ingress URL a tunnel provider saved, then the
   // runtime (LAN/tunnel) url.
   const mintUrl = (
     entry.localUrl ||
     entry.runtimeUrl ||
     `http://127.0.0.1:${GATEWAY_PORT}`
   ).replace(/\/+$/, "");
-  const advertisedUrl = (urlOverride || entry.runtimeUrl || mintUrl).replace(
-    /\/+$/,
-    "",
-  );
+  const savedIngressUrl =
+    !urlOverride && (qrPairing || webPairing)
+      ? loadUsableIngressUrl(entry)
+      : null;
+  const advertisedUrl = (
+    urlOverride ||
+    savedIngressUrl ||
+    entry.runtimeUrl ||
+    mintUrl
+  ).replace(/\/+$/, "");
+  if (savedIngressUrl && !jsonOutput) {
+    console.log(
+      `Using saved ingress URL ${savedIngressUrl} ` +
+        "(from vellum tunnel; override with --url).",
+    );
+  }
 
   // A local hatch's runtimeUrl is itself loopback (http://localhost:<port>),
   // so without an explicit --url the bundle would point the other machine at

package/src/lib/ingress-config.ts

@@ -51,6 +51,20 @@ export function saveIngressUrl(workspaceDir: string, publicUrl: string): void {
   saveRawConfig(workspaceDir, config);
 }
 
+/**
+ * Read the saved public ingress URL, or null when ingress is unset or
+ * explicitly disabled.
+ */
+export function loadIngressUrl(workspaceDir: string): string | null {
+  const config = loadRawConfig(workspaceDir);
+  const ingress = config.ingress as Record<string, unknown> | undefined;
+  if (!ingress || ingress.enabled === false) {
+    return null;
+  }
+  const url = ingress.publicBaseUrl;
+  return typeof url === "string" && url.trim() ? url.trim() : null;
+}
+
 /** Clear the ingress public base URL from the workspace config. */
 export function clearIngressUrl(workspaceDir: string): void {
   const config = loadRawConfig(workspaceDir);