feat(desktop): keep the machine awake for background chats and yield the page to the user

- Prevent sleep: while any chat has desktop work claimed on this machine, the
  app holds a prevent-app-suspension power blocker, released as soon as the
  last result is delivered. On by default, with a switch in Desktop settings
  that notes a closed lid still sleeps the computer. The switch is a new
  optional bridge method, so older shells simply do not show it.
- Takeover: when the user clicks, scrolls or types in the page an agent drives,
  that chat's next browser action waits, marked as needing attention, until
  the user has left the page alone for a few seconds, then resumes in the same
  page. A Stop still cancels it while it waits.

Author: waleedlatif1

apps/desktop/e2e/background-executor.spec.ts

@@ -359,6 +359,11 @@ async function launch(userData: string): Promise<{ app: ElectronApplication; win
       SIM_DESKTOP_USER_DATA: userData,
     },
   })
+  // A dialog listener stops Playwright auto-dismissing page dialogs, so the desktop's own handling
+  // decides their outcome exactly as it does in production.
+  const leaveDialogsToDesktop = (page: Page) => page.on('dialog', () => {})
+  app.context().pages().forEach(leaveDialogsToDesktop)
+  app.context().on('page', leaveDialogsToDesktop)
   const window = await app.firstWindow()
   return { app, window }
 }
@@ -730,6 +735,78 @@ test.describe('background executor', () => {
       expect(device).toEqual({ deviceId, protocolVersion: 1 })
     })
   })
+
+  test('I: the agent yields its page while the user works in it, then takes it back', async () => {
+    app = (await launch(mkdtempSync(join(tmpdir(), 'sim-executor-i-')))).app
+    const deviceId = await registeredDevice()
+    const opened = sim.issue(deviceId, CHAT_A, 'browser_open_url', {
+      url: `${sim.origin}/counter?chat=I`,
+    })
+    const outline = ((await settled(opened)).data?.snapshot as { outline: string }).outline
+    const button = refFor(outline, 'Count visit')
+
+    const typeInAgentPage = () =>
+      app?.evaluate(({ webContents }) => {
+        const page = webContents
+          .getAllWebContents()
+          .find((contents) => contents.getURL().includes('/counter?chat=I'))
+        page?.sendInputEvent({ type: 'keyDown', keyCode: 'Tab' })
+        page?.sendInputEvent({ type: 'keyUp', keyCode: 'Tab' })
+      })
+    await typeInAgentPage()
+    const click = sim.issue(deviceId, CHAT_A, 'browser_click', { elementId: button })
+    for (let i = 0; i < 4; i++) {
+      await sleep(500)
+      await typeInAgentPage()
+    }
+    const lastUserInputAt = Date.now()
+
+    await check('I: the click waits until the user stops, then runs once', async () => {
+      const completion = await settled(click, 30_000)
+      expect(completion.status, completion.message).toBe('success')
+      expect(completion.at - lastUserInputAt).toBeGreaterThanOrEqual(3_000)
+      await expect.poll(() => sim.hits.get('I')).toBe(1)
+    })
+  })
+
+  test('J: the machine stays awake only while a chat has work running', async () => {
+    app = (await launch(mkdtempSync(join(tmpdir(), 'sim-executor-j-')))).app
+    await app.evaluate(({ powerSaveBlocker }) => {
+      const log: string[] = []
+      const active = new Set<number>()
+      let next = 1
+      const target = globalThis as typeof globalThis & { __sleepBlocks?: string[] }
+      target.__sleepBlocks = log
+      powerSaveBlocker.start = (type) => {
+        log.push(`start:${type}`)
+        active.add(next)
+        return next++
+      }
+      powerSaveBlocker.stop = (id) => {
+        log.push('stop')
+        active.delete(id)
+        return true
+      }
+      powerSaveBlocker.isStarted = (id) => active.has(id)
+    })
+    const deviceId = await registeredDevice()
+    const sleepLog = () =>
+      app?.evaluate(() => (globalThis as { __sleepBlocks?: string[] }).__sleepBlocks ?? [])
+
+    const run = sim.issue(deviceId, CHAT_B, 'terminal', {
+      operation: 'run',
+      args: { command: 'sleep 3; echo awake', waitSeconds: 30 },
+    })
+    await check('J: a blocker is held while the command runs', async () => {
+      await expect.poll(sleepLog, { timeout: 15_000 }).toEqual(['start:prevent-app-suspension'])
+    })
+    await check('J: it is released once the result is delivered', async () => {
+      await settled(run)
+      await expect
+        .poll(sleepLog, { timeout: 10_000 })
+        .toEqual(['start:prevent-app-suspension', 'stop'])
+    })
+  })
 })
 
 function readFileSafe(path: string): string {

apps/desktop/src/main/browser-agent/driver.ts

@@ -32,7 +32,7 @@ import {
 import type { BrowserDownloadsState, BrowserToolbarCommand } from '@sim/desktop-bridge'
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
-import { sleep } from '@sim/utils/helpers'
+import { interruptibleSleep, sleep } from '@sim/utils/helpers'
 import { isRecordLike, omit, toArray, toRecord } from '@sim/utils/object'
 import type { BrowserWindow, MenuItemConstructorOptions, WebContents, WebFrameMain } from 'electron'
 import { Menu } from 'electron'
@@ -5094,6 +5094,30 @@ function withNotices(result: unknown): unknown {
   return { value: result, notices }
 }
 
+/** Quiet time after the user's last click or keystroke before the agent takes the page back. */
+const USER_TAKEOVER_IDLE_MS = 4_000
+
+function isUserWorkingInPage(): boolean {
+  const since = session.msSinceUserIntervention()
+  return since !== null && since < USER_TAKEOVER_IDLE_MS
+}
+
+/**
+ * The user and the agent never act in the same page at once. While the user is clicking, typing
+ * or scrolling in the tab the agent drives, the agent's next action waits, marked as needing
+ * attention, and resumes once the user has left the page alone for a few seconds.
+ */
+async function yieldToUser(toolCallId: string | undefined, signal: AbortSignal): Promise<void> {
+  session.setAutomationNeedsAttention(true)
+  logger.info('Browser automation yielding to the user', { toolCallId })
+  while (isUserWorkingInPage()) {
+    await interruptibleSleep(250, signal)
+    if (signal.aborted) throw new ToolError('This browser action was cancelled.')
+  }
+  session.setAutomationNeedsAttention(false)
+  logger.info('Browser automation resumed after the user stopped', { toolCallId })
+}
+
 export async function executeTool(
   scopeId: string,
   tool: BrowserToolName,
@@ -5190,6 +5214,9 @@ export async function executeTool(
           session.setAutomationActive(true)
         }
         try {
+          if (tool !== 'browser_request_takeover' && isUserWorkingInPage()) {
+            await yieldToUser(toolCallId, executionController.signal)
+          }
           const response = dialogResponse(tool, params)
           state.dialogResponse = response
             ? { contents: session.requireAutomationTab().view.webContents, response }

apps/desktop/src/main/browser-agent/session.ts

@@ -298,6 +298,8 @@ interface BrowserScopeState {
    */
   findingTabId: string | null
   findingRequestId: number | null
+  /** When the user last clicked, scrolled or typed in the tab the agent drives. */
+  userInterventionAt: number | null
 }
 
 function createBrowserScopeState(): BrowserScopeState {
@@ -319,6 +321,7 @@ function createBrowserScopeState(): BrowserScopeState {
     automationNeedsAttention: false,
     findingTabId: null,
     findingRequestId: null,
+    userInterventionAt: null,
   }
 }
 
@@ -2368,6 +2371,7 @@ function initializeTabView(
         return
       }
       const tab = tabs.find((entry) => entry.view.webContents === contents)
+      if (tab?.id === currentScope.automationTabId) noteUserIntervention()
       if (tab?.id === currentScope.activeTabId) {
         currentScope.visibleTabUserSelected = true
         if (mouse.type === 'mouseDown') tab.lastRealUserGestureAt = Date.now()
@@ -2484,6 +2488,13 @@ function initializeTabView(
     'before-input-event',
     bindToBrowserScope(scopeId, (event, input) => {
       const tab = tabs.find((entry) => entry.view === view)
+      if (
+        !isDispatchingAgentInput(contents) &&
+        input.type === 'keyDown' &&
+        tab?.id === currentScope.automationTabId
+      ) {
+        noteUserIntervention()
+      }
       if (!isDispatchingAgentInput(contents) && tab?.id === currentScope.activeTabId) {
         currentScope.visibleTabUserSelected = true
         if (input.type === 'keyDown' && !input.isAutoRepeat) tab.lastRealUserGestureAt = Date.now()
@@ -3117,8 +3128,20 @@ export function claimActiveTabForUser(): AgentTab | null {
   return tab
 }
 
+/** The user just acted in the page the agent drives; the agent yields until they stop. */
+function noteUserIntervention(): void {
+  currentScope.userInterventionAt = Date.now()
+}
+
+/** How long ago the user last acted in the current scope's agent tab, or null if never. */
+export function msSinceUserIntervention(): number | null {
+  const at = currentScope.userInterventionAt
+  return at === null ? null : Math.max(0, Date.now() - at)
+}
+
 /** Explicit hand-back after takeover lets automation resume in the same page. */
 export function returnAutomationTabToAgent(): void {
+  currentScope.userInterventionAt = null
   if (currentScope.activeTabId === currentScope.automationTabId) {
     currentScope.visibleTabUserSelected = false
   }

apps/desktop/src/main/config.ts

@@ -104,6 +104,8 @@ export interface DesktopSettings {
   /** Whether omnibox typing may request live Google search completions. */
   browserSearchSuggestionsEnabled?: boolean
   terminalEnabled?: boolean
+  /** Keep the machine awake while a chat is running desktop work in the background. */
+  preventSleepWhileRunning?: boolean
   /** Device-wide browser page appearance; `app` follows Sim. */
   browserTheme?: 'app' | 'light' | 'dark'
   /** Device-wide default zoom for built-in browser pages. */
@@ -236,6 +238,7 @@ const DEFAULT_SETTINGS: DesktopSettings = {
   browserEnabled: true,
   browserSearchSuggestionsEnabled: true,
   terminalEnabled: true,
+  preventSleepWhileRunning: true,
 }
 
 export interface ConfigStore {

apps/desktop/src/main/desktop-executor/service.ts

@@ -52,6 +52,8 @@ export interface DesktopExecutorServiceDeps {
   accountDataAvailable: () => boolean
   runner: DesktopToolRunner
   onApprovals?: (items: DesktopApprovalItem[]) => void
+  /** Whether any chat has desktop work claimed on this machine changed. */
+  onBusyChange?: (busy: boolean) => void
 }
 
 export interface DesktopExecutorService {
@@ -183,6 +185,7 @@ export function createDesktopExecutorService(
         leaseRenewMs: nextTiming.leaseRenewMs,
         onUnregistered: handleUnrecognized,
         ...(deps.onApprovals ? { onApprovals: deps.onApprovals } : {}),
+        ...(deps.onBusyChange ? { onBusyChange: deps.onBusyChange } : {}),
       })
       await executor.recover()
       // Signed out while recovering: sign-out already disposed this executor.

apps/desktop/src/main/desktop-executor/sleep-blocker.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createSleepBlocker } from '@/main/desktop-executor/sleep-blocker'
+
+function harness(enabled = true) {
+  let nextId = 1
+  const active = new Set<number>()
+  const powerSaveBlocker = {
+    start: vi.fn(() => {
+      const id = nextId++
+      active.add(id)
+      return id
+    }),
+    stop: vi.fn((id: number) => {
+      active.delete(id)
+    }),
+    isStarted: (id: number) => active.has(id),
+  }
+  let preference = enabled
+  const blocker = createSleepBlocker({ enabled: () => preference, powerSaveBlocker })
+  return {
+    blocker,
+    powerSaveBlocker,
+    active,
+    setPreference: (value: boolean) => {
+      preference = value
+      blocker.refresh()
+    },
+  }
+}
+
+describe('keeping the machine awake for background work', () => {
+  it('holds one blocker only while a chat has work running', () => {
+    const { blocker, powerSaveBlocker, active } = harness()
+
+    blocker.setBusy(true)
+    blocker.setBusy(true)
+    expect(active.size).toBe(1)
+    expect(powerSaveBlocker.start).toHaveBeenCalledWith('prevent-app-suspension')
+
+    blocker.setBusy(false)
+    expect(active.size).toBe(0)
+  })
+
+  it('never holds one while the user has switched it off, and follows the switch live', () => {
+    const { blocker, active, setPreference } = harness(false)
+
+    blocker.setBusy(true)
+    expect(active.size).toBe(0)
+
+    setPreference(true)
+    expect(active.size).toBe(1)
+    setPreference(false)
+    expect(active.size).toBe(0)
+  })
+
+  it('does not start one for an idle machine when the switch turns on', () => {
+    const { active, setPreference } = harness(false)
+
+    setPreference(true)
+
+    expect(active.size).toBe(0)
+  })
+})

apps/desktop/src/main/desktop-executor/sleep-blocker.ts

@@ -0,0 +1,45 @@
+/**
+ * Keeps the machine from idle-sleeping while a chat has desktop work running in the background,
+ * and only then. It cannot keep a closed laptop awake: the OS sleeps it anyway, and the work
+ * resumes reporting when it wakes.
+ */
+
+interface PowerSaveBlocker {
+  start(type: 'prevent-app-suspension'): number
+  stop(id: number): void
+  isStarted(id: number): boolean
+}
+
+interface SleepBlockerDeps {
+  /** The user's "prevent sleep while a chat is running" switch. */
+  enabled: () => boolean
+  powerSaveBlocker: PowerSaveBlocker
+}
+
+export function createSleepBlocker(deps: SleepBlockerDeps) {
+  let busy = false
+  let blockerId: number | null = null
+
+  const apply = () => {
+    const wanted = busy && deps.enabled()
+    const held = blockerId !== null && deps.powerSaveBlocker.isStarted(blockerId)
+    if (wanted && !held) {
+      blockerId = deps.powerSaveBlocker.start('prevent-app-suspension')
+    } else if (!wanted && blockerId !== null) {
+      if (held) deps.powerSaveBlocker.stop(blockerId)
+      blockerId = null
+    }
+  }
+
+  return {
+    /** Whether any chat has desktop work claimed on this machine. */
+    setBusy(next: boolean): void {
+      busy = next
+      apply()
+    },
+    /** Re-applies the user's switch to the work running now. */
+    refresh(): void {
+      apply()
+    },
+  }
+}

apps/desktop/src/main/desktop-settings.ts

@@ -37,6 +37,7 @@ export interface DesktopSettingsService {
   getPreferences(): DesktopPreferences
   setPreference(key: DesktopPreferenceKey, value: boolean): DesktopPreferences
   setBrowserSearchSuggestionsEnabled(enabled: boolean): DesktopPreferences
+  setPreventSleepWhileRunning(enabled: boolean): DesktopPreferences
   setAppearancePreference(
     key: DesktopAppearanceSettingKey,
     value: DesktopAppearanceTheme
@@ -60,6 +61,8 @@ interface DesktopSettingsServiceDeps {
   setBrowserEnabled: (enabled: boolean) => void
   /** Ends every open agent shell when the surface is turned off. */
   setTerminalEnabled: (enabled: boolean) => void
+  /** Starts or stops keeping the machine awake for background work already running. */
+  setPreventSleepWhileRunning: (enabled: boolean) => void
   /** Repaints current browser tabs when their persisted appearance changes. */
   setBrowserTheme: (theme: DesktopAppearanceTheme) => void
   /** Applies a new default zoom to current and future browser tabs. */
@@ -93,6 +96,7 @@ function readPreferences(
     browserEnabled: config.get('browserEnabled') ?? true,
     browserSearchSuggestionsEnabled: config.get('browserSearchSuggestionsEnabled') ?? true,
     terminalEnabled: config.get('terminalEnabled') ?? true,
+    preventSleepWhileRunning: config.get('preventSleepWhileRunning') ?? true,
     browserTheme: isDesktopAppearanceTheme(browserTheme) ? browserTheme : 'app',
     browserDefaultZoom: isDesktopZoomPercent(browserDefaultZoom) ? browserDefaultZoom : 100,
     browserDownloadDirectory:
@@ -160,6 +164,12 @@ export function createDesktopSettingsService(
       deps.config.flush()
       return read()
     },
+    setPreventSleepWhileRunning(enabled) {
+      deps.config.set('preventSleepWhileRunning', enabled)
+      deps.config.flush()
+      deps.setPreventSleepWhileRunning(enabled)
+      return read()
+    },
     setAppearancePreference(key, value) {
       const previousBrowserTheme = key === 'browserTheme' ? read().browserTheme : undefined
       deps.config.set(key, value)