feat(execution): callable execution service + structured error classifier

executeWorkflowService composes the same libs the v1 route holds inline
(call-chain guard, execution-id claim, LoggingSession, preprocessing,
deployed-state load + file-field processing, timeout-bound
executeWorkflowCore, output hydration/compaction) for the deployed-state
caller class — the seam the v2 execute route and in-process internal
callers share, making the HTTP endpoint syntactic sugar.

classifyExecutionError stops discarding the block context that
buildBlockExecutionError already attaches at throw sites: failed runs
now yield {message, code, blockId, blockName, blockType} with a stable
append-only code enum (TIMEOUT/CANCELLED/USAGE_LIMIT_EXCEEDED/
INVALID_INPUT/BLOCK_EXECUTION_FAILED/CHILD_WORKFLOW_FAILED/
OUTPUT_TOO_LARGE/EXECUTION_FAILED), so callers route on error class
instead of substring-matching messages — the single place raw errors
are interpreted.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CiHhAk2R1NryaS3R8n2yFz

Author: TheodoreSpeaks

apps/sim/executor/utils/errors.classify.test.ts

@@ -0,0 +1,149 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import type { ExecutionResult } from '@/executor/types'
+import {
+  attachExecutionResult,
+  buildBlockExecutionError,
+  classifyExecutionError,
+} from '@/executor/utils/errors'
+
+function failedResult(partial?: Partial<ExecutionResult>): ExecutionResult {
+  return { success: false, output: {}, ...partial }
+}
+
+describe('classifyExecutionError', () => {
+  it('reads block context from the fields buildBlockExecutionError attaches and strips the name prefix', () => {
+    const error = buildBlockExecutionError({
+      block: { id: 'block-1', metadata: { name: 'Send Email', id: 'gmail' } } as never,
+      error: new Error('Invalid credentials'),
+    })
+
+    const classified = classifyExecutionError(error)
+
+    expect(classified).toMatchObject({
+      message: 'Invalid credentials',
+      code: 'BLOCK_EXECUTION_FAILED',
+      blockId: 'block-1',
+      blockName: 'Send Email',
+      blockType: 'gmail',
+    })
+  })
+
+  it('falls back to the last failed, un-handled block log', () => {
+    const result = failedResult({
+      error: 'Agent: model refused',
+      logs: [
+        {
+          blockId: 'b-ok',
+          blockName: 'First',
+          blockType: 'function',
+          success: true,
+          startedAt: '',
+          endedAt: '',
+          durationMs: 1,
+        },
+        {
+          blockId: 'b-handled',
+          blockName: 'Handled',
+          blockType: 'api',
+          success: false,
+          errorHandled: true,
+          error: 'handled upstream',
+          startedAt: '',
+          endedAt: '',
+          durationMs: 1,
+        },
+        {
+          blockId: 'b-fail',
+          blockName: 'Agent',
+          blockType: 'agent',
+          success: false,
+          error: 'model refused',
+          startedAt: '',
+          endedAt: '',
+          durationMs: 1,
+        },
+      ],
+    })
+
+    const classified = classifyExecutionError(new Error('Agent: model refused'), result)
+
+    expect(classified).toMatchObject({
+      message: 'model refused',
+      code: 'BLOCK_EXECUTION_FAILED',
+      blockId: 'b-fail',
+      blockName: 'Agent',
+      blockType: 'agent',
+    })
+  })
+
+  it('classifies child-workflow failures so parents can route on error class', () => {
+    const result = failedResult({
+      logs: [
+        {
+          blockId: 'wf-block',
+          blockName: 'Enrich Lead',
+          blockType: 'workflow_input',
+          success: false,
+          error: 'Child workflow failed',
+          startedAt: '',
+          endedAt: '',
+          durationMs: 1,
+        },
+      ],
+    })
+
+    expect(classifyExecutionError(new Error('Child workflow failed'), result).code).toBe(
+      'CHILD_WORKFLOW_FAILED'
+    )
+  })
+
+  it('maps the attached 4xx statusCode families', () => {
+    const timeoutError = new Error('Execution exceeded the time limit')
+    Object.assign(timeoutError, { statusCode: 408 })
+    expect(classifyExecutionError(timeoutError).code).toBe('TIMEOUT')
+
+    const usageError = new Error('Usage limit exceeded for this billing period')
+    Object.assign(usageError, { statusCode: 402 })
+    expect(classifyExecutionError(usageError).code).toBe('USAGE_LIMIT_EXCEEDED')
+  })
+
+  it('uses the attached executionResult when none is passed explicitly', () => {
+    const error = new Error('Slack: channel not found')
+    attachExecutionResult(
+      error,
+      failedResult({
+        logs: [
+          {
+            blockId: 'slack-1',
+            blockName: 'Slack',
+            blockType: 'slack',
+            success: false,
+            error: 'channel not found',
+            startedAt: '',
+            endedAt: '',
+            durationMs: 1,
+          },
+        ],
+      })
+    )
+
+    expect(classifyExecutionError(error)).toMatchObject({
+      code: 'BLOCK_EXECUTION_FAILED',
+      blockId: 'slack-1',
+      message: 'channel not found',
+    })
+  })
+
+  it('falls back to EXECUTION_FAILED with the raw message when nothing is classifiable', () => {
+    expect(classifyExecutionError(new Error('something odd'))).toEqual({
+      message: 'something odd',
+      code: 'EXECUTION_FAILED',
+      blockId: undefined,
+      blockName: undefined,
+      blockType: undefined,
+    })
+  })
+})

apps/sim/executor/utils/errors.ts

@@ -117,3 +117,120 @@ export function normalizeError(error: unknown): string {
   }
   return String(error)
 }
+
+/**
+ * Stable, append-only error classes for failed workflow executions. Callers
+ * (v2 API consumers, parent workflows, MCP clients) route on these instead of
+ * substring-matching messages; this module is the single place raw errors are
+ * interpreted, so the executor can later attach codes natively at throw sites
+ * without a wire change.
+ */
+export type WorkflowExecutionErrorCode =
+  | 'TIMEOUT'
+  | 'CANCELLED'
+  | 'USAGE_LIMIT_EXCEEDED'
+  | 'INVALID_INPUT'
+  | 'BLOCK_EXECUTION_FAILED'
+  | 'CHILD_WORKFLOW_FAILED'
+  | 'OUTPUT_TOO_LARGE'
+  | 'EXECUTION_FAILED'
+
+export interface StructuredExecutionError {
+  message: string
+  code: WorkflowExecutionErrorCode
+  blockId?: string
+  blockName?: string
+  blockType?: string
+}
+
+interface AttachedBlockContext {
+  blockId?: unknown
+  blockName?: unknown
+  blockType?: unknown
+}
+
+function readAttachedBlockContext(error: unknown): {
+  blockId?: string
+  blockName?: string
+  blockType?: string
+} {
+  if (!(error instanceof Error)) return {}
+  const attached = error as unknown as AttachedBlockContext
+  return {
+    blockId: typeof attached.blockId === 'string' ? attached.blockId : undefined,
+    blockName: typeof attached.blockName === 'string' ? attached.blockName : undefined,
+    blockType: typeof attached.blockType === 'string' ? attached.blockType : undefined,
+  }
+}
+
+function lastFailedBlockLog(result: ExecutionResult | undefined): {
+  blockId?: string
+  blockName?: string
+  blockType?: string
+  error?: string
+} {
+  const logs = result?.logs
+  if (!logs?.length) return {}
+  for (let i = logs.length - 1; i >= 0; i--) {
+    const log = logs[i]
+    if (!log.success && log.errorHandled !== true) {
+      return {
+        blockId: log.blockId,
+        blockName: log.blockName,
+        blockType: log.blockType,
+        error: log.error,
+      }
+    }
+  }
+  return {}
+}
+
+const CHILD_WORKFLOW_BLOCK_TYPES = new Set(['workflow', 'workflow_input'])
+
+/**
+ * Classifies a failed execution into {@link StructuredExecutionError}.
+ * Block context comes from the fields {@link buildBlockExecutionError} already
+ * attaches at the throw site, falling back to the last failed, un-handled
+ * `BlockLog`. The message drops the historical `"BlockName: "` prefix once
+ * `blockName` is carried as its own field.
+ */
+export function classifyExecutionError(
+  error: unknown,
+  result?: ExecutionResult
+): StructuredExecutionError {
+  const executionResult = result ?? (hasExecutionResult(error) ? error.executionResult : undefined)
+  const attached = readAttachedBlockContext(error)
+  const fromLog = lastFailedBlockLog(executionResult)
+  const blockId = attached.blockId ?? fromLog.blockId
+  const blockName = attached.blockName ?? fromLog.blockName
+  const blockType = attached.blockType ?? fromLog.blockType
+
+  let message =
+    (error instanceof Error ? error.message : undefined) ??
+    executionResult?.error ??
+    fromLog.error ??
+    'Execution failed'
+  if (blockName && message.startsWith(`${blockName}: `)) {
+    message = message.slice(blockName.length + 2)
+  }
+
+  const statusCode = error instanceof Error ? getExecutionErrorStatus(error) : undefined
+  let code: WorkflowExecutionErrorCode
+  if (statusCode === 408 || /\btimed? ?out\b/i.test(message)) {
+    code = 'TIMEOUT'
+  } else if (statusCode === 402 || /usage limit/i.test(message)) {
+    code = 'USAGE_LIMIT_EXCEEDED'
+  } else if (executionResult?.status === 'cancelled' || /\bcancelled\b/i.test(message)) {
+    code = 'CANCELLED'
+  } else if (/invalid input format/i.test(message)) {
+    code = 'INVALID_INPUT'
+  } else if (blockType && CHILD_WORKFLOW_BLOCK_TYPES.has(blockType)) {
+    code = 'CHILD_WORKFLOW_FAILED'
+  } else if (blockId) {
+    code = 'BLOCK_EXECUTION_FAILED'
+  } else {
+    code = 'EXECUTION_FAILED'
+  }
+
+  return { message, code, blockId, blockName, blockType }
+}