pi-agent-browser-native 0.2.77 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## Unreleased
+
+## 0.3.0 - 2026-08-06
+
+### Changed
+
+- Raised the minimum supported Pi runtime to 0.84.0 with no compatibility shims for older Pi releases, bumped the package from 0.2.x to 0.3.0 for the breaking support-floor change, pinned direct Pi development dependencies and the fleet marker to 0.84.0, and retained optional wildcard Pi peer dependencies per Pi package guidance.
+- Audited the extension factory, native tool registration, schemas, Pi `tool_result` patching, TUI rendering, SDK/package harnesses, browser/session/profile lifecycle, artifacts, lookups, Electron paths, build/package scripts, docs, fixtures, and tests against all Pi 0.84.0 breaking changes. The package does not consume the renamed model transform, RPC delta accumulator, provider header/refresh/auth APIs, pi-agent-core harness repositories or custom filesystem, or remote-session summary APIs; the existing coding-agent `ModelRuntime`, `createAgentSession`, `SessionManager`, extension, and tool contracts remain valid on 0.84.0.
+- Added Pi 0.84.0's `scrollbarThumb` background color to the complete test theme fixture and refreshed the lockfile against the released 0.84.0 packages and TypeBox 1.3.7.
+- Updated the `protobufjs` safety override to 7.6.5, clearing the advisory carried by the previous 7.6.4 pin.
+
+### Fixed
+
+- Result `outputPath` writes now fail validation instead of overwriting a screenshot, download, recording, or other browser artifact when both destinations resolve to the same file; the browser artifact and its verified metadata remain intact, including through filesystem aliases such as hard links.
+
+- Headed wrapper-managed launches now disable upstream periodic restore autosave by default and retain that launch environment across every follow-up subprocess, including still-owned off-current sessions, transcript-restored sessions whose replacement cleanup failed, and Electron cleanup closes, preventing agent-browser 0.33.2's multi-origin storage collector from flashing temporary tabs, blocking daemon policy probes, or triggering daemon-configuration mismatches; native close still saves, while direct window close can lose newer state because headed browsers are exempt from idle shutdown. The effective launch-time interval, including an explicit `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`, is persisted across transcript resume; changing it in either direction on a running wrapper-owned headed session is rejected until close plus a fresh launch. Slow valid daemon inspections now receive the full 35-second policy budget instead of failing after five seconds.
+- `--headed` and `--headed false` are now enforced as launch-scoped choices instead of being silently sent to an already-running managed session.
+- Bare, review-only, fenced-reference, conditional, permissive/uncertain, directly negated, and Pi clipboard/attachment image/video paths no longer become requested output artifacts that block browser close; output enforcement now requires a direct artifact-creation phrase with a destination, carries that intent across contiguous plain or Markdown path-list lines, handles delimited paths, preserves subordinate requirements such as “do not close until you save,” scopes availability-qualified recordings before, within, or after their list, leaves explicitly optional artifacts unenforced, applies recording availability per path clause, makes required duplicate paths take precedence, handles Markdown-link destinations, scans single-line and multiline path lists once instead of once per path, and avoids pathological backtracking on slash-heavy non-path text.
+
+## 0.2.78 - 2026-08-04
+
+### Changed
+
+- Removed zero-behavior maintainer bloat: Purpose/Responsibilities file banners, barrel-only `lib/results.ts` and `lib/input-modes.ts` facades, the synthetic efficiency benchmark script/tests/verify mode, the completed Electron plan ADR, and the `AgentBrowserNextActionCollector` class (plain array helpers remain).
+- Folded tiny one-liner modules (`session-artifacts`, `artifact-state`, `electron/text`) into neighboring owners; pending-recording predicates live in `artifact-manifest.ts`.
+- Trimmed docs that only existed to index or advertise the removed surfaces (`AGENTS.md`, `RELEASE.md`, `SUPPORT_MATRIX.md`, `ARCHITECTURE.md`, `ELECTRON.md`, `TOOL_CONTRACT.md`, `COMMAND_REFERENCE.md`, README).
+
 ## 0.2.77 - 2026-08-04
 
 ### Fixed

package/README.md

@@ -89,7 +89,7 @@ The result is optimized for agent work:
 
 ## Fastest way to try it
 
-Use Pi 0.80.6 or newer. This package keeps Pi core imports as wildcard `peerDependencies` because Pi package docs require the host Pi install to provide those packages, and `pi-agent-browser-doctor` fails setup when `pi --version` is below the enforced runtime floor. The current source tree's Pi compatibility is audited and validated against the Pi 0.80.9 extension/package baseline, including Project Trust; the runtime floor remains 0.80.6 because this refresh requires no newer runtime API.
+Use Pi 0.84.0 or newer. This package keeps optional Pi core imports as wildcard `peerDependencies` because Pi package docs require the host Pi install to provide those packages, pins its direct Pi validation dependencies to 0.84.0, and makes older hosts a setup failure through `pi-agent-browser-doctor`. Version 0.3.0 intentionally provides no compatibility shims for older Pi releases.
 
 Install upstream `agent-browser` first and make sure it is on `PATH`:
 
@@ -125,7 +125,7 @@ For a one-off trial that does not touch your configured Pi extensions:
 pi --no-extensions -e npm:pi-agent-browser-native
 ```
 
-Pi 0.79+ may ask whether to trust the current project before loading project-local instructions, settings, or resources. This extension treats its own project-local package config as developer-trusted by default; use `--no-approve` when you intentionally want Pi and this extension to ignore project-local inputs for that run.
+Pi 0.84.0+ may ask whether to trust the current project before loading project-local instructions, settings, or resources. This extension treats its own project-local package config as developer-trusted by default; use `--no-approve` when you intentionally want Pi and this extension to ignore project-local inputs for that run.
 
 For a specific published version:
 
@@ -234,7 +234,7 @@ printf '%s' "$EXA_API_KEY" | npm exec --yes --package pi-agent-browser-native@la
 npm exec --yes --package pi-agent-browser-native@latest -- pi-agent-browser-config web-search set-command "op read 'op://Private/Brave Search/API Key'" --provider brave --global
 ```
 
-Config merges in this order: global → project → `PI_AGENT_BROWSER_CONFIG` override. Under Pi 0.79+, the globally installed or CLI-loaded extension still loads project-local `.pi/config/pi-agent-browser-native/config.json` when Pi trust allows that project layer; it skips that project layer when Pi reports the project is untrusted or when Pi is launched with `--no-approve`. `webSearch.enabled` is evaluated after the loaded layers merge. Use `web-search disable --global` for a user default, `web-search disable --project` for one repo, and a `PI_AGENT_BROWSER_CONFIG` override with `{ "webSearch": { "enabled": false } }` when web search must stay off even if project config exists. Loaded config may use plaintext, custom environment aliases, interpolation literals, malformed-or-late-bound `$` values, and `!command` credential sources; the resolved secret is passed to the provider request while tool content, details, status output, and docs examples stay redacted. `web-search set-key`, `set-command`, and `clear` require `--provider`; `set-env` infers Exa/Brave from `EXA_API_KEY` or `BRAVE_API_KEY` unless you pass `--provider`.
+Config merges in this order: global → project → `PI_AGENT_BROWSER_CONFIG` override. Under Pi 0.84.0+, the globally installed or CLI-loaded extension still loads project-local `.pi/config/pi-agent-browser-native/config.json` when Pi trust allows that project layer; it skips that project layer when Pi reports the project is untrusted or when Pi is launched with `--no-approve`. `webSearch.enabled` is evaluated after the loaded layers merge. Use `web-search disable --global` for a user default, `web-search disable --project` for one repo, and a `PI_AGENT_BROWSER_CONFIG` override with `{ "webSearch": { "enabled": false } }` when web search must stay off even if project config exists. Loaded config may use plaintext, custom environment aliases, interpolation literals, malformed-or-late-bound `$` values, and `!command` credential sources; the resolved secret is passed to the provider request while tool content, details, status output, and docs examples stay redacted. `web-search set-key`, `set-command`, and `clear` require `--provider`; `set-env` infers Exa/Brave from `EXA_API_KEY` or `BRAVE_API_KEY` unless you pass `--provider`.
 
 For Exa, the tool defaults to `searchType: "auto"` with `contents.highlights: true`. Agents may pass `searchType` (`fast`, `instant`, `deep-lite`, `deep`, or `deep-reasoning`) only when the task needs that latency/depth tradeoff; structured output schemas are intentionally not exposed yet.
 
@@ -268,6 +268,8 @@ Watch a browser window during a demo or QA run by adding upstream's global `--he
 { "args": ["screenshot", "/tmp/agent-browser-headed-check.png"] }
 ```
 
+For wrapper-owned headed launches, the extension disables upstream 0.33.2 periodic restore autosave by default because its multi-origin collector opens visible temporary tabs and can delay daemon policy inspection. The extension records the effective launch-time interval and reapplies it to every helper and follow-up subprocess, including still-owned off-current sessions (also after failed replacement cleanup), Electron cleanup closes, and reload/resume, so the receiving daemon does not see changing configuration. Native `close` still saves, but upstream exempts headed browsers from idle shutdown, so closing the window by hand can lose newer state. Set `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` before launch when periodic preservation matters; changing it on a running wrapper-owned headed daemon is rejected until you close that session and launch fresh.
+
 Render a WebGPU page by enabling upstream's WebGPU launch preset on a fresh local browser:
 
 ```json
@@ -321,7 +323,7 @@ Evaluate page JavaScript through stdin. Put the script in the top-level `stdin`
 { "args": ["eval", "--stdin"], "stdin": "({ title: document.title, url: location.href })", "outputPath": "logs/page-state.json" }
 ```
 
-Use `outputPath` when `eval`, `get`, `snapshot`, or another extraction should be saved as a durable workspace file. The wrapper writes `details.data` when present, otherwise the model-facing text content, and returns `details.outputFile` with the saved path and byte count. Explicit upstream `--json` content stays parseable; in that case the save notice lives only in `details.outputFile`.
+Use `outputPath` when `eval`, `get`, `snapshot`, or another extraction should be saved as a durable workspace file. Keep it distinct from screenshot, download, recording, and other browser artifact destinations; if the paths resolve to the same file, the wrapper preserves the browser artifact and rejects the result-data write. The wrapper writes `details.data` when present, otherwise the model-facing text content, and returns `details.outputFile` with the saved path and byte count. Explicit upstream `--json` content stays parseable; in that case the save notice lives only in `details.outputFile`.
 
 Extract several known refs or selectors in one `batch` call instead of many serial getter calls:
 
@@ -440,7 +442,7 @@ After either path, use `qa: { "attached": true, ... }` for a current-session smo
 
 ### Lightweight QA preset
 
-For a quick smoke/QA pass, use top-level `qa`. It compiles to the same batch path as `job` and uses `batch --bail` so failed readiness/text/selector assertions stop before slower diagnostics can burn the wrapper watchdog. The URL form clears enabled network/console/page-error buffers before opening the target URL, waits for page readiness, checks optional expected text or selector, inspects fresh network requests, console messages, and page errors when preceding assertions pass, and can capture an evidence screenshot. Successful reset rows are labeled as reset-scoped output and ignored by QA failure analysis so stale pre-target errors do not fail an otherwise healthy target page; real post-open diagnostic rows still fail or warn according to the normal QA rules. Expected text is checked with bounded visible-text `wait --fn … --timeout 5000` predicates after the requested load state so dense pages can pass on visible headings/copy and missing text becomes crisp QA evidence. The attached form (`qa: { "attached": true }`) runs checks against the current managed session, such as an attached Electron app, rejects `url`, and deliberately preserves existing diagnostics instead of clearing evidence; its diagnostic reads default off so stale buffers do not fail a current-page smoke unless `checkNetwork`, `checkConsole`, or `checkErrors` is explicitly `true`. `loadState` defaults to `"domcontentloaded"`; set it to `"load"` or `"networkidle"` only when the stricter state is useful and the site is not expected to keep background requests alive. For URL-opening QA, `checkNetwork`, `checkConsole`, and `checkErrors` default to true; set one to `false` to skip that diagnostic read. Network failures are classified by likely impact and failed rows are listed first in network previews: actionable document/script/API-style failures still fail QA, while some low-impact browser icon asset misses (for example certain `favicon` or `apple-touch-icon` paths when upstream marks the row failed and resource metadata looks image-like) surface only as warnings instead of failing an otherwise healthy smoke check (`details.qaPreset.warnings`, with human-readable `details.qaPreset.summary` when the preset still passes). Exact predicates live in [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#qa) and `classifyNetworkRequestFailure` in `extensions/agent-browser/lib/results/network.ts` (re-exported from the compatibility barrel).
+For a quick smoke/QA pass, use top-level `qa`. It compiles to the same batch path as `job` and uses `batch --bail` so failed readiness/text/selector assertions stop before slower diagnostics can burn the wrapper watchdog. The URL form clears enabled network/console/page-error buffers before opening the target URL, waits for page readiness, checks optional expected text or selector, inspects fresh network requests, console messages, and page errors when preceding assertions pass, and can capture an evidence screenshot. Successful reset rows are labeled as reset-scoped output and ignored by QA failure analysis so stale pre-target errors do not fail an otherwise healthy target page; real post-open diagnostic rows still fail or warn according to the normal QA rules. Expected text is checked with bounded visible-text `wait --fn … --timeout 5000` predicates after the requested load state so dense pages can pass on visible headings/copy and missing text becomes crisp QA evidence. The attached form (`qa: { "attached": true }`) runs checks against the current managed session, such as an attached Electron app, rejects `url`, and deliberately preserves existing diagnostics instead of clearing evidence; its diagnostic reads default off so stale buffers do not fail a current-page smoke unless `checkNetwork`, `checkConsole`, or `checkErrors` is explicitly `true`. `loadState` defaults to `"domcontentloaded"`; set it to `"load"` or `"networkidle"` only when the stricter state is useful and the site is not expected to keep background requests alive. For URL-opening QA, `checkNetwork`, `checkConsole`, and `checkErrors` default to true; set one to `false` to skip that diagnostic read. Network failures are classified by likely impact and failed rows are listed first in network previews: actionable document/script/API-style failures still fail QA, while some low-impact browser icon asset misses (for example certain `favicon` or `apple-touch-icon` paths when upstream marks the row failed and resource metadata looks image-like) surface only as warnings instead of failing an otherwise healthy smoke check (`details.qaPreset.warnings`, with human-readable `details.qaPreset.summary` when the preset still passes). Exact predicates live in [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md#qa) and `classifyNetworkRequestFailure` in `extensions/agent-browser/lib/results/network.ts`.
 
 ```json
 {
@@ -606,17 +608,6 @@ npm run verify -- pre-pr
 
 That mode composes the full default gate with `npm run verify -- package`, so package contents and forbidden repo-only files are checked without launching Pi lifecycle, Crabbox, or live dogfood flows. Package modes build through npm `prepare`; lifecycle and startup-profile build in their focused scripts; default and platform-target build before consuming `dist/`, so clean checkouts do not validate stale or missing compiled output. The same `prepare` script owns GitHub/source installs; when Pi installs with `npm install --omit=dev`, it installs the source-build dev dependencies with lifecycle scripts disabled before building the ignored `dist/` entrypoint that Pi loads.
 
-The deterministic agent-efficiency benchmark’s **standalone JSON/Markdown accounting run** is not part of default or pre-PR `npm run verify` (only `npm run verify -- benchmark` or `npm run benchmark:agent-browser` invokes the script). The full unit suite still exercises `test/agent-browser.efficiency-benchmark.test.ts`. Use the script before and after agent-facing abstractions to prove call-count, output-size, stale-ref, artifact, failure-category coverage, success-rate, and elapsed-time effects before changing the wrapper UX:
-
-```bash
-npm run benchmark:agent-browser
-npm run verify -- benchmark
-```
-
-Save a JSON baseline (for example before changing playbook or wrapper behavior), then compare later runs: `npm run benchmark:agent-browser -- --json > /tmp/agent-browser-benchmark.json` and `npm run benchmark:agent-browser -- --compare /tmp/agent-browser-benchmark.json`.
-
-It does not launch a browser or mutate local profiles; it models representative raw workflows and provides a stable baseline for later comparisons.
-
 The opt-in startup profiler measures only the package extension entrypoint import plus factory registration in fresh Node processes. It intentionally does **not** launch Pi, tmux, mise, npm, browsers, or `agent-browser`; full Pi TUI ready-prompt profiling proved too invasive for routine verification on the operator machine. Run it after package entrypoint, generated runtime, or top-level import changes:
 
 ```bash
@@ -704,7 +695,7 @@ Configured-source lifecycle validation:
 npm run verify -- lifecycle
 ```
 
-The harness defaults to Pi model `zai/glm-5.2` and **180000 ms** per-step tmux waits; pass `--model <id>` and/or `--timeout-ms <ms>` after `lifecycle` when you need different settings (see [Configured-source lifecycle validation](docs/RELEASE.md#configured-source-lifecycle-validation) in `docs/RELEASE.md`). It launches Pi 0.79 with `--approve` and a deterministic `--session-id`, drives `/reload`, closes Pi, relaunches the exact same session, asserts the JSONL header id, and checks managed-session continuity, compiled-entrypoint pickup after process restart, persisted spill reachability, and real Pi `tool_result` failure-patch behavior.
+The harness defaults to Pi model `zai/glm-5.2` and **180000 ms** per-step tmux waits; pass `--model <id>` and/or `--timeout-ms <ms>` after `lifecycle` when you need different settings (see [Configured-source lifecycle validation](docs/RELEASE.md#configured-source-lifecycle-validation) in `docs/RELEASE.md`). It launches the supported Pi runtime with `--approve` and a deterministic `--session-id`, drives `/reload`, closes Pi, relaunches the exact same session, asserts the JSONL header id, and checks managed-session continuity, compiled-entrypoint pickup after process restart, persisted spill reachability, and real Pi `tool_result` failure-patch behavior.
 
 Use lifecycle validation when testing `/reload`, exact-session relaunch, `/resume`, managed-session continuity, or persisted artifact behavior. Branch-backed state and `session_tree` cleanup ownership are covered by focused extension harness tests. Maintainers must run the lifecycle harness before every publish; see [Pre-release checks](docs/RELEASE.md#pre-release-checks).
 

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

@@ -1,25 +1,18 @@
-/**
- * Purpose: Register the native agent_browser tool for pi so agents can invoke agent-browser without going through bash.
- * Responsibilities: Define the tool schema, inject thin wrapper behavior around the upstream CLI, manage extension-owned browser session convenience, and return pi-friendly content/details.
- * Scope: Native tool registration and orchestration only; the wrapper intentionally stays close to the upstream agent-browser CLI.
- * Usage: Loaded by pi through the package manifest in this package, or explicitly via `pi --no-extensions -e .` during local checkout development.
- * Invariants/Assumptions: agent-browser is installed separately on PATH, the wrapper targets the current locally installed upstream version only, and no backward-compatibility shims are provided.
- */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { Text } from "@earendil-works/pi-tui";
 import { PROJECT_RULE_PROMPT, buildBrowserDefaultProfileGuideline, buildBrowserExecutablePathGuideline, buildToolPromptGuidelines, } from "./lib/playbook.js";
 import { SessionPageState } from "./lib/session-page-state.js";
-import { canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, restoreManagedSessionStateFromBranch, validateToolArgs, } from "./lib/runtime.js";
-import { extractExplicitNamespace, extractExplicitSessionName, resolveAgentBrowserNamespace } from "./lib/argv-grammar.js";
+import { canUseHeadlessCompatibilityUserAgent, createEphemeralSessionSeed, createFreshSessionName, createImplicitSessionName, extractCommandTokens, getImplicitSessionCloseTimeoutMs, getImplicitSessionIdleTimeoutMs, isRestorableManagedSessionName, restoreManagedSessionStateFromBranch, validateToolArgs, } from "./lib/runtime.js";
+import { extractExplicitNamespace, extractExplicitSessionName, isUpstreamEnvFlagEnabled, resolveAgentBrowserNamespace } from "./lib/argv-grammar.js";
 import { cleanupManagedSessionRestoreConfig, ManagedSessionRestoreState } from "./lib/managed-session-restore.js";
 import { isRecord } from "./lib/parsing.js";
 import { buildPromptPolicy, getLatestUserPrompt, shouldAppendBrowserSystemPrompt } from "./lib/prompt-policy.js";
 import { isCloseCommand } from "./lib/command-taxonomy.js";
 import { hasLaunchScopedFlagToken } from "./lib/launch-scoped-flags.js";
 import { cleanupSecureTempArtifacts } from "./lib/temp.js";
-import { AGENT_BROWSER_PARAMS, } from "./lib/input-modes.js";
+import { AGENT_BROWSER_PARAMS } from "./lib/input-modes/params.js";
 import { parseAllowedDomainsPolicyFromArgs } from "./lib/navigation-policy.js";
 import { closeManagedSession, getSessionContextKey, runAgentBrowserTool } from "./lib/orchestration/browser-run/index.js";
 import { findElectronLaunchRecordForSession, getActiveElectronRecords } from "./lib/orchestration/browser-run/session-state.js";
@@ -112,6 +105,57 @@ function restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, sessionN
     }
     return restored;
 }
+function restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, sessionName, namespace) {
+    let restored = false;
+    const targetKey = getSessionContextKey(sessionName, namespace);
+    for (const entry of branch) {
+        if (!isRecord(entry) || entry.type !== "message")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        if (!message || message.toolName !== "agent_browser")
+            continue;
+        const details = isRecord(message.details) ? message.details : undefined;
+        if (!details)
+            continue;
+        if (getSessionContextKey(typeof details.sessionName === "string" ? details.sessionName : undefined, typeof details.namespace === "string" ? details.namespace : undefined) !== targetKey)
+            continue;
+        const outcome = getManagedSessionOutcome(details);
+        const activeAfterFailure = outcome?.activeAfter === true
+            && typeof outcome.currentSessionName === "string"
+            && getSessionContextKey(outcome.currentSessionName, typeof outcome.currentSessionNamespace === "string" ? outcome.currentSessionNamespace : undefined) === targetKey;
+        if ((getSuccessfulToolResult(details, message) || activeAfterFailure) && typeof details.managedSessionHeadedAutosaveDisabled === "boolean") {
+            restored = details.managedSessionHeadedAutosaveDisabled;
+        }
+    }
+    return restored;
+}
+function restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, sessionName, namespace) {
+    let restored;
+    const targetKey = getSessionContextKey(sessionName, namespace);
+    for (const entry of branch) {
+        if (!isRecord(entry) || entry.type !== "message")
+            continue;
+        const message = isRecord(entry.message) ? entry.message : undefined;
+        if (!message || message.toolName !== "agent_browser")
+            continue;
+        const details = isRecord(message.details) ? message.details : undefined;
+        if (!details)
+            continue;
+        if (getSessionContextKey(typeof details.sessionName === "string" ? details.sessionName : undefined, typeof details.namespace === "string" ? details.namespace : undefined) !== targetKey)
+            continue;
+        const outcome = getManagedSessionOutcome(details);
+        const activeAfterFailure = outcome?.activeAfter === true
+            && typeof outcome.currentSessionName === "string"
+            && getSessionContextKey(outcome.currentSessionName, typeof outcome.currentSessionNamespace === "string" ? outcome.currentSessionNamespace : undefined) === targetKey;
+        if (!getSuccessfulToolResult(details, message) && !activeAfterFailure)
+            continue;
+        if (typeof details.managedSessionHeadedAutosaveInterval === "string")
+            restored = details.managedSessionHeadedAutosaveInterval;
+        else if (details.managedSessionHeadedAutosaveDisabled === true)
+            restored = "0";
+    }
+    return restored;
+}
 function getToolResultArgs(details) {
     if (Array.isArray(details.args) && details.args.every((arg) => typeof arg === "string"))
         return details.args;
@@ -125,7 +169,7 @@ function isAttachedBrowserInvocation(args, env = process.env) {
         || hasLaunchScopedFlagToken(args, "--cdp")
         || hasLaunchScopedFlagToken(args, "--auto-connect")
         || env.AGENT_BROWSER_CDP !== undefined
-        || (autoConnectEnv !== undefined && !["", "0", "false", "no"].includes(autoConnectEnv.toLowerCase()));
+        || isUpstreamEnvFlagEnabled(autoConnectEnv);
 }
 function restoreAttachedSessionKeysFromBranch(branch) {
     const attachedSessionKeys = new Set();
@@ -216,7 +260,9 @@ function trackOwnedManagedSession(sessions, sessionName, cwd, options = {}) {
     const key = getSessionContextKey(sessionName, options.namespace) ?? sessionName;
     const existing = sessions.get(key);
     const branchOwned = existing && !existing.branchOwned ? false : options.branchOwned === true;
-    sessions.set(key, { branchOwned, cwd, namespace: options.namespace, sessionName });
+    const headedManagedAutosaveDisabled = options.headedManagedAutosaveDisabled ?? existing?.headedManagedAutosaveDisabled;
+    const headedManagedAutosaveInterval = options.headedManagedAutosaveInterval ?? existing?.headedManagedAutosaveInterval;
+    sessions.set(key, { branchOwned, cwd, headedManagedAutosaveDisabled, headedManagedAutosaveInterval, namespace: options.namespace, sessionName });
 }
 function untrackOwnedManagedSession(sessions, sessionName, namespace) {
     if (!sessionName)
@@ -247,7 +293,11 @@ function syncOwnedManagedSessionsFromResult(sessions, result, cwd) {
     const attemptedSessionName = typeof outcome.attemptedSessionName === "string" ? outcome.attemptedSessionName : undefined;
     if (outcome.activeAfter === true && (status === "created" || status === "replaced" || status === "unchanged")) {
         const namespace = isRecord(details) && typeof details.namespace === "string" ? details.namespace : undefined;
-        trackOwnedManagedSession(sessions, currentSessionName, cwd, { namespace });
+        trackOwnedManagedSession(sessions, currentSessionName, cwd, {
+            headedManagedAutosaveDisabled: details?.managedSessionHeadedAutosaveDisabled === true,
+            headedManagedAutosaveInterval: typeof details?.managedSessionHeadedAutosaveInterval === "string" ? details.managedSessionHeadedAutosaveInterval : undefined,
+            namespace,
+        });
     }
     if (succeeded && status === "closed") {
         untrackOwnedManagedSession(sessions, attemptedSessionName ?? currentSessionName);
@@ -382,10 +432,18 @@ function setBranchRankForString(map, value, rank) {
     if (typeof value === "string" && value.length > 0)
         map.set(value, rank);
 }
+function setBranchManagedSessionActive(events, sessionName, namespace, rank) {
+    if (typeof sessionName !== "string" || sessionName.length === 0)
+        return;
+    const key = getSessionContextKey(sessionName, namespace) ?? sessionName;
+    events.managedSessionActiveIdentities.set(key, { namespace, sessionName });
+    events.managedSessionActiveRanks.set(key, rank);
+}
 function collectBranchManagedResourceEvents(branch) {
     const events = {
         electronLaunchActiveRanks: new Map(),
         electronLaunchCleanupRanks: new Map(),
+        managedSessionActiveIdentities: new Map(),
         managedSessionActiveRanks: new Map(),
         managedSessionCloseRanks: new Map(),
     };
@@ -414,17 +472,17 @@ function collectBranchManagedResourceEvents(branch) {
         const outcomeCurrentSessionName = typeof outcome?.currentSessionName === "string" ? outcome.currentSessionName : undefined;
         const outcomeAttemptedSessionName = typeof outcome?.attemptedSessionName === "string" ? outcome.attemptedSessionName : undefined;
         if (outcomeSucceeded && outcome.activeAfter === true && (outcomeStatus === "created" || outcomeStatus === "replaced" || outcomeStatus === "unchanged")) {
-            setBranchRankForString(events.managedSessionActiveRanks, getSessionContextKey(outcomeCurrentSessionName, namespace), eventRank);
+            setBranchManagedSessionActive(events, outcomeCurrentSessionName, namespace, eventRank);
         }
         if (outcomeSucceeded && outcomeStatus === "closed") {
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(outcomeAttemptedSessionName ?? outcomeCurrentSessionName ?? sessionName, namespace), eventRank);
         }
-        if (outcomeSucceeded && outcomeStatus === "replaced") {
+        if (outcome && outcomeStatus === "replaced" && outcome.replacedSessionClosed !== false) {
             const replacedSessionNamespace = typeof outcome.replacedSessionNamespace === "string" ? outcome.replacedSessionNamespace : namespace;
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(typeof outcome.replacedSessionName === "string" ? outcome.replacedSessionName : undefined, replacedSessionNamespace), eventRank);
         }
-        if (succeeded && !isCloseCommand(command) && sessionName && (usedImplicitSession || sessionMode === "fresh")) {
-            events.managedSessionActiveRanks.set(getSessionContextKey(sessionName, namespace) ?? sessionName, eventRank);
+        if (succeeded && !isCloseCommand(command) && sessionName && (usedImplicitSession || sessionMode === "fresh" || details.managedSessionHeadedAutosaveDisabled === true || typeof details.managedSessionHeadedAutosaveInterval === "string")) {
+            setBranchManagedSessionActive(events, sessionName, namespace, eventRank);
         }
         if (succeeded && isCloseCommand(command)) {
             setBranchRankForString(events.managedSessionCloseRanks, getSessionContextKey(explicitSessionName ?? sessionName ?? outcomeAttemptedSessionName ?? outcomeCurrentSessionName, namespace), eventRank);
@@ -475,7 +533,7 @@ async function closeOwnedManagedSessionsExcept(sessions, restoreState, keepSessi
     for (const [key, owner] of [...sessions]) {
         if (key === keepKey)
             continue;
-        const error = await closeManagedSession({ cwd: owner.cwd, namespace: owner.namespace, preserveAttachedBrowserSession: attachedSessionKeys.has(key), restoreState, sessionName: owner.sessionName, timeoutMs });
+        const error = await closeManagedSession({ cwd: owner.cwd, headedManagedAutosaveInterval: owner.headedManagedAutosaveInterval, namespace: owner.namespace, preserveAttachedBrowserSession: attachedSessionKeys.has(key), restoreState, sessionName: owner.sessionName, timeoutMs });
         if (!error)
             sessions.delete(key);
     }
@@ -614,6 +672,8 @@ export default function agentBrowserExtension(pi) {
     let managedSessionActive = false;
     let managedSessionBaseName = createImplicitSessionName(undefined, process.cwd(), ephemeralSessionSeed);
     let managedSessionCompatibilityWorkaround;
+    let managedSessionHeadedAutosaveDisabled = false;
+    let managedSessionHeadedAutosaveInterval;
     let managedSessionName = managedSessionBaseName;
     let managedSessionCwd = process.cwd();
     let managedSessionNamespace;
@@ -680,6 +740,11 @@ export default function agentBrowserExtension(pi) {
         managedSessionCompatibilityWorkaround = managedSessionActive
             ? restoreManagedSessionCompatibilityWorkaroundFromBranch(branch, managedSessionName, managedSessionNamespace)
             : undefined;
+        managedSessionHeadedAutosaveDisabled = managedSessionActive
+            && restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, managedSessionName, managedSessionNamespace);
+        managedSessionHeadedAutosaveInterval = managedSessionActive
+            ? restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, managedSessionName, managedSessionNamespace)
+            : undefined;
         managedSessionCwd = ctx.cwd;
         freshSessionOrdinal = nextFreshSessionOrdinal;
         sessionPageState = SessionPageState.fromBranch(branch);
@@ -704,8 +769,41 @@ export default function agentBrowserExtension(pi) {
             }
             removeInactiveOwnedElectronLaunchRecords(ownedElectronLaunchRecords, branchOwnedElectronLaunchIds, electronLaunchRecords, branchResourceEvents.electronLaunchActiveRanks, branchResourceEvents.electronLaunchCleanupRanks);
         }
+        for (const [sessionKey, identity] of branchResourceEvents.managedSessionActiveIdentities) {
+            const activeRank = branchResourceEvents.managedSessionActiveRanks.get(sessionKey);
+            const closeRank = branchResourceEvents.managedSessionCloseRanks.get(sessionKey);
+            if (activeRank === undefined || (closeRank !== undefined && closeRank >= activeRank))
+                continue;
+            if (!isRestorableManagedSessionName(identity.sessionName, managedSessionBaseName))
+                continue;
+            trackOwnedManagedSession(ownedManagedSessions, identity.sessionName, ctx.cwd, {
+                branchOwned: true,
+                headedManagedAutosaveDisabled: restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, identity.sessionName, identity.namespace),
+                headedManagedAutosaveInterval: restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, identity.sessionName, identity.namespace),
+                namespace: identity.namespace,
+            });
+        }
         if (restoredState.active) {
-            trackOwnedManagedSession(ownedManagedSessions, restoredState.sessionName, ctx.cwd, { branchOwned: true, namespace: restoredState.namespace });
+            trackOwnedManagedSession(ownedManagedSessions, restoredState.sessionName, ctx.cwd, {
+                branchOwned: true,
+                headedManagedAutosaveDisabled: managedSessionHeadedAutosaveDisabled,
+                headedManagedAutosaveInterval: managedSessionHeadedAutosaveInterval,
+                namespace: restoredState.namespace,
+            });
+        }
+        for (const record of getActiveElectronRecords(electronLaunchRecords)) {
+            if (!record.sessionName || !isRestorableManagedSessionName(record.sessionName, managedSessionBaseName))
+                continue;
+            const sessionKey = getSessionContextKey(record.sessionName) ?? record.sessionName;
+            const activeRank = branchResourceEvents.managedSessionActiveRanks.get(sessionKey);
+            const closeRank = branchResourceEvents.managedSessionCloseRanks.get(sessionKey);
+            if (activeRank === undefined || (closeRank !== undefined && closeRank >= activeRank))
+                continue;
+            trackOwnedManagedSession(ownedManagedSessions, record.sessionName, ctx.cwd, {
+                branchOwned: true,
+                headedManagedAutosaveDisabled: restoreManagedSessionHeadedAutosaveDisabledFromBranch(branch, record.sessionName),
+                headedManagedAutosaveInterval: restoreManagedSessionHeadedAutosaveIntervalFromBranch(branch, record.sessionName),
+            });
         }
         mergeActiveElectronLaunchRecords(ownedElectronLaunchRecords, electronLaunchRecords, {
             branchOwnedLaunchIds: branchOwnedElectronLaunchIds,
@@ -768,6 +866,7 @@ export default function agentBrowserExtension(pi) {
                 electronChildProcesses,
                 electronLaunchRecords: electronRecordsToCleanup,
                 managedSessionRestoreState,
+                ownedManagedSessions,
                 timeoutMs: implicitSessionCloseTimeoutMs,
             });
             preservedElectronProfileDirs = [...new Set([
@@ -784,6 +883,8 @@ export default function agentBrowserExtension(pi) {
         });
         managedSessionActive = false;
         managedSessionCompatibilityWorkaround = undefined;
+        managedSessionHeadedAutosaveDisabled = false;
+        managedSessionHeadedAutosaveInterval = undefined;
         managedSessionNamespace = undefined;
         sessionPageState.reset();
         traceOwners = new Map();
@@ -890,6 +991,7 @@ export default function agentBrowserExtension(pi) {
                     managedSessionName,
                     managedSessionNamespace,
                     managedSessionRestoreState,
+                    ownedManagedSessions,
                     redactedCompiledElectron,
                     sessionPageState,
                     signal,
@@ -917,6 +1019,8 @@ export default function agentBrowserExtension(pi) {
                         if (closedSessionName === managedSessionName) {
                             managedSessionActive = false;
                             managedSessionCompatibilityWorkaround = undefined;
+                            managedSessionHeadedAutosaveDisabled = false;
+                            managedSessionHeadedAutosaveInterval = undefined;
                             managedSessionNamespace = undefined;
                             freshSessionOrdinal += 1;
                             managedSessionName = createFreshSessionName(managedSessionBaseName, ephemeralSessionSeed, freshSessionOrdinal);
@@ -959,6 +1063,8 @@ export default function agentBrowserExtension(pi) {
                     managedSessionActive,
                     managedSessionBaseName,
                     managedSessionCompatibilityWorkaround,
+                    managedSessionHeadedAutosaveDisabled,
+                    managedSessionHeadedAutosaveInterval,
                     managedSessionCwd,
                     managedSessionName,
                     managedSessionNamespace,
@@ -1037,6 +1143,8 @@ export default function agentBrowserExtension(pi) {
                     freshSessionOrdinal = Math.max(freshSessionOrdinal, browserRunState.freshSessionOrdinal);
                     managedSessionActive = browserRunState.managedSessionActive;
                     managedSessionCompatibilityWorkaround = browserRunState.managedSessionCompatibilityWorkaround;
+                    managedSessionHeadedAutosaveDisabled = browserRunState.managedSessionHeadedAutosaveDisabled === true;
+                    managedSessionHeadedAutosaveInterval = browserRunState.managedSessionHeadedAutosaveInterval;
                     managedSessionCwd = browserRunState.managedSessionCwd;
                     managedSessionName = browserRunState.managedSessionName;
                     managedSessionNamespace = browserRunState.managedSessionNamespace;

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Parse raw agent-browser argv once into a stable command descriptor for planners and policy.
- * Responsibilities: Own command-token extraction, command/subcommand identification, and descriptor construction.
- * Scope: Pure argv parsing; runtime planning and session policy consume descriptors instead of re-parsing tokens.
- */
 import { GLOBAL_BOOLEAN_FLAGS_WITH_OPTIONAL_VALUES, VALUE_FLAGS, optionalGlobalValueFlagConsumesNext } from "./argv-grammar.js";
 import { isOpenNavigationCommand } from "./command-taxonomy.js";
 function isBooleanLiteral(token) {

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Shared argv flag-shape metadata and helpers for command discovery and sessionless policy checks.
- * Responsibilities: Own global/command value-flag sets and boolean/value-flag validation used during argv parsing.
- * Scope: Pure token grammar; command semantics and subprocess execution live elsewhere.
- */
 import { isKnownCommandToken } from "./command-taxonomy.js";
 export const GLOBAL_VALUE_FLAGS = [
     "--session",
@@ -125,6 +120,10 @@ export function getBooleanFlagValue(args, flag) {
 export function isBooleanFlagEnabled(args, flag) {
     return getBooleanFlagValue(args, flag) ?? false;
 }
+/** Match upstream env_var_is_truthy exactly: lowercase only, without trimming or accepting "off". */
+export function isUpstreamEnvFlagEnabled(value) {
+    return value !== undefined && !["", "0", "false", "no"].includes(value.toLowerCase());
+}
 /** Mirror upstream sanitize_session_component for namespace/socket/state identity. */
 export function canonicalizeAgentBrowserNamespace(value) {
     if (value === undefined)

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Own upstream command-shape policies that decide whether the wrapper should allocate a managed browser session.
- * Responsibilities: Keep local/sessionless command grammar out of the runtime execution planner while preserving exact upstream shapes.
- * Scope: Pure argv-token policy; command discovery, subprocess execution, and presentation live in focused modules.
- */
 import { hasOnlyBooleanFlags, hasOnlyOptionFlags, isNonFlagToken, stripSessionlessShapeGlobalFlags } from "./argv-grammar.js";
 const SESSIONLESS_AUTH_SUBCOMMANDS = new Set(["save", "list", "show", "delete", "remove"]);
 const PLUGIN_SESSIONLESS_SUBCOMMANDS = new Set(["list", "show", "add", "run"]);

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

@@ -1,9 +1,3 @@
-/**
- * Purpose: Centralize upstream agent-browser command capabilities that wrapper behavior depends on.
- * Responsibilities: Normalize command aliases once and expose capability predicates for runtime planning,
- * session/ref guards, result recommendations, and presentation summaries without coupling unrelated behaviors.
- * Scope: Static command capability taxonomy only; command-shape parsing, spawning, and formatting live elsewhere.
- */
 const ADDITIONAL_COMMAND_TOKENS = [
     "a11y", "auth", "chat", "clipboard", "confirm", "connect", "dashboard", "deny", "device", "dialog", "diff", "doctor", "errors", "eval", "find", "frame", "get", "highlight", "inspect", "install", "is", "mcp", "plugin", "plugins", "profiles", "profiler", "react", "record", "removeinitscript", "session", "set", "skills", "snapshot", "state", "stream", "trace", "upgrade", "vitals", "wait", "web-vitals", "window",
 ];

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

@@ -1,9 +1,4 @@
 // @ts-check
-/**
- * Purpose: Canonical pi-agent-browser-native config policy shared by runtime and setup CLI.
- * Responsibilities: Own config paths, provider descriptors, credential source parsing, layer validation/merge, status projection, and redacted summaries.
- * Scope: Pure configuration policy plus synchronous status loading; secret command execution and browser/web-search runtime calls live elsewhere.
- */
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";

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

@@ -1,9 +1,3 @@
-/**
- * Purpose: Load pi-agent-browser-native package configuration from Pi-scoped global, project, or explicit paths.
- * Responsibilities: Resolve config layers, resolve secrets without exposing values, and provide redacted status for tools/CLIs.
- * Scope: Package-owned configuration only; canonical config policy lives in config-policy.js, browser command execution and web-search API calls live in focused modules.
- * Invariants/Assumptions: Credential sources from loaded config are passed through to the runtime; command credentials are resolved lazily at execution time and displayed values stay redacted.
- */
 import { exec as execCallback } from "node:child_process";
 import { readFile } from "node:fs/promises";
 import { promisify } from "node:util";

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

@@ -1,10 +1,3 @@
-/**
- * Purpose: Parse and fetch Chrome DevTools Protocol metadata for wrapper-owned Electron launches.
- * Responsibilities: Normalize CDP version/target JSON and perform bounded localhost CDP JSON fetches.
- * Scope: Tiny Electron CDP boundary helpers only; launch, status, cleanup, and target selection stay in their owning modules.
- * Usage: Imported by Electron launch and cleanup paths when polling `/json/version` and `/json/list`.
- * Invariants/Assumptions: Malformed or unavailable CDP endpoints return undefined/empty metadata rather than throwing, matching prior caller behavior.
- */
 import { isRecord } from "../parsing.js";
 const ELECTRON_CDP_FETCH_TIMEOUT_MS = 1_000;
 function asString(value) {
@@ -49,3 +42,9 @@ export async function fetchCdpJson(url, signal) {
         clearTimeout(timeout);
     }
 }
+export function boundElectronProbeString(value, maxLength = 240) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return undefined;
+    return trimmed.length > maxLength ? `${trimmed.slice(0, Math.max(0, maxLength - 3))}...` : trimmed;
+}

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

@@ -1,10 +1,3 @@
-/**
- * Purpose: Inspect and clean wrapper-owned Electron launch resources.
- * Responsibilities: Report CDP liveness/targets without mutation and remove only tracked process/profile resources during explicit or shutdown cleanup.
- * Scope: Host-side Electron status and resource cleanup only; upstream managed-session close remains in the extension entrypoint.
- * Usage: Called by electron.status, electron.cleanup, and session_shutdown handling.
- * Invariants/Assumptions: Cleanup operates only on launch records produced by this wrapper and prefers partial cleanup reporting over killing or deleting untracked resources.
- */
 import { execFile } from "node:child_process";
 import { rm } from "node:fs/promises";
 import { promisify } from "node:util";

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

@@ -1,10 +1,3 @@
-/**
- * Purpose: Discover installed Electron desktop applications without invoking upstream agent-browser.
- * Responsibilities: Scan bounded macOS app bundles and Linux .desktop launchers, apply Electron framework evidence gates, and return small platform-tagged app metadata.
- * Scope: Discovery only; launch, cleanup, status, and CDP attachment live in later Electron lifecycle work items.
- * Usage: Called by the agent_browser top-level electron.list shorthand and directly by tests through parameterized scan locations.
- * Invariants/Assumptions: Discovery is best-effort, missing scan roots are ignored, malformed .desktop files are skipped, and results are capped before they reach model-visible output.
- */
 import { constants as fsConstants } from "node:fs";
 import { access, readdir, readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";

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

@@ -1,10 +1,3 @@
-/**
- * Purpose: Launch wrapper-owned Electron applications and discover their CDP endpoint.
- * Responsibilities: Resolve Electron targets, enforce caller-owned allow/deny policy, create isolated userDataDir profiles, launch with remote debugging on an OS-chosen port, poll DevToolsActivePort, and read bounded CDP version/target metadata.
- * Scope: Host-side Electron lifecycle setup only; upstream agent-browser attach/presentation stays in the extension entrypoint.
- * Usage: Called by the agent_browser electron.launch shorthand before routing through upstream `connect`.
- * Invariants/Assumptions: The wrapper only launches targets with Electron framework evidence, always uses an isolated temp profile, never accepts a caller-supplied remote debugging port, and cleans any spawned process/profile when cancellation interrupts readiness.
- */
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { readFile, rm } from "node:fs/promises";

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Compile top-level Electron wrapper inputs into validated Electron actions.
- * Responsibilities: Enforce action-specific fields, launch-target rules, and wrapper-owned flag safety.
- * Scope: Electron input-mode validation only; launch/probe/cleanup execution stays in the extension entrypoint.
- */
 import { isRecord } from "../parsing.js";
 import { AGENT_BROWSER_ELECTRON_ACTIONS, AGENT_BROWSER_ELECTRON_HANDOFFS, AGENT_BROWSER_ELECTRON_LIST_FIELDS, AGENT_BROWSER_ELECTRON_PROBE_FIELDS, AGENT_BROWSER_ELECTRON_RESERVED_APP_ARGS, AGENT_BROWSER_ELECTRON_TARGET_TYPES, } from "./types.js";
 function validateOptionalNonEmptyString(input, fieldName) {

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Compile constrained job and lightweight QA wrapper inputs to upstream batch commands.
- * Responsibilities: Validate job/QA fields, produce argv/stdin, and summarize QA diagnostic results.
- * Scope: Job and QA modes only.
- */
 import { isRecord } from "../parsing.js";
 import { summarizeNetworkFailures } from "../results/network.js";
 import { getBatchResultItems, getCommandNameFromBatchItem, getSelectValues } from "./shared.js";

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Compile and analyze experimental DOM/source and network source lookup input modes.
- * Responsibilities: Build lookup batches, collect DOM/React/workspace candidates, and redact network lookup surfaces.
- * Scope: Source lookup and network source lookup only.
- */
 import { readFile, readdir } from "node:fs/promises";
 import { extname, join } from "node:path";
 import { isRecord } from "../parsing.js";

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Define the Pi tool input schema for the native agent_browser wrapper.
- * Responsibilities: Keep TypeBox schema construction separate from runtime execution and input-mode compilers.
- * Scope: Schema-only; behavioral validation lives in the mode compilers.
- */
 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";
@@ -128,7 +123,7 @@ export function createAgentBrowserParamsSchema(Type = JsonSchema, StringEnum = l
             }, { additionalProperties: false }), { minItems: 1 }),
         }, { additionalProperties: false, description: "Constrained multi-step batch." })),
         stdin: Type.Optional(Type.String({ description: "Raw stdin for batch, eval --stdin, or auth save --password-stdin; unavailable with structured modes and electron." })),
-        outputPath: Type.Optional(Type.String({ description: "Workspace-relative or absolute result path.", minLength: 1 })),
+        outputPath: Type.Optional(Type.String({ description: "Workspace-relative or absolute result-data path; keep it distinct from screenshot, download, recording, and other browser artifact destinations.", minLength: 1 })),
         timeoutMs: Type.Optional(Type.Integer({ description: "Wrapper timeout in ms; exceed explicit waits. Electron uses electron.timeoutMs.", minimum: 1 })),
         sessionMode: Type.Optional(StringEnum(["auto", "fresh"], {
             description: "auto reuses the managed session; fresh starts one for launch-only flags, then makes it the managed session.",

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

@@ -1,8 +1,3 @@
-/**
- * Purpose: Compile semanticAction shorthand inputs into upstream agent-browser commands.
- * Responsibilities: Validate shorthand locator/action fields and expose compiled-command helpers.
- * Scope: semanticAction mode only.
- */
 import { isRecord } from "../parsing.js";
 import { getSelectValues } from "./shared.js";
 import { AGENT_BROWSER_SEMANTIC_ACTIONS, AGENT_BROWSER_SEMANTIC_LOCATORS, } from "./types.js";