fix(sdk): omit unsupported launch presentation

Author: SarthakWade

packages/headless-python/README.md

@@ -68,15 +68,17 @@ state.
 ```python
 from headless_sdk import launch
 
-with launch(presentation="background", allow=["example.com"]) as host:
+with launch(allow=["example.com"]) as host:
     print(host.client.host_status["pid"])
 ```
 
-`launch()` runs `headless start --background --supervised`, keeps the owner pipe open,
-and grants ownership only after the startup response PID matches the connected host
-PID. Closing the wrapper terminates and reaps only that owned launcher. It cannot
-adopt or stop a concurrently started shared host. Use `presentation="foreground"`
-to request the foreground app behavior. Custom executable paths must be absolute.
+`launch()` runs `headless start --supervised`, keeps the owner pipe open, and grants
+ownership only after the startup response PID matches the connected host PID.
+Closing the wrapper terminates and reaps only that owned launcher. It cannot adopt
+or stop a concurrently started shared host. Omit `presentation` to preserve the
+platform default. On macOS, pass `presentation="background"` or
+`presentation="foreground"` for an explicit override. Custom executable paths must
+be absolute.
 
 ## Authentication and untrusted data
 

packages/headless-python/src/headless_sdk/generated.py

@@ -13,7 +13,7 @@
 PROTOCOL_SCHEMA_VERSION = 1
 MAXIMUM_MESSAGE_BYTES = 1048576
 MAXIMUM_COMMAND_TIMEOUT_SECONDS = 125.0
-PROTOCOL_SCHEMA_SHA256 = 'c199f18185cfa05b5c16c9140e48e1f588c61188b5f2ea6fa58eea2ddc57dcbf'
+PROTOCOL_SCHEMA_SHA256 = '882634187c7ef02ec4ed51fff0e747114eadeff308c10bb9b3274b3630fad11d'
 PROTOCOL_FIXTURES_SHA256 = '0b51ffaa2d3e3aaf0c32adcfeb02c180dcbe44face0d49e1c332b69f403ae062'
 RESPONSE_ADDITIONAL_PROPERTIES = True
 COMMAND_ERROR_CODES = ('ARTIFACT_ERROR', 'AUTH_ACCOUNT_NOT_FOUND', 'AUTH_CHALLENGE_CONSUMED', 'AUTH_CHALLENGE_EXPIRED', 'AUTH_CHALLENGE_NOT_FOUND', 'AUTH_FORM_CHANGED', 'AUTH_ORIGIN_CHANGED', 'AUTH_REQUIRED', 'CREDENTIAL_ALIAS_EXISTS', 'ELEMENT_NOT_FOUND', 'FLOW_FAILED', 'HOST_STOPPING', 'HOST_UNAVAILABLE', 'INTERNAL_ERROR', 'INVALID_CAPTURE_FORMAT', 'INVALID_COMMAND', 'INVALID_FLOW', 'INVALID_INPUT', 'INVALID_REQUEST', 'INVALID_SESSION', 'MISSING_PARAMETER', 'OPERATION_FAILED', 'PEER_DENIED', 'RECORDER_UNAVAILABLE', 'RECORDING_ACTIVE', 'RECORDING_FAILED', 'RECORDING_NOT_ACTIVE', 'REGION_NOT_FOUND', 'RESPONSE_TOO_LARGE', 'SENSITIVE_DIAGNOSTICS_DISABLED', 'SESSION_EXISTS', 'SESSION_NOT_FOUND', 'TIMEOUT', 'UNSAFE_NAVIGATION', 'UNSAFE_RESOURCE_TYPE', 'UNSUPPORTED_CAPABILITY', 'USER_PRESENCE_DENIED', 'USER_PRESENCE_UNAVAILABLE', 'VAULT_LOCKED', 'VAULT_OPERATION_FAILED', 'VAULT_RESPONSE_INVALID', 'VAULT_UNAVAILABLE')
@@ -1661,7 +1661,7 @@ class AuthenticationRequired(TypedDict, total=False):
 LOCAL_LIFECYCLE: dict[str, Any] = {'connect': {'errors': ['HOST_UNAVAILABLE'],
              'ownership': 'shared',
              'transport': 'local-unix-socket'},
- 'launch': {'argv': ['start', '--background', '--supervised'],
+ 'launch': {'argv': ['start', '--supervised'],
             'command': 'start',
             'errors': ['HOST_START_FAILED',
                        'NAVIGATION_ALLOWLIST_CONFLICT',

packages/headless-python/src/headless_sdk/lifecycle.py

@@ -346,7 +346,7 @@ def launch(
     *,
     executable: str | os.PathLike[str] | None = None,
     socket_path: str | None = None,
-    presentation: LaunchPresentation = "background",
+    presentation: LaunchPresentation | None = None,
     allow: Sequence[str] = (),
     environment: Mapping[str, str] | None = None,
     startup_timeout: float = _DEFAULT_STARTUP_TIMEOUT,
@@ -374,18 +374,24 @@ def launch(
         default_socket_path(selected_environment) if socket_path is None else socket_path
     )
     validate_socket_location(selected_socket)
-    if not isinstance(presentation, str) or presentation not in LAUNCH_PRESENTATIONS:
+    if presentation is not None and (
+        not isinstance(presentation, str) or presentation not in LAUNCH_PRESENTATIONS
+    ):
         raise ValidationError(f"presentation must be one of {', '.join(LAUNCH_PRESENTATIONS)}")
     if isinstance(allow, (str, bytes)) or not isinstance(allow, Sequence):
         raise ValidationError("allow must be a sequence of host patterns")
     presentation_flags = {f"--{value}" for value in LAUNCH_PRESENTATIONS}
     argv = cast(list[str], list(LOCAL_LIFECYCLE["launch"]["argv"]))
     existing_flags = [argument for argument in argv if argument in presentation_flags]
-    if len(existing_flags) != 1:
+    if existing_flags:
         raise ValidationError("generated launch argv has an invalid presentation flag")
-    argv = [
-        f"--{presentation}" if argument in presentation_flags else argument for argument in argv
+    supervised_indexes = [
+        index for index, argument in enumerate(argv) if argument == "--supervised"
     ]
+    if len(supervised_indexes) != 1:
+        raise ValidationError("generated launch argv has an invalid supervised flag")
+    if presentation is not None:
+        argv.insert(supervised_indexes[0], f"--{presentation}")
     allow_definition = next(
         (option for option in LOCAL_LIFECYCLE["launch"]["options"] if option["name"] == "allow"),
         None,
@@ -537,7 +543,7 @@ async def alaunch(
     *,
     executable: str | os.PathLike[str] | None = None,
     socket_path: str | None = None,
-    presentation: LaunchPresentation = "background",
+    presentation: LaunchPresentation | None = None,
     allow: Sequence[str] = (),
     environment: Mapping[str, str] | None = None,
     startup_timeout: float = _DEFAULT_STARTUP_TIMEOUT,

packages/headless-python/tests/helpers.py

@@ -139,9 +139,12 @@ def write_mock_launcher(directory: Path) -> Path:
 
 PROTOCOL_VERSION = {PROTOCOL_VERSION!r}
 mode = os.environ.get("HEADLESS_TEST_MODE", "owned")
-expected_presentation = os.environ.get("HEADLESS_TEST_PRESENTATION", "background")
-expected = ["start", "--" + expected_presentation, "--supervised"]
-if sys.argv[1:4] != expected:
+expected_presentation = os.environ.get("HEADLESS_TEST_PRESENTATION")
+expected = ["start"]
+if expected_presentation:
+    expected.append("--" + expected_presentation)
+expected.append("--supervised")
+if sys.argv[1:1 + len(expected)] != expected:
     sys.exit(64)
 socket_path = os.environ["HEADLESS_SOCKET"]
 commands = json.loads(os.environ["HEADLESS_TEST_COMMANDS"])

packages/headless-python/tests/test_lifecycle.py

@@ -67,7 +67,7 @@ def test_supervised_launch_owns_only_exact_matching_host(tmp_path: Path) -> None
     }
     host = launch(executable=executable, socket_path=socket_path, environment=environment())
     try:
-        assert LOCAL_LIFECYCLE["launch"]["argv"] == ["start", "--background", "--supervised"]
+        assert LOCAL_LIFECYCLE["launch"]["argv"] == ["start", "--supervised"]
         assert host.pid == host.client.host_status["pid"]
         assert host.launcher_pid > 0
         assert signal.getsignal(signal.SIGINT) == signal_handlers[signal.SIGINT]