refactor(mothership): one desktop-tool classifier and a typed claim for each claimant

The authorize and confirm routes classify desktop tools through
lib/mothership/tools/desktop-tools.ts instead of inline checks. The Sim
execution claim and the desktop claim share one run-admission lock but
return their own outcome types, so a Sim caller can no longer receive the
desktop-only awaiting_permission outcome. The terminal-status mapping moves
to lifecycle as getTerminalConfirmationStatus, since confirm uses it for
every client tool.

Author: waleedlatif1

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

@@ -1,7 +1,5 @@
 import type { Span } from '@opentelemetry/api'
-import { isBrowserToolName } from '@sim/browser-protocol'
 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 { type NextRequest, NextResponse } from 'next/server'
@@ -14,6 +12,7 @@ import {
   type AsyncCompletionData,
   type AsyncConfirmationStatus,
   type AsyncTerminalStatus,
+  getTerminalConfirmationStatus,
   isDeliveredAsyncStatus,
   isTerminalAsyncStatus,
   isWorkflowToolExecutionClaimable,
@@ -41,12 +40,11 @@ import {
 import { withIncomingGoSpan } from '@/lib/mothership/request/otel'
 import { sealClientToolSettlement } from '@/lib/mothership/request/tools/client-completion-seal.server'
 import { isWorkflowToolName } from '@/lib/mothership/tools/client-executed-tools'
-import { getDesktopToolClaimOwner } from '@/lib/mothership/tools/desktop-tools'
+import { getDesktopToolClaimOwner, isNativeDesktopTool } from '@/lib/mothership/tools/desktop-tools'
 import {
   createStructuralWorkflowToolCompletionData,
   getWorkflowToolCompletionExecutionId,
   getWorkflowToolCompletionMessage,
-  getWorkflowToolConfirmationStatus,
   getWorkflowToolLaunchError,
   resolveWorkflowToolTargetId,
   WORKFLOW_EXECUTION_BUSY,
@@ -92,7 +90,7 @@ function acknowledgeSettledToolCall(
   toolCallId: string,
   storedStatus: AsyncTerminalStatus
 ): NextResponse {
-  const settledStatus = getWorkflowToolConfirmationStatus(storedStatus)
+  const settledStatus = getTerminalConfirmationStatus(storedStatus)
   span.setAttributes({
     [TraceAttr.ToolConfirmationStatus]: settledStatus,
     [TraceAttr.CopilotConfirmOutcome]: CopilotConfirmOutcome.Delivered,
@@ -264,7 +262,7 @@ export const POST = withRouteHandler((req: NextRequest) => {
             return createNotFoundResponse('Completed workflow execution not found')
           }
 
-          const terminalStatus = getWorkflowToolConfirmationStatus(existing.status)
+          const terminalStatus = getTerminalConfirmationStatus(existing.status)
           span.setAttributes({
             [TraceAttr.ToolConfirmationStatus]: terminalStatus,
             [TraceAttr.CopilotConfirmOutcome]: CopilotConfirmOutcome.Delivered,
@@ -308,10 +306,7 @@ export const POST = withRouteHandler((req: NextRequest) => {
         const isErrorOrCancelledOutcome =
           status === ASYNC_TOOL_CONFIRMATION_STATUS.error ||
           status === ASYNC_TOOL_CONFIRMATION_STATUS.cancelled
-        const isNativeClientTool =
-          isBrowserToolName(existing.toolName) ||
-          isTerminalToolName(existing.toolName) ||
-          existing.toolName === 'import_local_files'
+        const isNativeClientTool = isNativeDesktopTool(existing.toolName)
         const nativeClaimOwner = getDesktopToolClaimOwner(existing.toolName)
         const isPreclaimNativeTerminalOutcome =
           nativeClaimOwner !== undefined &&
@@ -376,7 +371,7 @@ export const POST = withRouteHandler((req: NextRequest) => {
             executionId = claimedExecutionId
             if (status !== ASYNC_TOOL_CONFIRMATION_STATUS.background) {
               if (trustedExecution) {
-                effectiveStatus = getWorkflowToolConfirmationStatus(trustedExecution.status)
+                effectiveStatus = getTerminalConfirmationStatus(trustedExecution.status)
               } else if (!isErrorOrCancelledOutcome) {
                 span.setAttribute(
                   TraceAttr.CopilotConfirmOutcome,
@@ -389,7 +384,7 @@ export const POST = withRouteHandler((req: NextRequest) => {
             executionId = submittedExecutionId
           } else if (trustedExecution) {
             executionId = trustedExecution.executionId
-            effectiveStatus = getWorkflowToolConfirmationStatus(trustedExecution.status)
+            effectiveStatus = getTerminalConfirmationStatus(trustedExecution.status)
           } else if (!isErrorOrCancelledOutcome) {
             effectiveStatus = ASYNC_TOOL_CONFIRMATION_STATUS.error
             executionId = undefined

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

@@ -17,7 +17,7 @@ vi.mock('@/lib/mothership/async-runs/repository', () => mothershipAsyncRunsMock)
 
 import { POST } from './route'
 
-const claimToolExecution = mothershipAsyncRunsMockFns.mockClaimToolExecution
+const claimDesktopToolCall = mothershipAsyncRunsMockFns.mockClaimToolExecution
 const getAsyncToolCall = mothershipAsyncRunsMockFns.mockGetAsyncToolCall
 const getRunSegment = mothershipAsyncRunsMockFns.mockGetRunSegment
 const resolveInvocationWorkspace = mothershipWorkspaceTargetMockFns.mockResolveInvocationWorkspace
@@ -50,7 +50,7 @@ describe('desktop tool authorization', () => {
       userId: 'user-1',
       status: 'active',
     })
-    claimToolExecution.mockResolvedValue({ outcome: 'claimed' })
+    claimDesktopToolCall.mockResolvedValue({ outcome: 'claimed' })
   })
 
   it('never returns presentation activity as an executable browser argument', async () => {
@@ -193,7 +193,7 @@ describe('desktop tool authorization', () => {
       new OrchestrationError('not_found', 'Workspace not found')
     )
     expect((await POST(request('import-1', true))).status).toBe(404)
-    claimToolExecution.mockResolvedValueOnce({ outcome: 'existing' })
+    claimDesktopToolCall.mockResolvedValueOnce({ outcome: 'existing' })
     expect((await POST(request('import-1', true))).status).toBe(409)
   })
 

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

@@ -1,5 +1,3 @@
-import { isCurrentBrowserToolName } from '@sim/browser-protocol'
-import { isTerminalToolName } from '@sim/terminal-protocol'
 import { isRecordLike, omit } from '@sim/utils/object'
 import { type NextRequest, NextResponse } from 'next/server'
 import { authorizeDesktopToolContract } from '@/lib/api/contracts/desktop-tool-authorization'
@@ -9,18 +7,21 @@ import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { resolveInvocationWorkspace } from '@/lib/mothership/application/workspace-target'
 import { DESKTOP_TOOL_CLAIM_OWNER } from '@/lib/mothership/async-runs/lifecycle'
 import {
-  claimToolExecution,
+  claimDesktopToolCall,
+  type DesktopToolCallClaim,
   getAsyncToolCall,
   getRunSegment,
-  type ToolExecutionClaim,
 } from '@/lib/mothership/async-runs/repository'
 import {
   authenticateCopilotRequestSessionOnly,
   createNotFoundResponse,
   createUnauthorizedResponse,
 } from '@/lib/mothership/request/http'
-import { isLocalReadToolCall } from '@/lib/mothership/tools/desktop-tools'
-import { isUserLocalVfsToolCall } from '@/lib/mothership/tools/local-filesystem'
+import {
+  getDesktopToolClaimOwner,
+  isDesktopToolCall,
+  isLocalReadToolCall,
+} from '@/lib/mothership/tools/desktop-tools'
 
 const admissionClosedResponse = () =>
   NextResponse.json(
@@ -30,7 +31,7 @@ const admissionClosedResponse = () =>
 
 /** A refused claim answers the same way for every tool, except how each reports a lost race. */
 function refusedClaimResponse(
-  claim: Exclude<ToolExecutionClaim['outcome'], 'claimed'>,
+  claim: Exclude<DesktopToolCallClaim['outcome'], 'claimed'>,
   notPending: () => NextResponse
 ): NextResponse {
   if (claim === 'closed') return admissionClosedResponse()
@@ -75,16 +76,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   }
 
   const args = isRecordLike(toolCall.args) ? (toolCall.args as Record<string, unknown>) : {}
-  const isBrowserTool = isCurrentBrowserToolName(toolCall.toolName)
-  const isTerminalTool = isTerminalToolName(toolCall.toolName)
-  const isLocalFileTool =
-    toolCall.toolName === 'read_local_file' || toolCall.toolName === 'import_local_files'
-  const authorized =
-    isBrowserTool ||
-    isTerminalTool ||
-    isLocalFileTool ||
-    isUserLocalVfsToolCall(toolCall.toolName, args)
-  if (!authorized) {
+  if (!isDesktopToolCall(toolCall.toolName, args)) {
     return NextResponse.json(
       { error: 'Tool call is not authorized for desktop execution' },
       { status: 403 }
@@ -116,7 +108,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
           { status: 409 }
         )
       if (toolCall.status !== 'pending') return alreadyStarted()
-      const { outcome } = await claimToolExecution({
+      const { outcome } = await claimDesktopToolCall({
         toolCallId: toolCall.toolCallId,
         runId: toolCall.runId,
         userId,
@@ -136,7 +128,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   if (parsed.data.body.claim && isLocalReadToolCall(toolCall.toolName, args)) {
     const notPending = () => createNotFoundResponse('Pending client tool call not found')
     if (toolCall.status === 'pending') {
-      const { outcome } = await claimToolExecution({
+      const { outcome } = await claimDesktopToolCall({
         toolCallId: toolCall.toolCallId,
         runId: toolCall.runId,
         userId,
@@ -151,16 +143,18 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   // machine, so the pending call is claimed here, atomically, before crossing
   // the Electron boundary — a replayed renderer event must not run a command
   // or click a button twice.
-  if (isBrowserTool || isTerminalTool) {
+  const actionClaimOwner = getDesktopToolClaimOwner(toolCall.toolName)
+  if (
+    actionClaimOwner === DESKTOP_TOOL_CLAIM_OWNER.browser ||
+    actionClaimOwner === DESKTOP_TOOL_CLAIM_OWNER.terminal
+  ) {
     const notPending = () => createNotFoundResponse('Pending client tool call not found')
     if (toolCall.status !== 'pending') return notPending()
-    const { outcome } = await claimToolExecution({
+    const { outcome } = await claimDesktopToolCall({
       toolCallId: toolCall.toolCallId,
       runId: toolCall.runId,
       userId,
-      claimedBy: isBrowserTool
-        ? DESKTOP_TOOL_CLAIM_OWNER.browser
-        : DESKTOP_TOOL_CLAIM_OWNER.terminal,
+      claimedBy: actionClaimOwner,
     })
     if (outcome !== 'claimed') return refusedClaimResponse(outcome, notPending)
   }

apps/sim/lib/mothership/async-runs/lifecycle.ts

@@ -128,6 +128,15 @@ export function isWorkflowToolExecutionClaimable(
   )
 }
 
+/** The confirmation status a settled call reports: its durable terminal status, as the wire names it. */
+export function getTerminalConfirmationStatus(
+  status: AsyncTerminalStatus
+): AsyncConfirmationStatus {
+  if (status === ASYNC_TOOL_STATUS.completed) return ASYNC_TOOL_CONFIRMATION_STATUS.success
+  if (status === ASYNC_TOOL_STATUS.cancelled) return ASYNC_TOOL_CONFIRMATION_STATUS.cancelled
+  return ASYNC_TOOL_CONFIRMATION_STATUS.error
+}
+
 export function isTerminalAsyncStatus(
   status: CopilotAsyncToolStatus | AsyncLifecycleStatus | string | null | undefined
 ): status is AsyncTerminalStatus {