feat(workflows): stop a manual v2 run after a block, and workflows run --stop-after

A manual v2 run can now name `run.stopAfterBlockId`; the run stops once that
block completes and downstream blocks do not execute. Combined with a block
entry on the same block, it re-runs exactly one block against a prior run's
persisted upstream outputs, server-side:

  sim workflows run W --from-block X --source-run R --stop-after X --select-output X.result

Agents verifying an edit no longer re-run every upstream block (often a slow
LLM or API call) or toggle blocks off to skip them.

- Contract: optional `stopAfterBlockId` on the manual run selection.
- Application: both manual operations refuse a block missing from the saved
  workflow or nested in a loop/parallel (the engine would otherwise run to the
  end or stop after one iteration), before anything runs.
- Execute service: threads the trusted value to the sync and stream paths.
- CLI: `--stop-after <blockId>` implies --manual and rejects --async.
- E2E: test-workflow-stop-after-e2e.ts against a running app; the http-e2e job
  gains a Redis service because hosted billing admits runs through a Redis
  usage reservation.

Author: Waleed Latif

.github/workflows/test-build.yml

@@ -125,6 +125,16 @@ jobs:
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-8vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 20
     services:
+      # Hosted billing admits a workflow run only through a Redis usage reservation.
+      redis:
+        image: redis:8.2-alpine
+        ports:
+          - 6379:6379
+        options: >-
+          --health-cmd "redis-cli ping"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
       postgres:
         image: pgvector/pgvector:pg17
         env:
@@ -212,6 +222,7 @@ jobs:
           ORGANIZATIONS_ENABLED: 'true'
           NEXT_PUBLIC_ORGANIZATIONS_ENABLED: 'true'
           INTERNAL_API_SECRET: scim-http-ci-local-secret-at-least-32-characters
+          REDIS_URL: redis://127.0.0.1:6379
           DB_TX_TRIPWIRE: throw
           DISABLE_TELEMETRY: 'true'
           NEXT_TELEMETRY_DISABLED: '1'
@@ -252,6 +263,10 @@ jobs:
           VERSION_COMPARE_E2E_AUTH_SECRET="$BETTER_AUTH_SECRET" \
           VERSION_COMPARE_E2E_REPORT_PATH="$report_dir/version-compare-http-report.json" \
             bun run test:workflow-version-compare:e2e
+          STOP_AFTER_E2E_BASE_URL="$NEXT_PUBLIC_APP_URL" \
+          STOP_AFTER_E2E_DATABASE_URL="$DATABASE_URL" \
+          STOP_AFTER_E2E_REPORT_PATH="$report_dir/stop-after-http-report.json" \
+            bun run test:workflow-stop-after:e2e
 
       - name: Upload end-to-end reports and server logs
         if: failure()

apps/docs/content/docs/cli/reference.mdx

@@ -6704,6 +6704,7 @@ sim workflows run <workflowId> [options]
 | `--mock-payload` | No | Use the selected trigger's server-derived mock payload; runs the current saved workflow state (implies --manual). |
 | `--from-block <blockId>` | No | Run manually from this saved workflow block. |
 | `--source-run <runId>` | No | Prior run whose persisted state supplies upstream outputs (requires --from-block). |
+| `--stop-after <blockId>` | No | Stop the run after this saved block; with --from-block on the same block, re-runs only that block (implies --manual). |
 | `--follow` | No | Stream the run as it happens; progress on stderr, result on stdout. The stream reports only success and output, so the result omits the run id and timings a non-streaming run returns. |
 | `--include-thinking` | No | Show model reasoning while following (requires --follow). |
 | `--include-tool-calls` | No | Show tool calls while following (requires --follow). |

apps/docs/content/docs/cli/workflows.mdx

@@ -642,6 +642,7 @@ sim workflows run <workflowId> [options]
 | `--mock-payload` | No | Use the selected trigger's server-derived mock payload; runs the current saved workflow state (implies --manual). |
 | `--from-block <blockId>` | No | Run manually from this saved workflow block. |
 | `--source-run <runId>` | No | Prior run whose persisted state supplies upstream outputs (requires --from-block). |
+| `--stop-after <blockId>` | No | Stop the run after this saved block; with --from-block on the same block, re-runs only that block (implies --manual). |
 | `--follow` | No | Stream the run as it happens; progress on stderr, result on stdout. The stream reports only success and output, so the result omits the run id and timings a non-streaming run returns. |
 | `--include-thinking` | No | Show model reasoning while following (requires --follow). |
 | `--include-tool-calls` | No | Show tool calls while following (requires --follow). |

apps/docs/openapi-v2-workflows.json

@@ -12615,6 +12615,11 @@
                         "additionalProperties": false
                       }
                     ]
+                  },
+                  "stopAfterBlockId": {
+                    "description": "Saved workflow block after which the run stops; downstream blocks do not execute. Must not be inside a loop or parallel. With a block entry naming the same block, re-runs only that block against the source run.",
+                    "type": "string",
+                    "minLength": 1
                   }
                 },
                 "required": ["source"],
@@ -12703,6 +12708,17 @@
                 "sourceRunId": "run_123"
               }
             }
+          },
+          {
+            "run": {
+              "source": "manual",
+              "entry": {
+                "type": "block",
+                "blockId": "block_123",
+                "sourceRunId": "run_123"
+              },
+              "stopAfterBlockId": "block_123"
+            }
           }
         ]
       },

apps/sim/app/api/v2/workflows/[workflowId]/execute/route.ts

@@ -448,6 +448,7 @@ export const POST = withRouteHandler(
               mode: body.stream ? 'stream' : resultStream ? 'sync-result-stream' : 'sync',
               blockId: manualRun.entry.blockId,
               sourceRunId: manualRun.entry.sourceRunId,
+              stopAfterBlockId: manualRun.stopAfterBlockId,
             },
             request: req,
           })
@@ -460,6 +461,7 @@ export const POST = withRouteHandler(
               mode: body.stream ? 'stream' : resultStream ? 'sync-result-stream' : 'sync',
               triggerBlockId: manualRun.entry?.blockId,
               useMockPayload: manualRun.entry?.useMockPayload === true,
+              stopAfterBlockId: manualRun.stopAfterBlockId,
             },
             request: req,
           })

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

@@ -1297,6 +1297,13 @@ export const v2WorkflowRunSelectionSchema = z.discriminatedUnion('source', [
         .describe(
           'Manual entry mode. Omit to enter through the workflow trigger; a block entry requires an exact source run.'
         ),
+      stopAfterBlockId: z
+        .string()
+        .min(1, 'run.stopAfterBlockId cannot be empty')
+        .optional()
+        .describe(
+          'Saved workflow block after which the run stops; downstream blocks do not execute. Must not be inside a loop or parallel. With a block entry naming the same block, re-runs only that block against the source run.'
+        ),
     })
     .strict(),
 ])
@@ -1412,6 +1419,13 @@ export const v2ExecuteWorkflowBodySchema = z
           entry: { type: 'block', blockId: 'block_123', sourceRunId: 'run_123' },
         },
       },
+      {
+        run: {
+          source: 'manual',
+          entry: { type: 'block', blockId: 'block_123', sourceRunId: 'run_123' },
+          stopAfterBlockId: 'block_123',
+        },
+      },
     ],
   })
 export type V2ExecuteWorkflowBody = z.input<typeof v2ExecuteWorkflowBodySchema>

apps/sim/lib/workflows/application/execute-manual-workflow.test.ts

@@ -300,6 +300,77 @@ describe('manual workflow execution application operations', () => {
     expect(mocks.loadSourceState).not.toHaveBeenCalled()
   })
 
+  it('rejects a stop block missing from the saved workflow before anything runs', async () => {
+    await expect(
+      executeManualWorkflowOperation.execute({
+        principal,
+        input: { ...baseInput, useMockPayload: false, stopAfterBlockId: 'missing' },
+      })
+    ).rejects.toMatchObject({ code: 'validation' })
+    await expect(
+      executeManualWorkflowFromBlockOperation.execute({
+        principal,
+        input: {
+          ...baseInput,
+          blockId: 'agent-1',
+          sourceRunId: 'source-run-1',
+          stopAfterBlockId: 'missing',
+        },
+      })
+    ).rejects.toMatchObject({ code: 'validation' })
+    expect(mocks.loadSourceState).not.toHaveBeenCalled()
+    expect(mocks.executeService).not.toHaveBeenCalled()
+  })
+
+  it('rejects a stop block nested in a loop or parallel, which the engine cannot stop on', async () => {
+    mockLoadManualState.mockResolvedValue({
+      blocks: {
+        'trigger-1': {},
+        'loop-1': { type: 'loop' },
+        'agent-1': { data: { parentId: 'loop-1' } },
+      },
+      edges: [],
+    })
+
+    await expect(
+      executeManualWorkflowOperation.execute({
+        principal,
+        input: { ...baseInput, useMockPayload: false, stopAfterBlockId: 'agent-1' },
+      })
+    ).rejects.toMatchObject({ code: 'validation' })
+    expect(mocks.executeService).not.toHaveBeenCalled()
+  })
+
+  it('stops the trigger and block entries after the requested block', async () => {
+    mocks.loadSourceState.mockResolvedValueOnce({ blockStates: {}, executedBlocks: [] })
+
+    await executeManualWorkflowOperation.execute({
+      principal,
+      input: { ...baseInput, useMockPayload: false, stopAfterBlockId: 'agent-1' },
+    })
+    await executeManualWorkflowFromBlockOperation.execute({
+      principal,
+      input: {
+        ...baseInput,
+        blockId: 'agent-1',
+        sourceRunId: 'source-run-1',
+        stopAfterBlockId: 'agent-1',
+      },
+    })
+
+    expect(mocks.executeService).toHaveBeenNthCalledWith(
+      1,
+      expect.objectContaining({ triggerBlockId: 'trigger-1', stopAfterBlockId: 'agent-1' })
+    )
+    expect(mocks.executeService).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        runFromBlock: expect.objectContaining({ startBlockId: 'agent-1' }),
+        stopAfterBlockId: 'agent-1',
+      })
+    )
+  })
+
   it('rejects a source run without persisted state for this workflow', async () => {
     mocks.loadSourceState.mockResolvedValueOnce(null)
 

apps/sim/lib/workflows/application/execute-manual-workflow.ts

@@ -20,6 +20,7 @@ interface ManualExecutionInput
   extends Omit<ExecuteWorkflowInput, 'input' | 'mode' | 'requestedTimeoutSeconds'> {
   input?: unknown
   mode: 'sync' | 'stream' | 'sync-result-stream'
+  stopAfterBlockId?: string
 }
 
 export interface ExecuteManualWorkflowInput extends ManualExecutionInput {
@@ -47,6 +48,31 @@ async function loadManualState(workflowId: string) {
   return state
 }
 
+type ManualWorkflowState = Awaited<ReturnType<typeof loadManualState>>
+
+/**
+ * The engine stops only when it completes a node whose id equals the target, so
+ * an unknown id would silently run the whole workflow, and a block inside a loop
+ * or parallel would stop after its first iteration or never. Both are refused,
+ * matching the editor, which offers "Run until block" only outside subflows.
+ */
+function assertStopAfterBlock(state: ManualWorkflowState, blockId: string | undefined): void {
+  if (blockId === undefined) return
+  const block = state.blocks[blockId]
+  if (!block) {
+    throw new OrchestrationError(
+      'validation',
+      `run.stopAfterBlockId "${blockId}" is not a block in the current saved workflow.`
+    )
+  }
+  if (block.data?.parentId) {
+    throw new OrchestrationError(
+      'validation',
+      `run.stopAfterBlockId "${blockId}" is inside loop or parallel "${block.data.parentId}"; stop after that container instead.`
+    )
+  }
+}
+
 function listTriggers(options: ReturnType<typeof resolveTriggerRunOptions>): string {
   return options.map((option) => `${option.triggerBlockId} (${option.blockName})`).join(', ')
 }
@@ -68,6 +94,7 @@ function executionServiceInput(params: {
     includeFileBase64: params.input.includeFileBase64,
     base64MaxBytes: params.input.base64MaxBytes,
     selectedOutputs: params.input.selectedOutputs,
+    stopAfterBlockId: params.input.stopAfterBlockId,
     rateLimitCounter: 'sync' as const,
     abortSignal: params.input.abortSignal,
     mode: params.input.mode,
@@ -90,6 +117,7 @@ export const executeManualWorkflowOperation = defineAuthorizedWorkflowUseCase({
       )
     }
     const state = await loadManualState(context.workflowId)
+    assertStopAfterBlock(state, input.stopAfterBlockId)
     const options = resolveTriggerRunOptions(mergeSubblockStateWithValues(state.blocks))
     if (options.length === 0) {
       throw new OrchestrationError(
@@ -141,6 +169,7 @@ export const executeManualWorkflowFromBlockOperation = defineAuthorizedWorkflowU
         `run.entry.blockId "${input.blockId}" is not a block in the current saved workflow.`
       )
     }
+    assertStopAfterBlock(state, input.stopAfterBlockId)
 
     const sourceSnapshot = await getExecutionStateForWorkflow(input.sourceRunId, context.workflowId)
     if (!sourceSnapshot) {

apps/sim/lib/workflows/executor/execute-service.ts

@@ -120,6 +120,8 @@ export interface ExecuteWorkflowServiceParams {
     /** Mocked upstream outputs (block name/id → output object) overlaid on the snapshot. */
     variableInputs?: Record<string, unknown>
   }
+  /** Saved block after which execution stops, validated by the application use case. */
+  stopAfterBlockId?: string
 }
 
 export interface ExecuteWorkflowServiceFailure {
@@ -272,6 +274,7 @@ export async function executeWorkflowService(
     useDraftState = false,
     triggerBlockId,
     runFromBlock,
+    stopAfterBlockId,
   } = params
 
   let reqLogger = logger.withMetadata({ requestId, workflowId, userId })
@@ -289,6 +292,9 @@ export async function executeWorkflowService(
   if (runFromBlock && !useDraftState) {
     throw new Error('Run-from-block requires manual execution state')
   }
+  if (stopAfterBlockId && !useDraftState) {
+    throw new Error('Stop-after-block requires manual execution state')
+  }
 
   if (callChain) {
     const chainError = validateCallChain(callChain)
@@ -589,6 +595,7 @@ export async function executeWorkflowService(
               triggerBlockId,
               useDraftState,
               runFromBlock,
+              stopAfterBlockId,
               onStream,
               onBlockComplete: (blockId, data) =>
                 onBlockComplete(blockId, data.output, data.outputBlockId),
@@ -689,6 +696,7 @@ export async function executeWorkflowService(
           base64MaxBytes,
           abortSignal: timeoutController.signal,
           runFromBlock,
+          stopAfterBlockId,
         })
 
         await handlePostExecutionPauseState({ result, workflowId, executionId, loggingSession })

apps/sim/package.json

@@ -23,6 +23,7 @@
     "test": "vitest run",
     "test:scim:e2e": "bun run scripts/test-scim-e2e.ts",
     "test:workflow-version-compare:e2e": "bun --no-env-file scripts/test-workflow-version-compare-e2e.ts",
+    "test:workflow-stop-after:e2e": "bun --no-env-file scripts/test-workflow-stop-after-e2e.ts",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
     "email:dev": "email dev --dir components/emails",