pi-agent-browser-native 0.2.43 → 0.2.45

package/extensions/agent-browser/lib/results/presentation.ts

@@ -66,6 +66,10 @@ function mergeNextActions(...groups: Array<AgentBrowserNextAction[] | undefined>
 	return merged.length > 0 ? merged : undefined;
 }
 
+function shouldAddAnnotatedScreenshotGuidance(commandInfo: CommandInfo, args: string[] | undefined): boolean {
+	return commandInfo.command === "screenshot" && (args?.includes("--annotate") ?? false);
+}
+
 export async function buildToolPresentation(options: {
 	artifactManifest?: SessionArtifactManifest;
 	args?: string[];
@@ -103,7 +107,7 @@ export async function buildToolPresentation(options: {
 
 	const data = enrichStreamStatusData(commandInfo, envelope?.data);
 	const presentationData = redactPresentationData(commandInfo, data);
-	const artifacts = await extractFileArtifacts({ artifactRequest, commandInfo: presentationCommandInfo, cwd, data, sessionName });
+	const artifacts = await extractFileArtifacts({ artifactManifest, artifactRequest, commandInfo: presentationCommandInfo, cwd, data, sessionName });
 	const artifactVerification = buildArtifactVerificationSummary(artifacts);
 	const artifactSummary = formatArtifactSummary(artifacts);
 	const summary = artifactSummary ?? formatPresentationSummary(commandInfo, data, compiledSemanticAction);
@@ -151,6 +155,11 @@ export async function buildToolPresentation(options: {
 		}
 	}
 
+	if (shouldAddAnnotatedScreenshotGuidance(commandInfo, args) && presentation.content[0]?.type === "text") {
+		const guidance = "Annotated screenshot note: dense pages can produce overlapping labels. If the labels are noisy, capture a scoped element screenshot, take a non-annotated screenshot, or use snapshot -i high-value refs as the machine-readable map.";
+		presentation.content[0] = { ...presentation.content[0], text: `${presentation.content[0].text}\n\n${guidance}` };
+	}
+
 	const imagePath = artifactRequest?.absolutePath ?? extractImagePath(commandInfo, cwd, data);
 	const presentationWithImage = imagePath ? await attachInlineImage(presentation, imagePath) : presentation;
 	const compactedPresentation = await compactLargePresentationOutput({

package/extensions/agent-browser/lib/results/snapshot-high-value-controls.ts

@@ -17,6 +17,7 @@ const SNAPSHOT_HIGH_VALUE_CONTROL_ROLES = new Set([
 	"button",
 	"checkbox",
 	"combobox",
+	"link",
 	"menuitem",
 	"option",
 	"radio",
@@ -30,11 +31,12 @@ const SNAPSHOT_HIGH_VALUE_CONTROL_ROLE_PRIORITY: Record<string, number> = {
 	textbox: 1,
 	combobox: 2,
 	button: 3,
-	tab: 4,
-	checkbox: 5,
-	radio: 6,
-	option: 7,
-	menuitem: 8,
+	link: 4,
+	tab: 5,
+	checkbox: 6,
+	radio: 7,
+	option: 8,
+	menuitem: 9,
 };
 
 const SNAPSHOT_SURFACE_CONTROL_NAME_PATTERNS = [
@@ -46,6 +48,10 @@ const SNAPSHOT_PRIMARY_ACTION_BUTTON_NAME_PATTERNS = [
 	/^(?:add|apply|ask|confirm|connect|continue|create|launch|new|open|refresh|retry|run|save|search|send|start|submit)\b/i,
 ];
 
+const SNAPSHOT_HIGH_VALUE_LINK_NAME_PATTERNS = [
+	/^[a-z0-9_.-]+\/[a-z0-9_.-]+$/i,
+];
+
 function getHighValueControlRole(entry: SnapshotRefEntry): string {
 	return entry.isEditable === true && (entry.role === "unknown" || entry.role === "generic") ? "textbox" : entry.role;
 }
@@ -129,9 +135,14 @@ const SNAPSHOT_HIGH_VALUE_CONTROL_CATEGORY_RULES: readonly HighValueControlCateg
 	},
 ] as const;
 
+function isHighValueLinkRef(entry: SnapshotRefEntry): boolean {
+	return entry.name.length > 0 && SNAPSHOT_HIGH_VALUE_LINK_NAME_PATTERNS.some((pattern) => pattern.test(entry.name));
+}
+
 export function isHighValueControlEntry(entry: SnapshotRefEntry): boolean {
 	const role = getHighValueControlRole(entry);
 	if (!SNAPSHOT_HIGH_VALUE_CONTROL_ROLES.has(role)) return false;
+	if (role === "link") return isHighValueLinkRef(entry);
 	if (entry.isEditable === false && (role === "searchbox" || role === "textbox" || role === "combobox")) return false;
 	return entry.name.length > 0 || isEditableControlRef(entry);
 }

package/extensions/agent-browser/lib/results/snapshot.ts

@@ -221,6 +221,7 @@ export async function buildSnapshotPresentation(
 		...(roleCountsText ? [`Top roles: ${roleCountsText}`] : []),
 		"",
 		"Compact snapshot view.",
+		"Viewport note: compact snapshots are DOM/signal-prioritized, not guaranteed to start with the currently scrolled viewport; use the full raw snapshot, a screenshot, or listed high-value refs when viewport context matters.",
 	];
 
 	if (fallbackPreview) {
@@ -294,6 +295,7 @@ export async function buildSnapshotPresentation(
 			fullOutputPath,
 			origin,
 			previewMode: fallbackPreview ? "outline" : "structured",
+			viewportOrdering: "dom-signal-prioritized",
 			spillError: spillErrorText,
 			previewRefIds: [...previewRefIds],
 			highValueControlRefIds: visibleHighValueControlEntries.map((entry) => entry.id),

package/extensions/agent-browser/lib/runtime.ts

@@ -619,6 +619,15 @@ export function createFreshSessionName(baseSessionName: string, ephemeralSeed: s
 	return `${baseSessionName}-fresh-${suffix}`;
 }
 
+function getSingleKeyCommandValidationError(args: string[]): string | undefined {
+	const { commandInfo, commandTokens } = parseArgvDescriptor(args);
+	const command = commandInfo.command;
+	if (command !== "press" && command !== "key" && command !== "keydown" && command !== "keyup") return undefined;
+	if (commandTokens.length === 2) return undefined;
+	const label = command === "key" ? "key/press" : command;
+	return `agent-browser ${label} accepts exactly one key argument. Do not pass a selector or ref to ${label}; focus or click the target first, then run ${command} <key> (for example: focus @e1, then press Enter).`;
+}
+
 export function validateToolArgs(args: string[]): string | undefined {
 	if (args.length === 0) {
 		return "`args` must contain at least one agent-browser command token.";
@@ -634,7 +643,7 @@ export function validateToolArgs(args: string[]): string | undefined {
 		return "Do not pass `--session-mode` in args. Use the top-level agent_browser `sessionMode` field instead, for example { args: [\"--profile\", \"Default\", \"open\", \"https://example.com\"], sessionMode: \"fresh\" }.";
 	}
 
-	return undefined;
+	return getSingleKeyCommandValidationError(args);
 }
 
 function getInvalidValueFlagDetails(args: string[]): InvalidValueFlagDetails | undefined {

package/extensions/agent-browser/lib/session-page-state.ts

@@ -8,6 +8,9 @@
 
 import { isCloseCommand, isReadOnlyDiagnosticSessionTargetCommand } from "./command-taxonomy.js";
 import { isRecord } from "./parsing.js";
+import { getEditableRefEvidence } from "./results/editable-ref-evidence.js";
+import { enrichSnapshotRefEntries, getSnapshotRefEntries } from "./results/snapshot-refs.js";
+import { parseSnapshotLines } from "./results/snapshot-segments.js";
 
 export interface SessionTabTarget {
 	title?: string;
@@ -21,7 +24,7 @@ interface OrderedSessionTabTarget {
 
 export interface SessionRefSnapshot {
 	refIds: string[];
-	refs?: Record<string, { name: string; role: string }>;
+	refs?: Record<string, { isContentEditable?: boolean; isEditable?: boolean; name: string; role: string }>;
 	target?: SessionTabTarget;
 }
 
@@ -230,11 +233,15 @@ function getRestoredSessionTabTarget(details: Record<string, unknown>, command:
 	return storedTarget;
 }
 
-function extractRefSnapshotRefs(data: unknown): Record<string, { name: string; role: string }> | undefined {
+function extractRefSnapshotRefs(data: unknown): Record<string, { isContentEditable?: boolean; isEditable?: boolean; name: string; role: string }> | undefined {
 	if (!isRecord(data) || !isRecord(data.refs)) return undefined;
-	const refs = Object.fromEntries(Object.entries(data.refs).flatMap(([refId, entry]) => {
-		if (!/^e\d+$/.test(refId) || !isRecord(entry) || typeof entry.name !== "string" || typeof entry.role !== "string") return [];
-		return [[refId, { name: entry.name, role: entry.role }] as const];
+	const snapshotLines = typeof data.snapshot === "string" ? parseSnapshotLines(data.snapshot) : [];
+	const lineByRef = new Map(snapshotLines.flatMap((line) => line.ref ? [[line.ref, line.raw] as const] : []));
+	const entries = enrichSnapshotRefEntries(getSnapshotRefEntries(data), snapshotLines);
+	const refs = Object.fromEntries(entries.flatMap((entry) => {
+		if (!/^e\d+$/.test(entry.id) || entry.role.length === 0) return [];
+		const isContentEditable = getEditableRefEvidence({ ref: entry.refData, text: lineByRef.get(entry.id) });
+		return [[entry.id, { ...(isContentEditable === true ? { isContentEditable: true } : {}), ...(entry.isEditable !== undefined ? { isEditable: entry.isEditable } : {}), name: entry.name, role: entry.role }] as const];
 	}));
 	return Object.keys(refs).length > 0 ? refs : undefined;
 }
@@ -310,7 +317,9 @@ function getRestoredRefSnapshot(details: Record<string, unknown>): SessionRefSna
 		? Object.fromEntries(refIds.flatMap((refId) => {
 			const entry = refRecord[refId];
 			if (!isRecord(entry) || typeof entry.name !== "string" || typeof entry.role !== "string") return [];
-			return [[refId, { name: entry.name, role: entry.role }] as const];
+			const isContentEditable = typeof entry.isContentEditable === "boolean" ? entry.isContentEditable : undefined;
+			const isEditable = typeof entry.isEditable === "boolean" ? entry.isEditable : undefined;
+			return [[refId, { ...(isContentEditable !== undefined ? { isContentEditable } : {}), ...(isEditable !== undefined ? { isEditable } : {}), name: entry.name, role: entry.role }] as const];
 		}))
 		: undefined;
 	return {

package/extensions/agent-browser/lib/web-search.ts

@@ -653,7 +653,7 @@ export function createAgentBrowserWebSearchTool(configState: AgentBrowserConfigS
 		promptSnippet: "Search the live web with Exa or Brave for current or external information.",
 		promptGuidelines: [
 			"Use agent_browser_web_search when live web search would help answer the task, find current external information, or discover candidate URLs for agent_browser.",
-			"The tool chooses Exa or Brave from configured keys; when both are available, Exa is preferred by default unless webSearch.preferredProvider says otherwise. Use provider only when the user/config calls for a specific provider.",
+			"agent_browser_web_search chooses Exa or Brave from configured keys; when both are available, Exa is preferred by default unless webSearch.preferredProvider says otherwise. Use provider only when the user/config calls for a specific provider.",
 			"Prefer agent_browser_web_search over opening a search engine results page with agent_browser when a quick result list is enough; use agent_browser for interaction, DOM, screenshots, or auth.",
 			"Do not issue parallel or repeated agent_browser_web_search calls; use one high-signal query, inspect the results, then only run a focused follow-up if needed. If the provider returns HTTP 429, stop searching and tell the user the API plan/rate limit needs time or a plan change.",
 			"After using agent_browser_web_search, cite result URLs in the final answer when web evidence informed the answer.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-agent-browser-native",
-  "version": "0.2.43",
+  "version": "0.2.45",
   "description": "pi extension that exposes agent-browser as a native tool for browser automation",
   "type": "module",
   "author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -62,9 +62,9 @@
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.78.0",
-    "@earendil-works/pi-coding-agent": "^0.78.0",
-    "@earendil-works/pi-tui": "^0.78.0",
+    "@earendil-works/pi-ai": "^0.78.1",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@earendil-works/pi-tui": "^0.78.1",
     "@types/node": "^25.6.1",
     "tsx": "^4.21.0",
     "typebox": "^1.1.38",
@@ -80,7 +80,7 @@
     "check:platform-smoke": "node --check platform-smoke.config.mjs && node --check scripts/platform-smoke.mjs && node --check scripts/platform-smoke/doctor.mjs && node --check scripts/platform-smoke/crabbox-runner.mjs && node --check scripts/platform-smoke/targets.mjs && node --check scripts/platform-smoke/artifacts.mjs && tsx --test test/platform-smoke.test.ts",
     "smoke:platform": "node scripts/platform-smoke.mjs",
     "smoke:platform:doctor": "node scripts/platform-smoke.mjs doctor",
-    "smoke:platform:ubuntu-image": "docker build -t pi-agent-browser-native-platform:node24-agent-browser0.27.1 --build-arg AGENT_BROWSER_VERSION=0.27.1 -f scripts/platform-smoke/linux-image/Dockerfile .",
+    "smoke:platform:ubuntu-image": "node scripts/platform-smoke/build-ubuntu-image.mjs",
     "smoke:platform:macos": "node scripts/platform-smoke.mjs run --target macos",
     "smoke:platform:ubuntu": "node scripts/platform-smoke.mjs run --target ubuntu",
     "smoke:platform:windows-native": "node scripts/platform-smoke.mjs run --target windows-native",

package/platform-smoke.config.mjs

@@ -3,16 +3,28 @@
 
 import { CAPABILITY_BASELINE } from "./scripts/agent-browser-capability-baseline.mjs";
 
+export const PLATFORM_SMOKE_AGENT_BROWSER_VERSION = CAPABILITY_BASELINE.targetVersion;
+export const PLATFORM_SMOKE_UBUNTU_IMAGE = `pi-agent-browser-native-platform:node24-agent-browser${PLATFORM_SMOKE_AGENT_BROWSER_VERSION}`;
+
 export default {
 	packageName: "pi-agent-browser-native",
 	artifactRoot: ".artifacts/platform-smoke",
 	requiredTargets: ["macos", "ubuntu", "windows-native"],
 	requiredSuites: ["platform-build", "browser-dogfood-smoke"],
+	supportedTargets: ["macos", "ubuntu", "windows-native"],
 	requiredCrabbox: {
 		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",
-		minVersion: "0.24.0",
+		minVersion: "0.26.0",
+	},
+	macos: {
+		host: "localhost",
+		port: 22,
+	},
+	ubuntuContainerImage: PLATFORM_SMOKE_UBUNTU_IMAGE,
+	windowsParallels: {
+		sourceVm: "pi-extension-windows-template",
+		snapshot: "crabbox-ready",
 	},
-	ubuntuContainerImage: "pi-agent-browser-native-platform:node24-agent-browser0.27.1",
 	nodeValidationMajor: 22,
-	agentBrowserVersion: CAPABILITY_BASELINE.targetVersion,
+	agentBrowserVersion: PLATFORM_SMOKE_AGENT_BROWSER_VERSION,
 };

package/scripts/doctor.mjs

@@ -22,6 +22,7 @@ const PACKAGE_NAME = "pi-agent-browser-native";
 const REPO_URL_FRAGMENT = "github.com/fitchmultz/pi-agent-browser-native";
 const EXTENSION_ENTRYPOINT = "extensions/agent-browser/index.ts";
 const EXPECTED_VERSION = CAPABILITY_BASELINE.targetVersion;
+const RECOMMENDED_PI_VERSION = "0.78.1";
 const DEFAULT_AGENT_DIR = resolve(homedir(), ".pi/agent");
 const THIS_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -29,6 +30,27 @@ export function normalizeAgentBrowserVersion(output) {
 	return String(output ?? "").trim().replace(/^agent-browser\s+/, "");
 }
 
+export function normalizePiVersion(output) {
+	return String(output ?? "").trim().replace(/^pi\s+/, "");
+}
+
+function parseVersionParts(version) {
+	const match = String(version ?? "").match(/^(\d+)\.(\d+)\.(\d+)(?:\b|[-+])/);
+	if (!match) return undefined;
+	return match.slice(1).map((part) => Number.parseInt(part, 10));
+}
+
+function versionAtLeast(actual, minimum) {
+	const actualParts = parseVersionParts(actual);
+	const minimumParts = parseVersionParts(minimum);
+	if (!actualParts || !minimumParts) return undefined;
+	for (let index = 0; index < minimumParts.length; index += 1) {
+		if (actualParts[index] > minimumParts[index]) return true;
+		if (actualParts[index] < minimumParts[index]) return false;
+	}
+	return true;
+}
+
 function printHelp() {
 	console.log(`pi-agent-browser-doctor
 
@@ -45,7 +67,8 @@ Options:
 Checks:
   1. agent-browser is installed on PATH.
   2. agent-browser --version matches the package capability baseline.
-  3. Pi settings and repo-local autoload locations do not point at multiple active pi-agent-browser-native sources.
+  3. pi --version is at least the recommended Pi floor for this release.
+  4. Pi settings and repo-local autoload locations do not point at multiple active pi-agent-browser-native sources.
 
 Examples:
   pi-agent-browser-doctor
@@ -101,6 +124,11 @@ async function defaultRunAgentBrowser(args) {
 	return `${stdout}${stderr}`;
 }
 
+async function defaultRunPi(args) {
+	const { stdout, stderr } = await execFile("pi", args, { maxBuffer: 1024 * 1024 });
+	return `${stdout}${stderr}`;
+}
+
 async function defaultPathExists(path) {
 	try {
 		await access(path);
@@ -270,6 +298,43 @@ async function collectRepoLocalSources({ cwd, pathExists }) {
 	return sources;
 }
 
+async function checkPiVersion({ runPi }) {
+	try {
+		const rawOutput = await runPi(["--version"]);
+		const version = normalizePiVersion(rawOutput);
+		const supported = versionAtLeast(version, RECOMMENDED_PI_VERSION);
+		if (supported === false) {
+			return {
+				status: "warn",
+				title: `Pi ${RECOMMENDED_PI_VERSION} or newer is recommended; found ${version || "<empty>"}.`,
+				lines: [
+					"This package does not hard-pin Pi 0.78.1, but this release was audited against Pi 0.78.1 extension/package behavior.",
+					"Update Pi before release validation or lifecycle debugging if you see tool routing, /reload, exact-session, or package-install differences.",
+				],
+			};
+		}
+		if (supported === undefined) {
+			return {
+				status: "warn",
+				title: `Could not parse pi --version output: ${version || "<empty>"}.`,
+				lines: [`Pi ${RECOMMENDED_PI_VERSION} or newer is recommended for this release's validation baseline.`],
+			};
+		}
+		return { status: "pass", title: `Pi version is within the recommended baseline: ${version}`, lines: [] };
+	} catch (error) {
+		const code = error && typeof error === "object" ? error.code : undefined;
+		return {
+			status: "warn",
+			title: "Could not inspect pi --version.",
+			lines: [
+				`Pi ${RECOMMENDED_PI_VERSION} or newer is recommended for this release's validation baseline, but it is not hard-pinned as a runtime requirement.`,
+				"Make sure the same shell that launches pi can run `pi --version` when debugging lifecycle or package-install behavior.",
+				code && code !== "ENOENT" ? `Spawn error: ${String(code)}` : undefined,
+			].filter(Boolean),
+		};
+	}
+}
+
 async function checkAgentBrowserVersion({ runAgentBrowser }) {
 	try {
 		const rawOutput = await runAgentBrowser(["--version"]);
@@ -358,6 +423,7 @@ export async function evaluateDoctor(options = {}) {
 	const readText = options.readText ?? ((path) => readFile(path, "utf8"));
 	const pathExists = options.pathExists ?? defaultPathExists;
 	const runAgentBrowser = options.runAgentBrowser ?? defaultRunAgentBrowser;
+	const runPi = options.runPi ?? defaultRunPi;
 	const checks = [];
 	const failures = [];
 	const warnings = [];
@@ -366,6 +432,9 @@ export async function evaluateDoctor(options = {}) {
 	checks.push(versionCheck);
 	if (versionCheck.status === "fail") failures.push(versionCheck);
 
+	const piVersionCheck = await checkPiVersion({ runPi });
+	checks.push(piVersionCheck);
+
 	if (!options.skipSourceCheck) {
 		const sourceCheck = await checkPiSources({ cwd, agentDir, settingsPaths, readText, pathExists });
 		checks.push(sourceCheck);

package/scripts/platform-smoke/build-ubuntu-image.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+import { CAPABILITY_BASELINE } from "../agent-browser-capability-baseline.mjs";
+
+const version = CAPABILITY_BASELINE.targetVersion;
+const image = `pi-agent-browser-native-platform:node24-agent-browser${version}`;
+const args = [
+	"build",
+	"-t",
+	image,
+	"--build-arg",
+	`AGENT_BROWSER_VERSION=${version}`,
+	"-f",
+	"scripts/platform-smoke/linux-image/Dockerfile",
+	".",
+];
+
+console.log(`Building ${image}`);
+const result = spawnSync("docker", args, { stdio: "inherit" });
+if (result.error) {
+	console.error(result.error.message);
+	process.exit(1);
+}
+process.exit(result.status ?? 1);

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

@@ -2,6 +2,10 @@
 
 import { spawn } from "node:child_process";
 
+import { CAPABILITY_BASELINE } from "../agent-browser-capability-baseline.mjs";
+
+const DEFAULT_UBUNTU_IMAGE = `pi-agent-browser-native-platform:node24-agent-browser${CAPABILITY_BASELINE.targetVersion}`;
+
 function env(name) {
 	return process.env[name] ?? "";
 }
@@ -14,49 +18,77 @@ function packageSlug(config = {}) {
 	return process.env.PLATFORM_SMOKE_PACKAGE_SLUG || config.packageName || "pi-agent-browser-native";
 }
 
-export function buildTargetBaseArgs(targetName, config = {}) {
+export function describeTarget(targetName, config = {}) {
+	const slug = packageSlug(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,
-			];
+			const host = env("PLATFORM_SMOKE_MAC_HOST") || config.macos?.host || "localhost";
+			const port = String(env("PLATFORM_SMOKE_MAC_PORT") || config.macos?.port || 22);
+			const workRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || config.macos?.workRoot || `/Users/${user}/crabbox/${slug}`;
+			return {
+				provider: "ssh",
+				crabboxTarget: "macos",
+				shell: "posix",
+				workRoot,
+				args: [
+					"--provider", "ssh",
+					"--target", "macos",
+					"--static-host", host,
+					"--static-user", user,
+					"--static-port", port,
+					"--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,
-			];
+			const image = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config.ubuntuContainerImage || DEFAULT_UBUNTU_IMAGE;
+			return {
+				provider: "local-container",
+				crabboxTarget: "linux",
+				shell: "posix",
+				image,
+				workRoot: config.localContainer?.workRoot || "/work/crabbox",
+				args: [
+					"--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,
-			];
+			const vm = env("PLATFORM_SMOKE_WINDOWS_VM") || config.windowsParallels?.sourceVm || "pi-extension-windows-template";
+			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || config.windowsParallels?.snapshot || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || config.windowsParallels?.user || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || config.windowsParallels?.workRoot || `C:\\crabbox\\${slug}`;
+			return {
+				provider: "parallels",
+				crabboxTarget: "windows",
+				shell: "powershell",
+				workRoot,
+				windowsMode: "normal",
+				sourceVm: vm,
+				snapshot,
+				args: [
+					"--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 buildTargetBaseArgs(targetName, config = {}) {
+	return describeTarget(targetName, config).args;
+}
+
 export function leaseIdFor(targetName, slug) {
 	if (targetName === "macos") return "static_localhost";
 	return slug;

package/scripts/platform-smoke/doctor.mjs

@@ -4,6 +4,10 @@ import { execFileSync, execSync } from "node:child_process";
 import { accessSync, constants, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { CAPABILITY_BASELINE } from "../agent-browser-capability-baseline.mjs";
+
+const DEFAULT_UBUNTU_IMAGE = `pi-agent-browser-native-platform:node24-agent-browser${CAPABILITY_BASELINE.targetVersion}`;
+
 function env(name) {
 	return process.env[name] ?? "";
 }
@@ -105,6 +109,17 @@ function checkForbiddenProjectFiles(failures) {
 }
 
 function crabboxProviders(cbox) {
+	const jsonOutput = silent(cbox, ["providers", "--json"]);
+	if (jsonOutput) {
+		try {
+			const parsed = JSON.parse(jsonOutput);
+			if (Array.isArray(parsed)) return parsed.map((provider) => provider.name ?? provider.id ?? provider.provider).filter(Boolean);
+			if (Array.isArray(parsed.providers)) return parsed.providers.map((provider) => provider.name ?? provider.id ?? provider.provider).filter(Boolean);
+			if (typeof parsed === "object" && parsed) return Object.keys(parsed.providers ?? parsed);
+		} catch {
+			// Fall through to text parsing for older or non-JSON provider output.
+		}
+	}
 	const output = silent(cbox, ["providers"]);
 	if (!output) return [];
 	return output.split(/\r?\n/)
@@ -209,25 +224,27 @@ export async function runDoctor(config) {
 	console.log("\n── Crabbox providers ──");
 	if (cboxPath) {
 		checkRequiredProviders(cbox, failures);
-		const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || "pi-agent-browser-native-platform:node24-agent-browser0.27.1";
+		const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || DEFAULT_UBUNTU_IMAGE;
 		checkCrabboxProvider(cbox, ["--provider", "local-container", "--local-container-image", ubuntuImage], "ubuntu local-container", failures);
 		const macUser = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
-		const macHost = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
-		const macRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || `/Users/${macUser}/crabbox/${packageName}`;
-		checkCrabboxProvider(cbox, ["--provider", "ssh", "--target", "macos", "--static-host", macHost, "--static-user", macUser, "--static-port", "22", "--static-work-root", macRoot], "macOS ssh", failures);
+		const macHost = env("PLATFORM_SMOKE_MAC_HOST") || config?.macos?.host || "localhost";
+		const macPort = String(env("PLATFORM_SMOKE_MAC_PORT") || config?.macos?.port || 22);
+		const macRoot = env("PLATFORM_SMOKE_MAC_WORK_ROOT") || config?.macos?.workRoot || `/Users/${macUser}/crabbox/${packageName}`;
+		checkCrabboxProvider(cbox, ["--provider", "ssh", "--target", "macos", "--static-host", macHost, "--static-user", macUser, "--static-port", macPort, "--static-work-root", macRoot], "macOS ssh", failures);
 	}
 
 	console.log("\n── Docker / Ubuntu ──");
 	const dockerVersion = shell("docker info --format '{{.ServerVersion}}'");
 	if (dockerVersion) ok(`Docker ${dockerVersion}`);
 	else fail("Docker is not available or not running", failures);
-	const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || "pi-agent-browser-native-platform:node24-agent-browser0.27.1";
+	const ubuntuImage = env("PLATFORM_SMOKE_UBUNTU_IMAGE") || config?.ubuntuContainerImage || DEFAULT_UBUNTU_IMAGE;
 	ok(`Ubuntu image: ${ubuntuImage}`);
 
 	console.log("\n── macOS SSH ──");
 	const sshUser = env("PLATFORM_SMOKE_MAC_USER") || env("USER");
-	const sshHost = env("PLATFORM_SMOKE_MAC_HOST") || "localhost";
-	const sshProbe = shell(`ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=no ${sshUser}@${sshHost} 'node --version && npm --version && git --version && agent-browser --version'`);
+	const sshHost = env("PLATFORM_SMOKE_MAC_HOST") || config?.macos?.host || "localhost";
+	const sshPort = String(env("PLATFORM_SMOKE_MAC_PORT") || config?.macos?.port || 22);
+	const sshProbe = shell(`ssh -o BatchMode=yes -o ConnectTimeout=5 -o StrictHostKeyChecking=no -p ${sshPort} ${sshUser}@${sshHost} 'node --version && npm --version && git --version && agent-browser --version'`);
 	if (sshProbe) {
 		ok(`SSH ${sshUser}@${sshHost}: ${sshProbe.split(/\r?\n/).join(" | ")}`);
 		if (agentBrowserVersion && !sshProbe.includes(agentBrowserVersion)) fail(`macOS SSH agent-browser does not match expected ${agentBrowserVersion}`, failures);
@@ -241,10 +258,10 @@ export async function runDoctor(config) {
 			fail("prlctl not found", failures);
 		} else {
 			ok("prlctl found");
-			const vmName = 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\\${packageName}`;
+			const vmName = env("PLATFORM_SMOKE_WINDOWS_VM") || config?.windowsParallels?.sourceVm || "pi-extension-windows-template";
+			const snapshot = env("PLATFORM_SMOKE_WINDOWS_SNAPSHOT") || config?.windowsParallels?.snapshot || "crabbox-ready";
+			const user = env("PLATFORM_SMOKE_WINDOWS_USER") || config?.windowsParallels?.user || env("USER");
+			const workRoot = env("PLATFORM_SMOKE_WINDOWS_WORK_ROOT") || config?.windowsParallels?.workRoot || `C:\\crabbox\\${packageName}`;
 			const list = shell("prlctl list -a --no-header 2>/dev/null");
 			if (!list) {
 				fail("prlctl list returned no VMs", failures);

package/scripts/platform-smoke/linux-image/Dockerfile

@@ -1,12 +1,10 @@
 # Local Crabbox Ubuntu/Linux target image for pi-agent-browser-native platform smoke.
-# Build with:
-#   docker build -t pi-agent-browser-native-platform:node24-agent-browser0.27.1 \
-#     --build-arg AGENT_BROWSER_VERSION=0.27.1 \
-#     -f scripts/platform-smoke/linux-image/Dockerfile .
+# Build with npm run smoke:platform:ubuntu-image so the agent-browser version
+# comes from scripts/agent-browser-capability-baseline.mjs.
 
 FROM node:24-bookworm
 
-ARG AGENT_BROWSER_VERSION=0.27.1
+ARG AGENT_BROWSER_VERSION
 
 USER root
 RUN apt-get update \