Fix issue where DevTools would not be immediately available when using --start-paused (#126698)

Service extensions are unable to handle requests when the isolate they were registered on is paused. The DevTools launcher logic was waiting for some service extension invocations to complete before advertising the already active DevTools instance, but when --start-paused was provided these requests would never complete, preventing users from using DevTools to resume the paused isolate.

Fixes https://github.com/flutter/flutter/issues/126691

packages/flutter_tools/lib/src/resident_devtools_handler.dart

@@ -35,6 +35,7 @@ abstract class ResidentDevtoolsHandler {
   Future<void> serveAndAnnounceDevTools({
     Uri? devToolsServerAddress,
     required List<FlutterDevice?> flutterDevices,
+    bool isStartPaused = false,
   });
 
   bool launchDevToolsInBrowser({required List<FlutterDevice?> flutterDevices});
@@ -71,6 +72,7 @@ class FlutterResidentDevtoolsHandler implements ResidentDevtoolsHandler {
   Future<void> serveAndAnnounceDevTools({
     Uri? devToolsServerAddress,
     required List<FlutterDevice?> flutterDevices,
+    bool isStartPaused = false,
   }) async {
     assert(!_readyToAnnounce);
     if (!_residentRunner.supportsServiceProtocol || _devToolsLauncher == null) {
@@ -88,20 +90,14 @@ class FlutterResidentDevtoolsHandler implements ResidentDevtoolsHandler {
       assert(!_readyToAnnounce);
       return;
     }
-    final List<FlutterDevice?> devicesWithExtension = await _devicesWithExtensions(flutterDevices);
-    await _maybeCallDevToolsUriServiceExtension(devicesWithExtension);
-    await _callConnectedVmServiceUriExtension(devicesWithExtension);
-
     if (_shutdown) {
       // If we're shutting down, no point reporting the debugger list.
       return;
     }
-    _readyToAnnounce = true;
-    assert(_devToolsLauncher!.activeDevToolsServer != null);
 
     final Uri? devToolsUrl = _devToolsLauncher!.devToolsUrl;
     if (devToolsUrl != null) {
-      for (final FlutterDevice? device in devicesWithExtension) {
+      for (final FlutterDevice? device in flutterDevices) {
         if (device == null) {
           continue;
         }
@@ -111,11 +107,35 @@ class FlutterResidentDevtoolsHandler implements ResidentDevtoolsHandler {
       }
     }
 
+    Future<void> callServiceExtensions() async {
+      final List<FlutterDevice?> devicesWithExtension = await _devicesWithExtensions(flutterDevices);
+      await Future.wait(
+        <Future<void>>[
+          _maybeCallDevToolsUriServiceExtension(devicesWithExtension),
+          _callConnectedVmServiceUriExtension(devicesWithExtension)
+        ]
+      );
+    }
+
+    // If the application is starting paused, we can't invoke service extensions
+    // as they're handled on the target app's paused isolate. Since invoking
+    // service extensions will block in this situation, we should wait to invoke
+    // them until after we've output the DevTools connection details.
+    if (!isStartPaused) {
+      await callServiceExtensions();
+    }
+
+    _readyToAnnounce = true;
+    assert(_devToolsLauncher!.activeDevToolsServer != null);
     if (_residentRunner.reportedDebuggers) {
       // Since the DevTools only just became available, we haven't had a chance to
       // report their URLs yet. Do so now.
       _residentRunner.printDebuggerList(includeVmService: false);
     }
+
+    if (isStartPaused) {
+      await callServiceExtensions();
+    }
   }
 
   // This must be guaranteed not to return a Future that fails.
@@ -295,7 +315,11 @@ class NoOpDevtoolsHandler implements ResidentDevtoolsHandler {
   }
 
   @override
-  Future<void> serveAndAnnounceDevTools({Uri? devToolsServerAddress, List<FlutterDevice?>? flutterDevices}) async {
+  Future<void> serveAndAnnounceDevTools({
+    Uri? devToolsServerAddress,
+    List<FlutterDevice?>? flutterDevices,
+    bool isStartPaused = false,
+  }) async {
     return;
   }
 

packages/flutter_tools/lib/src/run_cold.dart

@@ -86,6 +86,7 @@ class ColdRunner extends ResidentRunner {
         unawaited(residentDevtoolsHandler!.serveAndAnnounceDevTools(
           devToolsServerAddress: debuggingOptions.devToolsServerAddress,
           flutterDevices: flutterDevices,
+          isStartPaused: debuggingOptions.startPaused,
         ));
       }
       if (debuggingOptions.serveObservatory) {
@@ -173,6 +174,7 @@ class ColdRunner extends ResidentRunner {
         unawaited(residentDevtoolsHandler!.serveAndAnnounceDevTools(
           devToolsServerAddress: debuggingOptions.devToolsServerAddress,
           flutterDevices: flutterDevices,
+          isStartPaused: debuggingOptions.startPaused,
         ));
       }
       if (debuggingOptions.serveObservatory) {

packages/flutter_tools/lib/src/run_hot.dart

@@ -246,6 +246,7 @@ class HotRunner extends ResidentRunner {
       unawaited(residentDevtoolsHandler!.serveAndAnnounceDevTools(
         devToolsServerAddress: debuggingOptions.devToolsServerAddress,
         flutterDevices: flutterDevices,
+        isStartPaused: debuggingOptions.startPaused,
       ));
     }
 

packages/flutter_tools/test/general.shard/resident_devtools_handler_test.dart

@@ -156,6 +156,7 @@ void main() {
         },
       ),
       listViews,
+      listViews,
       const FakeVmServiceRequest(
         method: 'ext.flutter.activeDevToolsServerAddress',
         args: <String, Object>{
@@ -163,7 +164,6 @@ void main() {
           'value': 'http://localhost:8080',
         },
       ),
-      listViews,
       const FakeVmServiceRequest(
         method: 'ext.flutter.connectedVmServiceUri',
         args: <String, Object>{
@@ -314,6 +314,7 @@ void main() {
         },
       ),
       listViews,
+      listViews,
       const FakeVmServiceRequest(
         method: 'ext.flutter.activeDevToolsServerAddress',
         args: <String, Object>{
@@ -321,7 +322,6 @@ void main() {
           'value': 'http://localhost:8080',
         },
       ),
-      listViews,
       const FakeVmServiceRequest(
         method: 'ext.flutter.connectedVmServiceUri',
         args: <String, Object>{

packages/flutter_tools/test/integration.shard/devtools_uri_test.dart

+// Copyright 2014 The Flutter Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import 'dart:async';
+
+import 'package:flutter_tools/src/base/file_system.dart';
+import 'package:flutter_tools/src/base/io.dart';
+import 'package:flutter_tools/src/convert.dart';
+
+import '../src/common.dart';
+import 'test_data/basic_project.dart';
+import 'test_utils.dart';
+
+void main() {
+  late Directory tempDir;
+  final BasicProject project = BasicProject();
+
+  setUp(() async {
+    tempDir = createResolvedTempDirectorySync('run_test.');
+    await project.setUpIn(tempDir);
+  });
+
+  tearDown(() async {
+    tryToDelete(tempDir);
+  });
+
+  // Regression test for https://github.com/flutter/flutter/issues/126691
+  testWithoutContext('flutter run --start-paused prints DevTools URI', () async {
+    final Completer<void> completer = Completer<void>();
+    final RegExp matcher = RegExp(r'The Flutter DevTools debugger and profiler on');
+
+    final String flutterBin = fileSystem.path.join(getFlutterRoot(), 'bin', 'flutter');
+    final Process process = await processManager.start(<String>[
+      flutterBin,
+      'run',
+      '--start-paused',
+      '-d',
+      'flutter-tester',
+    ], workingDirectory: tempDir.path);
+
+    late StreamSubscription<String> sub;
+    sub = process.stdout.transform(utf8.decoder).listen((String message) {
+      if (message.contains(matcher)) {
+        completer.complete();
+        sub.cancel();
+      }
+    });
+    await completer.future;
+    process.kill();
+    await process.exitCode;
+  });
+}