feat(desktop): bind turns to a desktop and supervise their calls in the background

Wires the run loop to the background executor protocol, still inert until a
desktop that speaks it registers with the flag on:

- A desktop composer whose shell has a background executor sends its device
  id and protocol version. Admission binds the run to that device only when
  the flag is on for the user and the device is registered, as an executor,
  to the caller's own session; otherwise the turn stays with the chat view.
- On a bound run every desktop call is persisted pending. Once it may run, a
  supervisor offers it to the device and rings its doorbell, fails it at once
  as not started when the device is offline, fails it as not started when no
  one claims it within 15 s, and fails it as outcome unknown when a claimed
  call's lease lapses. Every failure is sealed like a device result and woken
  through the confirmation channel. A gated call rings an approval doorbell.
- The resume gate leaves bound desktop calls to that supervisor, so a long
  terminal command lives as long as the device renews its lease, and the Sim
  tool lease sweep no longer claims executor leases.
- The chat view's authorize and confirm routes refuse a bound run's calls,
  and Stop rings the device so it cancels what it is running.

Author: waleedlatif1

apps/sim/app/api/copilot/confirm/route.test.ts

@@ -131,6 +131,26 @@ describe('Copilot Confirm API Route', () => {
     expect(JSON.stringify(publishToolConfirmation.mock.calls)).not.toContain('resolved-secret')
   })
 
+  it("refuses a chat view's failure for a call a desktop's background executor owns", async () => {
+    getAsyncToolCall.mockResolvedValue({
+      ...existingRow,
+      toolName: 'browser_click',
+      status: 'pending',
+      claimedBy: null,
+    })
+    getRunSegment.mockResolvedValue({ id: 'run-1', userId: 'user-1', desktopDeviceId: 'device-1' })
+
+    const response = await POST(
+      createMockPostRequest({
+        toolCallId: 'tool-call-123',
+        status: 'error',
+        message: 'The desktop refused this claim',
+      })
+    )
+
+    expect(response.status).toBe(409)
+  })
+
   it('atomically detaches a live background confirmation', async () => {
     const response = await POST(
       createMockPostRequest({

apps/sim/app/api/copilot/confirm/route.ts

@@ -2,11 +2,12 @@ import { isBrowserToolName, isCurrentBrowserToolName } from '@sim/browser-protoc
 import { createLogger } from '@sim/logger'
 import { isTerminalToolName } from '@sim/terminal-protocol'
 import { getErrorMessage, toError } from '@sim/utils/errors'
-import { isPlainRecord } from '@sim/utils/object'
+import { isPlainRecord, toRecord } from '@sim/utils/object'
 import { type NextRequest, NextResponse } from 'next/server'
 import { copilotConfirmContract } from '@/lib/api/contracts/copilot'
 import { parseRequest, validationErrorResponse } from '@/lib/api/server'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { isDesktopExecutorTool } from '@/lib/desktop/executor/tools'
 import {
   ASYNC_TOOL_CONFIRMATION_STATUS,
   ASYNC_TOOL_STATUS,
@@ -228,6 +229,20 @@ export const POST = withRouteHandler((req: NextRequest) => {
           return NextResponse.json({ error: 'Forbidden' }, { status: 403 })
         }
 
+        if (
+          run.desktopDeviceId &&
+          isDesktopExecutorTool(existing.toolName, toRecord(existing.args))
+        ) {
+          span.setAttribute(TraceAttr.CopilotConfirmOutcome, CopilotConfirmOutcome.Forbidden)
+          return NextResponse.json(
+            {
+              error:
+                "This chat's desktop actions report through the desktop app's background executor",
+            },
+            { status: 409 }
+          )
+        }
+
         const isWorkflowTool = isWorkflowToolName(existing.toolName || '')
         const workflowId = isWorkflowTool
           ? resolveWorkflowToolTargetId(existing.args, run.workflowId)

apps/sim/app/api/desktop/tool/authorize/route.test.ts

@@ -72,6 +72,26 @@ describe('desktop tool authorization', () => {
     })
   })
 
+  it("refuses a chat view's claim on a run bound to a desktop's background executor", async () => {
+    getAsyncToolCall.mockResolvedValueOnce({
+      toolCallId: 'bound-click',
+      runId: 'run-1',
+      status: 'pending',
+      toolName: 'browser_click',
+      args: { ref: 'e1' },
+    })
+    getRunSegment.mockResolvedValueOnce({
+      id: 'run-1',
+      chatId: 'chat-1',
+      userId: 'user-1',
+      status: 'active',
+      desktopDeviceId: 'device-1',
+    })
+
+    const response = await POST(request('bound-click'))
+    expect(response.status).toBe(409)
+  })
+
   it('rejects retired browser tools retained only for history', async () => {
     getAsyncToolCall.mockResolvedValueOnce({
       toolCallId: 'retired-browser-tool',

apps/sim/app/api/desktop/tool/authorize/route.ts

@@ -47,6 +47,12 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   if (run.status === 'complete' || run.status === 'error' || run.status === 'cancelled') {
     return createNotFoundResponse('Pending client tool call not found')
   }
+  // The device's background executor claims a bound run's calls through its own fenced route.
+  if (run.desktopDeviceId)
+    return NextResponse.json(
+      { error: "This chat's desktop actions run in the desktop app's background executor" },
+      { status: 409 }
+    )
 
   const args = isRecordLike(toolCall.args) ? (toolCall.args as Record<string, unknown>) : {}
   const isBrowserTool = isCurrentBrowserToolName(toolCall.toolName)

apps/sim/lib/desktop/application/executor.ts

@@ -32,6 +32,7 @@ import {
 import {
   acknowledgeDesktopCallResult,
   claimOfferedDesktopCall,
+  getBindableDesktopDevice,
   getBoundDesktopCall,
   getBoundDesktopDevice,
   listDesktopInboxRows,
@@ -70,6 +71,31 @@ async function isDesktopBackgroundExecutorEnabled(userId: string): Promise<boole
   return isFeatureEnabled('mothership-desktop-background-executor', { userId })
 }
 
+/**
+ * The device a new turn binds to: the composer's own, but only while the executor is on for this
+ * user and the device is registered to this very session as an executor. Anything else leaves
+ * the turn to the chat view, as before the executor existed.
+ */
+export async function resolveTurnDesktopDevice(
+  principal: SessionPrincipal,
+  deviceId: string
+): Promise<string | null> {
+  if (!(await isDesktopBackgroundExecutorEnabled(principal.userId))) return null
+  const device = await getBindableDesktopDevice({
+    deviceId,
+    userId: principal.userId,
+    sessionId: principal.sessionId,
+  })
+  if (!device) {
+    logger.warn('Turn not bound: its desktop is not registered to this session', {
+      userId: principal.userId,
+      deviceId,
+    })
+    return null
+  }
+  return device.id
+}
+
 export interface RegisterDesktopDeviceInput extends DeviceInput {
   name: string
   appVersion: string

apps/sim/lib/desktop/executor/repository.ts

@@ -410,3 +410,147 @@ export async function acknowledgeDesktopCallResult(input: {
     return { outcome: 'superseded', status: row.status }
   })
 }
+
+/** A device the caller may bind a new turn to: theirs, on this session, and able to execute. */
+export async function getBindableDesktopDevice(identity: DesktopDeviceIdentity) {
+  const [row] = await db
+    .select({ id: desktopDevices.id })
+    .from(desktopDevices)
+    .where(
+      and(
+        eq(desktopDevices.id, identity.deviceId),
+        eq(desktopDevices.userId, identity.userId),
+        eq(desktopDevices.sessionId, identity.sessionId),
+        isNull(desktopDevices.revokedAt),
+        sql`coalesce((${desktopDevices.capabilities} ->> 'executor')::int, 0) >= 1`
+      )
+    )
+    .limit(1)
+  return row ?? null
+}
+
+/** The device a run's desktop calls are bound to, or null for a run the chat view serves. */
+export async function getRunDesktopDeviceId(runId: string): Promise<string | null> {
+  const [row] = await db
+    .select({ desktopDeviceId: copilotRuns.desktopDeviceId })
+    .from(copilotRuns)
+    .where(eq(copilotRuns.id, runId))
+    .limit(1)
+  return row?.desktopDeviceId ?? null
+}
+
+/**
+ * Offers a pending call to its device by opening its pickup window. Only an unowned pending call
+ * on a bound run can be offered, and only once.
+ */
+export async function offerDesktopCall(input: {
+  toolCallId: string
+  runId: string
+  pickupGraceMs: number
+}): Promise<boolean> {
+  const [row] = await db
+    .update(copilotAsyncToolCalls)
+    .set({
+      executionLeaseExpiresAt: sql`clock_timestamp() + ${input.pickupGraceMs} * interval '1 millisecond'`,
+    })
+    .where(
+      and(
+        eq(copilotAsyncToolCalls.toolCallId, input.toolCallId),
+        eq(copilotAsyncToolCalls.runId, input.runId),
+        eq(copilotAsyncToolCalls.status, ASYNC_TOOL_STATUS.pending),
+        isNull(copilotAsyncToolCalls.executionOwnerToken),
+        isNull(copilotAsyncToolCalls.executionLeaseExpiresAt),
+        sql`EXISTS (SELECT 1 FROM ${copilotRuns} r WHERE r.id = ${copilotAsyncToolCalls.runId}
+          AND r.desktop_device_id IS NOT NULL)`
+      )
+    )
+    .returning({ toolCallId: copilotAsyncToolCalls.toolCallId })
+  return Boolean(row)
+}
+
+/** Where a supervised call stands, measured on the database clock every CAS uses. */
+export async function getDesktopCallState(toolCallId: string) {
+  const [row] = await db
+    .select({
+      status: copilotAsyncToolCalls.status,
+      ownerToken: copilotAsyncToolCalls.executionOwnerToken,
+      result: copilotAsyncToolCalls.result,
+      msUntilLeaseEnd: sql<
+        number | null
+      >`(extract(epoch from (${copilotAsyncToolCalls.executionLeaseExpiresAt} - clock_timestamp())) * 1000)::float8`,
+    })
+    .from(copilotAsyncToolCalls)
+    .where(eq(copilotAsyncToolCalls.toolCallId, toolCallId))
+    .limit(1)
+  return row ?? null
+}
+
+interface DesktopCallFailure {
+  toolCallId: string
+  runId: string
+  result: AsyncCompletionData
+  error: string
+}
+
+/**
+ * Fails a call nobody claimed: the inverse CAS of the claim, so exactly one of the two wins.
+ * `deadlinePassed` limits it to a call whose pickup window has closed.
+ */
+export async function failUnclaimedDesktopCall(
+  input: DesktopCallFailure & { deadlinePassed: boolean }
+): Promise<boolean> {
+  const [row] = await db
+    .update(copilotAsyncToolCalls)
+    .set({
+      status: ASYNC_TOOL_STATUS.failed,
+      result: sanitizeValueForJsonb(input.result),
+      error: input.error,
+      completedAt: sql`now()`,
+      updatedAt: sql`now()`,
+    })
+    .where(
+      and(
+        eq(copilotAsyncToolCalls.toolCallId, input.toolCallId),
+        eq(copilotAsyncToolCalls.runId, input.runId),
+        eq(copilotAsyncToolCalls.status, ASYNC_TOOL_STATUS.pending),
+        isNull(copilotAsyncToolCalls.executionOwnerToken),
+        input.deadlinePassed
+          ? sql`${copilotAsyncToolCalls.executionLeaseExpiresAt} <= clock_timestamp()`
+          : undefined
+      )
+    )
+    .returning({ toolCallId: copilotAsyncToolCalls.toolCallId })
+  return Boolean(row)
+}
+
+/**
+ * Fails a claimed call whose lease lapsed with this token still on it. The token stays on the row,
+ * so the device's late result is answered as superseded and acknowledges the cancellation.
+ */
+export async function failLapsedDesktopCall(
+  input: DesktopCallFailure & { ownerToken: string }
+): Promise<boolean> {
+  const [row] = await db
+    .update(copilotAsyncToolCalls)
+    .set({
+      status: ASYNC_TOOL_STATUS.failed,
+      result: sanitizeValueForJsonb(input.result),
+      error: input.error,
+      claimedBy: null,
+      claimedAt: null,
+      completedAt: sql`now()`,
+      updatedAt: sql`now()`,
+    })
+    .where(
+      and(
+        eq(copilotAsyncToolCalls.toolCallId, input.toolCallId),
+        eq(copilotAsyncToolCalls.runId, input.runId),
+        eq(copilotAsyncToolCalls.status, ASYNC_TOOL_STATUS.running),
+        eq(copilotAsyncToolCalls.executionOwnerToken, input.ownerToken),
+        isNull(copilotAsyncToolCalls.executionRevokedAt),
+        sql`${copilotAsyncToolCalls.executionLeaseExpiresAt} <= clock_timestamp()`
+      )
+    )
+    .returning({ toolCallId: copilotAsyncToolCalls.toolCallId })
+  return Boolean(row)
+}