feat: improve browser use session controls

server/modules/browser-use/browser-use.routes.ts

@@ -119,6 +119,33 @@ router.post('/sessions/:sessionId/navigate', async (req: AuthenticatedRequest, r
   }
 });
 
+router.post('/sessions/:sessionId/click', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await browserUseService.userClick(requireUser(req), readParam(req.params.sessionId), {
+      x: Number(req.body?.x),
+      y: Number(req.body?.y),
+    });
+    res.json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to click browser session.',
+    });
+  }
+});
+
+router.post('/sessions/:sessionId/press-key', async (req: AuthenticatedRequest, res) => {
+  try {
+    const session = await browserUseService.userPressKey(requireUser(req), readParam(req.params.sessionId), String(req.body?.key || ''));
+    res.json({ success: true, data: { session } });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to send browser key input.',
+    });
+  }
+});
+
 router.post('/sessions/:sessionId/agent-access/grant', async (req: AuthenticatedRequest, res) => {
   try {
     const session = await browserUseService.grantAgentAccess(requireUser(req), readParam(req.params.sessionId));
@@ -155,4 +182,16 @@ router.post('/sessions/:sessionId/stop', async (req: AuthenticatedRequest, res)
   }
 });
 
+router.delete('/sessions/:sessionId', async (req: AuthenticatedRequest, res) => {
+  try {
+    const result = await browserUseService.deleteSession(requireUser(req), readParam(req.params.sessionId));
+    res.json({ success: true, data: result });
+  } catch (error) {
+    res.status(400).json({
+      success: false,
+      error: error instanceof Error ? error.message : 'Failed to delete browser session.',
+    });
+  }
+});
+
 export default router;

server/modules/browser-use/browser-use.service.ts

@@ -38,6 +38,15 @@ type BrowserUseSession = {
   message: string | null;
   agentAccessEnabled: boolean;
   profileName: string | null;
+  viewport: {
+    width: number;
+    height: number;
+  } | null;
+  cursor: {
+    x: number;
+    y: number;
+    actor: 'agent' | 'user';
+  } | null;
 };
 
 type PublicBrowserUseSession = Omit<BrowserUseSession, 'ownerId'>;
@@ -397,6 +406,10 @@ function ownerSessions(ownerId: string): BrowserUseSession[] {
   return [...sessions.values()].filter((session) => session.ownerId === ownerId);
 }
 
+function canAccessSession(ownerId: string, session: BrowserUseSession): boolean {
+  return session.ownerId === ownerId || session.ownerId === AGENT_OWNER_ID || session.agentAccessEnabled;
+}
+
 async function closeHandle(sessionId: string): Promise<void> {
   const handle = handles.get(sessionId);
   handles.delete(sessionId);
@@ -428,9 +441,36 @@ async function captureSession(session: BrowserUseSession, page: any): Promise<vo
   session.screenshotDataUrl = `data:image/jpeg;base64,${Buffer.from(screenshot).toString('base64')}`;
   session.title = await page.title().catch(() => null);
   session.url = page.url() || session.url;
+  session.viewport = page.viewportSize?.() || session.viewport;
   session.updatedAt = new Date().toISOString();
 }
 
+async function getActionPoint(page: any, input: { selector?: string; text?: string; x?: number; y?: number }) {
+  if (typeof input.x === 'number' && typeof input.y === 'number') {
+    return { x: input.x, y: input.y };
+  }
+
+  const locator = input.selector
+    ? page.locator(input.selector).first()
+    : input.text
+      ? page.getByText(input.text, { exact: false }).first()
+      : null;
+
+  if (!locator) {
+    return null;
+  }
+
+  const box = await locator.boundingBox().catch(() => null);
+  if (!box) {
+    return null;
+  }
+
+  return {
+    x: Math.round(box.x + box.width / 2),
+    y: Math.round(box.y + box.height / 2),
+  };
+}
+
 export const browserUseService = {
   async getSettings() {
     return readSettings();
@@ -530,7 +570,7 @@ export const browserUseService = {
     const ownerId = getOwnerId(owner);
     await expireStaleSessions();
     return [...sessions.values()]
-      .filter((session) => session.ownerId === ownerId || session.ownerId === AGENT_OWNER_ID || session.agentAccessEnabled)
+      .filter((session) => canAccessSession(ownerId, session))
       .map(publicSession);
   },
 
@@ -556,6 +596,8 @@ export const browserUseService = {
       message: null,
       agentAccessEnabled: options?.agentAccessEnabled ?? createdBy === 'agent',
       profileName,
+      viewport: { width: 1440, height: 900 },
+      cursor: null,
     };
 
     const activeOwnerSessions = ownerSessions(ownerId).filter((item) => item.status === 'ready');
@@ -667,7 +709,7 @@ export const browserUseService = {
     await expireStaleSessions();
 
     const session = sessions.get(sessionId);
-    if (!session || session.ownerId !== ownerId) {
+    if (!session || !canAccessSession(ownerId, session)) {
       throw new Error('Browser session not found.');
     }
 
@@ -683,6 +725,7 @@ export const browserUseService = {
     const url = await normalizeUrl(rawUrl);
     await handle.page.goto(url, { waitUntil: 'domcontentloaded', timeout: 30_000 });
     session.lastAction = `navigate:${url}`;
+    session.cursor = null;
     await captureSession(session, handle.page);
     return publicSession(session);
   },
@@ -726,6 +769,7 @@ export const browserUseService = {
     if (!handle?.page) {
       throw new Error('Browser runtime handle is not available.');
     }
+    const point = await getActionPoint(handle.page, input);
 
     if (input.selector) {
       await handle.page.locator(input.selector).first().click({ timeout: 10_000 });
@@ -738,6 +782,7 @@ export const browserUseService = {
     }
 
     session.lastAction = 'click';
+    session.cursor = point ? { ...point, actor: 'agent' } : null;
     await captureSession(session, handle.page);
     return publicSession(session);
   },
@@ -751,6 +796,9 @@ export const browserUseService = {
 
     if (input.selector) {
       await handle.page.locator(input.selector).first().fill(input.text, { timeout: 10_000 });
+      session.cursor = await getActionPoint(handle.page, input).then((point) => (
+        point ? { ...point, actor: 'agent' as const } : null
+      ));
     } else {
       await handle.page.keyboard.type(input.text);
     }
@@ -773,6 +821,11 @@ export const browserUseService = {
       await handle.page.locator(field.selector).first().fill(field.value, { timeout: 10_000 });
     }
     session.lastAction = 'fill_form';
+    if (fields[0]) {
+      session.cursor = await getActionPoint(handle.page, { selector: fields[0].selector }).then((point) => (
+        point ? { ...point, actor: 'agent' as const } : null
+      ));
+    }
     await captureSession(session, handle.page);
     return publicSession(session);
   },
@@ -797,6 +850,9 @@ export const browserUseService = {
     }
     await handle.page.locator(selector).first().selectOption(values, { timeout: 10_000 });
     session.lastAction = 'select_option';
+    session.cursor = await getActionPoint(handle.page, { selector }).then((point) => (
+      point ? { ...point, actor: 'agent' as const } : null
+    ));
     await captureSession(session, handle.page);
     return publicSession(session);
   },
@@ -864,7 +920,7 @@ export const browserUseService = {
   async stopSession(owner: BrowserUseOwner, sessionId: string) {
     const ownerId = getOwnerId(owner);
     const session = sessions.get(sessionId);
-    if (!session || (session.ownerId !== ownerId && session.ownerId !== AGENT_OWNER_ID && !session.agentAccessEnabled)) {
+    if (!session || !canAccessSession(ownerId, session)) {
       return { stopped: false };
     }
 
@@ -873,10 +929,65 @@ export const browserUseService = {
     session.status = 'stopped';
     session.updatedAt = new Date().toISOString();
     session.lastAction = 'stop';
-    session.message = 'Browser session stopped.';
+    session.message = 'Browser session stopped. Create a new session to continue browsing.';
     return { stopped: true, session: publicSession(session) };
   },
 
+  async deleteSession(owner: BrowserUseOwner, sessionId: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      return { deleted: false };
+    }
+
+    await closeHandle(sessionId);
+    sessions.delete(sessionId);
+    return { deleted: true, sessionId };
+  },
+
+  async userClick(owner: BrowserUseOwner, sessionId: string, input: { x: number; y: number }) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      throw new Error('Browser session not found.');
+    }
+    if (session.status !== 'ready') {
+      throw new Error(session.message || 'Browser session is not available.');
+    }
+
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+
+    await handle.page.mouse.click(input.x, input.y);
+    session.lastAction = 'click';
+    session.cursor = { x: input.x, y: input.y, actor: 'user' };
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
+  async userPressKey(owner: BrowserUseOwner, sessionId: string, key: string) {
+    const ownerId = getOwnerId(owner);
+    const session = sessions.get(sessionId);
+    if (!session || !canAccessSession(ownerId, session)) {
+      throw new Error('Browser session not found.');
+    }
+    if (session.status !== 'ready') {
+      throw new Error(session.message || 'Browser session is not available.');
+    }
+
+    const handle = handles.get(sessionId);
+    if (!handle?.page) {
+      throw new Error('Browser runtime handle is not available.');
+    }
+
+    await handle.page.keyboard.press(key);
+    session.lastAction = `press_key:${key}`;
+    await captureSession(session, handle.page);
+    return publicSession(session);
+  },
+
   async agentStopSession(sessionId: string) {
     await this.getAgentSession(sessionId);
     return this.stopSession({ id: AGENT_OWNER_ID }, sessionId);

src/components/browser-use/view/BrowserUsePanel.tsx

@@ -1,5 +1,5 @@
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import { Bot, Download, ExternalLink, Globe, Loader2, MonitorPlay, Navigation, Pause, RefreshCw, Share2, Square, X } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState, type KeyboardEvent, type MouseEvent } from 'react';
+import { Bot, Download, Expand, ExternalLink, Globe, Loader2, MonitorPlay, Navigation, RefreshCw, Share2, Square, Trash2, X } from 'lucide-react';
 
 import { Badge, Button } from '../../../shared/view/ui';
 import { authenticatedFetch } from '../../../utils/api';
@@ -29,6 +29,15 @@ type BrowserUseSession = {
   agentAccessEnabled: boolean;
   createdBy: 'user' | 'agent';
   profileName: string | null;
+  viewport: {
+    width: number;
+    height: number;
+  } | null;
+  cursor: {
+    x: number;
+    y: number;
+    actor: 'agent' | 'user';
+  } | null;
 };
 
 type BrowserUsePanelProps = {
@@ -50,7 +59,9 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
   const [targetUrl, setTargetUrl] = useState('https://example.com');
   const [isBusy, setIsBusy] = useState(false);
   const [isInstalling, setIsInstalling] = useState(false);
+  const [isFullscreen, setIsFullscreen] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const viewerRef = useRef<HTMLDivElement | null>(null);
 
   const selectedSession = useMemo(
     () => sessions.find((session) => session.id === selectedSessionId) || sessions[0] || null,
@@ -78,6 +89,11 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
     void refresh().catch((err) => setError(err instanceof Error ? err.message : 'Failed to load Browser Use'));
   }, [isVisible, refresh]);
 
+  useEffect(() => {
+    if (!selectedSession?.url) return;
+    setTargetUrl(selectedSession.url);
+  }, [selectedSession?.id, selectedSession?.url]);
+
   const runAction = useCallback(async (action: () => Promise<void>) => {
     setIsBusy(true);
     setError(null);
@@ -114,6 +130,13 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
     await readJson(response);
   });
 
+  const deleteSession = () => runAction(async () => {
+    if (!selectedSession) return;
+    const response = await authenticatedFetch(`/api/browser-use/sessions/${selectedSession.id}`, { method: 'DELETE' });
+    await readJson(response);
+    setIsFullscreen(false);
+  });
+
   const grantAgentAccess = () => runAction(async () => {
     if (!selectedSession) return;
     const response = await authenticatedFetch(`/api/browser-use/sessions/${selectedSession.id}/agent-access/grant`, { method: 'POST' });
@@ -126,7 +149,7 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
     await readJson(response);
   });
 
-  const installRuntime = () => runAction(async () => {
+  const installBrowserBinaries = () => runAction(async () => {
     setIsInstalling(true);
     try {
       const response = await authenticatedFetch('/api/browser-use/runtime/install', { method: 'POST' });
@@ -136,7 +159,99 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
     }
   });
 
-  const canInstallRuntime = Boolean(status?.enabled && (!status.playwrightInstalled || !status.chromiumInstalled));
+  const clickViewer = useCallback((event: MouseEvent<HTMLImageElement>) => {
+    if (!selectedSession || selectedSession.status !== 'ready' || !selectedSession.viewport) {
+      return;
+    }
+    viewerRef.current?.focus();
+
+    const bounds = event.currentTarget.getBoundingClientRect();
+    const scaleX = selectedSession.viewport.width / bounds.width;
+    const scaleY = selectedSession.viewport.height / bounds.height;
+    const x = Math.round((event.clientX - bounds.left) * scaleX);
+    const y = Math.round((event.clientY - bounds.top) * scaleY);
+
+    void runAction(async () => {
+      const response = await authenticatedFetch(`/api/browser-use/sessions/${selectedSession.id}/click`, {
+        method: 'POST',
+        body: JSON.stringify({ x, y }),
+      });
+      await readJson(response);
+    });
+  }, [runAction, selectedSession]);
+
+  const keyForEvent = useCallback((event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === ' ') return 'Space';
+    return event.key;
+  }, []);
+
+  const pressViewerKey = useCallback((event: KeyboardEvent<HTMLDivElement>) => {
+    if (!selectedSession || selectedSession.status !== 'ready') {
+      return;
+    }
+
+    const ignoredKeys = new Set(['Shift', 'Control', 'Alt', 'Meta', 'CapsLock']);
+    if (ignoredKeys.has(event.key)) {
+      return;
+    }
+
+    event.preventDefault();
+    const key = keyForEvent(event);
+    void runAction(async () => {
+      const response = await authenticatedFetch(`/api/browser-use/sessions/${selectedSession.id}/press-key`, {
+        method: 'POST',
+        body: JSON.stringify({ key }),
+      });
+      await readJson(response);
+    });
+  }, [keyForEvent, runAction, selectedSession]);
+
+  const needsBrowserBinaries = Boolean(status?.enabled && (!status.playwrightInstalled || !status.chromiumInstalled));
+
+  const cursorStyle = selectedSession?.cursor && selectedSession.viewport
+    ? {
+      left: `${(selectedSession.cursor.x / selectedSession.viewport.width) * 100}%`,
+      top: `${(selectedSession.cursor.y / selectedSession.viewport.height) * 100}%`,
+    }
+    : null;
+
+  const renderBrowserSurface = (fullscreen = false) => (
+    <div
+      ref={viewerRef}
+      tabIndex={selectedSession?.status === 'ready' ? 0 : -1}
+      onKeyDown={pressViewerKey}
+      className={`flex min-h-[360px] flex-1 items-center justify-center bg-neutral-950 outline-none ${fullscreen ? 'min-h-[80vh]' : ''}`}
+    >
+      {selectedSession?.screenshotDataUrl ? (
+        <div className="relative inline-block max-h-full">
+          <img
+            src={selectedSession.screenshotDataUrl}
+            alt="Browser session screenshot"
+            className={fullscreen ? 'block max-h-[80vh] w-auto max-w-full object-contain' : 'block max-h-[70vh] w-auto max-w-full object-contain'}
+            onClick={clickViewer}
+          />
+          {cursorStyle && (
+            <div
+              className="pointer-events-none absolute h-5 w-5 -translate-x-1/2 -translate-y-1/2 rounded-full border-2 border-white/90 bg-sky-500/80 shadow-[0_0_0_6px_rgba(14,165,233,0.18)]"
+              style={cursorStyle}
+            >
+              <div className="absolute left-1/2 top-1/2 h-2 w-2 -translate-x-1/2 -translate-y-1/2 rounded-full bg-white" />
+            </div>
+          )}
+        </div>
+      ) : (
+        <div className="max-w-md px-6 text-center">
+          <MonitorPlay className="mx-auto h-10 w-10 text-neutral-500" />
+          <div className="mt-3 text-sm font-medium text-neutral-100">
+            {selectedSession?.message || 'Create a browser session to start.'}
+          </div>
+          <p className="mt-2 text-xs leading-relaxed text-neutral-400">
+            Install browser binaries from this panel or enable Browser Use from Settings.
+          </p>
+        </div>
+      )}
+    </div>
+  );
 
   return (
     <div className="flex h-full min-h-0 flex-col bg-background">
@@ -164,21 +279,25 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
 
       <div className="grid min-h-0 flex-1 grid-cols-1 lg:grid-cols-[280px_minmax(0,1fr)]">
         <aside className="border-b border-border/60 p-3 lg:border-b-0 lg:border-r">
-          <div className="rounded-lg border border-border/70 bg-card/40 p-3">
-            <div className="text-xs font-medium uppercase tracking-wide text-muted-foreground">Runtime</div>
-            <div className="mt-2 text-sm text-foreground">{status?.available ? 'Available' : 'Setup required'}</div>
-            <p className="mt-1 text-xs leading-relaxed text-muted-foreground">{status?.message || 'Loading Browser Use status...'}</p>
-            {status?.enabled && (
-              <div className="mt-3 rounded-md border border-border/70 bg-background/60 px-2 py-2 text-xs text-muted-foreground">
-                Agent tools: {status.agentToolsEnabled ? 'enabled' : 'disabled in settings'}
+          {needsBrowserBinaries && (
+            <div className="rounded-lg border border-border/70 bg-card/40 p-3">
+              <div className="text-xs font-medium uppercase tracking-wide text-muted-foreground">Browser binaries required</div>
+              <p className="mt-2 text-xs leading-relaxed text-muted-foreground">
+                {status?.message || 'Install the browser binaries needed to create Browser Use sessions.'}
+              </p>
+              <div className="mt-3 flex flex-wrap gap-2 text-xs text-muted-foreground">
+                <span className="rounded-md border border-border px-2 py-1">
+                  Playwright: {status?.playwrightInstalled ? 'installed' : 'missing'}
+                </span>
+                <span className="rounded-md border border-border px-2 py-1">
+                  Chromium: {status?.chromiumInstalled ? 'installed' : 'missing'}
+                </span>
               </div>
-            )}
-            {canInstallRuntime && (
               <Button
                 type="button"
                 size="sm"
                 className="mt-3 w-full"
-                onClick={installRuntime}
+                onClick={installBrowserBinaries}
                 disabled={isBusy || isInstalling || status?.installInProgress}
               >
                 {isInstalling || status?.installInProgress ? (
@@ -186,10 +305,10 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
                 ) : (
                   <Download className="h-4 w-4" />
                 )}
-                Install Runtime
+                Install Binaries
               </Button>
-            )}
-          </div>
+            </div>
+          )}
 
           <div className="mt-3 space-y-2">
             <div className="rounded-lg border border-border/70 bg-muted/30 p-3 text-xs leading-relaxed text-muted-foreground">
@@ -212,17 +331,11 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
                   <Badge variant="outline" className="text-[10px]">{session.status}</Badge>
                 </div>
                 <div className="mt-1 flex flex-wrap gap-1">
-                  {session.createdBy === 'agent' && (
-                    <span className="rounded border border-primary/30 px-1.5 py-0.5 text-[10px] text-primary">agent</span>
-                  )}
                   {session.agentAccessEnabled && (
                     <span className="rounded border border-emerald-500/30 px-1.5 py-0.5 text-[10px] text-emerald-600 dark:text-emerald-300">
                       shared
                     </span>
                   )}
-                  {session.profileName && (
-                    <span className="rounded border border-border px-1.5 py-0.5 text-[10px]">profile: {session.profileName}</span>
-                  )}
                 </div>
                 <div className="mt-1 truncate text-xs">{session.url || session.message || session.id}</div>
               </button>
@@ -258,14 +371,18 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
                 Give Agent Access
               </Button>
             )}
-            <Button variant="outline" size="sm" disabled>
-              <Pause className="h-4 w-4" />
-              Pause
+            <Button variant="outline" size="sm" onClick={() => setIsFullscreen(true)} disabled={!selectedSession?.screenshotDataUrl}>
+              <Expand className="h-4 w-4" />
+              Full Screen
             </Button>
-            <Button variant="outline" size="sm" onClick={stopSession} disabled={isBusy || !selectedSession}>
+            <Button variant="outline" size="sm" onClick={stopSession} disabled={isBusy || !selectedSession || selectedSession.status !== 'ready'}>
               <Square className="h-4 w-4" />
               Stop
             </Button>
+            <Button variant="outline" size="sm" onClick={deleteSession} disabled={isBusy || !selectedSession}>
+              <Trash2 className="h-4 w-4" />
+              Delete
+            </Button>
           </div>
 
           {error && (
@@ -286,29 +403,25 @@ export default function BrowserUsePanel({ isVisible }: BrowserUsePanelProps) {
                   </span>
                 )}
               </div>
-              <div className="flex min-h-[360px] flex-1 items-center justify-center bg-neutral-950">
-                {selectedSession?.screenshotDataUrl ? (
-                  <img
-                    src={selectedSession.screenshotDataUrl}
-                    alt="Browser session screenshot"
-                    className="h-full max-h-[70vh] w-full object-contain"
-                  />
-                ) : (
-                  <div className="max-w-md px-6 text-center">
-                    <MonitorPlay className="mx-auto h-10 w-10 text-neutral-500" />
-                    <div className="mt-3 text-sm font-medium text-neutral-100">
-                      {selectedSession?.message || 'Create a browser session to start.'}
-                    </div>
-                    <p className="mt-2 text-xs leading-relaxed text-neutral-400">
-                      Install the Browser Use runtime from this panel or enable it from Settings.
-                    </p>
-                  </div>
-                )}
-              </div>
+              {renderBrowserSurface()}
             </div>
           </div>
         </main>
       </div>
+      {isFullscreen && selectedSession && (
+        <div className="fixed inset-0 z-50 bg-black/90 p-6">
+          <div className="flex h-full flex-col rounded-lg border border-white/10 bg-black">
+            <div className="flex items-center justify-between border-b border-white/10 px-4 py-3 text-sm text-white/80">
+              <div className="min-w-0 truncate">{selectedSession.title || selectedSession.url || 'Browser session'}</div>
+              <Button variant="outline" size="sm" onClick={() => setIsFullscreen(false)}>
+                <X className="h-4 w-4" />
+                Close
+              </Button>
+            </div>
+            {renderBrowserSurface(true)}
+          </div>
+        </div>
+      )}
     </div>
   );
 }

src/components/settings/view/tabs/browser-use-settings/BrowserUseSettingsTab.tsx

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useState } from 'react';
-import { Download, Loader2, MonitorPlay, RefreshCw } from 'lucide-react';
+import { Download, ExternalLink, Loader2 } from 'lucide-react';
 
 import { Button } from '../../../../../shared/view/ui';
 import { authenticatedFetch } from '../../../../../utils/api';
@@ -77,7 +77,7 @@ export default function BrowserUseSettingsTab() {
     }
   };
 
-  const installRuntime = async () => {
+  const installBrowserBinaries = async () => {
     setIsInstalling(true);
     setError(null);
     try {
@@ -85,13 +85,13 @@ export default function BrowserUseSettingsTab() {
       await readJson(response);
       await loadState();
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Failed to install Browser Use runtime');
+      setError(err instanceof Error ? err.message : 'Failed to install browser binaries');
     } finally {
       setIsInstalling(false);
     }
   };
 
-  const needsRuntime = Boolean(settings.enabled && status && (!status.playwrightInstalled || !status.chromiumInstalled));
+  const needsBrowserBinaries = Boolean(settings.enabled && status && (!status.playwrightInstalled || !status.chromiumInstalled));
 
   return (
     <div className="space-y-8">
@@ -100,6 +100,24 @@ export default function BrowserUseSettingsTab() {
         description="Manage local Playwright browser sessions used for captured browser screenshots and guarded navigation."
       >
         <SettingsCard divided>
+          <div className="flex flex-col gap-3 px-4 py-4 sm:flex-row sm:items-center sm:justify-between">
+            <div className="min-w-0">
+              <div className="text-sm font-medium text-foreground">How Browser Use Works</div>
+              <p className="mt-0.5 text-sm text-muted-foreground">
+                Learn what agents can do with browser sessions, when to share access, and what the current limitations are.
+              </p>
+            </div>
+            <a
+              href="https://cloudcli.ai/docs/user-guide/browser-use"
+              target="_blank"
+              rel="noreferrer"
+              className="inline-flex h-9 flex-shrink-0 items-center justify-center gap-2 rounded-md border border-input bg-background px-3 text-sm font-medium shadow-sm transition-colors hover:bg-accent hover:text-accent-foreground"
+            >
+              Open Guide
+              <ExternalLink className="h-4 w-4" />
+            </a>
+          </div>
+
           <SettingsRow
             label="Enable Browser Use"
             description="Allow CloudCLI to create owner-scoped Playwright browser sessions."
@@ -124,52 +142,49 @@ export default function BrowserUseSettingsTab() {
             />
           </SettingsRow>
 
-          <div className="space-y-4 px-4 py-4">
-            <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
-              <div className="min-w-0 space-y-1">
-                <div className="flex items-center gap-2 text-sm font-medium text-foreground">
-                  <MonitorPlay className="h-4 w-4 text-primary" />
-                  Runtime
-                </div>
-                <p className="text-sm text-muted-foreground">
-                  {status?.message || (isLoading ? 'Checking Browser Use runtime...' : 'Runtime status unavailable.')}
-                </p>
-                {status && (
-                  <div className="flex flex-wrap gap-2 pt-1 text-xs text-muted-foreground">
-                    <span className="rounded-md border border-border px-2 py-1">
-                      Playwright: {status.playwrightInstalled ? 'installed' : 'missing'}
-                    </span>
-                    <span className="rounded-md border border-border px-2 py-1">
-                      Chromium: {status.chromiumInstalled ? 'installed' : 'missing'}
-                    </span>
+          {(needsBrowserBinaries || error) && (
+            <div className="space-y-4 px-4 py-4">
+              {needsBrowserBinaries && (
+                <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+                  <div className="min-w-0 space-y-1">
+                    <div className="text-sm font-medium text-foreground">Browser binaries required</div>
+                    <p className="text-sm text-muted-foreground">
+                      {status?.message || 'Install the browser binaries needed to create Browser Use sessions.'}
+                    </p>
+                    <div className="flex flex-wrap gap-2 pt-1 text-xs text-muted-foreground">
+                      <span className="rounded-md border border-border px-2 py-1">
+                        Playwright: {status?.playwrightInstalled ? 'installed' : 'missing'}
+                      </span>
+                      <span className="rounded-md border border-border px-2 py-1">
+                        Chromium: {status?.chromiumInstalled ? 'installed' : 'missing'}
+                      </span>
+                    </div>
                   </div>
-                )}
-              </div>
 
-              <div className="flex flex-shrink-0 gap-2">
-                <Button type="button" variant="outline" size="sm" onClick={() => void loadState()} disabled={isLoading || isInstalling}>
-                  <RefreshCw className="h-4 w-4" />
-                  Refresh
-                </Button>
-                {needsRuntime && (
-                  <Button type="button" size="sm" onClick={() => void installRuntime()} disabled={isInstalling || status?.installInProgress}>
+                  <Button
+                    type="button"
+                    size="sm"
+                    onClick={() => void installBrowserBinaries()}
+                    disabled={isInstalling || status?.installInProgress}
+                    className="flex-shrink-0"
+                  >
                     {isInstalling || status?.installInProgress ? (
                       <Loader2 className="h-4 w-4 animate-spin" />
                     ) : (
                       <Download className="h-4 w-4" />
                     )}
-                    Install Runtime
+                    Install Binaries
                   </Button>
-                )}
-              </div>
-            </div>
+                </div>
+              )}
 
-            {error && (
-              <div className="rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700 dark:border-red-900/50 dark:bg-red-950/30 dark:text-red-200">
-                {error}
-              </div>
-            )}
-          </div>
+              {error && (
+                <div className="rounded-md border border-red-200 bg-red-50 px-3 py-2 text-sm text-red-700 dark:border-red-900/50 dark:bg-red-950/30 dark:text-red-200">
+                  {error}
+                </div>
+              )}
+            </div>
+          )}
         </SettingsCard>
       </SettingsSection>
     </div>