fix(sdk): preserve platform launch defaults

Author: SarthakWade

packages/headless-npm/README.md

@@ -50,10 +50,11 @@ that trust marker when sending page content to an agent or another system.
 ## Supervised host
 
 Use `launch()` when this process must own a new host. It invokes the installed
-CLI with `headless start --background --supervised`, keeps the ownership pipe
-open, verifies that the startup response and socket report the same host PID,
-and reaps only that launcher during disposal. It fails rather than claiming an
-already-running shared host.
+CLI with `headless start --supervised`, keeps the ownership pipe open, verifies
+that the startup response and socket report the same host PID, and reaps only
+that launcher during disposal. Omit `presentation` to preserve the platform
+default, or explicitly select `background` or `foreground` on macOS. Launch
+fails rather than claiming an already-running shared host.
 
 ```ts
 import { launch } from "@lockintime/headless";

packages/headless-npm/src/generated.ts

@@ -7,7 +7,7 @@ export type Untrusted<T> = Readonly<{ readonly untrustedContent: true; readonly
 export const PROTOCOL_VERSION = "0.5" as const;
 export const PROTOCOL_SCHEMA_VERSION = 1 as const;
 export const MAXIMUM_MESSAGE_BYTES = 1048576 as const;
-export const PROTOCOL_SCHEMA_SHA256 = "c199f18185cfa05b5c16c9140e48e1f588c61188b5f2ea6fa58eea2ddc57dcbf" as const;
+export const PROTOCOL_SCHEMA_SHA256 = "882634187c7ef02ec4ed51fff0e747114eadeff308c10bb9b3274b3630fad11d" as const;
 export const PROTOCOL_FIXTURES_SHA256 = "0b51ffaa2d3e3aaf0c32adcfeb02c180dcbe44face0d49e1c332b69f403ae062" as const;
 export const RESPONSE_ADDITIONAL_PROPERTIES = true as const;
 export const MAXIMUM_COMMAND_TIMEOUT_MS = 125000 as const;
@@ -22,7 +22,6 @@ export const LOCAL_LIFECYCLE = {
   "launch": {
     "argv": [
       "start",
-      "--background",
       "--supervised"
     ],
     "command": "start",

packages/headless-npm/src/lifecycle.ts

@@ -337,19 +337,23 @@ export async function launch(options: LaunchOptions = {}): Promise<HeadlessHost>
     : AbortSignal.any([options.signal, deadlineSignal]);
   const socketPath = options.socketPath ?? defaultSocketPath(options.environment ?? process.env);
   validateSocketLocation(socketPath);
-  const presentation = options.presentation ?? "background";
-  if (!(LAUNCH_PRESENTATIONS as readonly string[]).includes(presentation)) {
+  const presentation = options.presentation;
+  if (presentation !== undefined
+    && !(LAUNCH_PRESENTATIONS as readonly string[]).includes(presentation)) {
     throw new ValidationError(`presentation must be one of ${LAUNCH_PRESENTATIONS.join(", ")}`);
   }
   const presentationFlags = new Set(LAUNCH_PRESENTATIONS.map((value) => `--${value}`));
   const generatedPresentationFlags = LOCAL_LIFECYCLE.launch.argv
     .filter((argument) => presentationFlags.has(argument));
-  if (generatedPresentationFlags.length !== 1) {
+  if (generatedPresentationFlags.length !== 0) {
     throw new ValidationError("generated launch argv has an invalid presentation flag");
   }
-  const argumentsList: string[] = LOCAL_LIFECYCLE.launch.argv.map((argument) => (
-    presentationFlags.has(argument) ? `--${presentation}` : argument
-  ));
+  const argumentsList: string[] = [...LOCAL_LIFECYCLE.launch.argv];
+  const supervisedIndex = argumentsList.indexOf("--supervised");
+  if (supervisedIndex < 0 || argumentsList.lastIndexOf("--supervised") !== supervisedIndex) {
+    throw new ValidationError("generated launch argv has an invalid supervised flag");
+  }
+  if (presentation !== undefined) argumentsList.splice(supervisedIndex, 0, `--${presentation}`);
   const allowDefinition = LOCAL_LIFECYCLE.launch.options.find((option) => option.name === "allow");
   const allow = options.allow ?? [];
   if (!allowDefinition || allow.length > allowDefinition.maximumItems) {

packages/headless-npm/test/lifecycle.test.mjs

@@ -46,9 +46,15 @@ import { chmodSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { createServer } from "node:net";
 import { dirname } from "node:path";
 
-const expectedPresentation = process.env.HEADLESS_TEST_EXPECT_PRESENTATION ?? "background";
-const expected = ["start", "--" + expectedPresentation, "--supervised"];
-if (JSON.stringify(process.argv.slice(2, 5)) !== JSON.stringify(expected)) process.exit(64);
+const expectedPresentation = process.env.HEADLESS_TEST_EXPECT_PRESENTATION;
+const expected = [
+  "start",
+  ...(expectedPresentation ? ["--" + expectedPresentation] : []),
+  "--supervised",
+];
+if (JSON.stringify(process.argv.slice(2, 2 + expected.length)) !== JSON.stringify(expected)) {
+  process.exit(64);
+}
 const mode = process.env.HEADLESS_TEST_MODE ?? "owned";
 const socketPath = process.env.HEADLESS_SOCKET;
 const commands = JSON.parse(process.env.HEADLESS_TEST_COMMANDS);
@@ -158,7 +164,7 @@ test("supervised launch uses generated argv and owns only the matching host", as
     socketPath,
     environment: launchEnvironment(),
   });
-  assert.deepEqual(LOCAL_LIFECYCLE.launch.argv, ["start", "--background", "--supervised"]);
+  assert.deepEqual(LOCAL_LIFECYCLE.launch.argv, ["start", "--supervised"]);
   assert.equal(host.client.hostStatus.pid > 0, true);
   assert.deepEqual(
     { SIGINT: process.listenerCount("SIGINT"), SIGTERM: process.listenerCount("SIGTERM") },