fix(copilot): surface actionable server tool errors

Author: Sg312

apps/sim/lib/copilot/tools/server/files/doc-extract.ts

@@ -1,3 +1,4 @@
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { CodeLanguage } from '@/lib/execution/languages'
 import { executeInSandbox } from '@/lib/execution/remote-sandbox'
 
@@ -28,7 +29,10 @@ export interface DocExtract {
 export async function extractDocText(args: { binary: Buffer; ext: string }): Promise<DocExtract> {
   const ext = args.ext.toLowerCase()
   if (!isExtractableDocExt(ext)) {
-    throw new Error(`Cannot extract text from .${ext} (supported: pdf, pptx, docx, xlsx)`)
+    throw new OrchestrationError(
+      'validation',
+      `Cannot extract text from .${ext} (supported: pdf, pptx, docx, xlsx)`
+    )
   }
 
   const script = `
@@ -102,7 +106,7 @@ print("__SIM_RESULT__=" + json.dumps({"text": text}))
   })
 
   if (result.error) {
-    throw new Error(`Document extraction failed: ${result.error}`)
+    throw new OrchestrationError('validation', `Document extraction failed: ${result.error}`)
   }
   const payload = result.result as { text?: string } | null
   const full = payload?.text ?? ''

apps/sim/lib/copilot/tools/server/files/doc-render.ts

@@ -1,3 +1,4 @@
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { CodeLanguage } from '@/lib/execution/languages'
 import { executeInSandbox } from '@/lib/execution/remote-sandbox'
 
@@ -37,7 +38,10 @@ export async function renderDocToGrid(args: {
 }): Promise<DocRender> {
   const ext = args.ext.toLowerCase()
   if (!isRenderableDocExt(ext)) {
-    throw new Error(`Cannot render .${ext} to images (supported: pptx, docx, pdf)`)
+    throw new OrchestrationError(
+      'validation',
+      `Cannot render .${ext} to images (supported: pptx, docx, pdf)`
+    )
   }
 
   const script = `
@@ -99,7 +103,7 @@ else:
   })
 
   if (result.error) {
-    throw new Error(`Document render failed: ${result.error}`)
+    throw new OrchestrationError('validation', `Document render failed: ${result.error}`)
   }
   const payload = result.result as { grid?: string | null; pageCount?: number } | null
   if (!payload?.grid) {

apps/sim/lib/copilot/tools/server/files/file-folder-application.ts

@@ -1,5 +1,6 @@
 import { executeCopilotFileUseCase } from '@/lib/copilot/application/execute-file-use-case'
 import type { CopilotFileDelegationContext } from '@/lib/copilot/auth/file-delegation'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { findWorkspaceFileFolderIdByPath } from '@/lib/uploads/contexts/workspace/workspace-file-folder-manager'
 import { createWorkspaceFileFolderOperation } from '@/lib/workspace-files/application/workspace-file-folders'
 
@@ -13,7 +14,10 @@ export function requireCopilotWorkspace(
 ): string {
   if (!context.workspaceId) throw new Error('Copilot execution workspace is required')
   if (assertedWorkspaceId && assertedWorkspaceId !== context.workspaceId) {
-    throw new Error('Workspace ID does not match the Copilot execution workspace')
+    throw new OrchestrationError(
+      'validation',
+      'Workspace ID does not match the Copilot execution workspace'
+    )
   }
   return context.workspaceId
 }

apps/sim/lib/copilot/tools/server/generated-schema.ts

@@ -1,5 +1,6 @@
 import Ajv, { type ErrorObject, type ValidateFunction } from 'ajv'
 import { TOOL_RUNTIME_SCHEMAS } from '@/lib/copilot/generated/tool-schemas-v1'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 
 const ajv = new Ajv({
   allErrors: true,
@@ -42,7 +43,13 @@ export function validateGeneratedToolPayload<T>(
 
   if (!validator(payload)) {
     const label = schemaKind === 'parameters' ? 'input' : 'output'
-    throw new Error(`${toolName} ${label} validation failed: ${formatErrors(validator.errors)}`)
+    const message = `${toolName} ${label} validation failed: ${formatErrors(validator.errors)}`
+    // Input validation is the CALLER's mistake — classified, so the copilot
+    // error projection surfaces it verbatim and the model can fix its
+    // arguments instead of blind-retrying a masked "system error". Output
+    // validation failing is the tool's own bug and stays internal.
+    if (schemaKind === 'parameters') throw new OrchestrationError('validation', message)
+    throw new Error(message)
   }
 
   return payload

apps/sim/lib/copilot/tools/server/other/search-online.ts

@@ -4,6 +4,7 @@ import { WebSearch } from '@/lib/copilot/generated/tool-catalog-v1'
 import { projectToolErrorMessageForCopilot } from '@/lib/copilot/request/tools/resolved-secret-result'
 import type { BaseServerTool, ServerToolContext } from '@/lib/copilot/tools/server/base-tool'
 import { env } from '@/lib/core/config/env'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { executeTool } from '@/tools'
 
 interface OnlineSearchParams {
@@ -35,7 +36,8 @@ export const searchOnlineServerTool: BaseServerTool<OnlineSearchParams, SearchRe
   async execute(params: OnlineSearchParams, context?: ServerToolContext): Promise<SearchResponse> {
     const logger = createLogger('SearchOnlineServerTool')
     const { query, num = 10, type = 'search', gl, hl } = params
-    if (!query || typeof query !== 'string') throw new Error('query is required')
+    if (!query || typeof query !== 'string')
+      throw new OrchestrationError('validation', 'query is required')
 
     const hasExaApiKey = Boolean(env.EXA_API_KEY && String(env.EXA_API_KEY).length > 0)
     const hasSerperApiKey = Boolean(env.SERPER_API_KEY && String(env.SERPER_API_KEY).length > 0)
@@ -104,7 +106,8 @@ export const searchOnlineServerTool: BaseServerTool<OnlineSearchParams, SearchRe
     }
 
     if (!hasSerperApiKey) {
-      throw new Error(
+      throw new OrchestrationError(
+        'forbidden',
         'Web search is not configured on this Sim deployment and cannot be enabled from a tool. Answer from the workspace instead (grep/glob/read, search_sim_docs) or tell the user web search is unavailable.'
       )
     }
@@ -126,7 +129,9 @@ export const searchOnlineServerTool: BaseServerTool<OnlineSearchParams, SearchRe
 
     if (!result.success) {
       const errorMsg = (result as { error?: string }).error ?? 'Search failed'
-      throw new Error(errorMsg)
+      // Classified so the provider's actual failure (rate limit, bad query)
+      // reaches the model instead of the generic system-error mask.
+      throw new OrchestrationError('conflict', errorMsg)
     }
 
     return {

apps/sim/lib/copilot/tools/server/router.ts

@@ -61,6 +61,7 @@ import { getCredentialsServerTool } from '@/lib/copilot/tools/server/user/get-cr
 import { setEnvironmentVariablesServerTool } from '@/lib/copilot/tools/server/user/set-environment-variables'
 import { editWorkflowServerTool } from '@/lib/copilot/tools/server/workflow/edit-workflow'
 import { queryLogsServerTool } from '@/lib/copilot/tools/server/workflow/query-logs'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { listCustomBlocksWithInputsForWorkspace } from '@/lib/workflows/custom-blocks/operations'
 import { withCustomBlockOverlay } from '@/blocks/custom/server-overlay'
 import { withBlockVisibility } from '@/blocks/visibility/server-context'
@@ -219,7 +220,7 @@ export async function routeExecution(
 ): Promise<unknown> {
   const tool = getServerToolRegistry()[toolName]
   if (!tool) {
-    throw new Error(`Unknown server tool: ${toolName}`)
+    throw new OrchestrationError('validation', `Unknown server tool: ${toolName}`)
   }
 
   logger.debug(
@@ -233,7 +234,10 @@ export async function routeExecution(
     const action = (p?.operation ?? p?.action) as string | undefined
     if (isWriteAction(toolName, action) && !copilotToolCanWrite(context?.userPermission)) {
       const actionLabel = action ? `'${action}' on ` : ''
-      throw new Error(
+      // Classified so the projection surfaces it: a permission denial is
+      // caller-actionable (stop retrying, tell the user), not a system error.
+      throw new OrchestrationError(
+        'forbidden',
         `Permission denied: ${actionLabel}${toolName} requires write access. You have '${context?.userPermission ?? 'none'}' permission.`
       )
     }

apps/sim/lib/copilot/tools/server/user/get-credentials.ts

@@ -7,6 +7,7 @@ import { decodeJwt } from 'jose'
 import { createPermissionError, verifyWorkflowAccess } from '@/lib/copilot/auth/permissions'
 import type { BaseServerTool } from '@/lib/copilot/tools/server/base-tool'
 import { getAllowedIntegrationsFromEnv } from '@/lib/core/config/env-flags'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { getAccessibleOAuthCredentials } from '@/lib/credentials/environment'
 import { getPersonalAndWorkspaceEnv } from '@/lib/environment/utils'
 import { createIntegrationCredentialVisibility } from '@/lib/integrations/credential-visibility.server'
@@ -50,7 +51,7 @@ export const getCredentialsServerTool: BaseServerTool<GetCredentialsParams, any>
           workflowId: params.workflowId,
           authenticatedUserId,
         })
-        throw new Error(errorMessage)
+        throw new OrchestrationError('forbidden', errorMessage)
       }
 
       workspaceId = wId

apps/sim/lib/copilot/tools/server/user/set-environment-variables.ts

@@ -7,6 +7,7 @@ import {
   getDefaultWorkspaceId,
 } from '@/lib/copilot/tools/handlers/access'
 import type { BaseServerTool, ServerToolContext } from '@/lib/copilot/tools/server/base-tool'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { performUpdateCredential } from '@/lib/credentials/orchestration'
 import { listVisibleWorkspaceCredentials } from '@/lib/credentials/queries'
 import { upsertPersonalEnvVars, upsertWorkspaceEnvVars } from '@/lib/environment/utils'
@@ -67,7 +68,8 @@ function normalizeDescriptions(
     if (!item || typeof item.name !== 'string' || item.description === undefined) continue
     const description = item.description?.trim() ?? ''
     if (description.length > DESCRIPTION_MAX_LENGTH) {
-      throw new Error(
+      throw new OrchestrationError(
+        'validation',
         `description for ${item.name} must be at most ${DESCRIPTION_MAX_LENGTH} characters`
       )
     }
@@ -159,7 +161,10 @@ async function resolveWorkspaceId(
   if (params.workflowId) {
     const { workflow } = await ensureWorkflowAccess(params.workflowId, userId, 'write')
     if (!workflow.workspaceId) {
-      throw new Error(`Workflow ${params.workflowId} is not associated with a workspace`)
+      throw new OrchestrationError(
+        'validation',
+        `Workflow ${params.workflowId} is not associated with a workspace`
+      )
     }
     return workflow.workspaceId
   }
@@ -202,7 +207,10 @@ export const setEnvironmentVariablesServerTool: BaseServerTool<
     // per-workspace mirrors, so there is no single row to hold its description —
     // one written here would exist in this workspace alone.
     if (scope === 'personal' && Object.keys(descriptions).length > 0) {
-      throw new Error('description is only supported for a workspace secret')
+      throw new OrchestrationError(
+        'validation',
+        'description is only supported for a workspace secret'
+      )
     }
     const { variables: validatedVariables } = EnvVarSchema.parse({ variables: normalized })
     const variableNames = Object.keys(validatedVariables)
@@ -249,7 +257,10 @@ export const setEnvironmentVariablesServerTool: BaseServerTool<
     // A failed description never fails a stored value — but a describe-only call
     // has nothing else to report, so its failure is the result.
     if (descriptionFailures.length > 0 && workspaceUpdated.length === 0) {
-      throw new Error(`Could not describe: ${descriptionFailures.join('; ')}`)
+      throw new OrchestrationError(
+        'conflict',
+        `Could not describe: ${descriptionFailures.join('; ')}`
+      )
     }
 
     const parts: string[] = []

apps/sim/lib/copilot/tools/server/workflow/edit-workflow/index.ts

@@ -101,9 +101,9 @@ export const editWorkflowServerTool: BaseServerTool<EditWorkflowParams, unknown>
     const logger = createLogger('EditWorkflowServerTool')
     const { operations, workflowId, currentUserWorkflow } = params
     if (!Array.isArray(operations) || operations.length === 0) {
-      throw new Error('operations are required and must be an array')
+      throw new OrchestrationError('validation', 'operations are required and must be an array')
     }
-    if (!workflowId) throw new Error('workflowId is required')
+    if (!workflowId) throw new OrchestrationError('validation', 'workflowId is required')
     if (!context?.userId) {
       throw new Error('Unauthorized workflow access')
     }
@@ -135,7 +135,7 @@ export const editWorkflowServerTool: BaseServerTool<EditWorkflowParams, unknown>
       operationsReferenceSimSandbox(operations) &&
       (!workspaceId || !(await hasWorkspaceSandboxAccess(workspaceId)))
     ) {
-      throw new Error(MAX_PLAN_REQUIRED)
+      throw new OrchestrationError('forbidden', MAX_PLAN_REQUIRED)
     }
 
     logger.info('Executing edit_workflow', {
@@ -153,7 +153,7 @@ export const editWorkflowServerTool: BaseServerTool<EditWorkflowParams, unknown>
         workflowState = JSON.parse(currentUserWorkflow)
       } catch (error) {
         logger.error('Failed to parse currentUserWorkflow', error)
-        throw new Error('Invalid currentUserWorkflow format')
+        throw new OrchestrationError('validation', 'Invalid currentUserWorkflow format')
       }
     } else {
       const fromDb = await getCurrentWorkflowStateFromDb(workflowId)
@@ -251,7 +251,10 @@ export const editWorkflowServerTool: BaseServerTool<EditWorkflowParams, unknown>
         errors: validation.errors,
         warnings: validation.warnings,
       })
-      throw new Error(`Invalid edited workflow: ${validation.errors.join('; ')}`)
+      throw new OrchestrationError(
+        'validation',
+        `Invalid edited workflow: ${validation.errors.join('; ')}`
+      )
     }
 
     if (validation.warnings.length > 0) {
@@ -387,7 +390,7 @@ export const editWorkflowServerTool: BaseServerTool<EditWorkflowParams, unknown>
         workflowId,
         error: saveResult.error,
       })
-      throw new Error(`Failed to save workflow: ${saveResult.error}`)
+      throw new OrchestrationError('conflict', `Failed to save workflow: ${saveResult.error}`)
     }
 
     // Update workflow's lastSynced timestamp

apps/sim/lib/copilot/tools/server/workflow/query-logs.ts

@@ -2,6 +2,7 @@ import { createLogger } from '@sim/logger'
 import { z } from 'zod'
 import { QueryLogs } from '@/lib/copilot/generated/tool-catalog-v1'
 import type { BaseServerTool, ServerToolContext } from '@/lib/copilot/tools/server/base-tool'
+import { OrchestrationError } from '@/lib/core/orchestration/types'
 import {
   collectLargeValueExecutionIds,
   collectLargeValueKeys,
@@ -120,7 +121,7 @@ type QueryLogsArgs = z.infer<typeof queryLogsArgsSchema>
 function resolveWorkspaceId(args: QueryLogsArgs, context?: ServerToolContext): string {
   const workspaceId = args.workspaceId ?? context?.workspaceId
   if (!workspaceId) {
-    throw new Error('workspaceId is required')
+    throw new OrchestrationError('validation', 'workspaceId is required')
   }
   return workspaceId
 }