pi-agent-browser-native 0.2.38 → 0.2.40

package/scripts/config.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Manage pi-agent-browser-native package config under Pi-scoped config paths.
+ * Responsibilities: Print config paths/status, write redacted web-search and browser profile settings, preserve safe permissions, and avoid echoing secrets.
+ * Scope: Maintainer/user setup CLI only; extension runtime validation and tool execution live under extensions/agent-browser/lib/.
+ */
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import process from "node:process";
+
+const CONFIG_ENV = "PI_AGENT_BROWSER_CONFIG";
+const BRAVE_API_KEY_ENV = "BRAVE_API_KEY";
+const RELATIVE_CONFIG = [".pi", "config", "pi-agent-browser-native", "config.json"];
+const DEFAULT_CONFIG = { version: 1 };
+
+class UsageError extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "UsageError";
+	}
+}
+
+function usage() {
+	return `pi-agent-browser-config
+
+Usage:
+  pi-agent-browser-config paths
+  pi-agent-browser-config show
+  pi-agent-browser-config web-search status
+  pi-agent-browser-config web-search set-key --stdin [--global]
+  pi-agent-browser-config web-search set-env <ENV_VAR> [--global|--project]
+  pi-agent-browser-config web-search set-command <command> [--global]
+  pi-agent-browser-config web-search clear [--global|--project]
+  pi-agent-browser-config browser profile status
+  pi-agent-browser-config browser profile set <name> [--policy explicit-only|authenticated-only|always] [--global|--project]
+  pi-agent-browser-config browser profile clear [--global|--project]
+
+Notes:
+  Global config:  ~/.pi/config/pi-agent-browser-native/config.json
+  Project config: .pi/config/pi-agent-browser-native/config.json
+  Override:       PI_AGENT_BROWSER_CONFIG=/path/to/config.json
+  Project-local plaintext, interpolation-literal, malformed, and command-backed web-search keys are refused; use exact set-env references there.
+`;
+}
+
+function getHome(env = process.env) {
+	return env.HOME?.trim() || env.USERPROFILE?.trim();
+}
+
+function getGlobalConfigPath(env = process.env) {
+	const home = getHome(env);
+	if (!home) throw new Error("Could not resolve home directory for global config.");
+	return resolve(home, ...RELATIVE_CONFIG);
+}
+
+function getProjectConfigPath(cwd = process.cwd()) {
+	return resolve(cwd, ...RELATIVE_CONFIG);
+}
+
+function getPaths(env = process.env, cwd = process.cwd()) {
+	const override = env[CONFIG_ENV]?.trim();
+	return {
+		global: getGlobalConfigPath(env),
+		project: getProjectConfigPath(cwd),
+		override: override ? resolve(override) : undefined,
+	};
+}
+
+function parseArgs(argv) {
+	const positional = [];
+	const flags = new Map();
+	for (let index = 0; index < argv.length; index += 1) {
+		const arg = argv[index];
+		if (!arg.startsWith("--")) {
+			positional.push(arg);
+			continue;
+		}
+		if (arg === "--global" || arg === "--project" || arg === "--stdin" || arg === "--help") {
+			flags.set(arg, true);
+			continue;
+		}
+		if (arg === "--policy") {
+			const value = argv[index + 1];
+			if (!value || value.startsWith("--")) throw new UsageError("--policy requires a value.");
+			flags.set(arg, value);
+			index += 1;
+			continue;
+		}
+		throw new UsageError(`Unknown option: ${arg}`);
+	}
+	if (flags.get("--global") && flags.get("--project")) throw new UsageError("Use only one of --global or --project.");
+	return { flags, positional };
+}
+
+function readConfig(path) {
+	if (!existsSync(path)) return { ...DEFAULT_CONFIG };
+	const parsed = JSON.parse(readFileSync(path, "utf8"));
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error(`${path} must contain a JSON object.`);
+	return { ...DEFAULT_CONFIG, ...parsed };
+}
+
+function writeConfig(path, config) {
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+	try {
+		chmodSync(dirname(path), 0o700);
+		chmodSync(path, 0o600);
+	} catch {
+		// Best effort on platforms/filesystems that do not support POSIX modes.
+	}
+}
+
+function selectWritePath(flags) {
+	const paths = getPaths();
+	if (flags.get("--project")) return { path: paths.project, scope: "project" };
+	return { path: paths.global, scope: "global" };
+}
+
+function classifyCredential(rawValue) {
+	const trimmed = String(rawValue ?? "").trim();
+	if (!trimmed) return "not configured";
+	if (trimmed.startsWith("!")) return "configured via command";
+	if (trimmed.includes("$")) return "configured via environment interpolation";
+	return "configured as plaintext [redacted]";
+}
+
+function mergeConfig() {
+	const paths = getPaths();
+	const layers = [];
+	for (const [scope, path] of [["global", paths.global], ["project", paths.project], ...(paths.override ? [["override", paths.override]] : [])]) {
+		if (!existsSync(path)) continue;
+		layers.push({ scope, path, config: readConfig(path) });
+	}
+	const merged = layers.reduce((current, layer) => ({
+		...current,
+		...layer.config,
+		browser: { ...(current.browser ?? {}), ...(layer.config.browser ?? {}) },
+		webSearch: { ...(current.webSearch ?? {}), ...(layer.config.webSearch ?? {}) },
+	}), { ...DEFAULT_CONFIG });
+	return { layers, merged, paths };
+}
+
+function printPaths() {
+	const paths = getPaths();
+	console.log(`Global: ${paths.global}`);
+	console.log(`Project: ${paths.project}`);
+	console.log(`Override: ${paths.override ?? `${CONFIG_ENV} not set`}`);
+}
+
+function printStatus() {
+	const { layers, merged, paths } = mergeConfig();
+	printPaths();
+	console.log("");
+	console.log("Config files:");
+	for (const [scope, path] of [["global", paths.global], ["project", paths.project], ...(paths.override ? [["override", paths.override]] : [])]) {
+		console.log(`  ${scope}: ${path} ${existsSync(path) ? "[exists]" : "[missing]"}`);
+	}
+	console.log("");
+	console.log("Effective config:");
+	const source = merged.webSearch?.braveApiKey;
+	console.log(`  webSearch.braveApiKey: ${source ? classifyCredential(source) : process.env[BRAVE_API_KEY_ENV]?.trim() ? `configured via ${BRAVE_API_KEY_ENV} environment fallback` : "not configured"}`);
+	const profile = merged.browser?.defaultProfile;
+	console.log(`  browser.defaultProfile: ${profile?.name ? `${profile.name} (policy: ${profile.policy ?? "authenticated-only"})` : "not configured"}`);
+	if (layers.length === 0) console.log("  layers: none");
+}
+
+async function readSecretFromStdin(useStdin) {
+	if (!useStdin) throw new UsageError("set-key requires --stdin so the key is not passed through argv or an echoed prompt.");
+	let input = "";
+	for await (const chunk of process.stdin) input += chunk;
+	const value = input.trim();
+	if (!value) throw new UsageError("No key was provided on stdin.");
+	return value;
+}
+
+function mutateConfig(path, mutate) {
+	const config = readConfig(path);
+	mutate(config);
+	writeConfig(path, config);
+}
+
+async function handleWebSearch(args, flags) {
+	const action = args[0];
+	if (action === "status") {
+		printStatus();
+		return;
+	}
+	if (action === "set-key") {
+		if (flags.get("--project")) throw new UsageError("Plaintext Brave keys cannot be written to project-local config. Use set-env or set-command.");
+		const key = await readSecretFromStdin(Boolean(flags.get("--stdin")));
+		const { path } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			config.webSearch = { ...(config.webSearch ?? {}), braveApiKey: key };
+		});
+		console.log(`Saved Brave Search key to global config: ${path}`);
+		return;
+	}
+	if (action === "set-env") {
+		const envName = args[1];
+		if (!envName || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(envName)) throw new UsageError("set-env requires a valid environment variable name.");
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			config.webSearch = { ...(config.webSearch ?? {}), braveApiKey: `$${envName}` };
+		});
+		console.log(`Saved Brave Search ${scope} env reference to: ${path}`);
+		return;
+	}
+	if (action === "set-command") {
+		if (flags.get("--project")) throw new UsageError("Command-backed Brave keys cannot be written to project-local config. Use set-env there.");
+		const command = args.slice(1).join(" ").trim();
+		if (!command) throw new UsageError("set-command requires a command string.");
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			config.webSearch = { ...(config.webSearch ?? {}), braveApiKey: `!${command}` };
+		});
+		console.log(`Saved Brave Search ${scope} command source to: ${path}`);
+		return;
+	}
+	if (action === "clear") {
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			if (config.webSearch) delete config.webSearch.braveApiKey;
+		});
+		console.log(`Cleared Brave Search credential source in ${scope} config: ${path}`);
+		return;
+	}
+	throw new UsageError(`Unsupported web-search action: ${action ?? ""}`);
+}
+
+function handleBrowser(args, flags) {
+	if (args[0] !== "profile") throw new UsageError(`Unsupported browser action: ${args[0] ?? ""}`);
+	const action = args[1];
+	if (action === "status") {
+		printStatus();
+		return;
+	}
+	if (action === "set") {
+		const name = args[2]?.trim();
+		if (!name) throw new UsageError("browser profile set requires a profile name.");
+		const policy = flags.get("--policy") || "authenticated-only";
+		if (!["explicit-only", "authenticated-only", "always"].includes(policy)) throw new UsageError("Invalid --policy value.");
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			config.browser = { ...(config.browser ?? {}), defaultProfile: { name, policy } };
+		});
+		console.log(`Saved browser default profile in ${scope} config: ${path}`);
+		return;
+	}
+	if (action === "clear") {
+		const { path, scope } = selectWritePath(flags);
+		mutateConfig(path, (config) => {
+			if (config.browser) delete config.browser.defaultProfile;
+		});
+		console.log(`Cleared browser default profile in ${scope} config: ${path}`);
+		return;
+	}
+	throw new UsageError(`Unsupported browser profile action: ${action ?? ""}`);
+}
+
+export async function main(argv = process.argv.slice(2)) {
+	const { flags, positional } = parseArgs(argv);
+	if (flags.get("--help") || positional.length === 0) {
+		console.log(usage());
+		return 0;
+	}
+	const command = positional[0];
+	if (command === "paths") {
+		printPaths();
+		return 0;
+	}
+	if (command === "show") {
+		printStatus();
+		return 0;
+	}
+	if (command === "web-search") {
+		await handleWebSearch(positional.slice(1), flags);
+		return 0;
+	}
+	if (command === "browser") {
+		handleBrowser(positional.slice(1), flags);
+		return 0;
+	}
+	throw new UsageError(`Unknown command: ${command}`);
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+	main().catch((error) => {
+		if (error instanceof UsageError) {
+			console.error(error.message);
+			console.error(usage());
+			process.exit(2);
+		}
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exit(1);
+	});
+}

package/scripts/platform-smoke/artifacts.mjs

@@ -0,0 +1,94 @@
+/** Artifact helpers for platform smoke suites. */
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { relative, resolve } from "node:path";
+
+export function createSuiteDir(artifactRoot, runId, targetName, suiteName) {
+	const dir = resolve(process.cwd(), artifactRoot, runId, targetName, suiteName);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+export function writeCommand(dir, command) {
+	writeFileSync(resolve(dir, "command.txt"), `${command}\n`);
+}
+
+export function writeExitCode(dir, code, signal) {
+	writeFileSync(resolve(dir, "exit-code.txt"), `code=${code}\nsignal=${signal ?? "none"}\n`);
+}
+
+export function writeSummary(dir, data) {
+	writeFileSync(resolve(dir, "summary.json"), JSON.stringify({ ...data, writtenAt: new Date().toISOString() }, null, 2));
+}
+
+export function writeManifest(dir, expectedFiles) {
+	const present = [];
+	function walk(current) {
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const path = resolve(current, entry.name);
+			if (entry.isDirectory()) walk(path);
+			else if (entry.isFile()) present.push(relative(dir, path));
+		}
+	}
+	if (existsSync(dir)) walk(dir);
+	const allPresent = [...new Set([...present, "artifact-manifest.json"])].sort();
+	const manifest = {
+		expected: expectedFiles,
+		present: allPresent,
+		missing: expectedFiles.filter((file) => !allPresent.includes(file)),
+		writtenAt: new Date().toISOString(),
+	};
+	writeFileSync(resolve(dir, "artifact-manifest.json"), JSON.stringify(manifest, null, 2));
+	return manifest;
+}
+
+export function collectSecretValues(envNames, env = process.env) {
+	return [...new Set(envNames.map((name) => env[name]).filter((value) => typeof value === "string" && value.length >= 8))];
+}
+
+export function redactSecrets(text, secretValues = []) {
+	let redacted = String(text ?? "");
+	for (const secret of secretValues) {
+		redacted = redacted.split(secret).join("[REDACTED_SECRET]");
+	}
+	return redacted;
+}
+
+export function scanForSecrets(text, secretValues = []) {
+	const content = String(text ?? "");
+	const violations = [];
+	for (const secret of secretValues) {
+		if (secret && content.includes(secret)) violations.push("raw forwarded secret value");
+	}
+	for (const [pattern, label] of [
+		[/bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/gi, "bearer token"],
+		[/Authorization:\s*Bearer\s+[A-Za-z0-9\-._~+/]{20,}=*/gi, "authorization header"],
+		[/(?:api[_-]?key|access[_-]?token|refresh[_-]?token|cookie)\s*[:=]\s*["']?[A-Za-z0-9_./+\-=]{20,}/gi, "token-like field"],
+	]) {
+		if (pattern.test(content)) violations.push(label);
+	}
+	return [...new Set(violations)];
+}
+
+export function scanArtifactTextFiles(dir, secretValues = []) {
+	const findings = [];
+	function walk(current) {
+		for (const entry of readdirSync(current, { withFileTypes: true })) {
+			const path = resolve(current, entry.name);
+			if (entry.isDirectory()) {
+				walk(path);
+				continue;
+			}
+			if (!entry.isFile()) continue;
+			if (!/\.(?:txt|json|jsonl|md|log|ps1|mjs|js)$/i.test(entry.name)) continue;
+			try {
+				const text = readFileSync(path, "utf8");
+				for (const violation of scanForSecrets(text, secretValues)) findings.push({ file: relative(dir, path), violation });
+			} catch {
+				// Ignore unreadable or non-text files.
+			}
+		}
+	}
+	walk(dir);
+	return findings;
+}

package/scripts/platform-smoke/browser-dogfood-windows.ps1

@@ -0,0 +1,110 @@
+param(
+  [Parameter(Mandatory=$true)][string]$AgentBrowserVersion
+)
+
+$ErrorActionPreference = "Continue"
+$SourceRoot = (Get-Location).Path
+$RunRoot = Join-Path ".platform-smoke-runs" ("browser-dogfood-{0}-{1}" -f ((Get-Date).ToUniversalTime().ToString("yyyyMMddTHHmmssZ")), $PID)
+$DogfoodDir = Join-Path $SourceRoot (Join-Path $RunRoot "dogfood")
+$DogfoodArtifactDir = Join-Path $env:TEMP ("pi-agent-browser-dogfood-artifacts-{0}" -f $PID)
+New-Item -ItemType Directory -Force -Path $DogfoodDir | Out-Null
+New-Item -ItemType Directory -Force -Path $DogfoodArtifactDir | Out-Null
+
+function Write-Section($Name, $Path) {
+  Write-Output "--- $Name START ---"
+  if (Test-Path $Path) { Get-Content -Raw $Path }
+  Write-Output "--- $Name END ---"
+}
+
+function Get-AgentBrowserVersion() {
+  if (-not (Get-Command agent-browser -ErrorAction SilentlyContinue)) { return "" }
+  return (& agent-browser --version 2>$null)
+}
+
+function Test-AgentBrowser($Version) {
+  $Expected = "agent-browser $Version"
+  $Current = Get-AgentBrowserVersion
+  Write-Output "PLATFORM_AGENT_BROWSER_VERSION=$Current"
+  $script:AgentBrowserReadyExit = if ($Current -eq $Expected) { 0 } else { 1 }
+}
+
+function Test-AgentBrowserBrowserCache() {
+  $Candidates = @(
+    (Join-Path $env:USERPROFILE ".agent-browser\browsers"),
+    "C:\WINDOWS\system32\config\systemprofile\.agent-browser\browsers"
+  )
+  foreach ($Candidate in $Candidates) {
+    if (-not $Candidate -or -not (Test-Path $Candidate)) { continue }
+    $Chrome = Get-ChildItem -Path $Candidate -Recurse -Filter chrome.exe -ErrorAction SilentlyContinue | Select-Object -First 1
+    if ($Chrome) {
+      Write-Output "PLATFORM_AGENT_BROWSER_BROWSER_PATH=$($Chrome.FullName)"
+      $script:BrowserCacheExit = 0
+      return
+    }
+  }
+  Write-Output "PLATFORM_AGENT_BROWSER_BROWSER_PATH="
+  $script:BrowserCacheExit = 1
+}
+
+Write-Output "Starting browser-dogfood-smoke in $SourceRoot at $((Get-Date).ToUniversalTime().ToString('o'))"
+Write-Output "PLATFORM_RUN_ROOT=$RunRoot"
+Write-Output "PLATFORM_DOGFOOD_ARTIFACT_DIR=$DogfoodArtifactDir"
+
+$NodeVersion = (& node --version 2>$null)
+Write-Output "PLATFORM_NODE_VERSION=$NodeVersion"
+
+& npm ci 2>&1
+$NpmCiExit = $LASTEXITCODE
+Write-Output "PLATFORM_NPM_CI_EXIT=$NpmCiExit"
+
+$script:AgentBrowserReadyExit = 1
+Test-AgentBrowser $AgentBrowserVersion
+$AgentBrowserExit = $script:AgentBrowserReadyExit
+Write-Output "PLATFORM_AGENT_BROWSER_READY_EXIT=$AgentBrowserExit"
+$script:BrowserCacheExit = 1
+if ($AgentBrowserExit -eq 0) { Test-AgentBrowserBrowserCache }
+$BrowserCacheExit = $script:BrowserCacheExit
+Write-Output "PLATFORM_AGENT_BROWSER_BROWSER_CACHE_EXIT=$BrowserCacheExit"
+$BrowserPrewarmExit = 1
+if ($BrowserCacheExit -eq 0) {
+  $PrewarmPath = Join-Path $DogfoodArtifactDir "prewarm.html"
+  "<h1>Example Domain</h1>" | Set-Content $PrewarmPath
+  $PrewarmUrl = "file:///" + ($PrewarmPath -replace "\\", "/")
+  for ($Attempt = 1; $Attempt -le 3; $Attempt++) {
+    Write-Output "PLATFORM_AGENT_BROWSER_PREWARM_ATTEMPT=$Attempt"
+    & agent-browser open --json --session "platform-smoke-prewarm-$Attempt" $PrewarmUrl 2>&1
+    $BrowserPrewarmExit = $LASTEXITCODE
+    & agent-browser close --json --session "platform-smoke-prewarm-$Attempt" 2>&1
+    if ($BrowserPrewarmExit -eq 0) { break }
+    Start-Sleep -Seconds 2
+  }
+}
+Write-Output "PLATFORM_AGENT_BROWSER_PREWARM_EXIT=$BrowserPrewarmExit"
+
+$env:PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS = "55000"
+Write-Output "PLATFORM_PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS=$env:PI_AGENT_BROWSER_PROCESS_TIMEOUT_MS"
+
+$TsxCli = Join-Path $SourceRoot "node_modules/.bin/tsx.cmd"
+if (-not (Test-Path $TsxCli)) { $TsxCli = Join-Path $SourceRoot "node_modules/.bin/tsx" }
+if (-not (Test-Path $TsxCli)) { $TsxCli = "tsx" }
+Write-Output "PLATFORM_TSX_CLI=$TsxCli"
+
+$DogfoodStdout = Join-Path $DogfoodDir "dogfood.stdout.txt"
+$DogfoodStderr = Join-Path $DogfoodDir "dogfood.stderr.txt"
+if ($NpmCiExit -eq 0 -and $AgentBrowserExit -eq 0 -and $BrowserCacheExit -eq 0 -and $BrowserPrewarmExit -eq 0) {
+  & $TsxCli "scripts/verify-agent-browser-dogfood.ts" --artifact-dir $DogfoodArtifactDir --json >$DogfoodStdout 2>$DogfoodStderr
+  $DogfoodExit = $LASTEXITCODE
+} else {
+  "npm ci or agent-browser setup failed" | Set-Content $DogfoodStderr
+  $DogfoodExit = 1
+}
+Write-Output "PLATFORM_DOGFOOD_EXIT=$DogfoodExit"
+Write-Section "DOGFOOD_STDOUT" $DogfoodStdout
+Write-Section "DOGFOOD_STDERR" $DogfoodStderr
+
+if ($NpmCiExit -ne 0 -or $AgentBrowserExit -ne 0 -or $BrowserCacheExit -ne 0 -or $BrowserPrewarmExit -ne 0 -or $DogfoodExit -ne 0) {
+  Write-Output "PLATFORM_BROWSER_DOGFOOD_FAILED"
+  exit 1
+}
+
+Write-Output "PLATFORM_BROWSER_DOGFOOD_OK"

package/scripts/platform-smoke/crabbox-runner.mjs

@@ -0,0 +1,149 @@
+/** Thin Crabbox CLI wrapper for cross-platform smoke tests. */
+
+import { spawn } from "node:child_process";
+
+function env(name) {
+	return process.env[name] ?? "";
+}
+
+export function crabboxBin() {
+	return process.env.PLATFORM_SMOKE_CRABBOX || "crabbox";
+}
+
+function packageSlug(config = {}) {
+	return process.env.PLATFORM_SMOKE_PACKAGE_SLUG || config.packageName || "pi-agent-browser-native";
+}
+
+export function buildTargetBaseArgs(targetName, config = {}) {
+	switch (targetName) {
+		case "macos": {
+			const user = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
+			const host = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
+			const workRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${user}/crabbox/${packageSlug(config)}`;
+			return [
+				"--provider", "ssh",
+				"--target", "macos",
+				"--static-host", host,
+				"--static-user", user,
+				"--static-port", "22",
+				"--static-work-root", workRoot,
+			];
+		}
+		case "ubuntu": {
+			const image = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config.ubuntuContainerImage || "pi-agent-browser-native-platform:node24-agent-browser0.27.1";
+			return [
+				"--provider", "local-container",
+				"--target", "linux",
+				"--local-container-image", image,
+			];
+		}
+		case "windows-native": {
+			const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || "pi-extension-windows-template";
+			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || `C:\\crabbox\\${packageSlug(config)}`;
+			return [
+				"--provider", "parallels",
+				"--target", "windows",
+				"--windows-mode", "normal",
+				"--parallels-source", vm,
+				"--parallels-source-snapshot", snapshot,
+				"--parallels-user", user,
+				"--parallels-work-root", workRoot,
+			];
+		}
+		default:
+			throw new Error(`unknown platform smoke target: ${targetName}`);
+	}
+}
+
+export function leaseIdFor(targetName, slug) {
+	if (targetName === "macos") return "static_localhost";
+	return slug;
+}
+
+function parseLeaseId(text) {
+	return text.match(/\bleased\s+(\S+)/)?.[1]
+		?? text.match(/\blease=(\S+)/)?.[1]
+		?? null;
+}
+
+export function execCrabbox(args, options = {}) {
+	return new Promise((resolvePromise) => {
+		const child = spawn(crabboxBin(), args, {
+			stdio: ["ignore", "pipe", "pipe"],
+			env: { ...process.env, CRABBOX_SYNC_GIT_SEED: "false", ...options.env },
+		});
+		const stdout = [];
+		const stderr = [];
+		let timeout;
+		let killTimeout;
+		if (options.timeout) {
+			timeout = setTimeout(() => {
+				stderr.push(Buffer.from(`\n[platform-smoke] crabbox timed out after ${options.timeout}ms\n`));
+				try { child.kill("SIGTERM"); } catch {}
+				killTimeout = setTimeout(() => {
+					try { child.kill("SIGKILL"); } catch {}
+				}, 10_000);
+			}, options.timeout);
+		}
+		child.stdout.on("data", (chunk) => stdout.push(chunk));
+		child.stderr.on("data", (chunk) => stderr.push(chunk));
+		child.on("error", (error) => {
+			if (timeout) clearTimeout(timeout);
+			if (killTimeout) clearTimeout(killTimeout);
+			resolvePromise({ stdout: Buffer.concat(stdout).toString(), stderr: `${Buffer.concat(stderr).toString()}${error.message}\n`, code: 1, signal: null });
+		});
+		child.on("close", (code, signal) => {
+			if (timeout) clearTimeout(timeout);
+			if (killTimeout) clearTimeout(killTimeout);
+			resolvePromise({ stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), code: code ?? (signal ? 1 : 0), signal });
+		});
+	});
+}
+
+function isRetryableWarmupFailure(targetName, result) {
+	if (targetName !== "windows-native" || result.code === 0) return false;
+	return /Could not create a linked clone of the virtual hard disk|due to an internal error|context canceled|timed out after 300000ms/i.test(`${result.stdout}\n${result.stderr}`);
+}
+
+export async function warmupLease(targetName, slug, config = {}) {
+	const args = ["warmup", ...buildTargetBaseArgs(targetName, config), "--slug", slug, "--keep"];
+	let result;
+	for (let attempt = 1; attempt <= 2; attempt += 1) {
+		console.log(`  [crabbox] ${args.join(" ")}${attempt > 1 ? ` (retry ${attempt})` : ""}`);
+		result = await execCrabbox(args, { timeout: 300_000 });
+		if (!isRetryableWarmupFailure(targetName, result)) break;
+		await cleanupStaleTargetState(targetName, config);
+	}
+	return {
+		...result,
+		ok: result.code === 0,
+		leaseId: parseLeaseId(`${result.stdout}\n${result.stderr}`) ?? leaseIdFor(targetName, slug),
+	};
+}
+
+export async function runOnLease(targetName, leaseId, command, options = {}) {
+	const args = ["run", ...buildTargetBaseArgs(targetName, options.config ?? {}), "--id", leaseId];
+	for (const name of options.allowEnv ?? []) {
+		args.push("--allow-env", name);
+	}
+	if (options.sync === false) args.push("--no-sync");
+	else args.push("--fresh-sync");
+	args.push("--shell", command);
+	console.log(`  [crabbox] run ${targetName} ${options.sync === false ? "--no-sync" : "--fresh-sync"}`);
+	return execCrabbox(args, { timeout: options.timeout ?? 900_000 });
+}
+
+export async function stopLease(targetName, leaseId, config = {}) {
+	const args = ["stop", ...buildTargetBaseArgs(targetName, config), "--id", leaseId];
+	console.log(`  [crabbox] ${args.join(" ")}`);
+	return execCrabbox(args, { timeout: 90_000 });
+}
+
+export async function cleanupStaleTargetState(targetName, config = {}) {
+	if (targetName === "macos") return null;
+	const args = ["cleanup", ...buildTargetBaseArgs(targetName, config)];
+	console.log(`  [crabbox] ${args.join(" ")}`);
+	return execCrabbox(args, { timeout: 120_000 });
+}