feat(ui-tars): local browser availability detection (#509)

ulivz · web-flow · commit 6e3204ac670d · 2025-04-20T00:36:07.000+08:00
diff --git a/apps/ui-tars/src/main/ipcRoutes/browser.ts b/apps/ui-tars/src/main/ipcRoutes/browser.ts
@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Bytedance, Inc. and its affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { initIpc } from '@ui-tars/electron-ipc/main';
+import { checkBrowserAvailability } from '../services/browserCheck';
+
+const t = initIpc.create();
+
+export const browserRoute = t.router({
+  checkBrowserAvailability: t.procedure.input<void>().handle(async () => {
+    return await checkBrowserAvailability();
+  }),
+});
diff --git a/apps/ui-tars/src/main/ipcRoutes/index.ts b/apps/ui-tars/src/main/ipcRoutes/index.ts
@@ -7,6 +7,7 @@ import { screenRoute } from './screen';
 import { windowRoute } from './window';
 import { permissionRoute } from './permission';
 import { agentRoute } from './agent';
+import { browserRoute } from './browser';
 
 const t = initIpc.create();
 
@@ -15,6 +16,7 @@ export const ipcRoutes = t.router({
   ...windowRoute,
   ...permissionRoute,
   ...agentRoute,
+  ...browserRoute,
 });
 export type Router = typeof ipcRoutes;
 
diff --git a/apps/ui-tars/src/main/main.ts b/apps/ui-tars/src/main/main.ts
@@ -34,6 +34,7 @@ import { createTray } from './tray';
 import { registerSettingsHandlers } from './services/settings';
 import { sanitizeState } from './utils/sanitizeState';
 import { windowManager } from './services/windowManager';
+import { checkBrowserAvailability } from './services/browserCheck';
 
 const { isProd } = env;
 
@@ -86,6 +87,8 @@ const initializeApp = async () => {
     logger.info('ensureScreenCapturePermission', ensureScreenCapturePermission);
   }
 
+  await checkBrowserAvailability();
+
   // if (env.isDev) {
   await loadDevDebugTools();
   // }
diff --git a/apps/ui-tars/src/main/services/browserCheck.ts b/apps/ui-tars/src/main/services/browserCheck.ts
@@ -0,0 +1,24 @@
+/**
+ * Copyright (c) 2025 Bytedance, Inc. and its affiliates.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { DefaultBrowserOperator } from '@ui-tars/operator-browser';
+import { logger } from '@main/logger';
+import { store } from '@main/store/create';
+
+/**
+ * Check if there is a browser available in the system
+ */
+export async function checkBrowserAvailability(): Promise<boolean> {
+  try {
+    logger.info('Checking browser availability...');
+    const available = DefaultBrowserOperator.hasBrowser();
+    logger.info(`Browser availability: ${available}`);
+    store.setState({ browserAvailable: available });
+    return available;
+  } catch (error) {
+    logger.error('Error checking browser availability:', error);
+    store.setState({ browserAvailable: false });
+    return false;
+  }
+}
diff --git a/apps/ui-tars/src/main/services/runAgent.ts b/apps/ui-tars/src/main/services/runAgent.ts
@@ -25,6 +25,7 @@ import {
 import { SettingStore } from '@main/store/setting';
 import { AppState, VLMProviderV2 } from '@main/store/types';
 import { GUIAgentManager } from '../ipcRoutes/agent';
+import { checkBrowserAvailability } from './browserCheck';
 
 const getModelVersion = (
   provider: VLMProviderV2 | undefined,
@@ -132,6 +133,17 @@ export const runAgent = async (
   if (settings.operator === 'nutjs') {
     operator = new NutJSElectronOperator();
   } else {
+    await checkBrowserAvailability();
+    const { browserAvailable } = getState();
+    if (!browserAvailable) {
+      setState({
+        ...getState(),
+        status: StatusEnum.ERROR,
+        errorMsg:
+          'Browser is not available. Please install Chrome and try again.',
+      });
+      return;
+    }
     operator = await DefaultBrowserOperator.getInstance(
       false,
       false,
diff --git a/apps/ui-tars/src/main/store/create.ts b/apps/ui-tars/src/main/store/create.ts
@@ -20,5 +20,6 @@ export const store = createStore<AppState>(
       ensurePermissions: {},
       abortController: null,
       thinking: false,
+      browserAvailable: false, // Defaults to false until the detection is complete
     }) satisfies AppState,
 );
diff --git a/apps/ui-tars/src/main/store/types.ts b/apps/ui-tars/src/main/store/types.ts
@@ -31,6 +31,7 @@ export type AppState = {
   messages: ConversationWithSoM[];
   abortController: AbortController | null;
   thinking: boolean;
+  browserAvailable: boolean;
 };
 
 export enum VlmProvider {
diff --git a/apps/ui-tars/src/renderer/src/components/ChatInput/SelectOperator.tsx b/apps/ui-tars/src/renderer/src/components/ChatInput/SelectOperator.tsx
@@ -2,8 +2,16 @@
  * Copyright (c) 2025 Bytedance, Inc. and its affiliates.
  * SPDX-License-Identifier: Apache-2.0
  */
+import { useEffect } from 'react';
 import { Button } from '@renderer/components/ui/button';
-import { ChevronDown, Globe, Monitor, Check } from 'lucide-react';
+import {
+  ChevronDown,
+  Globe,
+  Monitor,
+  Check,
+  AlertCircle,
+  RefreshCw,
+} from 'lucide-react';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -13,6 +21,15 @@ import {
 import { useSetting } from '@renderer/hooks/useSetting';
 import { useState } from 'react';
 import { BROWSER_USE, COMPUTERR_USE } from '@renderer/const';
+import { useStore } from '@renderer/hooks/useStore';
+import { api } from '@renderer/api';
+import { toast } from 'sonner';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@renderer/components/ui/tooltip';
 
 type Operator = 'nutjs' | 'browser';
 
@@ -40,18 +57,62 @@ const getOperatorLabel = (type: string) => {
 
 export const SelectOperator = () => {
   const [isOpen, setIsOpen] = useState(false);
+  const [tooltipOpen, setTooltipOpen] = useState(false);
+
   const { settings, updateSetting } = useSetting();
+  const { browserAvailable } = useStore();
+  const [isRetrying, setIsRetrying] = useState(false);
 
-  // console.log('settings', settings);
+  // Get the current operating mode and automatically
+  // switch to computer mode if browser mode is not available
+  const currentOperator = browserAvailable
+    ? settings.operator || 'nutjs'
+    : 'nutjs';
 
-  const currentOperator = settings.operator || 'nutjs';
+  // If the current setting is browser but the browser
+  // is not available, automatically switched to Computer Use mode.
+  useEffect(() => {
+    if (settings.operator === 'browser' && !browserAvailable) {
+      updateSetting({
+        ...settings,
+        operator: 'nutjs',
+      });
+      toast.info('Automatically switched to Computer Use mode', {
+        description: 'Browser mode is not available',
+      });
+    }
+  }, [browserAvailable, settings, updateSetting]);
 
   const handleSelect = (type: Operator) => {
+    if (type === 'browser' && !browserAvailable) {
+      return;
+    }
+
     updateSetting({
       ...settings,
       operator: type,
     });
-    console.log('handleSelect', type);
+  };
+
+  const handleRetryBrowserCheck = async () => {
+    try {
+      setIsRetrying(true);
+      const available = await api.checkBrowserAvailability();
+      if (available) {
+        toast.success('Browser detected successfully!', {
+          description: 'You can now use Browser mode.',
+        });
+        setTooltipOpen(false);
+      } else {
+        toast.error('No browser detected', {
+          description: 'Please install Chrome and try again.',
+        });
+      }
+    } catch (error) {
+      toast.error('Failed to check browser availability');
+    } finally {
+      setIsRetrying(false);
+    }
   };
 
   return (
@@ -74,13 +135,69 @@ export const SelectOperator = () => {
             Computer Use
             {currentOperator === 'nutjs' && <Check className="h-4 w-4 ml-2" />}
           </DropdownMenuItem>
-          <DropdownMenuItem onClick={() => handleSelect('browser')}>
-            <Globe className="h-4 w-4 mr-2" />
-            Browser Use
-            {currentOperator === 'browser' && (
-              <Check className="h-4 w-4 ml-2" />
+
+          <div className="relative">
+            <DropdownMenuItem
+              onClick={() => browserAvailable && handleSelect('browser')}
+              disabled={!browserAvailable}
+              className="flex items-center justify-start"
+            >
+              <Globe className="h-4 w-4 mr-2" />
+              Browser Use
+              {currentOperator === 'browser' && (
+                <Check className="h-4 w-4 ml-2" />
+              )}
+            </DropdownMenuItem>
+
+            {!browserAvailable && (
+              <div
+                className="absolute right-2 top-1/2 -translate-y-1/2"
+                onClick={(e) => e.stopPropagation()}
+              >
+                <TooltipProvider>
+                  <Tooltip open={tooltipOpen} onOpenChange={setTooltipOpen}>
+                    <TooltipTrigger asChild>
+                      <AlertCircle
+                        className="h-4 w-4 text-yellow-500"
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          setTooltipOpen(true);
+                        }}
+                      />
+                    </TooltipTrigger>
+                    <TooltipContent
+                      side="right"
+                      align="center"
+                      className="p-3 bg-white border border-gray-200 shadow-md w-64 z-50"
+                    >
+                      <div className="flex flex-col gap-3">
+                        <p className="text-sm text-gray-700 font-medium text-center">
+                          Chrome browser not detected.
+                        </p>
+                        <Button
+                          size="sm"
+                          variant="secondary"
+                          onClick={(e) => {
+                            e.preventDefault();
+                            e.stopPropagation();
+                            handleRetryBrowserCheck();
+                          }}
+                          disabled={isRetrying}
+                        >
+                          {isRetrying ? (
+                            <RefreshCw className="h-4 w-4 animate-spin" />
+                          ) : (
+                            <RefreshCw className="h-4 w-4" />
+                          )}
+                          {isRetrying ? 'Checking...' : 'Retry Detection'}
+                        </Button>
+                      </div>
+                    </TooltipContent>
+                  </Tooltip>
+                </TooltipProvider>
+              </div>
             )}
-          </DropdownMenuItem>
+          </div>
         </DropdownMenuContent>
       </DropdownMenu>
     </div>
diff --git a/apps/ui-tars/src/renderer/src/components/ui/tooltip.tsx b/apps/ui-tars/src/renderer/src/components/ui/tooltip.tsx
@@ -54,7 +54,7 @@ function TooltipContent({
         {...props}
       >
         {children}
-        <TooltipPrimitive.Arrow className="bg-primary fill-primary z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
+        <TooltipPrimitive.Arrow className="bg-white fill-white z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />
       </TooltipPrimitive.Content>
     </TooltipPrimitive.Portal>
   );
diff --git a/docs/quick-start.md b/docs/quick-start.md
@@ -6,6 +6,12 @@ The previous version of UI-TARS Desktop version 0.0.8 will be upgraded to a new
 
 <br />
 
+## Prerequisites
+
+- Install [Chrome](https://www.google.com/chrome/) for **Browser use**.
+
+<br />
+
 ## Download
 
 You can download the [latest release](https://github.com/bytedance/UI-TARS-desktop/releases/latest) version of UI-TARS Desktop from our releases page.
diff --git a/packages/ui-tars/operators/browser-operator/examples/default.ts b/packages/ui-tars/operators/browser-operator/examples/default.ts
@@ -5,9 +5,14 @@
 import { LocalBrowser } from '@agent-infra/browser';
 import { ConsoleLogger } from '@agent-infra/logger';
 import { GUIAgent, StatusEnum } from '@ui-tars/sdk';
-import { BrowserOperator } from '../src';
+import { BrowserOperator, DefaultBrowserOperator } from '../src';
 
 async function main() {
+  if (!DefaultBrowserOperator.hasBrowser()) {
+    console.error('No available browser found on this system.');
+    process.exit(1);
+  }
+
   // 1. Create a local browser
   const logger = new ConsoleLogger('[BrowserGUIAgent]');
   const browser = new LocalBrowser({
diff --git a/packages/ui-tars/operators/browser-operator/package.json b/packages/ui-tars/operators/browser-operator/package.json
@@ -36,6 +36,7 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "@agent-infra/browser": "workspace:*",
     "@agent-infra/logger": "workspace:*",
     "@ui-tars/sdk": "workspace:*"
   },
@@ -50,4 +51,4 @@
     "ts-node": "^10.9.2",
     "@types/big.js": "^6.2.2"
   }
-}
+}
diff --git a/packages/ui-tars/operators/browser-operator/src/browser-operator.ts b/packages/ui-tars/operators/browser-operator/src/browser-operator.ts
@@ -14,6 +14,7 @@ import type {
 } from '@ui-tars/sdk/core';
 import { BrowserOperatorOptions } from './types';
 import { UIHelper } from './ui-helper';
+import { BrowserFinder } from '@agent-infra/browser';
 
 const KEY_MAPPINGS: Record<string, string> = {
   enter: 'Enter',
@@ -501,6 +502,23 @@ export class DefaultBrowserOperator extends BrowserOperator {
     super(options);
   }
 
+  /**
+   * Check whether the local environment has a browser available
+   * @returns {boolean}
+   */
+  public static hasBrowser(): boolean {
+    try {
+      const browserFinder = new BrowserFinder();
+      browserFinder.findBrowser();
+      return true;
+    } catch (error) {
+      if (this.logger) {
+        this.logger.error('No available browser found:', error);
+      }
+      return false;
+    }
+  }
+
   public static async getInstance(
     highlight = false,
     showActionInfo = false,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

Original file line number	Diff line number	Diff line change
`@@ -54,7 +54,7 @@ function TooltipContent({`
`54`	`54`	`{...props}`
`55`	`55`	`>`
`56`	`56`	`{children}`
`57`		`- <TooltipPrimitive.Arrow className="bg-primary fill-primary z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />`
	`57`	`+ <TooltipPrimitive.Arrow className="bg-white fill-white z-50 size-2.5 translate-y-[calc(-50%_-_2px)] rotate-45 rounded-[2px]" />`
`58`	`58`	`</TooltipPrimitive.Content>`
`59`	`59`	`</TooltipPrimitive.Portal>`
`60`	`60`	`);`