fix(workflows): preserve v2 terminal cancellation responses

Author: j15z

apps/docs/openapi-v2-workflows.json

@@ -9986,7 +9986,7 @@
           },
           "durablyRecorded": {
             "type": "boolean",
-            "description": "Whether this request durably recorded a cancellation. False when an already-cancelled run needed no further durable write."
+            "description": "Whether this request durably recorded a cancellation. Always false for a run that was already terminal, where the request is satisfied but nothing was written."
           },
           "locallyAborted": {
             "type": "boolean",
@@ -9997,7 +9997,7 @@
             "description": "Whether a paused execution was cancelled."
           },
           "reason": {
-            "description": "Machine-readable cancellation outcome. `recorded`, `queue_cancelled`, and `already_cancelled` are successful outcomes; the remaining values identify a degraded or incomplete cancellation step.",
+            "description": "Machine-readable cancellation outcome, present on every cancellation including full successes. `recorded` and `queue_cancelled` are successful cancellation values. `already_cancelled`, `already_completed`, and `already_failed` mean the run had already reached that terminal state, so nothing was cancelled and `durablyRecorded` is false. The remaining values identify a degraded or incomplete cancellation step.",
             "type": "string",
             "enum": [
               "recorded",
@@ -10024,7 +10024,7 @@
         ],
         "additionalProperties": false,
         "title": "Cancel workflow run result",
-        "description": "Outcome of the shared workflow-run cancellation lifecycle used by internal UI, Copilot, and v2 callers."
+        "description": "Outcome of a workflow run cancellation request. Cancellation is best-effort: a run already in a terminal state succeeds with no effect, reported as `durablyRecorded: false` with an `already_*` reason naming the state observed."
       },
       "CancelWorkflowRunResponse": {
         "type": "object",

apps/sim/app/api/v2/workflows/[workflowId]/runs/[runId]/cancel/route.test.ts

@@ -11,6 +11,7 @@ import {
 } from '@sim/testing'
 import { NextRequest } from 'next/server'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { WorkflowRunAlreadyTerminalError } from '@/lib/execution/workflow-run-already-terminal-error'
 
 const mocks = vi.hoisted(() => ({
   cancel: vi.fn(),
@@ -104,4 +105,36 @@ describe('POST /api/v2/workflows/[workflowId]/runs/[runId]/cancel', () => {
       reason: 'already_cancelled',
     })
   })
+
+  it.each([
+    ['completed', 'already_completed'],
+    ['failed', 'already_failed'],
+  ] as const)(
+    'preserves the v2 terminal no-op response when a standalone run is already %s',
+    async (executionStatus, reason) => {
+      mocks.cancel.mockRejectedValue(
+        new WorkflowRunAlreadyTerminalError({
+          executionId: RUN_ID,
+          executionStatus,
+          redisAvailable: true,
+          locallyAborted: false,
+        })
+      )
+
+      const response = await POST(request(), context)
+
+      expect(response.status).toBe(200)
+      await expect(response.json()).resolves.toEqual({
+        data: {
+          success: true,
+          runId: RUN_ID,
+          redisAvailable: true,
+          durablyRecorded: false,
+          locallyAborted: false,
+          pausedCancelled: false,
+          reason,
+        },
+      })
+    }
+  )
 })

apps/sim/app/api/v2/workflows/[workflowId]/runs/[runId]/cancel/route.ts

@@ -12,7 +12,7 @@ export const POST = defineV2JsonRoute({
   auth: v2ApiKeyAuth,
   operation: workflowOperations.cancelRun,
   rateLimit: v2RateLimits.publicApi,
-  errorPolicy: v2WorkflowErrorPolicies.concealRunAuthorization,
+  errorPolicy: v2WorkflowErrorPolicies.cancelRun,
   mapInput: ({ params }) => ({ workflowId: params.workflowId, runId: params.runId }),
   useCase: cancelWorkflowRun,
   present: (result) => ({

apps/sim/app/api/workflows/[id]/executions/[executionId]/cancel/route.test.ts

@@ -3,7 +3,7 @@
  */
 import { NextRequest } from 'next/server'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
-import { OrchestrationError } from '@/lib/core/orchestration/types'
+import { WorkflowRunAlreadyTerminalError } from '@/lib/execution/workflow-run-already-terminal-error'
 
 const mocks = vi.hoisted(() => ({
   cancel: vi.fn(),
@@ -83,7 +83,12 @@ describe('POST /api/workflows/[id]/executions/[executionId]/cancel', () => {
 
   it('projects application conflicts without reimplementing cancellation errors', async () => {
     mocks.cancel.mockRejectedValue(
-      new OrchestrationError('conflict', 'Execution cannot be cancelled while completed')
+      new WorkflowRunAlreadyTerminalError({
+        executionId: 'execution-1',
+        executionStatus: 'completed',
+        redisAvailable: true,
+        locallyAborted: false,
+      })
     )
 
     const response = await POST(request(), context)

apps/sim/lib/api/contracts/v2/workflows.ts

@@ -1865,21 +1865,21 @@ export const v2CancelWorkflowRunDataSchema = z
     durablyRecorded: z
       .boolean()
       .describe(
-        'Whether this request durably recorded a cancellation. False when an already-cancelled run needed no further durable write.'
+        'Whether this request durably recorded a cancellation. Always false for a run that was already terminal, where the request is satisfied but nothing was written.'
       ),
     locallyAborted: z.boolean().describe('Whether an in-process execution was aborted.'),
     pausedCancelled: z.boolean().describe('Whether a paused execution was cancelled.'),
     reason: cancelWorkflowExecutionReasonSchema
       .optional()
       .describe(
-        'Machine-readable cancellation outcome. `recorded`, `queue_cancelled`, and `already_cancelled` are successful outcomes; the remaining values identify a degraded or incomplete cancellation step.'
+        'Machine-readable cancellation outcome, present on every cancellation including full successes. `recorded` and `queue_cancelled` are successful cancellation values. `already_cancelled`, `already_completed`, and `already_failed` mean the run had already reached that terminal state, so nothing was cancelled and `durablyRecorded` is false. The remaining values identify a degraded or incomplete cancellation step.'
       ),
   })
   .meta({
     id: 'CancelWorkflowRunResult',
     title: 'Cancel workflow run result',
     description:
-      'Outcome of the shared workflow-run cancellation lifecycle used by internal UI, Copilot, and v2 callers.',
+      'Outcome of a workflow run cancellation request. Cancellation is best-effort: a run already in a terminal state succeeds with no effect, reported as `durablyRecorded: false` with an `already_*` reason naming the state observed.',
   })
 export type V2CancelWorkflowRunData = z.output<typeof v2CancelWorkflowRunDataSchema>
 

apps/sim/lib/copilot/tools/handlers/workflow/mutations.test.ts

@@ -3,6 +3,7 @@
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import type { ExecutionContext } from '@/lib/copilot/request/types'
+import { WorkflowRunAlreadyTerminalError } from '@/lib/execution/workflow-run-already-terminal-error'
 
 const { mocks } = vi.hoisted(() => ({
   mocks: {
@@ -202,8 +203,11 @@ describe('workflow mutation Copilot adapters', () => {
 
   it('returns a cancellation application error to the Run agent', async () => {
     mocks.executeWorkflowUseCase.mockRejectedValue(
-      Object.assign(new Error('Execution cannot be cancelled while completed'), {
-        code: 'conflict',
+      new WorkflowRunAlreadyTerminalError({
+        executionId: 'execution-1',
+        executionStatus: 'completed',
+        redisAvailable: true,
+        locallyAborted: false,
       })
     )
 

apps/sim/lib/execution/cancel-workflow-execution.test.ts

@@ -106,6 +106,7 @@ import {
   cancelWorkflowExecution,
   WorkflowExecutionNotFoundError,
 } from '@/lib/execution/cancel-workflow-execution'
+import { WorkflowRunAlreadyTerminalError } from '@/lib/execution/workflow-run-already-terminal-error'
 
 const INPUT: CancelWorkflowExecutionInput = {
   workflowId: 'wf-1',
@@ -1369,14 +1370,44 @@ describe('cancelWorkflowExecution', () => {
     await expect(response.json()).resolves.toEqual({ error: 'database unavailable' })
   })
 
-  it('returns 409 when the execution is already terminal', async () => {
+  it.each(['completed', 'failed'] as const)(
+    'raises a typed conflict when a standalone execution is already %s',
+    async (executionStatus) => {
+      dbChainMockFns.limit.mockResolvedValueOnce([
+        { status: executionStatus, workspaceId: 'workspace-1' },
+      ])
+
+      const error = await cancelWorkflowExecution(INPUT).catch((caught: unknown) => caught)
+
+      expect(error).toBeInstanceOf(WorkflowRunAlreadyTerminalError)
+      expect(error).toEqual(
+        expect.objectContaining({
+          code: 'conflict',
+          executionId: 'ex-1',
+          executionStatus,
+          redisAvailable: true,
+          locallyAborted: false,
+        })
+      )
+      expect(mockMarkExecutionCancelled).not.toHaveBeenCalled()
+      expect(mockCancelByExecution).not.toHaveBeenCalled()
+    }
+  )
+
+  it('keeps workflow-group terminal conflicts strict', async () => {
     dbChainMockFns.limit.mockResolvedValueOnce([
-      { status: 'completed', workspaceId: 'workspace-1' },
+      {
+        executionOrigin: 'workflow_group',
+        status: 'completed',
+        workspaceId: 'workspace-1',
+      },
     ])
 
-    const response = await POST(makeRequest(), makeParams())
-
-    expect(response.status).toBe(409)
+    await expect(cancelWorkflowExecution(INPUT)).rejects.toMatchObject({
+      name: 'OrchestrationError',
+      code: 'conflict',
+      message: 'Execution cannot be cancelled while completed',
+    })
     expect(mockMarkExecutionCancelled).not.toHaveBeenCalled()
     expect(mockCancelByExecution).not.toHaveBeenCalled()
   })
@@ -1392,12 +1423,18 @@ describe('cancelWorkflowExecution', () => {
       ])
       .mockResolvedValueOnce([{ status: 'completed' }])
 
-    const response = await POST(makeRequest(), makeParams())
+    const error = await cancelWorkflowExecution(INPUT).catch((caught: unknown) => caught)
 
-    expect(response.status).toBe(409)
-    await expect(response.json()).resolves.toEqual({
-      error: 'Execution cannot be cancelled while completed',
-    })
+    expect(error).toBeInstanceOf(WorkflowRunAlreadyTerminalError)
+    expect(error).toEqual(
+      expect.objectContaining({
+        code: 'conflict',
+        executionId: 'ex-1',
+        executionStatus: 'completed',
+        redisAvailable: true,
+        locallyAborted: false,
+      })
+    )
     expect(returning).toHaveBeenCalledOnce()
     expect(mockClearExecutionCancellation).toHaveBeenCalledWith('ex-1')
     expect(mockWriteTerminalEvent).not.toHaveBeenCalled()

apps/sim/lib/execution/cancel-workflow-execution.ts

@@ -15,6 +15,10 @@ import {
 } from '@/lib/execution/cancellation'
 import { createExecutionEventWriter, readExecutionMetaState } from '@/lib/execution/event-buffer'
 import { abortManualExecution } from '@/lib/execution/manual-cancellation'
+import {
+  isWorkflowRunAlreadyTerminalStatus,
+  WorkflowRunAlreadyTerminalError,
+} from '@/lib/execution/workflow-run-already-terminal-error'
 import { cancelledExecutionLogFields } from '@/lib/logs/execution/cancellation'
 import { workflowExecutionOriginSql } from '@/lib/logs/execution-origin'
 import {
@@ -622,6 +626,14 @@ export async function cancelWorkflowExecution({
     }
 
     if (execution.status !== 'running' && execution.status !== 'pending') {
+      if (!isWorkflowGroupExecution && isWorkflowRunAlreadyTerminalStatus(execution.status)) {
+        throw new WorkflowRunAlreadyTerminalError({
+          executionId,
+          executionStatus: execution.status,
+          redisAvailable: true,
+          locallyAborted: false,
+        })
+      }
       throw new OrchestrationError(
         'conflict',
         `Execution cannot be cancelled while ${execution.status}`
@@ -859,6 +871,17 @@ export async function cancelWorkflowExecution({
           }
         )
       }
+      if (
+        !isWorkflowGroupExecution &&
+        isWorkflowRunAlreadyTerminalStatus(competingTerminalStatus)
+      ) {
+        throw new WorkflowRunAlreadyTerminalError({
+          executionId,
+          executionStatus: competingTerminalStatus,
+          redisAvailable: stopSummary.cancellation.reason !== 'redis_unavailable',
+          locallyAborted: stopSummary.locallyAborted,
+        })
+      }
       throw new OrchestrationError(
         'conflict',
         isWorkflowGroupExecution

apps/sim/lib/execution/workflow-run-already-terminal-error.ts

@@ -0,0 +1,33 @@
+import { OrchestrationError } from '@/lib/core/orchestration/types'
+
+export type WorkflowRunAlreadyTerminalStatus = 'completed' | 'failed'
+
+interface WorkflowRunAlreadyTerminalErrorOptions {
+  executionId: string
+  executionStatus: WorkflowRunAlreadyTerminalStatus
+  redisAvailable: boolean
+  locallyAborted: boolean
+}
+
+/** A standalone run reached a non-cancellable terminal state before cancellation won. */
+export class WorkflowRunAlreadyTerminalError extends OrchestrationError {
+  readonly executionId: string
+  readonly executionStatus: WorkflowRunAlreadyTerminalStatus
+  readonly redisAvailable: boolean
+  readonly locallyAborted: boolean
+
+  constructor(options: WorkflowRunAlreadyTerminalErrorOptions) {
+    super('conflict', `Execution cannot be cancelled while ${options.executionStatus}`)
+    this.name = 'WorkflowRunAlreadyTerminalError'
+    this.executionId = options.executionId
+    this.executionStatus = options.executionStatus
+    this.redisAvailable = options.redisAvailable
+    this.locallyAborted = options.locallyAborted
+  }
+}
+
+export function isWorkflowRunAlreadyTerminalStatus(
+  status: string
+): status is WorkflowRunAlreadyTerminalStatus {
+  return status === 'completed' || status === 'failed'
+}

apps/sim/lib/workflows/api/route-policies.ts

@@ -4,6 +4,7 @@ import type {
   SessionPrincipal,
   WorkspaceApiKeyPrincipal,
 } from '@sim/auth/principal'
+import { v2CancelWorkflowRunDataSchema } from '@/lib/api/contracts/v2/workflows'
 import {
   createInternalResourceConcealmentPolicy,
   createInternalSessionOrExecutorAuth,
@@ -19,10 +20,32 @@ import {
 } from '@/lib/api/server/routes'
 import { authenticateApiKeyFromHeader, updateApiKeyLastUsed } from '@/lib/api-key/service'
 import { asOrchestrationError, statusForOrchestrationError } from '@/lib/core/orchestration/types'
+import { WorkflowRunAlreadyTerminalError } from '@/lib/execution/workflow-run-already-terminal-error'
 import { WORKFLOW_DELEGATION_AUDIENCE } from '@/lib/workflows/application/authorization'
 import { WorkflowImportError } from '@/lib/workflows/application/workflow-import-error'
 import { WorkflowOperationsNotAppliedError } from '@/lib/workflows/application/workflow-operations-error'
-import { v2CaughtOrchestrationError, v2ErrorForOrchestration } from '@/app/api/v2/lib/response'
+import {
+  v2CaughtOrchestrationError,
+  v2Data,
+  v2ErrorForOrchestration,
+} from '@/app/api/v2/lib/response'
+
+function v2CancelRunErrorResponse(error: unknown) {
+  if (error instanceof WorkflowRunAlreadyTerminalError) {
+    return v2Data(
+      v2CancelWorkflowRunDataSchema.parse({
+        success: true,
+        runId: error.executionId,
+        redisAvailable: error.redisAvailable,
+        durablyRecorded: false,
+        locallyAborted: error.locallyAborted,
+        pausedCancelled: false,
+        reason: error.executionStatus === 'completed' ? 'already_completed' : 'already_failed',
+      })
+    )
+  }
+  return v2CaughtOrchestrationError(error)
+}
 
 export const v2WorkflowErrorPolicies = {
   default: v2OrchestrationErrorPolicy,
@@ -61,6 +84,10 @@ export const v2WorkflowErrorPolicies = {
   concealRunAuthorization: createV2ResourceConcealmentPolicy({
     notFoundMessage: 'Run not found',
   }),
+  cancelRun: createV2ResourceConcealmentPolicy({
+    notFoundMessage: 'Run not found',
+    render: v2CancelRunErrorResponse,
+  }),
 } as const
 
 export const internalWorkflowSessionOrExecutorAuth = createInternalSessionOrExecutorAuth({