pi-agent-browser-native 0.9.5 → 0.9.7

package/docs/platform-smoke.md

@@ -1,14 +1,14 @@
 # Platform smoke testing
 
-`pi-agent-browser-native` uses a Crabbox-backed local platform smoke gate to prove the package on macOS, Ubuntu Linux, and native Windows before release.
+`pi-agent-browser-native` uses a Crabbox-backed required local platform gate on **macOS and Ubuntu Linux**. Native Windows is **best-effort and explicitly on demand**, not a required default PR or release target.
 
-**Current 0.6.16 rollout exception:** the owner explicitly waived Windows qualification on 2026-09-21, including available runners. Windows failures remain visible but nonblocking, not passed; no further Windows repair experiments are part of this rollout. Linux/macOS and all other required checks remain required. See [release waiver and artifact requirements](RELEASE.md#current-0616-rollout-waiver) and [follow-up #191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191). The commands below are unchanged and a waived Windows result does not make the full composition a passing matrix.
+The owner's 2026-10-22 best-effort decision supersedes [#191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191) / PR291's blocking policy, not their unresolved process-lock/Electron failures. The September waiver is historical, not current authority. Routine Windows CI is one nonblocking official-host build/import/process smoke; broader official/fork full qualification and its environment self-check require manual `windows-qualification=true`. Neither a green required aggregate nor a not-run deep suite is a Windows pass.
 
-Outside that rollout exception, this is a release-blocking gate. Missing setup is not a skipped pass. When a maintainer approves an [alternate native transport](#alternate-native-transports), it must prove the same target-local suites; missing upstream `agent-browser` or browser dependencies still blocks that target.
+Missing macOS/Ubuntu setup is not a skipped pass. Default doctor requires only their providers/setup, not Windows, Parallels or Windows credentials. Explicit Windows doctor/run remains strict and returns real nonzero status. No test assertions, runtime ownership checks or budgets are relaxed.
 
 ## Required release gate
 
-Run the cheap harness checks first, build the project-owned Ubuntu image, run doctor explicitly, then run the full matrix and inspect the evidence:
+Run the cheap harness checks first, build the project-owned Ubuntu image, run doctor explicitly, then run the required matrix and inspect the evidence:
 
 ```sh
 npm run check:platform-smoke
@@ -16,33 +16,34 @@ npm run smoke:platform:ubuntu-image
 npm run smoke:platform:doctor
 npm run smoke:platform:all
 crabbox list --provider local-container
-crabbox list --provider parallels
 ```
 
-`smoke:platform:all` also runs `smoke:platform:doctor` before any target suite starts, so the explicit doctor step is a readable release checklist step rather than a hidden precondition. The canonical `npm run verify -- release` gate also runs the configured-source lifecycle harness, then the same platform doctor and full `macos,ubuntu,windows-native` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without lifecycle and platform gates. After the matrix, inspect `.artifacts/platform-smoke/<run-id>/...` summaries and manifests; a green Crabbox exit without matching suite assertions is not release proof. Use provider-specific `crabbox list` commands for cleanup review because this host may have unrelated Crabbox providers configured that require credentials.
+`smoke:platform:all` means all **required** configured targets, not optional Windows. It also runs `smoke:platform:doctor` before any target suite starts, so the explicit doctor step is a readable release checklist step rather than a hidden precondition. The canonical `npm run verify -- release` gate also runs the configured-source lifecycle harness, then the same platform doctor and configured required `macos,ubuntu` matrix after default verification and packaged Pi smoke, so `npm publish` cannot pass `prepublishOnly` without lifecycle and platform gates. After the matrix, inspect `.artifacts/platform-smoke/<run-id>/...` summaries and manifests; a green Crabbox exit without matching suite assertions is not release proof. Use provider-specific `crabbox list` commands for cleanup review because this host may have unrelated Crabbox providers configured that require credentials.
 
 Per-target commands are for diagnosis:
 
 ```sh
 npm run smoke:platform:macos
 npm run smoke:platform:ubuntu
+node scripts/platform-smoke.mjs doctor --target windows-native
 npm run smoke:platform:windows-native
+crabbox list --provider parallels # only after an explicitly selected Windows run
 npm run verify -- platform-smoke run --target ubuntu --suite platform-build
 ```
 
 ## Targets
 
-| Target           | Crabbox provider       | Shell contract                                     | Release status                                                      |
-| ---------------- | ---------------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
-| `macos`          | `ssh` static localhost | POSIX shell on macOS                               | Required                                                            |
-| `ubuntu`         | `local-container`      | POSIX shell in a Docker-compatible local container | Required                                                            |
-| `windows-native` | `parallels`            | native Windows PowerShell over OpenSSH             | Nonblocking for the owner-waived 0.6.16 rollout; otherwise required |
+| Target           | Crabbox provider       | Shell contract                                     | Release status                       |
+| ---------------- | ---------------------- | -------------------------------------------------- | ------------------------------------ |
+| `macos`          | `ssh` static localhost | POSIX shell on macOS                               | Required                             |
+| `ubuntu`         | `local-container`      | POSIX shell in a Docker-compatible local container | Required                             |
+| `windows-native` | `parallels`            | native Windows PowerShell over OpenSSH             | Best-effort; explicit selection only |
 
 ## Alternate native transports
 
-With maintainer approval, local macOS execution can replace localhost SSH. Routine GitHub Actions has no Windows job; the separate Crabbox/Parallels release target remains as documented above. Record alternate native checks separately from Crabbox SSH or Parallels results. The default `release` and `prepublishOnly` commands still select the Crabbox matrix; record alternate suite evidence separately rather than reporting those commands as passed.
+With maintainer approval, local macOS execution can replace localhost SSH. For native Windows, routine GitHub Actions includes only the nonblocking smoke. On-demand full Windows jobs and Crabbox/Parallels target results retain their own scope and failures; neither is substituted for required macOS/Ubuntu evidence or relabeled a browser-dogfood pass. Record alternate native checks separately from Crabbox SSH or Parallels results. The default `release` and `prepublishOnly` commands still select the Crabbox matrix; record alternate suite evidence separately rather than reporting those commands as passed.
 
-On macOS, run the unchanged commands returned by `buildPlatformBuildCommand('macos', 'pi-agent-browser-native', '24.21.0')` and `buildBrowserDogfoodCommand('macos', '0.38.1', true)` in [`scripts/platform-smoke/targets.mjs`](../scripts/platform-smoke/targets.mjs), serially in a clean private source copy. Use private HOME, npm and Pi settings, and headless browser profiles, and clear inherited `PI_*` variables first: a shell started from Pi exports `PI_PACKAGE_DIR` and `PI_MANAGED_CLI`, which make the archived Pi CLI report the host package instead of the locked suite version. No Remote Login or host security change is required.
+On macOS, run the unchanged commands returned by `buildPlatformBuildCommand('macos', 'pi-agent-browser-native', '24.21.0')` and `buildBrowserDogfoodCommand('macos', '0.41.0', true)` in [`scripts/platform-smoke/targets.mjs`](../scripts/platform-smoke/targets.mjs), serially in a clean private source copy. Use private HOME, npm and Pi settings, and headless browser profiles, and clear inherited `PI_*` variables first: a shell started from Pi exports `PI_PACKAGE_DIR` and `PI_MANAGED_CLI`, which make the archived Pi CLI report the host package instead of the locked suite version. No Remote Login or host security change is required.
 
 Retain the exact source head/tree, package and tool versions, native OS/architecture, generated commands, stdout/stderr, every `PLATFORM_*` exit marker, actual Pi registration output, dogfood JSON and verified screenshot. Check the suite assertions below and clean up only the run's processes and temporary files. These alternatives do not waive Ubuntu or any non-platform release check.
 
@@ -71,6 +72,7 @@ PLATFORM_SMOKE_MAC_PORT=22
 # The tag suffix is derived from scripts/agent-browser-capability-baseline.mjs.
 PLATFORM_SMOKE_UBUNTU_IMAGE="pi-agent-browser-native-platform:node24-agent-browser<baseline-version>"
 
+# Optional: needed only when windows-native is explicitly selected.
 PLATFORM_SMOKE_WINDOWS_VM="pi-extension-windows-template"
 PLATFORM_SMOKE_WINDOWS_SNAPSHOT="crabbox-ready-ab-0.33.0"
 PLATFORM_SMOKE_WINDOWS_USER="<windows-ssh-user>"
@@ -80,7 +82,7 @@ PLATFORM_SMOKE_WINDOWS_WORK_ROOT="C:\\crabbox\\pi-agent-browser-native"
 PLATFORM_SMOKE_AUTH_ENV=""
 ```
 
-The Ubuntu target image is derived from `node:24-bookworm`, installs the `agent-browser` version from [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs), installs Debian Chromium plus the upstream Linux WebGPU/Xvfb runtime packages (`libvulkan1`, `mesa-vulkan-drivers`, and `xvfb`) through apt, copies the official Go 1.27.1 toolchain onto `PATH` so `platform-target` can build the [corrected quality checker](CODE_QUALITY.md), creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebuild it after upstream rebaselining, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command; a missing tool is image/template drift.
+The Ubuntu target image is derived from `node:24-bookworm`, installs the latest stock `agent-browser` and checks it against [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs), installs Debian Chromium plus the upstream Linux WebGPU/Xvfb runtime packages (`libvulkan1`, `mesa-vulkan-drivers`, and `xvfb`) through apt, copies the official Go 1.27.1 toolchain onto `PATH` so `platform-target` can build the [corrected quality checker](CODE_QUALITY.md), creates a non-root `circleci` user, and sets `AGENT_BROWSER_EXECUTABLE_PATH=/usr/bin/chromium`. Rebaseline the project when current upstream differs from the audited version, then rebuild the image, or override `PLATFORM_SMOKE_UBUNTU_IMAGE` with an equivalent prepared local image. Do not install `agent-browser` ad hoc inside the Ubuntu smoke command; a missing tool is image/template drift.
 
 The configured upstream `agent-browser` baseline is imported from [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs). Target-local browser suites verify that exact `agent-browser` version before running. Bake the exact upstream CLI and browser runtime into the Windows template/snapshot for speed and reproducibility; missing or stale Windows `agent-browser` / browser readiness is a blocked setup, not something the smoke command repairs. The Windows browser suite checks the preinstalled browser cache and prewarms one short loopback HTTP URL before the extension harness runs.
 
@@ -112,6 +114,8 @@ Each required target runs `platform-build` and `browser-dogfood-smoke` on one Cr
 8. Run `pi list --approve` and assert the package is registered under project packages from the packed install.
 9. Assert the release proof did not use `pi -e .` or `pi --extension .`.
 
+When `PI_AGENT_BROWSER_RELEASE_TARBALL` names a retained release candidate, the harness copies it through the ordinary Crabbox workspace sync and installs that archive in step 6 instead of the target-local pack. The target-local `npm pack` still runs. Each target records and checks the candidate SHA-256 before and after installation; the caller remains responsible for comparing the original archive with the shared preparation receipt.
+
 ### `browser-dogfood-smoke`
 
 1. Run `npm ci` in the synced checkout if needed.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-agent-browser-native",
-	"version": "0.9.5",
+	"version": "0.9.7",
 	"description": "pi extension that exposes agent-browser as a native tool for browser automation",
 	"type": "module",
 	"author": "Mitch Fultz (https://github.com/fitchmultz)",
@@ -32,7 +32,14 @@
 		"pi-agent-browser-doctor": "scripts/doctor.mjs"
 	},
 	"files": [
-		"dist",
+		"dist/extensions/agent-browser/index.js",
+		"dist/extensions/agent-browser/script-worker.js",
+		"dist/packaged/lib/config-policy.js",
+		"dist/packaged/lib/browser-session-conversion.js",
+		"dist/packaged/lib/parsing.js",
+		"dist/packaged/lib/playbook.js",
+		"dist/packaged/lib/results/snapshot.js",
+		"dist/packaged/lib/runtime.js",
 		"platform-smoke.config.mjs",
 		"scripts/config.mjs",
 		"scripts/convert-browser-session.mjs",
@@ -53,6 +60,8 @@
 		"LICENSE",
 		"docs/ARCHITECTURE.md",
 		"docs/CODE_QUALITY.md",
+		"docs/PERFORMANCE.md",
+		"docs/performance/2026-10-12.json",
 		"docs/COMMAND_REFERENCE.md",
 		"docs/ELECTRON.md",
 		"docs/RELEASE.md",
@@ -111,14 +120,15 @@
 		"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",
-		"smoke:platform:all": "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run --target macos,ubuntu,windows-native",
+		"smoke:platform:all": "npm run smoke:platform:doctor && node scripts/platform-smoke.mjs run",
 		"check:compat": "node scripts/compat-host.mjs && npm run typecheck && npm test && node scripts/verify-package.mjs --smoke-pi",
 		"typecheck": "node ./scripts/project.mjs verify typecheck",
-		"test": "node ./scripts/build.mjs && node ./scripts/prepare-quality-checker.mjs && tsx --test --test-reporter=tap \"test/**/!(*.serial).test.ts\" && tsx --test --test-reporter=tap --test-concurrency=1 \"test/**/*.serial.test.ts\"",
+		"test": "node ./scripts/project.mjs test",
 		"verify": "node ./scripts/project.mjs verify",
 		"prepublishOnly": "npm run verify -- release && npm pack --dry-run",
 		"build": "node ./scripts/build.mjs",
 		"startup-profile": "node ./scripts/profile-startup.mjs",
+		"performance-profile": "node --expose-gc ./scripts/profile-performance.mjs",
 		"prepare": "node ./scripts/prepare.mjs"
 	},
 	"packageManager": "npm@12.2.0",
@@ -139,8 +149,12 @@
 	"dependencies": {
 		"cross-spawn": "7.0.6",
 		"path-key": "3.1.1",
+		"stream-chain": "4.2.6",
 		"stream-json": "3.7.0",
 		"strip-json-comments": "5.0.3",
 		"which": "2.0.2"
+	},
+	"overrides": {
+		"undici": "8.12.3"
 	}
 }

package/platform-smoke.config.mjs

@@ -1,5 +1,5 @@
 // Platform smoke configuration for pi-agent-browser-native.
-// Crabbox owns the target lease/sync loop; this file is the project source of truth for release-blocking platform coverage.
+// Crabbox owns the target lease/sync loop; this file is the project source of truth for required and explicitly selected best-effort platform coverage.
 
 import packageJson from "./package.json" with { type: "json" };
 import { CAPABILITY_BASELINE } from "./scripts/agent-browser-capability-baseline.mjs";
@@ -10,7 +10,8 @@ const PLATFORM_SMOKE_UBUNTU_IMAGE = `pi-agent-browser-native-platform:node24-age
 export default {
 	packageName: "pi-agent-browser-native",
 	artifactRoot: ".artifacts/platform-smoke",
-	requiredTargets: ["macos", "ubuntu", "windows-native"],
+	requiredTargets: ["macos", "ubuntu"],
+	optionalTargets: ["windows-native"],
 	requiredSuites: ["platform-build", "browser-dogfood-smoke"],
 	requiredCrabbox: {
 		install: "Homebrew package or PLATFORM_SMOKE_CRABBOX override",

package/scripts/agent-browser-capability-baseline.mjs

@@ -89,6 +89,8 @@ const inventorySections = Object.freeze([
 			"session list",
 			"state save <path>",
 			"state load <path>",
+			"skippedOrigins",
+			"restoreSkippedOrigins",
 			"state list",
 			"state show <filename>",
 			"state rename <old-name> <new-name>",
@@ -118,6 +120,7 @@ const inventorySections = Object.freeze([
 			["session help", "--namespace <name>"],
 			["state help", "save <path>"],
 			["state help", "load <path>"],
+			["state help", "elsewhere are skipped and listed"],
 			["state help", "list"],
 			["state help", "show <filename>"],
 			["state help", "rename <old-name> <new-name>"],
@@ -144,7 +147,8 @@ const inventorySections = Object.freeze([
 		"Network, storage, artifacts, diagnostics, and performance",
 		[
 			"network <action>",
-			"network route <url> [--abort|--body <json>] [--resource-type <csv>]",
+			"network route <url> [--abort|--body <json> [--allow-origin <origin>]] [--resource-type <csv>]",
+			"--allow-origin <origin>",
 			"network unroute [url]",
 			"network requests [--clear] [--filter <pattern>] [--type <csv>] [--method <method>] [--status <code|range>]",
 			"network request <requestId>",
@@ -210,6 +214,7 @@ const inventorySections = Object.freeze([
 			root("network <action>"),
 			root("--resource-type <csv>"),
 			["network help", "unroute [url]"],
+			["network help", "--allow-origin <origin>"],
 			["network help", "network har start"],
 			["network help", "network har start --content all"],
 			["network help", "--content <mode>"],
@@ -285,6 +290,7 @@ const inventorySections = Object.freeze([
 		"Batch, auth, confirmations, setup, dashboard, devices, and AI commands",
 		[
 			"batch [--bail]",
+			"batch --bail --omit-command",
 			"auth save <name>",
 			"auth save <name> --url <url> --username <user> --password <pass>",
 			"auth save <name> --username-selector <s> --password-selector <s> --submit-selector <s>",
@@ -314,8 +320,10 @@ const inventorySections = Object.freeze([
 			"doctor --webgpu --headed",
 			"doctor --json",
 			"mcp",
+			"mcp call <tool>",
 			"mcp --tools core,webmcp",
 			"plugin add <ref>",
+			"plugin add <ref> --project",
 			"plugin [list]",
 			"plugin show <name>",
 			"plugin run <name> <type>",
@@ -323,7 +331,7 @@ const inventorySections = Object.freeze([
 			"profiles",
 		],
 		[
-			root("batch [--bail]"),
+			root('batch [options] ["cmd" ...]'),
 			root("auth save <name>"),
 			root("auth login <name>"),
 			root("confirm <id>"),
@@ -340,6 +348,8 @@ const inventorySections = Object.freeze([
 			root("doctor [--fix]"),
 			root("profiles"),
 			["batch help", "--bail"],
+			["batch help", "--omit-command"],
+			["batch help", "does not make output safe for secrets"],
 			["auth help", "--url <url>"],
 			["auth help", "--username <user>"],
 			["auth help", "--password <pass>"],
@@ -361,8 +371,12 @@ const inventorySections = Object.freeze([
 			["auth help", "--credential-provider <p>"],
 			["auth help", "--no-navigate"],
 			["mcp help", "agent_browser_open"],
+			["mcp help", "mcp call <tool>"],
+			["mcp help", "_meta.agentBrowserVersion"],
 			["mcp help", "--tools"],
 			["plugin help", "Add a plugin from npm or GitHub"],
+			["plugin help", "plugin add writes ~/.agent-browser/config.json by default"],
+			["plugin help", "--project"],
 			["plugin help", "credential.read"],
 		],
 	),

package/scripts/agent-browser-target.mjs

@@ -1,5 +1,5 @@
 export const TARGET_AGENT_BROWSER_SOURCE = "scripts/agent-browser-target.mjs";
-export const TARGET_AGENT_BROWSER_VERSION = "0.38.1";
+export const TARGET_AGENT_BROWSER_VERSION = "0.41.0";
 export const TARGET_AGENT_BROWSER_VERSION_LABEL = `agent-browser ${TARGET_AGENT_BROWSER_VERSION}`;
 export const MINIMUM_AGENT_BROWSER_VERSION = "0.35.0";
 export const MINIMUM_AGENT_BROWSER_VERSION_LABEL = `agent-browser ${MINIMUM_AGENT_BROWSER_VERSION}`;

package/scripts/build.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * Purpose: Produce the compiled runtime files that the published Pi package loads.
- * Responsibilities: Remove stale dist output, emit runtime assets, bundle the native entrypoint, and fail with clear build output.
+ * Responsibilities: Remove stale dist output, emit all checkout runtime assets, bundle the packaged entrypoints, and fail with clear build output.
  * Scope: Maintainer/package build only; runtime behavior remains in extensions/agent-browser TypeScript sources.
  * Usage: `npm run build` before package verification, lifecycle validation, and npm pack/publish.
  * Invariants/Assumptions: `node_modules` provides `typescript` and `esbuild`; Termux supplies Android-native `tsgo` on PATH. `dist/` is generated output.
@@ -51,14 +51,25 @@ async function main() {
 		}
 		throw error;
 	}
-	// Retain emitted workers and CLI modules; bundle the extension's reachable modules with package imports external.
-	const entrypoint = join(process.cwd(), "dist", "extensions", "agent-browser", "index.js");
+	// Raw checkout libraries share module-owned state; package-only bundles must not overwrite them.
+	const distDirectory = join(process.cwd(), "dist");
+	const runtimeDirectory = join(process.cwd(), "dist", "extensions", "agent-browser");
 	await build({
 		allowOverwrite: true,
 		bundle: true,
-		entryPoints: [entrypoint],
+		entryPoints: [
+			{ in: join(runtimeDirectory, "index.js"), out: "extensions/agent-browser/index" },
+			...[
+				"lib/config-policy",
+				"lib/browser-session-conversion",
+				"lib/parsing",
+				"lib/playbook",
+				"lib/results/snapshot",
+				"lib/runtime",
+			].map((path) => ({ in: join(runtimeDirectory, `${path}.js`), out: `packaged/${path}` })),
+		],
 		format: "esm",
-		outfile: entrypoint,
+		outdir: distDirectory,
 		packages: "external",
 		platform: "node",
 		target: "node24.21",

package/scripts/capability-options.mjs

@@ -56,6 +56,9 @@ export const optionsAndEnv = section(
 		"--no-ca-cert",
 		"AGENT_BROWSER_CA_CERT",
 		"AGENT_BROWSER_CLEAR_CA_CERT",
+		"--use-system-ca",
+		"AGENT_BROWSER_USE_SYSTEM_CA",
+		"SSL_CERT_FILE",
 		"--allow-file-access",
 		"AGENT_BROWSER_ALLOW_FILE_ACCESS",
 		"--hide-scrollbars <bool>",
@@ -75,6 +78,9 @@ export const optionsAndEnv = section(
 		"AGENT_BROWSER_DOWNLOAD_PATH",
 		"--engine <name>",
 		"AGENT_BROWSER_ENGINE",
+		"--engine obscura",
+		"OBSCURA_ALLOW_PRIVATE_NETWORK",
+		"AGENT_BROWSER_OBSCURA_STEALTH",
 		"--input-mode <mode>",
 		"--no-auto-dialog",
 		"AGENT_BROWSER_NO_AUTO_DIALOG",
@@ -141,11 +147,15 @@ export const optionsAndEnv = section(
 		"BROWSERLESS_STEALTH",
 		"BROWSERLESS_TTL",
 		"BROWSER_USE_API_KEY",
+		"BROWSER_USE_PROFILE_ID",
+		"BROWSER_USE_PROXY_COUNTRY",
+		"BROWSER_USE_ENABLE_RECORDING",
 		"KERNEL_API_KEY",
 		"KERNEL_HEADLESS",
 		"KERNEL_STEALTH",
 		"KERNEL_TIMEOUT_SECONDS",
 		"KERNEL_PROFILE_NAME",
+		"KERNEL_PROFILE_SAVE_CHANGES",
 		"AGENTCORE_API_KEY",
 		"AGENTCORE_REGION",
 		"AGENTCORE_BROWSER_ID",
@@ -210,6 +220,9 @@ export const optionsAndEnv = section(
 		root("--no-ca-cert"),
 		root("AGENT_BROWSER_CA_CERT"),
 		root("AGENT_BROWSER_CLEAR_CA_CERT"),
+		root("--use-system-ca"),
+		root("AGENT_BROWSER_USE_SYSTEM_CA"),
+		["core skill full", "SSL_CERT_FILE"],
 		root("--allow-file-access"),
 		root("AGENT_BROWSER_ALLOW_FILE_ACCESS"),
 		root("--hide-scrollbars <bool>"),
@@ -226,6 +239,12 @@ export const optionsAndEnv = section(
 		root("AGENT_BROWSER_DOWNLOAD_PATH"),
 		root("--engine <name>"),
 		root("AGENT_BROWSER_ENGINE"),
+		root("--engine obscura"),
+		root("OBSCURA_ALLOW_PRIVATE_NETWORK"),
+		root("AGENT_BROWSER_OBSCURA_STEALTH"),
+		root("BROWSER_USE_PROFILE_ID"),
+		root("BROWSER_USE_PROXY_COUNTRY"),
+		root("BROWSER_USE_ENABLE_RECORDING"),
 		root("--input-mode <mode>"),
 		root("--no-auto-dialog"),
 		root("AGENT_BROWSER_NO_AUTO_DIALOG"),
@@ -266,6 +285,7 @@ export const optionsAndEnv = section(
 		root("--debug"),
 		root("AGENT_BROWSER_DEBUG"),
 		root("--config <path>"),
+		root("The auto-discovered ./agent-browser.json cannot set executablePath, args or plugins"),
 		root("AGENT_BROWSER_CONFIG"),
 		root("AGENT_BROWSER_DEFAULT_TIMEOUT"),
 		root("AGENT_BROWSER_AUTOSAVE_INTERVAL_MS"),

package/scripts/capability-samples.mjs

@@ -1,9 +1,10 @@
 /** Audited upstream source evidence and the native help commands sampled for drift. */
 export const sourceEvidence = Object.freeze({
 	repository: "vercel-labs/agent-browser",
-	upstreamHead: "aff6125c023b810ea3f2e5deec5379e9a4270bdc",
-	upstreamPackageVersion: "0.38.1",
+	upstreamHead: "1453dd37a40c730fe00f592bc32198a896ff8747",
+	upstreamPackageVersion: "0.41.0",
 	inspectedSources: Object.freeze([
+		"stock npm agent-browser@0.41.0 tarball and skill-data/",
 		"agent-browser --version",
 		"agent-browser --help",
 		"selected agent-browser <command> --help output",
@@ -20,19 +21,28 @@ export const sourceEvidence = Object.freeze({
 		"bin/agent-browser.js",
 		"cli/src/ca_bundle.rs",
 		"cli/src/commands.rs",
+		"cli/src/connection.rs",
 		"cli/src/mcp.rs",
 		"cli/src/flags.rs",
+		"cli/src/main.rs",
+		"cli/src/session_files.rs",
+		"cli/src/plugins.rs",
 		"cli/src/read.rs",
+		"cli/src/tls.rs",
 		"cli/src/doctor/ffmpeg.rs",
 		"cli/src/doctor/webgpu.rs",
 		"cli/src/native/actions.rs",
 		"cli/src/native/a11y/mod.rs",
 		"cli/src/native/browser.rs",
+		"cli/src/native/cdp/obscura.rs",
+		"cli/src/native/policy.rs",
+		"cli/src/native/providers.rs",
 		"cli/src/native/tab_binding.rs",
 		"cli/src/native/daemon.rs",
 		"cli/src/native/element.rs",
 		"cli/src/native/recording.rs",
 		"cli/src/native/snapshot.rs",
+		"cli/src/native/state.rs",
 		"cli/src/native/interaction.rs",
 		"cli/src/native/screenshot.rs",
 		"cli/src/native/stream/cdp_loop.rs",
@@ -41,13 +51,17 @@ export const sourceEvidence = Object.freeze({
 		"cli/src/native/test_fixtures/webmcp_probe.html",
 		"cli/src/native/webmcp.rs",
 		"cli/src/output.rs",
-		"docs/src/app/webgpu/page.mdx",
-		"docs/src/app/webmcp/page.mdx",
-		"docs/src/app/network/page.mdx",
-		"docs/src/app/proxy/page.mdx",
-		"docs/src/app/selectors/page.mdx",
-		"docs/src/app/skills/page.mdx",
-		"docs/src/app/commands/page.mdx",
+		"docs/content/docs/webgpu.mdx",
+		"docs/content/docs/webmcp.mdx",
+		"docs/content/docs/network.mdx",
+		"docs/content/docs/proxy.mdx",
+		"docs/content/docs/selectors.mdx",
+		"docs/content/docs/skills.mdx",
+		"docs/content/docs/commands.mdx",
+		"docs/content/docs/engines/obscura.mdx",
+		"docs/content/docs/providers/browser-use.mdx",
+		"docs/content/docs/providers/kernel.mdx",
+		"cli/tests/tls_cli.rs",
 		"skill-data/derive-client/SKILL.md",
 		"skill-data/core/SKILL.md",
 		"skill-data/core/references/video-recording.md",
@@ -60,7 +74,6 @@ export const sourceEvidence = Object.freeze({
 		"packages/@agent-browser/sandbox/README.md",
 		"packages/@agent-browser/sandbox/src/shared.ts",
 		"packages/@agent-browser/sandbox/src/vercel.ts",
-		"packages/@agent-browser/sandbox/src/eve.ts",
 	]),
 });
 

package/scripts/config.mjs

@@ -17,7 +17,7 @@ async function loadConfigPolicyModule() {
 	if (existsSync(sourcePolicyUrl)) {
 		return import(sourcePolicyUrl.href);
 	}
-	return import("../dist/extensions/agent-browser/lib/config-policy.js");
+	return import("../dist/packaged/lib/config-policy.js");
 }
 
 const {

package/scripts/convert-browser-session.mjs

@@ -23,7 +23,7 @@ if (values.help) {
 			);
 		}
 		const { convertBrowserSession } =
-			await import("../dist/extensions/agent-browser/lib/browser-session-conversion.js");
+			await import("../dist/packaged/lib/browser-session-conversion.js");
 		const receipt = await convertBrowserSession({
 			source: values.source,
 			destination: values.output,

package/scripts/platform-smoke/commands.mjs

@@ -10,10 +10,19 @@ function psSingleQuote(value) {
 	return `'${String(value).replace(/'/g, "''")}'`;
 }
 
-export function buildPlatformBuildCommand(targetName, packageName, nodeValidationVersion) {
+export function buildPlatformBuildCommand(
+	targetName,
+	packageName,
+	nodeValidationVersion,
+	candidate,
+) {
 	if (platformFor(targetName) === "powershell") {
-		return `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\\scripts\\platform-smoke\\platform-build-windows.ps1 -PackageName ${psSingleQuote(packageName)} -NodeValidationVersion ${psSingleQuote(nodeValidationVersion)}`;
+		const candidateArgs = candidate
+			? ` -CandidatePath ${psSingleQuote(candidate.path)} -CandidateSha256 ${psSingleQuote(candidate.sha256)}`
+			: "";
+		return `powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\\scripts\\platform-smoke\\platform-build-windows.ps1 -PackageName ${psSingleQuote(packageName)} -NodeValidationVersion ${psSingleQuote(nodeValidationVersion)}${candidateArgs}`;
 	}
+	const candidateHash = `node -e 'process.stdout.write(require("node:crypto").createHash("sha256").update(require("node:fs").readFileSync(process.argv[1])).digest("hex"))' "$PACK_FILE"`;
 	return [
 		`echo "Starting platform-build in $(pwd) at $(date -u +%Y-%m-%dT%H:%M:%SZ)"`,
 		`RUN_ROOT=".platform-smoke-runs/platform-build-$(date -u +%Y%m%dT%H%M%SZ)-$$"`,
@@ -37,11 +46,21 @@ export function buildPlatformBuildCommand(targetName, packageName, nodeValidatio
 		`cat "$PACK_DIR/npm-pack.stderr.txt"`,
 		`PACK_FILE="$PACK_DIR/$PACK_TARBALL"`,
 		`echo "PLATFORM_NPM_PACK_EXIT=$PACK_EXIT"`,
+		...(candidate
+			? [
+					`CANDIDATE_EXIT=0`,
+					`CANDIDATE_SOURCE=${shellQuote(candidate.path)}`,
+					`PACK_FILE="$PACK_DIR/release-candidate.tgz"`,
+					`if cp "$SOURCE_ROOT/$CANDIDATE_SOURCE" "$PACK_FILE"; then CANDIDATE_BEFORE=$(${candidateHash}); else CANDIDATE_BEFORE=""; fi`,
+					`echo "PLATFORM_CANDIDATE_SHA256_BEFORE=$CANDIDATE_BEFORE"`,
+					`if [ "$CANDIDATE_BEFORE" != ${shellQuote(candidate.sha256)} ]; then CANDIDATE_EXIT=1; fi`,
+				]
+			: []),
 		`echo "PLATFORM_PACKED_TARBALL=$PACK_FILE"`,
 		`PI_CLI="$SOURCE_ROOT/node_modules/.bin/pi"`,
 		`if [ ! -x "$PI_CLI" ]; then PI_CLI="$(command -v pi || true)"; fi`,
 		`echo "PLATFORM_PI_CLI=$PI_CLI"`,
-		`if [ -n "$PACK_TARBALL" ] && [ -f "$PACK_FILE" ]; then (cd "$PI_PROJECT" && npm init -y >"$PACK_DIR/packed-node-install.stdout.txt" 2>"$PACK_DIR/packed-node-install.stderr.txt" && npm install --no-save "$PACK_FILE" >>"$PACK_DIR/packed-node-install.stdout.txt" 2>>"$PACK_DIR/packed-node-install.stderr.txt"); PACKED_NODE_INSTALL_EXIT=$?; else echo "missing tarball" >"$PACK_DIR/packed-node-install.stderr.txt"; PACKED_NODE_INSTALL_EXIT=1; fi`,
+		`if [ -n "$PACK_TARBALL" ] && [ -f "$PACK_FILE" ]${candidate ? ' && [ "$CANDIDATE_EXIT" -eq 0 ]' : ""}; then (cd "$PI_PROJECT" && npm init -y >"$PACK_DIR/packed-node-install.stdout.txt" 2>"$PACK_DIR/packed-node-install.stderr.txt" && npm install --no-save "$PACK_FILE" >>"$PACK_DIR/packed-node-install.stdout.txt" 2>>"$PACK_DIR/packed-node-install.stderr.txt"); PACKED_NODE_INSTALL_EXIT=$?; else echo "missing or invalid tarball" >"$PACK_DIR/packed-node-install.stderr.txt"; PACKED_NODE_INSTALL_EXIT=1; fi`,
 		`echo "PLATFORM_PACKED_NODE_INSTALL_EXIT=$PACKED_NODE_INSTALL_EXIT"`,
 		`echo "--- PACKED_NODE_INSTALL_STDOUT START ---"; cat "$PACK_DIR/packed-node-install.stdout.txt" 2>/dev/null || true; echo "--- PACKED_NODE_INSTALL_STDOUT END ---"`,
 		`echo "--- PACKED_NODE_INSTALL_STDERR START ---"; cat "$PACK_DIR/packed-node-install.stderr.txt" 2>/dev/null || true; echo "--- PACKED_NODE_INSTALL_STDERR END ---"`,
@@ -53,7 +72,14 @@ export function buildPlatformBuildCommand(targetName, packageName, nodeValidatio
 		`echo "PLATFORM_PI_LIST_EXIT=$PI_LIST_EXIT"`,
 		`echo "--- PI_LIST_STDOUT START ---"; cat "$PACK_DIR/pi-list.stdout.txt" 2>/dev/null || true; echo "--- PI_LIST_STDOUT END ---"`,
 		`echo "--- PI_LIST_STDERR START ---"; cat "$PACK_DIR/pi-list.stderr.txt" 2>/dev/null || true; echo "--- PI_LIST_STDERR END ---"`,
-		`if [ "$NODE_VERSION_EXIT" -ne 0 ] || [ "$NPM_CI_EXIT" -ne 0 ] || [ "$VERIFY_EXIT" -ne 0 ] || [ "$PACK_EXIT" -ne 0 ] || [ "$PACKED_NODE_INSTALL_EXIT" -ne 0 ] || [ "$PI_INSTALL_EXIT" -ne 0 ] || [ "$PI_LIST_EXIT" -ne 0 ]; then echo "PLATFORM_BUILD_FAILED"; exit 1; fi`,
+		...(candidate
+			? [
+					`CANDIDATE_AFTER=$(${candidateHash})`,
+					`echo "PLATFORM_CANDIDATE_SHA256_AFTER=$CANDIDATE_AFTER"`,
+					`if [ "$CANDIDATE_AFTER" != ${shellQuote(candidate.sha256)} ]; then CANDIDATE_EXIT=1; fi`,
+				]
+			: []),
+		`if [ "$NODE_VERSION_EXIT" -ne 0 ] || [ "$NPM_CI_EXIT" -ne 0 ] || [ "$VERIFY_EXIT" -ne 0 ] || [ "$PACK_EXIT" -ne 0 ] || [ "$PACKED_NODE_INSTALL_EXIT" -ne 0 ] || [ "$PI_INSTALL_EXIT" -ne 0 ] || [ "$PI_LIST_EXIT" -ne 0 ]${candidate ? ' || [ "$CANDIDATE_EXIT" -ne 0 ]' : ""}; then echo "PLATFORM_BUILD_FAILED"; exit 1; fi`,
 		`echo "PLATFORM_BUILD_OK"`,
 	].join("\n");
 }

package/scripts/platform-smoke/doctor-support.mjs

@@ -85,12 +85,21 @@ function isForbiddenProjectPath(path) {
 	);
 }
 function npmPackFiles() {
-	const output = silent("npm", ["pack", "--dry-run", "--json"]);
+	const windows = process.platform === "win32";
+	const output = silent(windows ? "npm.cmd" : "npm", ["pack", "--dry-run", "--json"], {
+		timeout: 0,
+		shell: windows,
+	});
 	if (!output) {
 		return null;
 	}
 	try {
-		return JSON.parse(output)[0]?.files?.map((file) => file.path) ?? [];
+		const parsed = JSON.parse(output);
+		const packages = Array.isArray(parsed) ? parsed : Object.values(parsed);
+		if (packages.length !== 1 || !Array.isArray(packages[0]?.files)) {
+			return null;
+		}
+		return packages[0].files.map((file) => file.path);
 	} catch {
 		return null;
 	}

package/scripts/platform-smoke/doctor-windows.mjs

@@ -183,7 +183,7 @@ export function checkWindows({
 }) {
 	console.log("\n── Windows native / Parallels ──");
 	if (!(config?.requiredTargets ?? []).includes("windows-native")) {
-		report.warn("windows-native is not listed in requiredTargets for this configuration");
+		report.warn("windows-native not selected (best-effort); setup not checked, not a pass");
 		return;
 	}
 	if (!commandPath("prlctl")) {

package/scripts/platform-smoke/doctor.mjs

@@ -51,13 +51,19 @@ function crabboxProviders(cbox) {
 		.filter(Boolean);
 }
 
-function checkRequiredProviders(cbox, report) {
+function checkRequiredProviders(cbox, config, report) {
 	const providers = crabboxProviders(cbox);
 	if (providers.length === 0) {
 		report.fail("could not read crabbox providers");
 		return;
 	}
-	for (const provider of ["ssh", "local-container", "parallels"]) {
+	const providersByTarget = {
+		macos: "ssh",
+		ubuntu: "local-container",
+		"windows-native": "parallels",
+	};
+	for (const target of config.requiredTargets) {
+		const provider = providersByTarget[target];
 		if (providers.includes(provider)) {
 			report.ok(`crabbox provider available: ${provider}`);
 		} else {
@@ -163,13 +169,18 @@ function macSettings(config, packageName) {
 }
 
 function checkProviders(cbox, config, settings, report) {
-	checkRequiredProviders(cbox, report);
-	checkCrabboxProvider(
-		cbox,
-		["--provider", "local-container", "--local-container-image", settings.ubuntuImage],
-		"ubuntu local-container",
-		report,
-	);
+	checkRequiredProviders(cbox, config, report);
+	if (config.requiredTargets.includes("ubuntu")) {
+		checkCrabboxProvider(
+			cbox,
+			["--provider", "local-container", "--local-container-image", settings.ubuntuImage],
+			"ubuntu local-container",
+			report,
+		);
+	}
+	if (!config.requiredTargets.includes("macos")) {
+		return;
+	}
 	const mac = macSettings(config, settings.packageName);
 	checkCrabboxProvider(
 		cbox,
@@ -251,8 +262,12 @@ export async function runDoctor(config) {
 	if (cboxPath) {
 		checkProviders(cbox, config, { packageName, ubuntuImage }, report);
 	}
-	checkDocker(ubuntuImage, report);
-	checkMacSsh(config, packageName, report);
+	if (config.requiredTargets.includes("ubuntu")) {
+		checkDocker(ubuntuImage, report);
+	}
+	if (config.requiredTargets.includes("macos")) {
+		checkMacSsh(config, packageName, report);
+	}
 	checkWindows({
 		cbox,
 		config,