pi-agent-browser-native 0.9.0 → 0.9.2

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## Unreleased
+
+## 0.9.2 - 2026-10-04
+
+### Fixed
+
+- Treat `--engine` as launch-scoped so switching an active managed browser uses the existing fresh-session recovery instead of replacing its page in place.
+- Label positively identified Lightpanda images as text-rendered in direct, native batch and selected browser-code output; retain image bytes while refusing CSS/mouse-coordinate geometry even when synthetic dimensions match.
+- Omit wrapper-supplied Chrome profile/executable bootstrap defaults when CLI, environment or native config selects Lightpanda, without changing caller-selected launch settings.
+
+### Documentation
+
+- Keep Chrome default and Lightpanda opt-in. Document separate installation, single-target/visual/authentication limits, native unsupported commands, CORS and telemetry; add no driver, browser bundle or automatic fallback.
+
+## 0.9.1 - 2026-10-02
+
+### Removed
+
+- Deleted dead production code surfaced by the test audit: `getOwnedManagedSessionRestoreKey`, `parseValidBatchStepEntries`, `normalizeCommandName` (alias resolution is owned by the capability-table predicates), `AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS`, `isProjectSafeCredentialValueForProvider`, `isPlaintextCredentialValue`, the unused async `loadAgentBrowserConfig` duplicate of the sync loader, the unused `ensureAgentBrowserSocketDir` wrapper, and 46 export keywords (22 files) with no cross-module consumers. No behavior changed; owning tests now assert through the exported boundaries (`loadAgentBrowserConfigSync`, `getAgentBrowserSocketDirValidationError`, `runAgentBrowserScript`, capability predicates).
+
+### Changed
+
+- Share the unchanged 300000ms code timeout ceiling between its schema and runner, and the unchanged startup measurement/250ms budget between the regression test and safe profiler (retaining the Android test's 1000ms exception). Remove the unreachable platform-smoke passthrough entry without changing facade gates.
+- Move retained regressions to focused queue, artifact, input-validation, Electron host/branch, and Pi-pipeline owners. Relocate queue and concurrent artifact-merge helpers out of the extension entrypoint without changing their behavior. Consolidate required platform paths and private-file/tarball leak checks into the canonical package verifier and its existing real-tarball test. Allocate the macOS artifact alias fixture under `/tmp` so its path-alias contract does not depend on `TMPDIR`.
+- Consolidate duplicate test invocations into their owning tables and delivery boundaries, preserving distinct lifecycle, redaction, recovery, and native activation checks. Split recording dependency, reservation, and batch-lifecycle assertions into named contracts. Test-only; no production behavior changed.
+- Repaired 23 weak test assertions found by the test audit: literal prompt-byte expectations instead of source-derived constants, per-fixture bound expectations replacing pass-for-every-row alternations, real execution and credential-laziness probes for web-search/config, exact root-session `get url` probe matrices in passthrough coverage, complete guarded-set and key-set assertions, and anchored literal launcher/argv-delivery checks. Test-only; no production behavior changed.
+
+### Fixed
+
+- Execute maintainer command-reference and startup-profile scripts correctly through symlink and space/percent-encoded paths using Node's native main-module detection.
+- Keep ordinary `cookies set --curl` import paths visible in invocation echoes and failed batch diagnostics without exposing inline cookie values, secret-bearing flags or file contents.
+- Host the permissioned `agent_browser_code` child with a real Node runtime from `PATH` when Pi runs as a Bun-compiled binary, and fail as `missing-binary` with a clear remediation when no Node runtime is available instead of hanging the worker handshake (#238).
+- Resolve npm `.cmd` shims on Windows in `pi-agent-browser-doctor` PATH checks so installed `agent-browser` and `pi` binaries stop producing false negatives (#219).
+
+- Host cold-boundaries, cold-resume, and destination-cancel fixture browser sockets in a short private `0700` directory (`/tmp/piab-s-…`, via `createShortPrivateSocketDir` in the test harness) so realpath-canonicalized CI temp roots cannot exceed the macOS 103-byte Unix socket path cap. Test-only; production length and privacy guards are unchanged, and the fallback keeps the previous fixture-root path on Windows or when `/tmp` is unusable.
+
 ## 0.9.0 - 2026-10-01
 
 ### Breaking changes

package/README.md

@@ -321,7 +321,7 @@ npm exec --yes --package pi-agent-browser-native@latest -- pi-agent-browser-conf
 npm exec --yes --package pi-agent-browser-native@latest -- pi-agent-browser-config browser executable set "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
 ```
 
-Profile hints with `authenticated-only` remain advisory. Global/override profile names with `policy: "always"` and executable defaults bootstrap inactive automatic root browsers; active roots and unrelated explicit sessions retain their native settings. Configure profile/executable guidance globally, in trusted project config, or through `PI_AGENT_BROWSER_CONFIG`. Ask the agent to run `agent_browser` with `args: ["profiles"]` and `args: ["doctor"]` when profile resolution fails. The upstream `profiles` command lists Chrome profiles from Chrome's user data directory; `Default` is not canonical on every machine. Use the displayed profile directory name, a full profile/user-data directory path when upstream accepts one, or a configured `browser.executablePath` plus `sessionMode: "fresh"` for a different Chromium-compatible browser.
+Profile hints with `authenticated-only` remain advisory. Global/override profile names with `policy: "always"` and executable defaults bootstrap inactive automatic root browsers only when the effective engine is Chrome; active roots and unrelated explicit sessions retain their native settings. Configure profile/executable guidance globally, in trusted project config, or through `PI_AGENT_BROWSER_CONFIG`. Ask the agent to run `agent_browser` with `args: ["profiles"]` and `args: ["doctor"]` when profile resolution fails. The upstream `profiles` command lists Chrome profiles from Chrome's user data directory; `Default` is not canonical on every machine. Use the displayed profile directory name, a full profile/user-data directory path when upstream accepts one, or a configured `browser.executablePath` plus `sessionMode: "fresh"` for a different Chromium-compatible browser.
 
 ## Common agent calls
 
@@ -338,6 +338,21 @@ Chromium launch switches belong in the value of `--args`, for example `{ "args":
 
 Local Chrome startup uses the stock binary's `--args --no-startup-window` capability to suppress Chrome's extra startup window. Headless remains the default. Caller launch arguments keep native CLI → environment → config precedence and follow this default; browsers started before this change with custom arguments may restart once when their native launch configuration changes. Ordinary follow-ups do not resend bootstrap settings. CDP, providers, Electron, and Lightpanda remain native-owned; no tabs are deleted or profiles edited by this behavior.
 
+### Opt-in Lightpanda
+
+Chrome remains the default. Install [Lightpanda](https://github.com/lightpanda-io/browser/releases/tag/1.0.0) separately on supported macOS/Linux hosts, put `lightpanda` on `PATH`, then select it explicitly:
+
+```json
+{ "args": ["--engine", "lightpanda", "open", "https://example.com"], "sessionMode": "fresh" }
+{ "args": ["snapshot", "-i"] }
+```
+
+`--engine` is launch-scoped; changing an active managed browser uses the existing fresh-session recovery. `AGENT_BROWSER_ENGINE` and native config also select the engine. Wrapper-supplied Chrome profile/executable defaults are omitted for Lightpanda; caller arguments, environment, and native config remain unchanged.
+
+Lightpanda screenshots render page text, not graphical layout. Positively identified captures carry `imageObservations[].rendering: "text"` and unknown coordinate geometry; keep using refs, not image-derived mouse coordinates. Lightpanda is not Chrome-parity visual QA, profile login, multi-tab, or WebMCP support, and this wrapper never falls back automatically. See [capabilities and limits](docs/COMMAND_REFERENCE.md#lightpanda-engine).
+
+### Native navigation and interaction
+
 `open` without a URL uses native `get url`: it launches when needed and otherwise preserves the current page. This also applies to effective batch rows and code calls. `details.args` preserves the request, while `effectiveArgs`, command, URL data, and lifecycle describe the actual native operation. Use `open about:blank` only when you intend to navigate there. Help/version requests remain unchanged.
 
 Watch a browser window during a demo, QA run, or user-completed login by adding upstream's global `--headed` flag on the first launch. Use `sessionMode: "fresh"` if a managed session may already exist, because headed/headless state is launch-scoped. A successful first/fresh local wrapper-managed headed launch, including a launch inside `batch`, returns `details.browserWindow = { mode: "headed", ownership: "wrapper-managed", sessionName, visibility: "unverified" }` and one visible handoff sentence; CDP, auto-connect, provider, and Electron attachments do not. This proves that the wrapper requested and upstream launched headed mode, not that the OS window is visible on the user's display; remote, container, or virtual-display setups can still hide it. After the user finishes in the window, continue with `sessionMode: "auto"`.
@@ -505,7 +520,7 @@ Use the exact returned recovery payload after errors. Timeout partial progress r
 
 Both JSON and prose results expose a bounded canonical observation with recovery actions and artifact receipts. Oversized observations name an `observationPath` for the complete redacted result; audit-only `details` is not the model's sole recovery channel. Inner code calls avoid full model rendering, spills, and image encoding until output is selected.
 
-Screenshots expose measured image dimensions and capture geometry when supported by matching before/after samples. A full-page or element image is not a viewport screenshot. Native mouse coordinates are viewport CSS pixels; use the [geometry contract](docs/TOOL_CONTRACT.md#image-observations) and current scroll/frame state before converting image pixels. Unknown geometry stays unknown, including ambiguous or scrolled element captures and unmeasured batch captures. Pi image-resize notes only map sent pixels to original image pixels.
+Screenshots expose measured image dimensions and capture geometry when supported by matching before/after samples. A full-page or element image is not a viewport screenshot. Native mouse coordinates are viewport CSS pixels; use the [geometry contract](docs/TOOL_CONTRACT.md#image-observations) and current scroll/frame state before converting image pixels. Unknown geometry stays unknown, including ambiguous or scrolled element captures, unmeasured batch captures, and Lightpanda text-rendered images (`rendering: "text"`). Pi image-resize notes only map sent pixels to original image pixels.
 
 Save artifacts to the user's exact paths and check `artifactVerification` before claiming they exist or are fresh. Conditional `changed: false` screenshots produce no new attachment. `outputPath` is a separate result-data destination and must not alias a screenshot, download, or recording. Close ends the browser session; explicit files remain host-owned. Recording starts remain pending until stop and receipt/file verification.
 
@@ -570,6 +585,7 @@ Use these rules:
 - Prefer page actions and storage checks over cookie dumps. `cookies get` can expose real profile cookies.
 - Prefer `auth save --password-stdin` over putting passwords in `args`; the wrapper only accepts caller `stdin` for `batch`, `eval --stdin`, and `auth save --password-stdin` (advanced QA and source tools generate their own batch stdin).
 - Use `state save <path>` / `state load <path>` for portable test state. `state save` is reported as a file artifact with verification metadata; if an upstream-successful artifact command reports a non-pending file path that the wrapper cannot find or did not update during this command, the tool fails with `failureCategory: "artifact-missing"` instead of treating missing/stale evidence as durable. `state load` may mention a path but is not treated as a newly saved artifact.
+- `cookies set --curl <file>` treats its operand as a file path, not a cookie value: invocation echoes and failed batch diagnostics keep ordinary import paths visible. Inline cookie values and secret-bearing flags or path text still redact.
 - Treat `cookies get`, `storage local|session`, `state show`, and `auth show` output as sensitive. `state show` is presented as saved-state metadata only, and cookie/localStorage/sessionStorage values are redacted from structured details. The native presentation summarizes and redacts credential-like values while allowing benign primitive storage values to aid local QA, but avoid requesting broad dumps unless the task needs them.
 - Use `dialog status`, `dialog accept [text]`, `dialog dismiss`, and `frame <selector|main>` through native `args`; dialog commands use a shorter wrapper timeout and timed-out interactions add `inspect-dialog-after-timeout` / `dismiss-dialog-after-timeout` / fresh-session recovery actions so a blocking alert/prompt does not burn the full default watchdog. Use exact `confirm <id>` / `deny <id>` next actions for guarded-action confirmations.
 
@@ -729,7 +745,7 @@ Install upstream `agent-browser`, then install dependencies:
 npm install
 ```
 
-Use the npm version declared in `package.json` `packageManager` when refreshing `package-lock.json` (for example `npx -y npm@12.1.0 install`) so optional-platform lockfile metadata does not drift. Use Node 24.21.0 and Pi 1.0.0 or newer for lifecycle and interactive browser smokes; the pinned Pi 1.0.0 devDependencies are validation fixtures, not an exact-version requirement for the host CLI. See [Environment and automation pitfalls](docs/RELEASE.md#environment-and-automation-pitfalls) in `docs/RELEASE.md`.
+Use the npm version declared in `package.json` `packageManager` when refreshing `package-lock.json` (for example `npx -y npm@12.2.0 install`) so optional-platform lockfile metadata does not drift. Use Node 24.21.0 and Pi 1.0.0 or newer for lifecycle and interactive browser smokes; the pinned Pi 1.0.0 devDependencies are validation fixtures, not an exact-version requirement for the host CLI. See [Environment and automation pitfalls](docs/RELEASE.md#environment-and-automation-pitfalls) in `docs/RELEASE.md`.
 
 Checkout-only extension smoke test:
 

package/dist/extensions/agent-browser/index.js

@@ -1,4 +1,3 @@
-import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
@@ -21,6 +20,8 @@ import { getAgentBrowserProcessEnvironment, withAgentBrowserProcessEnvironment,
 import { withNativeSessionDefaults } from "./lib/orchestration/native-session-defaults.js";
 import { getBrowserCwdError, resolveExecutionCwd } from "./lib/execution-cwd.js";
 import { resolveOperationPaths } from "./lib/orchestration/operation-paths.js";
+import { AsyncExecutionQueue, KeyedAsyncExecutionQueue } from "./lib/orchestration/execution-queue.js";
+import { mergeBrowserRunArtifactManifest } from "./lib/orchestration/browser-run/artifact-merge.js";
 import { closeManagedSession, inspectManagedSessionDaemon } from "./lib/orchestration/browser-run/managed-session-daemon-policy.js";
 import { MINIMUM_AGENT_BROWSER_VERSION, SUPPORTED_AGENT_BROWSER_VERSION_LABEL, TARGET_AGENT_BROWSER_VERSION, getAgentBrowserVersionValidationError, parseAgentBrowserVersionOutput, } from "./lib/upstream-version.js";
 import { buildPromptPolicy, getLatestUserMessage, getMessageText } from "./lib/prompt-policy.js";
@@ -37,7 +38,7 @@ import { applyAgentBrowserOutputPath, canWriteAgentBrowserOutput, normalizeReque
 import { appendScriptSessionLease, createBrowserCodeOutput, getScriptSessionLeasesFromBranch } from "./lib/orchestration/script-mode.js";
 import { resolveBrowserExecutionIdentity, withBrowserExecutionLock, withBrowserExecutionLocks } from "./lib/managed-session-policy-lock.js";
 import { AGENT_BROWSER_INSTRUCTION_GROUP, AGENT_BROWSER_TOOL_INVENTORY, registerAgentBrowserToolSurface } from "./lib/tool-surface.js";
-import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isPendingRecordingCommand, isSessionArtifactManifest, mergeSessionArtifactManifest, retirePendingRecordingManifestEntries } from "./lib/results/artifact-manifest.js";
+import { formatSessionArtifactRetentionSummary, getSessionArtifactManifestEntryKey, isSessionArtifactManifest, retirePendingRecordingManifestEntries } from "./lib/results/artifact-manifest.js";
 import { appendUniqueAgentBrowserNextActions, applyNamespaceToNextActions, applySessionToNextActions, buildNextToolAction } from "./lib/results/next-actions.js";
 import { canRegisterWebSearchTool, loadAgentBrowserConfigSync } from "./lib/config.js";
 import { appendRecordingReservationTransition, applyRecordingArtifactsToReservations, restoreRecordingReservationStateFromBranch, retireRecordingReservation, } from "./lib/recording-reservations.js";
@@ -647,90 +648,6 @@ function shouldSerializeBrowserCommand(options) {
         return true;
     return getActiveElectronRecords(options.ownedElectronLaunchRecords).some((record) => record.sessionName === options.explicitSessionName);
 }
-// Serializes managed-session read/modify/write work so overlapping tool calls cannot promote stale state or close an in-use session.
-class AsyncExecutionQueue {
-    tail = Promise.resolve();
-    active = new AsyncLocalStorage();
-    isCurrent() { return this.active.getStore()?.active === true; }
-    run(work, signal, barrier = Promise.resolve()) {
-        if (this.isCurrent()) {
-            signal?.throwIfAborted();
-            return work();
-        }
-        const previous = this.tail;
-        let release;
-        this.tail = new Promise((resolve) => {
-            release = resolve;
-        });
-        let rejectWaiting;
-        const cancelled = new Promise((_resolve, reject) => { rejectWaiting = reject; });
-        const abortWaiting = () => rejectWaiting(signal?.reason);
-        signal?.addEventListener("abort", abortWaiting, { once: true });
-        if (signal?.aborted)
-            abortWaiting();
-        const execution = (async () => {
-            await Promise.all([previous, barrier]);
-            signal?.removeEventListener("abort", abortWaiting);
-            try {
-                signal?.throwIfAborted();
-                const scope = { active: true };
-                try {
-                    return await this.active.run(scope, work);
-                }
-                finally {
-                    scope.active = false;
-                }
-            }
-            finally {
-                release();
-            }
-        })();
-        return signal ? Promise.race([execution, cancelled]) : execution;
-    }
-}
-export class KeyedAsyncExecutionQueue {
-    barriers = new Map();
-    entries = new Map();
-    async run(key, namespace, work, signal) {
-        const entry = this.entries.get(key) ?? { queue: new AsyncExecutionQueue(), users: 0 };
-        if (entry.queue.isCurrent())
-            return work();
-        const barrier = this.barriers.get(getAgentBrowserSessionIdentityKey("", namespace)) ?? Promise.resolve();
-        entry.users += 1;
-        this.entries.set(key, entry);
-        try {
-            return await entry.queue.run(work, signal, barrier);
-        }
-        finally {
-            entry.users -= 1;
-            if (entry.users === 0 && this.entries.get(key) === entry)
-                this.entries.delete(key);
-        }
-    }
-    async runExclusive(namespace, work) {
-        const namespaceKey = getAgentBrowserSessionIdentityKey("", namespace);
-        const previous = this.barriers.get(namespaceKey) ?? Promise.resolve();
-        let release;
-        const blocked = new Promise((resolve) => {
-            release = resolve;
-        });
-        const barrier = previous.then(() => blocked);
-        this.barriers.set(namespaceKey, barrier);
-        const drains = [...this.entries]
-            .filter(([key]) => isAgentBrowserSessionIdentityKeyInNamespace(key, namespace))
-            .map(([, { queue }]) => queue.run(async () => undefined));
-        await previous;
-        await Promise.all(drains);
-        try {
-            return await work();
-        }
-        finally {
-            release();
-            if (this.barriers.get(namespaceKey) === barrier)
-                this.barriers.delete(namespaceKey);
-        }
-    }
-}
 function mergeBrowserRunMap(current, initial, updated) {
     if (updated === initial)
         return current;
@@ -745,27 +662,6 @@ function mergeBrowserRunMap(current, initial, updated) {
     }
     return merged;
 }
-export function mergeBrowserRunArtifactManifest(current, initial, updated) {
-    if (!updated || updated === initial)
-        return current;
-    if (current === initial)
-        return updated;
-    const initialEntries = new Map((initial?.entries ?? []).map((entry) => [getSessionArtifactManifestEntryKey(entry), entry]));
-    const changedEntries = updated.entries
-        .map((entry, index) => ({ entry, index }))
-        .filter(({ entry }) => initialEntries.get(getSessionArtifactManifestEntryKey(entry)) !== entry)
-        .sort((left, right) => left.entry.createdAtMs - right.entry.createdAtMs
-        || Number(isPendingRecordingCommand(left.entry.command, left.entry.subcommand, left.entry.kind)) - Number(isPendingRecordingCommand(right.entry.command, right.entry.subcommand, right.entry.kind))
-        || left.index - right.index)
-        .map(({ entry }) => entry);
-    return changedEntries.length === 0
-        ? current
-        : mergeSessionArtifactManifest({
-            base: current,
-            entries: changedEntries,
-            nowMs: Math.max(Date.now(), (current?.updatedAtMs ?? 0) + 1, updated.updatedAtMs),
-        });
-}
 function findPackageRoot(startDir) {
     let currentDir = startDir;
     while (true) {

package/dist/extensions/agent-browser/lib/argv-descriptor.js

@@ -76,7 +76,7 @@ function getOpenCommandTarget(commandTokens) {
     }
     return undefined;
 }
-export function parseCommandInfoFromTokens(commandTokens) {
+function parseCommandInfoFromTokens(commandTokens) {
     const upstreamCommandTokens = stripUpstreamGlobalFlags(commandTokens);
     const command = upstreamCommandTokens[0];
     return {

package/dist/extensions/agent-browser/lib/argv-grammar.js

@@ -38,7 +38,7 @@ export const GLOBAL_VALUE_FLAGS = [
     "--idle-timeout",
     "--input-mode",
 ];
-export const COMMAND_VALUE_FLAGS = [
+const COMMAND_VALUE_FLAGS = [
     "--allowed-origins",
     "--baseline",
     "--body",
@@ -79,7 +79,7 @@ export const COMMAND_VALUE_FLAGS = [
     "--password",
     "--wait-until",
 ];
-export const OPTIONAL_GLOBAL_VALUE_FLAGS = new Set(["--restore"]);
+const OPTIONAL_GLOBAL_VALUE_FLAGS = new Set(["--restore"]);
 export const VALUE_FLAGS = new Set([...GLOBAL_VALUE_FLAGS, ...COMMAND_VALUE_FLAGS]);
 export const PREVALIDATED_VALUE_FLAGS = new Set(GLOBAL_VALUE_FLAGS);
 export const GLOBAL_VALUE_FLAGS_ALLOWING_DASH_VALUE = new Set(["--args", "--session"]);
@@ -246,7 +246,7 @@ export function extractRequestedRestoreKey(args, sessionName, envValue) {
     }
     return restoreKey;
 }
-export function getFlagName(token) {
+function getFlagName(token) {
     return token.split("=", 1)[0] ?? token;
 }
 export function isNonFlagToken(token) {

package/dist/extensions/agent-browser/lib/browser-transcript.js

@@ -4,7 +4,7 @@ import { buildPageTransitionRefSnapshotInvalidation, normalizeSessionTabTarget,
 import { getSessionArtifactManifestEntryKey, isPendingRecordingArtifact, isSessionArtifactManifest } from "./results/artifact-manifest.js";
 import { extractAgentBrowserLifecycle } from "./results/presentation/common.js";
 export const BROWSER_TRANSITION_ENTRY = "agent-browser-transition";
-export const BROWSER_EVENT_VERSION = 1;
+const BROWSER_EVENT_VERSION = 1;
 export const BROWSER_RESULT_TOOLS = new Set([
     "agent_browser", "agent_browser_code", "agent_browser_action", "agent_browser_qa", "agent_browser_electron",
     "agent_browser_source", "agent_browser_network_source",

package/dist/extensions/agent-browser/lib/command-taxonomy.js

@@ -295,9 +295,6 @@ function getCommandCapability(command) {
 function hasCommandCapability(command, capability) {
     return getCommandCapability(command)?.[capability] === true;
 }
-export function normalizeCommandName(command) {
-    return getCommandCapability(command)?.command ?? command;
-}
 export function isCloseCommand(command) {
     return hasCommandCapability(command, "closesSession");
 }

package/dist/extensions/agent-browser/lib/config-policy.js

@@ -229,19 +229,6 @@ function validateBrowserDefaultProfile(value, path, errors) {
     }
     return { name, policy: /** @type {BrowserDefaultProfilePolicy} */ (policy) };
 }
-/** @param {string} rawValue */
-export function isPlaintextCredentialValue(rawValue) {
-    const trimmed = rawValue.trim();
-    return Boolean(trimmed) && !trimmed.startsWith("!") && !trimmed.startsWith("$");
-}
-/**
- * @param {string} rawValue
- * @param {WebSearchProvider} provider
- */
-export function isProjectSafeCredentialValueForProvider(rawValue, provider) {
-    void provider;
-    return rawValue.trim().length > 0;
-}
 /**
  * @param {unknown} value
  * @param {string} path

package/dist/extensions/agent-browser/lib/config.js

@@ -1,53 +1,8 @@
 import { exec as execCallback } from "node:child_process";
-import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";
-import { SECRET_COMMAND_TIMEOUT_MS, buildAgentBrowserConfigState, getAgentBrowserConfigPaths, getWebSearchCredentialSource, getWebSearchProviderOrder, loadAgentBrowserConfigStateSync, mergeAgentBrowserConfig, parseAgentBrowserConfigLayer, resolveEnvInterpolations, } from "./config-policy.js";
-export { AGENT_BROWSER_CONFIG_ENV, BRAVE_API_KEY_ENV, CONFIG_RELATIVE_PATH, DEFAULT_WEB_SEARCH_PROVIDER, EXA_API_KEY_ENV, EXA_SEARCH_TYPES, GLOBAL_CONFIG_RELATIVE_PATH, SECRET_COMMAND_TIMEOUT_MS, WEB_SEARCH_PROVIDER_CONFIG_KEYS, WEB_SEARCH_PROVIDER_DESCRIPTORS, WEB_SEARCH_PROVIDER_ENV_VARS, WEB_SEARCH_PROVIDERS, buildAgentBrowserConfigState, buildWebSearchCredentialSources, canRegisterWebSearchTool, classifyCredentialSource, formatBrowserExecutableStatus, formatBrowserProfileStatus, getAgentBrowserConfigPaths, getCredentialSourceSummary, getGlobalAgentBrowserConfigPath, getProjectAgentBrowserConfigPath, getWebSearchCredentialSource, getWebSearchProviderConfigKey, getWebSearchProviderDescriptor, getWebSearchProviderEnvVar, getWebSearchProviderLabel, getWebSearchProviderOrder, hasPotentialCredentialSource, isPlaintextCredentialValue, isProjectSafeCredentialValueForProvider, isWebSearchProvider, loadAgentBrowserConfigStateSync, mergeAgentBrowserConfig, parseAgentBrowserConfigLayer, resolveEnvInterpolations, summarizeConfigFiles, validateAgentBrowserConfig, validateWebSearchProvider, } from "./config-policy.js";
+import { SECRET_COMMAND_TIMEOUT_MS, getWebSearchCredentialSource, getWebSearchProviderOrder, loadAgentBrowserConfigStateSync, resolveEnvInterpolations, } from "./config-policy.js";
+export { AGENT_BROWSER_CONFIG_ENV, BRAVE_API_KEY_ENV, CONFIG_RELATIVE_PATH, DEFAULT_WEB_SEARCH_PROVIDER, EXA_API_KEY_ENV, EXA_SEARCH_TYPES, GLOBAL_CONFIG_RELATIVE_PATH, SECRET_COMMAND_TIMEOUT_MS, WEB_SEARCH_PROVIDER_CONFIG_KEYS, WEB_SEARCH_PROVIDER_DESCRIPTORS, WEB_SEARCH_PROVIDER_ENV_VARS, WEB_SEARCH_PROVIDERS, buildAgentBrowserConfigState, buildWebSearchCredentialSources, canRegisterWebSearchTool, classifyCredentialSource, formatBrowserExecutableStatus, formatBrowserProfileStatus, getAgentBrowserConfigPaths, getCredentialSourceSummary, getGlobalAgentBrowserConfigPath, getProjectAgentBrowserConfigPath, getWebSearchCredentialSource, getWebSearchProviderConfigKey, getWebSearchProviderDescriptor, getWebSearchProviderEnvVar, getWebSearchProviderLabel, getWebSearchProviderOrder, hasPotentialCredentialSource, isWebSearchProvider, loadAgentBrowserConfigStateSync, mergeAgentBrowserConfig, parseAgentBrowserConfigLayer, resolveEnvInterpolations, summarizeConfigFiles, validateAgentBrowserConfig, validateWebSearchProvider, } from "./config-policy.js";
 const exec = promisify(execCallback);
-async function readConfigLayer(path, scope, errors, warnings) {
-    let raw;
-    try {
-        raw = await readFile(path, "utf8");
-    }
-    catch (error) {
-        if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
-            return undefined;
-        }
-        errors.push(`Could not read ${scope} config ${path}: ${error instanceof Error ? error.message : String(error)}`);
-        return undefined;
-    }
-    return parseAgentBrowserConfigLayer(raw, path, scope, errors, warnings);
-}
-export async function loadAgentBrowserConfig(options = {}) {
-    const env = options.env ?? process.env;
-    const paths = getAgentBrowserConfigPaths({ cwd: options.cwd, env });
-    const includeProjectConfig = options.includeProjectConfig !== false;
-    const errors = [];
-    const warnings = [];
-    const layerCandidates = [
-        { path: paths.global, scope: "global" },
-        ...(includeProjectConfig ? [{ path: paths.project, scope: "project" }] : []),
-        ...(paths.override ? [{ path: paths.override, scope: "override" }] : []),
-    ];
-    const layers = [];
-    let mergedConfig = {};
-    for (const candidate of layerCandidates) {
-        const layer = await readConfigLayer(candidate.path, candidate.scope, errors, warnings);
-        if (!layer)
-            continue;
-        layers.push(layer);
-        mergedConfig = mergeAgentBrowserConfig(mergedConfig, layer.config);
-    }
-    return buildAgentBrowserConfigState({
-        env,
-        errors,
-        layers,
-        mergedConfig,
-        paths,
-        projectConfigIncluded: includeProjectConfig,
-        warnings,
-    });
-}
 export function loadAgentBrowserConfigSync(options = {}) {
     return loadAgentBrowserConfigStateSync(options);
 }
@@ -70,7 +25,7 @@ async function resolveCommandCredential(rawValue, signal) {
         throw new Error("Credential command failed without exposing command output. Check pi-agent-browser-config web-search status and the configured secret manager command.");
     }
 }
-export async function resolveCredentialSource(source, options = {}) {
+async function resolveCredentialSource(source, options = {}) {
     if (!source)
         return undefined;
     let value;

package/dist/extensions/agent-browser/lib/electron/launch.js

@@ -6,8 +6,8 @@ import { fetchCdpJson, parseCdpTargets, parseCdpVersion, } from "./cdp.js";
 import { discoverElectronApps, inspectElectronAppPath, inspectElectronExecutablePath, } from "./discovery.js";
 import { createSecureTempDirectory, preserveSecureTempDirectory } from "../temp.js";
 export const ELECTRON_LAUNCH_RECORD_VERSION = 1;
-export const ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS = 15_000;
-export const ELECTRON_LAUNCH_MAX_TIMEOUT_MS = 120_000;
+const ELECTRON_LAUNCH_DEFAULT_TIMEOUT_MS = 15_000;
+const ELECTRON_LAUNCH_MAX_TIMEOUT_MS = 120_000;
 const DEVTOOLS_ACTIVE_PORT_FILE = "DevToolsActivePort";
 export const ELECTRON_PROFILE_DIR_PREFIX = "electron-profile-";
 const ELECTRON_DEFAULT_APP_ARGS = ["--disable-extensions", "--no-first-run", "--no-default-browser-check"];
@@ -46,7 +46,7 @@ function policyEntryMatchesApp(entry, app) {
         return false;
     return appIdentifiers(app).some((identifier) => identifier.toLowerCase().includes(normalizedEntry));
 }
-export function evaluateElectronLaunchPolicy(options) {
+function evaluateElectronLaunchPolicy(options) {
     const denyEntry = options.deny?.find((entry) => policyEntryMatchesApp(entry, options.target));
     if (denyEntry) {
         return {
@@ -66,7 +66,7 @@ export function evaluateElectronLaunchPolicy(options) {
     }
     return undefined;
 }
-export async function resolveElectronLaunchTarget(options) {
+async function resolveElectronLaunchTarget(options) {
     if (options.appPath)
         return inspectElectronAppPath(options.appPath);
     if (options.executablePath)

package/dist/extensions/agent-browser/lib/input-modes/params.js

@@ -1,9 +1,8 @@
 import { JsonSchema } from "../json-schema.js";
 import { StringEnum as localStringEnum } from "../string-enum-schema.js";
 import { ELECTRON_DISCOVERY_DEFAULT_MAX_RESULTS, ELECTRON_DISCOVERY_MAX_RESULTS } from "../electron/discovery.js";
-import { AGENT_BROWSER_ELECTRON_HANDOFFS, AGENT_BROWSER_ELECTRON_TARGET_TYPES, AGENT_BROWSER_QA_LOAD_STATES, AGENT_BROWSER_SEMANTIC_ACTIONS, AGENT_BROWSER_SEMANTIC_LOCATORS, DEFAULT_SESSION_MODE, SOURCE_LOOKUP_MAX_WORKSPACE_FILES, } from "./types.js";
-export const AGENT_BROWSER_ADVANCED_TOOLS = ["action", "qa", "electron", "source", "network"];
-export const AGENT_BROWSER_CODE_MAX_TIMEOUT_MS = 300_000;
+import { AGENT_BROWSER_CODE_MAX_TIMEOUT_MS, AGENT_BROWSER_ELECTRON_HANDOFFS, AGENT_BROWSER_ELECTRON_TARGET_TYPES, AGENT_BROWSER_QA_LOAD_STATES, AGENT_BROWSER_SEMANTIC_ACTIONS, AGENT_BROWSER_SEMANTIC_LOCATORS, DEFAULT_SESSION_MODE, SOURCE_LOOKUP_MAX_WORKSPACE_FILES, } from "./types.js";
+const AGENT_BROWSER_ADVANCED_TOOLS = ["action", "qa", "electron", "source", "network"];
 function outputProperties(Type) {
     return {
         outputPath: Type.Optional(Type.String({ description: "Result-data path, separate from browser artifact paths.", minLength: 1 })),

package/dist/extensions/agent-browser/lib/input-modes/script.js

@@ -2,20 +2,34 @@ import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import which from "which";
 import { isRecord } from "../parsing.js";
 import { extractExplicitNamespace, extractExplicitSessionName, scanUpstreamGlobalFlagOccurrences } from "../argv-grammar.js";
 import { getUpstreamEffectiveBatchSteps } from "../orchestration/batch-stdin.js";
 import { extractUpstreamCommandTokens } from "../argv-descriptor.js";
 import { isCloseAllCommand } from "../command-taxonomy.js";
 import { redactSensitiveText, validateToolArgs } from "../runtime.js";
+import { AGENT_BROWSER_CODE_MAX_TIMEOUT_MS } from "./types.js";
 export const AGENT_BROWSER_SCRIPT_CODE_MAX_BYTES = 64 * 1_024;
 export const AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS = 120_000;
 export const AGENT_BROWSER_SCRIPT_NAMESPACE = "";
-export const AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS = 300_000;
 export const AGENT_BROWSER_SCRIPT_MAX_CALLS = 25;
 export const AGENT_BROWSER_SCRIPT_FINAL_OUTPUT_MAX_BYTES = 64 * 1_024;
 export const AGENT_BROWSER_SCRIPT_IPC_MESSAGE_MAX_BYTES = 1 * 1_024 * 1_024;
-export const AGENT_BROWSER_SCRIPT_IPC_CUMULATIVE_MAX_BYTES = 8 * 1_024 * 1_024;
+const AGENT_BROWSER_SCRIPT_IPC_CUMULATIVE_MAX_BYTES = 8 * 1_024 * 1_024;
+/**
+ * Resolve the Node runtime that hosts the permissioned code child. A Bun-compiled Pi binary
+ * points `process.execPath` at the pi executable, which rejects Node-only flags like
+ * `--permission`, so those hosts must spawn a real `node` from PATH instead.
+ */
+export function resolveScriptChildNodePath(options) {
+    if (options.runtime.bun === undefined)
+        return options.execPath;
+    const nodePath = options.whichNode();
+    if (nodePath === null)
+        throw new Error("agent_browser_code requires a `node` runtime on PATH when pi runs on a Bun binary.");
+    return nodePath;
+}
 function findPackageRoot(startDir) {
     let currentDir = startDir;
     for (;;) {
@@ -34,7 +48,7 @@ function resolveScriptWorkerPath() {
     return workerPath;
 }
 const SCRIPT_SESSION_NAME_PATTERN = /^piab-script-[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
-export function validateAgentBrowserScriptSource(input) {
+function validateAgentBrowserScriptSource(input) {
     if (typeof input !== "string")
         return { error: "script must be a string." };
     const bytes = Buffer.byteLength(input, "utf8");
@@ -175,8 +189,8 @@ export async function runAgentBrowserScript(options) {
         return buildFailedRun({ callCount: 0, emitCount: 0, error: compiled.error, failureCategory: "validation-error", rejectedCallCount: 0, steps: [] });
     }
     const timeoutMs = options.timeoutMs ?? AGENT_BROWSER_SCRIPT_DEFAULT_TIMEOUT_MS;
-    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS) {
-        return buildFailedRun({ callCount: 0, emitCount: 0, error: `script timeoutMs must be between 1 and ${AGENT_BROWSER_SCRIPT_MAX_TIMEOUT_MS}.`, failureCategory: "validation-error", rejectedCallCount: 0, steps: [] });
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > AGENT_BROWSER_CODE_MAX_TIMEOUT_MS) {
+        return buildFailedRun({ callCount: 0, emitCount: 0, error: `script timeoutMs must be between 1 and ${AGENT_BROWSER_CODE_MAX_TIMEOUT_MS}.`, failureCategory: "validation-error", rejectedCallCount: 0, steps: [] });
     }
     if (options.signal?.aborted) {
         return buildFailedRun({ aborted: true, callCount: 0, emitCount: 0, error: "Script execution was aborted.", failureCategory: "aborted", rejectedCallCount: 0, steps: [] });
@@ -189,7 +203,15 @@ export async function runAgentBrowserScript(options) {
         const message = error instanceof Error ? error.message : "Compiled script worker is missing.";
         return buildFailedRun({ callCount: 0, emitCount: 0, error: message, failureCategory: "missing-binary", rejectedCallCount: 0, steps: [] });
     }
-    const child = spawn(process.execPath, [
+    let childNodePath;
+    try {
+        childNodePath = resolveScriptChildNodePath({ runtime: { bun: process.versions.bun }, execPath: process.execPath, whichNode: () => which.sync("node", { nothrow: true }) });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "No Node runtime is available for the code child.";
+        return buildFailedRun({ callCount: 0, emitCount: 0, error: message, failureCategory: "missing-binary", rejectedCallCount: 0, steps: [] });
+    }
+    const child = spawn(childNodePath, [
         "--permission",
         "--max-old-space-size=64",
         workerPath,

package/dist/extensions/agent-browser/lib/input-modes/types.js

@@ -1,8 +1,8 @@
 export const DEFAULT_SESSION_MODE = "auto";
+export const AGENT_BROWSER_CODE_MAX_TIMEOUT_MS = 300_000;
 export const AGENT_BROWSER_SEMANTIC_ACTIONS = ["check", "click", "fill", "select"];
 export const AGENT_BROWSER_SEMANTIC_LOCATORS = ["alt", "label", "placeholder", "role", "testid", "text", "title"];
-export const AGENT_BROWSER_JOB_TYPE_DELAYED_TEXT_MAX_CHARACTERS = 200;
-export const AGENT_BROWSER_JOB_STEP_ACTIONS = ["open", "click", "fill", "type", "select", "wait", "assertText", "assertUrl", "waitForDownload", "screenshot", "snapshot"];
+const AGENT_BROWSER_JOB_STEP_ACTIONS = ["open", "click", "fill", "type", "select", "wait", "assertText", "assertUrl", "waitForDownload", "screenshot", "snapshot"];
 export const AGENT_BROWSER_QA_LOAD_STATES = ["domcontentloaded", "load", "networkidle"];
 export const AGENT_BROWSER_ELECTRON_ACTIONS = ["list", "launch", "status", "cleanup", "probe"];
 export const AGENT_BROWSER_ELECTRON_HANDOFFS = ["connect", "tabs", "snapshot"];

package/dist/extensions/agent-browser/lib/launch-scoped-flags.js

@@ -29,6 +29,10 @@ export const LAUNCH_SCOPED_FLAG_DEFINITIONS = [
         flag: "--enable",
         reason: "selects built-in page init scripts before the upstream browser session is launched",
     },
+    {
+        flag: "--engine",
+        reason: "selects the browser engine used for the upstream launch",
+    },
     {
         flag: "--executable-path",
         reason: "selects the browser executable used for the upstream launch",

package/dist/extensions/agent-browser/lib/managed-session-restore.js

@@ -82,9 +82,6 @@ const ownedManagedSessionStorage = new AsyncLocalStorage();
 export async function withOwnedManagedSessionContext(context, run) {
     return await ownedManagedSessionStorage.run(context, run);
 }
-export function getOwnedManagedSessionRestoreKey() {
-    return ownedManagedSessionStorage.getStore()?.restoreKey;
-}
 export function resolveOwnedManagedSessionContext(options) {
     const namespace = canonicalizeAgentBrowserNamespace(options.namespace);
     const currentNamespace = canonicalizeAgentBrowserNamespace(options.currentManagedSessionNamespace);
@@ -115,7 +112,7 @@ function hasExplicitConfigArg(args) {
 function closesBrowserSession(args) {
     return ["close", "exit", "quit"].includes(parseCommandInfo(args).command ?? "");
 }
-export function agentBrowserExplicitConfigIsPresent(parentEnv = getAgentBrowserProcessEnvironment(), args = []) {
+function agentBrowserExplicitConfigIsPresent(parentEnv = getAgentBrowserProcessEnvironment(), args = []) {
     return hasExplicitConfigArg(args) || hasUpstreamEnvValue(parentEnv, AGENT_BROWSER_CONFIG_ENV);
 }
 /** Caller-selected upstream config disables the wrapper's automatic restore injection without blocking that config. */

package/dist/extensions/agent-browser/lib/orchestration/batch-stdin.js

@@ -139,12 +139,3 @@ export function getUpstreamEffectiveBatchSteps(commandTokens, stdin) {
         return argumentSteps;
     return parseUserBatchStdin(stdin).steps ?? [];
 }
-export function parseValidBatchStepEntries(stdin) {
-    const parsed = parseBatchStdinJsonArray(stdin);
-    if (parsed.error || parsed.steps === undefined)
-        return [];
-    return parsed.steps.flatMap((step, index) => {
-        const validated = validateUserBatchStep(step, index);
-        return validated.ok ? [{ index, step: validated.step }] : [];
-    });
-}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/artifact-merge.js

@@ -0,0 +1,22 @@
+import { getSessionArtifactManifestEntryKey, isPendingRecordingCommand, mergeSessionArtifactManifest } from "../../results/artifact-manifest.js";
+export function mergeBrowserRunArtifactManifest(current, initial, updated) {
+    if (!updated || updated === initial)
+        return current;
+    if (current === initial)
+        return updated;
+    const initialEntries = new Map((initial?.entries ?? []).map((entry) => [getSessionArtifactManifestEntryKey(entry), entry]));
+    const changedEntries = updated.entries
+        .map((entry, index) => ({ entry, index }))
+        .filter(({ entry }) => initialEntries.get(getSessionArtifactManifestEntryKey(entry)) !== entry)
+        .sort((left, right) => left.entry.createdAtMs - right.entry.createdAtMs
+        || Number(isPendingRecordingCommand(left.entry.command, left.entry.subcommand, left.entry.kind)) - Number(isPendingRecordingCommand(right.entry.command, right.entry.subcommand, right.entry.kind))
+        || left.index - right.index)
+        .map(({ entry }) => entry);
+    return changedEntries.length === 0
+        ? current
+        : mergeSessionArtifactManifest({
+            base: current,
+            entries: changedEntries,
+            nowMs: Math.max(Date.now(), (current?.updatedAtMs ?? 0) + 1, updated.updatedAtMs),
+        });
+}

package/dist/extensions/agent-browser/lib/orchestration/browser-run/diagnostics.js

@@ -566,7 +566,7 @@ export function formatQaAttachedTargetText(target) {
         return undefined;
     return ["QA attached target:", target.sessionName, target.title, target.url].filter((part) => typeof part === "string" && part.length > 0).join(" — ");
 }
-export function buildQaAttachedRecoveryNextActions(sessionName) {
+function buildQaAttachedRecoveryNextActions(sessionName) {
     const sessionArgs = (args) => withOptionalSessionArgs(sessionName, args);
     return [
         buildNextToolAction({

package/dist/extensions/agent-browser/lib/orchestration/browser-run/final-result.js

@@ -26,13 +26,13 @@ export function buildMissingBinaryMessage() {
     ].join("\n");
 }
 const SEMANTIC_ACTION_CANDIDATE_ACTION_IDS = new Set(["try-button-name-candidate", "try-link-name-candidate"]);
-export function formatSemanticActionCandidateText(actions) {
+function formatSemanticActionCandidateText(actions) {
     const candidateActions = actions.filter((action) => SEMANTIC_ACTION_CANDIDATE_ACTION_IDS.has(action.id) && action.params?.args);
     if (candidateActions.length === 0)
         return undefined;
     return ["Agent-browser candidate fallbacks:", ...candidateActions.map((action) => `- ${action.id}: agent_browser ${JSON.stringify({ args: action.params?.args })} — ${action.reason}`)].join("\n");
 }
-export function buildSemanticActionCandidateActions(compiled) {
+function buildSemanticActionCandidateActions(compiled) {
     const commandIndex = getCompiledSemanticActionCommandIndex(compiled);
     if (commandIndex < 0 || compiled.args[commandIndex] !== "find")
         return [];