@vellumai/cli 0.9.1-staging.1 → 0.10.0-staging.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.9.1-staging.1",
+  "version": "0.10.0-staging.3",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {

package/src/__tests__/nginx-ingress.test.ts

@@ -127,8 +127,6 @@ describe("buildIngressNginxConfig", () => {
       "location = /v1/pair/ { return 404; }",
       "location = /v1/pair/web-init { return 404; }",
       "location = /v1/pair/web-init/ { return 404; }",
-      "location = /v1/remote-web/pairing-challenge { return 404; }",
-      "location = /v1/remote-web/pairing-challenge/ { return 404; }",
       "location = /v1/devices { return 404; }",
       "location = /v1/devices/ { return 404; }",
       "location = /v1/devices/revoke { return 404; }",

package/src/__tests__/pair.test.ts

@@ -268,4 +268,203 @@ describe("pair command", () => {
     const out = JSON.parse(logs.join("\n"));
     expect(out.gatewayUrl).toBe(OVERRIDE);
   });
+
+  test("--web creates a browser pairing URL without printing tokens", async () => {
+    const calls: Array<[string, RequestInit | undefined]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      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`) {
+        return new Response(
+          JSON.stringify({
+            deviceCode: "device-code",
+            userCode: "ABCD-EFGH",
+            verificationUri:
+              "https://abc123.ngrok.app/assistant-123/assistant/pair",
+            expiresAt: "2026-06-04T00:10:00.000Z",
+            expiresInSeconds: 600,
+            intervalSeconds: 5,
+          }),
+          { 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",
+      "--web",
+      "--url",
+      "https://abc123.ngrok.app/assistant-123/assistant/",
+      "--json",
+    ];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(calls).toHaveLength(2);
+    expect(calls[1][0]).toBe(`${LOCAL_URL}/v1/remote-web/pairing-challenge`);
+    expect(JSON.parse(calls[1][1]?.body as string)).toEqual({
+      publicBaseUrl: "https://abc123.ngrok.app/assistant-123",
+    });
+
+    const out = JSON.parse(logs.join("\n"));
+    expect(out).toEqual({
+      pairUrl:
+        "https://abc123.ngrok.app/assistant-123/assistant/pair#device_code=device-code",
+      userCode: "ABCD-EFGH",
+      verificationUri: "https://abc123.ngrok.app/assistant-123/assistant/pair",
+      expiresAt: "2026-06-04T00:10:00.000Z",
+      expiresInSeconds: 600,
+    });
+    expect(logs.join("\n")).not.toContain("access");
+    expect(logs.join("\n")).not.toContain("refresh");
+  });
+
+  test("--web refuses when the web remote ingress feature flag is off", async () => {
+    const calls: Array<[string, RequestInit | undefined]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      return new Response(
+        JSON.stringify({
+          flags: [{ key: "web-remote-ingress", enabled: false }],
+        }),
+        { status: 200, headers: { "content-type": "application/json" } },
+      );
+    }) 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",
+      "--web",
+      "--url",
+      "https://abc123.ngrok.app",
+    ];
+    let exited = false;
+    try {
+      await pair();
+    } catch (e) {
+      exited = (e as Error).message === "exit:1";
+    } finally {
+      errSpy.mockRestore();
+      exitSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(exited).toBe(true);
+    expect(errors.join("\n")).toContain("web-remote-ingress");
+    expect(calls).toHaveLength(1);
+    expect(calls[0][0]).toBe(
+      `${LOCAL_URL}/v1/assistants/pair-test/feature-flags`,
+    );
+  });
+
+  test("--web-approve approves a browser pairing code over loopback", async () => {
+    writeFileSync(
+      join(testDir, ".vellum.lock.json"),
+      JSON.stringify({
+        assistants: [
+          {
+            assistantId: "pair-test",
+            runtimeUrl: LOCAL_URL,
+            localUrl: LOCAL_URL,
+            cloud: "local",
+          },
+        ],
+        activeAssistant: "pair-test",
+      }),
+    );
+
+    const calls: Array<[string, RequestInit | undefined]> = [];
+    const origFetch = globalThis.fetch;
+    globalThis.fetch = (async (url: string, init?: RequestInit) => {
+      calls.push([url, init]);
+      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-verification`) {
+        return new Response(
+          JSON.stringify({
+            status: "approved",
+            verificationUri: "https://abc123.ngrok.app/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",
+      "--web-approve",
+      "ABCD-EFGH",
+      "--json",
+    ];
+    try {
+      await pair();
+    } finally {
+      logSpy.mockRestore();
+      globalThis.fetch = origFetch;
+    }
+
+    expect(calls).toHaveLength(2);
+    expect(calls[1][0]).toBe(`${LOCAL_URL}/v1/remote-web/pairing-verification`);
+    expect(JSON.parse(calls[1][1]?.body as string)).toEqual({
+      userCode: "ABCD-EFGH",
+    });
+    expect(JSON.parse(logs.join("\n"))).toEqual({
+      status: "approved",
+      verificationUri: "https://abc123.ngrok.app/assistant/pair",
+      expiresAt: "2026-06-04T00:10:00.000Z",
+    });
+  });
 });

package/src/commands/pair.ts

@@ -25,6 +25,11 @@ import {
   getClientRegistrationHeaders,
 } from "../lib/client-identity.js";
 import { GATEWAY_PORT } from "../lib/constants.js";
+import {
+  formatFeatureFlagGateMessage,
+  isAssistantFeatureFlagEnabled,
+  WEB_REMOTE_INGRESS_FLAG,
+} from "../lib/feature-flags.js";
 import { getLocalLanIPv4 } from "../lib/local.js";
 import { loopbackSafeFetch } from "../lib/loopback-fetch.js";
 
@@ -50,12 +55,17 @@ OPTIONS:
     --url <url>      Reachable gateway URL to advertise in the bundle
                     (default: the assistant's runtime URL, not loopback)
     --label <name>   Human label for this pairing (echoed in the output)
+    --web            Create a browser pairing URL for remote web access
+    --web-approve <code>
+                    Approve a browser pairing code shown by /assistant/pair
     --json           Output the raw bundle as JSON
 
 EXAMPLES:
     vellum pair
     vellum pair "My Assistant" --label "phone"
     vellum pair --url https://abc123.ngrok.app
+    vellum pair --web --url https://abc123.ngrok.app
+    vellum pair --web-approve ABCD-EFGH
     vellum pair --json
 `);
 }
@@ -72,6 +82,71 @@ interface PairResponse {
   refreshAfter?: string;
 }
 
+interface RemoteWebPairingChallengeResponse {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  expiresAt: string;
+  expiresInSeconds: number;
+}
+
+interface RemoteWebPairingApprovalResponse {
+  status: "approved";
+  verificationUri: string;
+  expiresAt: string;
+}
+
+function normalizePublicBaseUrl(value: string): string {
+  const url = new URL(value);
+  url.search = "";
+  url.hash = "";
+  const parts = url.pathname.split("/").filter(Boolean);
+  const assistantIndex = parts.indexOf("assistant");
+  if (assistantIndex >= 0) {
+    parts.splice(assistantIndex);
+  }
+  url.pathname = parts.length ? `/${parts.join("/")}` : "/";
+  return url.toString().replace(/\/+$/, "");
+}
+
+function buildRemoteWebPairingUrl(
+  challenge: RemoteWebPairingChallengeResponse,
+): string {
+  const url = new URL(challenge.verificationUri);
+  url.hash = new URLSearchParams({
+    device_code: challenge.deviceCode,
+  }).toString();
+  return url.toString();
+}
+
+async function assertWebRemoteIngressEnabled(
+  assistantId: string,
+  runtimeUrl: string,
+): Promise<void> {
+  let enabled: boolean;
+  try {
+    enabled = await isAssistantFeatureFlagEnabled(
+      assistantId,
+      WEB_REMOTE_INGRESS_FLAG,
+      { runtimeUrl },
+    );
+  } catch (err) {
+    console.error(
+      `Error: could not verify the \`${WEB_REMOTE_INGRESS_FLAG}\` feature flag. Is the assistant running? Try \`vellum wake\` and retry. ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    process.exit(1);
+  }
+
+  if (!enabled) {
+    console.error(
+      `Error: ${formatFeatureFlagGateMessage(WEB_REMOTE_INGRESS_FLAG)}`,
+    );
+    process.exit(1);
+  }
+}
+
 export async function pair(): Promise<void> {
   const rawArgs = process.argv.slice(3);
 
@@ -81,12 +156,27 @@ export async function pair(): Promise<void> {
   }
 
   const jsonOutput = rawArgs.includes("--json");
-  let args = rawArgs.filter((a) => a !== "--json");
+  const webPairing = rawArgs.includes("--web");
+  const webApproval = rawArgs.includes("--web-approve");
+  let args = rawArgs.filter((a) => a !== "--json" && a !== "--web");
 
   const [label, afterLabel] = extractFlag(args, "--label");
-  const [urlOverride, afterUrl] = extractFlag(afterLabel, "--url");
+  const [webApproveCode, afterWebApprove] = extractFlag(
+    afterLabel,
+    "--web-approve",
+  );
+  const [urlOverride, afterUrl] = extractFlag(afterWebApprove, "--url");
   args = afterUrl;
 
+  if (webPairing && webApproveCode) {
+    console.error("Error: use either --web or --web-approve, not both.");
+    process.exit(1);
+  }
+  if (webApproval && !webApproveCode) {
+    console.error("Error: --web-approve requires a pairing code.");
+    process.exit(1);
+  }
+
   // Resolve the target. An explicit argument is matched by display name OR id
   // (with the standard ambiguity error); no argument falls back to the active
   // assistant. Join positional tokens so multi-word display names work even
@@ -126,7 +216,7 @@ export async function pair(): Promise<void> {
   // so without an explicit --url the bundle would point the other machine at
   // its own localhost. Refuse to advertise a loopback URL unless the user
   // explicitly passed one. (An explicit --url is trusted as-is.)
-  if (!urlOverride && isLoopbackHost(advertisedUrl)) {
+  if (!urlOverride && !webApproveCode && isLoopbackHost(advertisedUrl)) {
     const lan = getLocalLanIPv4();
     // Use THIS assistant's gateway port (not the global default) — second
     // local instances listen on a different port.
@@ -149,6 +239,126 @@ export async function pair(): Promise<void> {
     process.exit(1);
   }
 
+  if (webApproveCode) {
+    await assertWebRemoteIngressEnabled(entry.assistantId, mintUrl);
+
+    let response: Response;
+    try {
+      response = await loopbackSafeFetch(
+        `${mintUrl}/v1/remote-web/pairing-verification`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ userCode: webApproveCode }),
+        },
+      );
+    } catch (err) {
+      console.error(
+        `Error: could not reach the gateway at ${mintUrl} ` +
+          `(${err instanceof Error ? err.message : String(err)}).`,
+      );
+      console.error("Is the assistant running? Try `vellum wake`.");
+      process.exit(1);
+    }
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      console.error(
+        `Error: HTTP ${response.status}: ${body || response.statusText}`,
+      );
+      process.exit(1);
+    }
+
+    const result = (await response.json()) as RemoteWebPairingApprovalResponse;
+    if (jsonOutput) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log("Remote web pairing approved.");
+    console.log(`Expires: ${result.expiresAt}`);
+    return;
+  }
+
+  if (webPairing) {
+    await assertWebRemoteIngressEnabled(entry.assistantId, mintUrl);
+
+    let publicBaseUrl: string;
+    try {
+      publicBaseUrl = normalizePublicBaseUrl(advertisedUrl);
+    } catch {
+      console.error(`Error: invalid --url value '${advertisedUrl}'.`);
+      process.exit(1);
+    }
+
+    let response: Response;
+    try {
+      response = await loopbackSafeFetch(
+        `${mintUrl}/v1/remote-web/pairing-challenge`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ publicBaseUrl }),
+        },
+      );
+    } catch (err) {
+      console.error(
+        `Error: could not reach the gateway at ${mintUrl} ` +
+          `(${err instanceof Error ? err.message : String(err)}).`,
+      );
+      console.error("Is the assistant running? Try `vellum wake`.");
+      process.exit(1);
+    }
+
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      console.error(
+        `Error: HTTP ${response.status}: ${body || response.statusText}`,
+      );
+      process.exit(1);
+    }
+
+    const challenge =
+      (await response.json()) as RemoteWebPairingChallengeResponse;
+    const pairUrl = buildRemoteWebPairingUrl(challenge);
+
+    if (jsonOutput) {
+      console.log(
+        JSON.stringify(
+          {
+            pairUrl,
+            userCode: challenge.userCode,
+            verificationUri: challenge.verificationUri,
+            expiresAt: challenge.expiresAt,
+            expiresInSeconds: challenge.expiresInSeconds,
+          },
+          null,
+          2,
+        ),
+      );
+      return;
+    }
+
+    const displayName = entry.name || entry.assistantName || entry.assistantId;
+    console.log(`Created remote web pairing for ${displayName}.`);
+    console.log("");
+    console.log("Open this URL in the browser:");
+    console.log("");
+    console.log(`  ${pairUrl}`);
+    console.log("");
+    console.log("Approve this pairing locally when you're ready:");
+    console.log("");
+    const approveTarget = assistantName
+      ? `${JSON.stringify(assistantName)} `
+      : "";
+    console.log(`  Code: ${challenge.userCode}`);
+    console.log(
+      `  Run:  vellum pair ${approveTarget}--web-approve ${challenge.userCode}`,
+    );
+    console.log("");
+    console.log(`Expires: ${challenge.expiresAt}`);
+    return;
+  }
+
   // Fresh per-pairing device identity — each `vellum pair` is independently
   // revocable.
   const deviceId = nanoid();

package/src/lib/nginx-ingress.ts

@@ -255,8 +255,6 @@ function buildRemoteWebIngressLocations(opts: {
     location = /v1/pair/ { return 404; }
     location = /v1/pair/web-init { return 404; }
     location = /v1/pair/web-init/ { return 404; }
-    location = /v1/remote-web/pairing-challenge { return 404; }
-    location = /v1/remote-web/pairing-challenge/ { return 404; }
     location = /v1/devices { return 404; }
     location = /v1/devices/ { return 404; }
     location = /v1/devices/revoke { return 404; }
@@ -265,6 +263,8 @@ function buildRemoteWebIngressLocations(opts: {
     location = /v1/guardian/init/ { return 404; }
     location = /v1/guardian/reset-bootstrap { return 404; }
     location = /v1/guardian/reset-bootstrap/ { return 404; }
+    location = /v1/remote-web/pairing-verification { return 404; }
+    location = /v1/remote-web/pairing-verification/ { return 404; }
     location ^~ /assistant/__local/ { return 404; }
     location ^~ /assistant/__gateway/ { return 404; }
 

package/src/shared/provider-env-vars.ts

@@ -27,6 +27,7 @@ export const LLM_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   fireworks: "FIREWORKS_API_KEY",
   openrouter: "OPENROUTER_API_KEY",
   minimax: "MINIMAX_API_KEY",
+  atlascloud: "ATLASCLOUD_API_KEY",
 };
 
 /** Search-provider env var names. Mirrors `SEARCH_PROVIDER_CATALOG` BYOK entries. */
@@ -34,6 +35,7 @@ export const SEARCH_PROVIDER_ENV_VAR_NAMES: Record<string, string> = {
   perplexity: "PERPLEXITY_API_KEY",
   brave: "BRAVE_API_KEY",
   tavily: "TAVILY_API_KEY",
+  firecrawl: "FIRECRAWL_API_KEY",
 };
 
 /**