pi-agent-browser-native 0.9.6 → 0.9.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/CHANGELOG.md +95 -1
  2. package/README.md +14 -6
  3. package/dist/extensions/agent-browser/index.js +1276 -350
  4. package/dist/packaged/lib/browser-session-conversion.js +157 -21
  5. package/dist/packaged/lib/playbook.js +42 -8
  6. package/dist/packaged/lib/results/snapshot.js +140 -11
  7. package/dist/packaged/lib/runtime.js +58 -10
  8. package/docs/ARCHITECTURE.md +19 -10
  9. package/docs/CODE_QUALITY.md +21 -5
  10. package/docs/COMMAND_REFERENCE.md +154 -38
  11. package/docs/ELECTRON.md +1 -1
  12. package/docs/PERFORMANCE.md +12 -3
  13. package/docs/REFERENCE.md +14 -14
  14. package/docs/RELEASE.md +41 -18
  15. package/docs/REQUIREMENTS.md +6 -0
  16. package/docs/SESSION_STORAGE.md +3 -3
  17. package/docs/SUPPORT_MATRIX.md +25 -23
  18. package/docs/TOOL_CONTRACT.md +37 -14
  19. package/docs/platform-smoke.md +18 -14
  20. package/package.json +6 -3
  21. package/platform-smoke.config.mjs +3 -2
  22. package/scripts/agent-browser-capability-baseline.mjs +16 -2
  23. package/scripts/agent-browser-target.mjs +1 -1
  24. package/scripts/capability-options.mjs +20 -0
  25. package/scripts/capability-samples.mjs +23 -10
  26. package/scripts/platform-smoke/commands.mjs +30 -4
  27. package/scripts/platform-smoke/doctor-support.mjs +11 -2
  28. package/scripts/platform-smoke/doctor-windows.mjs +1 -1
  29. package/scripts/platform-smoke/doctor.mjs +26 -11
  30. package/scripts/platform-smoke/linux-image/Dockerfile +6 -3
  31. package/scripts/platform-smoke/platform-build-windows.ps1 +23 -3
  32. package/scripts/platform-smoke/suite-checks.mjs +11 -1
  33. package/scripts/platform-smoke/targets.mjs +4 -3
  34. package/scripts/platform-smoke.mjs +68 -25
package/docs/SUPPORT_MATRIX.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Current upstream support matrix
2
2
 
3
- Root browser groups use native named sessions plus per-root restore, with scoped Chrome profile-name bootstrap from existing package config. `test/agent-browser.shared-defaults.test.ts` covers root separation, descendant routing, exact root-name follow-ups, helper launch consistency, explicit overrides, and quit ownership; the companion pi-subagents tests cover foreground/detached launch and saved revive identity. Native JSON restore supports cookies and web storage, not new IndexedDB-only or memory credentials. Real SDK/native-browser restart and concurrency evidence is required for this boundary; a profile metadata match alone is not login proof.
3
+ Root browser groups use native named sessions plus per-root restore, with scoped Chrome profile-name bootstrap from existing package config. `test/agent-browser.shared-defaults.test.ts` covers root separation, current and legacy descendant routing for direct and code calls, exact root-name follow-ups, helper launch consistency, explicit overrides, and quit ownership; the companion pi-subagents tests cover child lineage: a delegated child's process receives its main's exact native ID as both `PI_INTERCOM_ROOT_SESSION_ID` and `PI_INTERCOM_PARENT_SESSION_ID`, and a malformed pair (one missing, empty, padded or unequal) stops the package from loading. Native JSON restore supports cookies and web storage, not new IndexedDB-only or memory credentials. Real SDK/native-browser restart and concurrency evidence is required for this boundary; a profile metadata match alone is not login proof.
4
4
 
5
5
  Related docs:
6
6
 
@@ -40,7 +40,8 @@ The compact direct/code/loader surface replaces public multimode inputs while re
40
40
  | RQ-0066 / RQ-0067 source | Flat source/network tools retain bounded host scans and candidates-only semantics even in browser-only hosts. |
41
41
  | RQ-0068 recipes | No recipe registry, persistent JavaScript, second driver, or interpreter dependency. |
42
42
  | RQ-0072 refs | Page-scoped ref checks scan effective raw/stdin batch plans through every snapshot. A snapshot clears the invalidation latch, but a later page-changing step sets it again even when no refs precede that snapshot; later guarded ref use fails before spawn unless another snapshot intervenes. Same-snapshot fill and role-checked form-control exceptions remain. [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details), `test/agent-browser.extension-ref-guards.test.ts` own this contract. |
43
- | RQ-0096 Electron | Flat lifecycle tool preserves app/process/profile ownership and cancellation; native browser/code operations reuse its returned session. CDP readiness/liveness requires a nonempty Browser/browser string. Restored cleanup requires the launch-time process start identity and fails closed without a match ([`ELECTRON.md`](ELECTRON.md)). |
43
+ | Native indexed batches | Exact `--omit-command` preserves index-only public receipts and spills with ordinary credential/error redaction, ordered close/reopen/ref state, and artifact verification. Original native indexes include skipped empty stdin rows; artifact requests and recording-recovery merges use compact returned-row positions, retaining unrelated artifacts and later-recording actions. Recording `outputPath` receipts use redacted internal attribution; every returned result, including unconfirmed finishes, omits step commands. Raw argv still overrides stdin. `test/agent-browser.batch-fidelity.test.ts` owns live direct/code/input/lifecycle/artifact proof on natives with `--omit-command` (0.40.0+; older supported natives skip that case); `test/agent-browser.presentation-diagnostics.test.ts` owns full-spill redaction; `test/agent-browser.storage-recovery.test.ts` owns unconfirmed-finish omission. |
44
+ | RQ-0096 Electron | Flat lifecycle tool preserves app/process/profile ownership and cancellation; native browser/code operations reuse its returned session. CDP readiness/liveness requires a nonempty Browser/browser string. Restored cleanup requires the launch-time process start identity and fails closed without a match. Managed fork restart dispositions `handoff`/`provisional` keep active branch-visible launches, profiles, and managed sessions for the replacement worker; `release` and absent dispositions clean as quit ([`ELECTRON.md`](ELECTRON.md)). |
44
45
  | RQ-0142 code | Fresh permissioned Node child over persistent parent-selected browser; explicit JSON/current-cell image output, visible failures/counts, ordinary auth/config/environment, ordered Pi intent/completion transitions, child cancellation/reaping, no legacy public execution. |
45
46
  | Hotpath boundaries | Unrelated tools/harmless Bash return before prompt policy. Latest raw user intent is seeded on start/tree, updated by `message_end` and refreshed after native content replacement. Captured admission uses a validated append-only prefix; one queued replay restores branch/lease state and folds per-session launch settings once. Per-row renderer memoization skips unchanged formatting. No broad config/trust/history cache, new wait/timer or budget increase. |
46
47
  | Shared ordering | Actual socket/namespace/session lock spans helper/action or entire cell; sorted identity sets for replacement/cleanup and namespace barrier for direct close-all. Requires every participating Pi to run the updated package; no human/third-party/older-version guarantee or transaction. |
@@ -48,14 +49,15 @@ The compact direct/code/loader surface replaces public multimode inputs while re
48
49
  | Observation and geometry | Canonical bounded JSON/prose/code/native `structuredContent` observations expose exact recovery and receipts, with native namespace/output-schema metadata and canonical returned `isError`; complete observation spills preserve large output. Image dimensions/CSS viewport/DPR/crop/scroll/frame evidence is measured or explicitly unknown; no viewport-coordinate assumptions for full-page/element images. |
49
50
  | Pi integration | Pi 1.0 floor with independently qualified official/fork graphs. Five advanced direct tools use native `defaultActive: false`; a narrow additive initial-resume fallback preserves available transcript selections without overriding explicit/defaultTools/filtered host selection. Loader/tree/reload retain native history; public `pi:instruction-groups` registration supplies one full `browser` instruction source. Managed hosts own deferred delivery; unmanaged/stock hosts receive identical full eager guidance even for generic prompts. No permission widening or legacy discovery metadata. `test/agent-browser.discovery.test.ts` covers full-text parity, dynamic ownership, and startup/late registration; tool-surface tests preserve host selections, with pipeline coverage in `test/agent-browser.pi-pipeline.test.ts`. No checkpoint or fork metadata/revision APIs, provider payload edits or image-detail overrides. |
50
51
 
51
- See [migration](TOOL_CONTRACT.md#07-migration), [canonical observations](TOOL_CONTRACT.md#canonical-observation), and [release qualification/rollback](RELEASE.md#07-upgrade-and-rollback). Routine GitHub Actions runs official/fork Linux compatibility, a macOS packed-Pi smoke, and Native lifecycle Linux qualification on PRs to `main`; Windows CI is excluded. Release/platform evidence and review remain separate from these focused checks.
52
+ See [migration](TOOL_CONTRACT.md#07-migration), [canonical observations](TOOL_CONTRACT.md#canonical-observation), and [release qualification/rollback](RELEASE.md#07-upgrade-and-rollback). Routine GitHub Actions runs official/fork Linux compatibility, a macOS packed-Pi smoke, Native lifecycle Linux, and one nonblocking latest-official native-Windows build/import/process smoke on PRs to `main`. Native Windows is best-effort. Its broader official/fork environment/full-contract/Git/npm-consumer qualification is manual-only, with real failures and artifacts retained. Release/platform evidence and review remain separate from these focused checks.
52
53
 
53
54
  ## Audit result
54
55
 
55
- - Recommended upstream: `agent-browser 0.38.1` (must match `TARGET_AGENT_BROWSER_VERSION` in [`scripts/agent-browser-target.mjs`](../scripts/agent-browser-target.mjs); the capability baseline imports it). Runtime support accepts stable versions at or above the 0.35.0 floor without version-specific shims.
56
+ - Recommended upstream: `agent-browser 0.41.0` (must match `TARGET_AGENT_BROWSER_VERSION` in [`scripts/agent-browser-target.mjs`](../scripts/agent-browser-target.mjs); the capability baseline imports it). Runtime support accepts stable versions at or above the 0.35.0 floor without version-specific shims.
56
57
  - Source of truth: `CAPABILITY_BASELINE.inventorySections` in the same file (stable `id` keys: `skills`, `core-commands`, `state-tabs-frames-dialogs`, `network-storage-artifacts-diagnostics`, `batch-auth-setup-ai`, `options-and-env`).
57
- - Status: source and wrapper adaptation target the exact 0.38.1 release (`aff6125c023b810ea3f2e5deec5379e9a4270bdc`), audited on 2026-09-17. The update covers delta snapshot/ref presentation, pathless conditional screenshots, native pointer-mode parsing, recording cursor/contact sheets, stateful auth guidance, and WebMCP catalog updates. Keeps 0.33.0 a11y/HAR/`find` coverage, documents 0.33.1 idle-timeout/tab-recovery and 0.33.2 stream quality/size env vars, and enables Git-checkout-generation-stable `AGENT_BROWSER_RESTORE` for extension-managed `piab-*` sessions so SSO cookies survive browser relaunches. Prior helper idle-timeout, post-`tab close` target refresh, and document-direction scroll behavior remain.
58
- - High-priority support gaps: 2026-05-26 audit found sessionless local commands and command-scoped value flags needed sharper wrapper handling; runtime/tests/docs now cover those paths. The 0.28.0 rebaseline added local `mcp` and `plugin` surfaces plus plugin-backed credential login; wrapper docs/tests mark `mcp` and known `plugin` commands sessionless, with no compatibility shim for older upstream releases. The 0.29.1 rebaseline added upstream `@agent-browser/sandbox` helper-package guidance and stricter `install --with-deps` failure semantics; no new wrapper runtime mode or bundled dependency was required. The 0.30.1 rebaseline fixed native `wait --url` glob matching; fixed-sequence assertions use that native command. The 0.31.0 rebaseline adds restore workflow and namespace/session lifecycle surfaces (`--restore`, restore checks, `--namespace`, `session id`, and `session info`) without adding a wrapper compatibility layer. The 0.31.1 rebaseline fixes upstream React renderer selection for `react tree`, `react inspect`, and `react suspense`; no wrapper runtime change was required. The 0.31.2 rebaseline adds the local-launch-only `--webgpu` preset and `doctor --webgpu`, plus periodic restore-state autosaves controlled by `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`; the wrapper treats WebGPU as launch-scoped and, for wrapper-owned headed launches, defaults autosave off to avoid upstream 0.33.2's visible temporary storage-collector tabs while preserving save-on-close and explicit opt-in at daemon launch; changing a running daemon requires close plus a fresh launch. The 0.32.0 rebaseline hardens request/worker/popup/WebRTC containment behind `--allowed-domains`, fixes waits against already-complete documents, and adds a separate `@agent-browser/eve` package; the wrapper makes containment launch-scoped, leaves enforcement upstream-owned, and adds no Eve-specific mode. The 0.32.1–0.32.2 rebaseline updates only eve compatibility/packaging, but the full current-surface audit also found the local reference had omitted upstream `read [url]` since 0.30.0; baseline/help sampling, content-first presentation, tab-target preservation, timeout budgeting, docs, and tests now cover it. The 0.32.3–0.32.4 rebaseline adds HAR response-body capture modes, the `derive-client` skill, fixed `find role` implicit-ARIA / accessible-name matching with locator-detail misses, and an advertised `find` action list of `click, fill, check, hover, text` only; the wrapper documents and classifies those surfaces without adding a new input mode. Remaining upstream-owned caveat: some help paths still mention `wait <selector> --state hidden` / `detached`, but runtime probes show those shapes still fail, so wrapper docs keep `wait --fn` disappearance predicates and top-level `uncheck` / `type` / `focus` passthrough instead of `find` for those actions. `wait --download <path>` still reports the requested path without guaranteed on-disk persistence ([#1300](https://github.com/vercel-labs/agent-browser/issues/1300)).
58
+ - Status: source/help audit targets separately installed stock npm 0.41.0 and upstream commit `1453dd37a40c730fe00f592bc32198a896ff8747` (2026-10-30). Crossed releases 0.39.3, 0.39.4, 0.40.0, and 0.41.0 add indexed batch receipts, route CORS configuration, finite MCP CLI calls, and native fixes for completed downloads, restore-origin isolation, project-config trust, daemon `.config` cleanup, screenshots, tab/process ownership, and Windows output capture. Native owns these behaviors; no version-specific emulation is added. The `.config` fix prevents new daemon-file accumulation but does not sweep historical orphans or change the wrapper's socket-directory scan. A metadata update cannot speed an already-0.41.0 installation. Optional engines, cloud providers, and Windows remain separately qualified; see the [current guide](COMMAND_REFERENCE.md#upstream-0410-rebaseline).
59
+ - High-priority support gaps: 2026-05-26 audit found sessionless local commands and command-scoped value flags needed sharper wrapper handling; runtime/tests/docs now cover those paths. The 0.28.0 rebaseline added local `mcp` and `plugin` surfaces plus plugin-backed credential login; wrapper docs/tests mark `mcp` and known `plugin` commands sessionless, with no compatibility shim for older upstream releases. The 0.29.1 rebaseline added upstream `@agent-browser/sandbox` helper-package guidance and stricter `install --with-deps` failure semantics; no new wrapper runtime mode or bundled dependency was required. The 0.30.1 rebaseline fixed native `wait --url` glob matching; fixed-sequence assertions use that native command. The 0.31.0 rebaseline adds restore workflow and namespace/session lifecycle surfaces (`--restore`, restore checks, `--namespace`, `session id`, and `session info`) without adding a wrapper compatibility layer. The 0.31.1 rebaseline fixes upstream React renderer selection for `react tree`, `react inspect`, and `react suspense`; no wrapper runtime change was required. The 0.31.2 rebaseline adds the local-launch-only `--webgpu` preset and `doctor --webgpu`, plus periodic restore-state autosaves controlled by `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS`; the wrapper treats WebGPU as launch-scoped and, for wrapper-owned headed launches, defaults autosave off to avoid upstream 0.33.2's visible temporary storage-collector tabs while preserving save-on-close and explicit opt-in at daemon launch; changing a running daemon requires close plus a fresh launch. The 0.32.0 rebaseline hardens request/worker/popup/WebRTC containment behind `--allowed-domains`, fixes waits against already-complete documents, and adds a separate `@agent-browser/eve` package; the wrapper makes containment launch-scoped, leaves enforcement upstream-owned, and adds no Eve-specific mode. The 0.32.1–0.32.2 rebaseline updates only eve compatibility/packaging, but the full current-surface audit also found the local reference had omitted upstream `read [url]` since 0.30.0; baseline/help sampling, content-first presentation, tab-target preservation, timeout budgeting, docs, and tests now cover it. The 0.32.3–0.32.4 rebaseline adds HAR response-body capture modes, the `derive-client` skill, fixed `find role` implicit-ARIA / accessible-name matching with locator-detail misses, and an advertised `find` action list of `click, fill, check, hover, text` only; the wrapper documents and classifies those surfaces without adding a new input mode. Remaining upstream-owned caveat: some help paths still mention `wait <selector> --state hidden` / `detached`, but runtime probes show those shapes still fail, so wrapper docs keep `wait --fn` disappearance predicates and top-level `uncheck` / `type` / `focus` passthrough instead of `find` for those actions. Native 0.39.4+ fixes already-completed `wait --download <path>` and moves downloaded bytes to the requested path for locally launched browsers; attached/remote CDP paths are not movable through that operation. The current native fixture requires saved bytes and verified artifacts, while reported-but-missing output still fails through the artifact-presentation owner.
60
+ - MCP boundary: native 0.41.0 `mcp call <tool>` and finite stdin-driven MCP complete normally, but the wrapper currently rejects every non-help MCP invocation. Native inner session/namespace identity, cross-session coordination, credential presentation, and image delivery are not integrated. This is a concrete support limitation, not a claim that finite MCP hangs; see the [contract](TOOL_CONTRACT.md#native-mcp-boundary).
59
61
  - Established outcomes remain: semantic/ref recovery, same-snapshot form batching, click-dispatch diagnostics, requested-artifact evidence, QA, Electron, source/network correlation, and optional Exa/Brave search. The 0.7 tools preserve these capabilities under compact direct/code and discoverable advanced contracts. Reusable browser recipes remain intentionally absent.
60
62
 
61
63
  ## UX/reliability decisions from 2026-05-29 agent feedback
@@ -96,11 +98,11 @@ Current summary:
96
98
  | RQ-0153 | Browser storage retains native JSONL authority, once-stored ancestral ref definitions, small correlated begin/finish events, explicit uncertainty/reuse and native-generation validation, invocation-only artifact receipts and ordered row changes. Failed persistence never retries effects; ordinary forks retain facts without acquiring parent cleanup rights. Read-only token replay automatically normalizes historical receipts through the same canonical reducer at the unchanged locator/bytes, retaining mixed-format ancestry, confirmation settings/provenance and cleanup ownership. Optional stopped separate-copy conversion reuses that decoder. | [`docs/SESSION_STORAGE.md`](SESSION_STORAGE.md), `lib/browser-transcript.ts`, `lib/browser-journal.ts`, `lib/browser-session-conversion.ts`, `test/agent-browser.storage-growth.test.ts`, `test/agent-browser.storage-recovery.test.ts`, existing script/ref/confirmation/Electron lifecycle tests |
97
99
  | RQ-0152 | Agent feedback closes recovery and evidence gaps without a new runtime layer: unknown-target timeouts return a visibly executable `get url` → `snapshot -i` fail-fast action while dialog recovery remains allowed; successful tab creation/selection/close, including dispatched batch rows, live-verifies URL/fresh titles and retains new, selected, and post-close blank tabs; compacted direct or batched `outputPath` writes use only full command-redacted live wrapper spills and fail rather than save metadata; explicit URL reads/all-read batches avoid browser helpers and managed replacement, while proven native read confirmations preserve exact session routing and capability-gated browser independence; single session-info preflights distinguish daemon/browser/native/Pi ownership; native recording receipts expose capture versus encoded measurements and survive failure/timeout exports, with bounded identity-matched recovery and no file-only success; direct or batched first/fresh local headed launches expose an unverified `browserWindow` handoff while attachments do not; snapshot spills and SAML/OAuth URL values are redacted at model/persistence boundaries; unsupported direct/batch `scrollintoview text=...` fails before upstream false success with visible native recovery payloads while help passes through; and web search sends Exa primary/version guidance, removes exact normalized-URL duplicates without overfetch, and labels provider page dates without claiming crawl/version proof. | [`docs/TOOL_CONTRACT.md`](TOOL_CONTRACT.md), [`docs/COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md), [`docs/ARCHITECTURE.md`](ARCHITECTURE.md), `test/agent-browser.extension-errors-artifacts.test.ts`, `test/agent-browser.extension-tabs.test.ts`, `test/agent-browser.extension-validation.test.ts`, `test/agent-browser.page-target-validation.test.ts`, `test/agent-browser.runtime.test.ts`, `test/agent-browser.snapshot-presentation.test.ts`, `test/agent-browser.web-search.test.ts`, `test/agent-browser.real-upstream-contract.test.ts` |
98
100
 
99
- Browser journal storage (RQ-0153) uses one canonical small event/reducer, once-stored complete captures and journal-ordered artifact changes. `test/agent-browser.storage-growth.test.ts` protects the incident-sized map and ordinary-code growth; `test/agent-browser.storage-recovery.test.ts` covers actual append-fault dispatch counts, concurrent publication during captured-branch replay, unpublished selected-leaf refusal, unknown prefixes, same-URL generation replacement, branch conversion and strict token validation. Existing tab/ref, read-confirmation, recording, artifact and Electron lifecycle suites retain their contracts. The opt-in `test/helpers/large-browser-journal.mjs` exercises a >1 GiB original with a giant ignored value under a constrained V8 heap; it reports actual RSS separately. Official and fork load/restart qualification remains independent, and stock official 1.0.0's native eager loader is not repaired by the extension alone. Ordinary legacy resume preserves the original locator and bytes; optional archive conversion is offline and source-retaining. The shared harness retains raw legacy fixtures so resume suites exercise runtime normalization, not pre-converted journals. See [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
101
+ Browser journal storage (RQ-0153) uses one canonical small event/reducer, once-stored complete captures and journal-ordered artifact changes. Incomparable persisted process-start formats invalidate refs without reopening a live same-PID/socket managed page; the activation regression and proven-replacement controls live in `test/agent-browser.storage-recovery.test.ts`. `test/agent-browser.incremental-replay.test.ts` exercises real native SDK appends/tree selection and measures actual file-read bytes, with full-scan fallback for changed locators, native reseeds, rotation, truncation and same-size edits; torn publication and genuine file errors remain failures rather than cached success. Only structural metadata is reused, not selected ref definitions. `test/agent-browser.storage-growth.test.ts` protects the incident-sized map and ordinary-code growth; `test/agent-browser.storage-recovery.test.ts` covers actual append-fault dispatch counts, concurrent publication during captured-branch replay, unpublished selected-leaf refusal, unknown prefixes, same-URL generation replacement, branch conversion and strict token validation. Existing tab/ref, read-confirmation, recording, artifact and Electron lifecycle suites retain their contracts. The opt-in `test/helpers/large-browser-journal.mjs` exercises a >1 GiB original with a giant ignored value under a constrained V8 heap; it reports actual RSS separately. Official and fork load/restart qualification remains independent, and stock official 1.0.0's native eager loader is not repaired by the extension alone. Ordinary legacy resume preserves the original locator and bytes; optional archive conversion is offline and source-retaining. The shared harness retains raw legacy fixtures so resume suites exercise runtime normalization, not pre-converted journals. See [`SESSION_STORAGE.md`](SESSION_STORAGE.md).
100
102
 
101
103
  QA truthfulness (#121, RQ-0145) is covered by the registered-tool controls in `test/agent-browser.extension-input-modes.test.ts` and the strict `contract suite matches QA non-pass after same-URL error-buffer rollover` case in `test/agent-browser.real-upstream-contract.test.ts`. The real fixture fills the native error FIFO with identical rows, then verifies that a new document actually throws again at the same URL and that QA is always non-pass. Matched rows fail as an unverified check, not an application-error assertion. Empty/cleared and explicit `checkErrors: false` controls preserve valid passes; the wrapper does not fix upstream `errors --clear` or accept a warning-only pass as resolution.
102
104
 
103
- Explicit native text preserves standalone and compound/raw-or-stdin batch output without changing caller input. `test/agent-browser.text-output.test.ts` covers opaque JSON/confirmation-like page strings, complete whitespace-preserving stdout and redacted subprocess/presentation spills, text-only output export success/failure notices, nonzero failure and strict malformed JSON; the `real native explicit text` case in `test/agent-browser.real-upstream-contract.test.ts` proves native URL reads, both diff orders, row boolean operands and last-wins outer selection. The same native case protects empty stdin-row skipping, later successful rows, Unicode results, bail behavior and original row positions in text errors; malformed shapes still fail before dispatch. Failed-exit stderr is primary while zero-exit malformed JSON remains strict, covered by the registered `failed-json`/`strict-json` cases. Text contains no trusted row, confirmation, lifecycle, page-target or artifact receipts; use JSON for those fields. See [the output contract](TOOL_CONTRACT.md#wrapper-json).
105
+ Explicit native text preserves standalone and compound/raw-or-stdin batch output without changing caller input. `test/agent-browser.text-output.test.ts` covers opaque JSON/confirmation-like page strings, complete whitespace-preserving stdout and redacted subprocess/presentation spills, text-only output export success/failure notices, nonzero failure and strict malformed JSON; the `real native explicit text` case in `test/agent-browser.real-upstream-contract.test.ts` proves native URL reads, both diff orders, row boolean operands and last-wins outer selection. The same native case protects empty stdin-row skipping, later successful rows, Unicode results, bail behavior and original row positions in text errors; malformed shapes still fail before dispatch. Failed-exit stderr remains diagnostic evidence while zero-exit malformed JSON remains strict, covered by the registered `failed-json`/`strict-json` cases. Signal-only exits never become zero: process tests cover signal/timeout precedence, and registered killed-CLI tests cover empty stdout/stderr, launcher exit 137, retained signal/exit details, a possible-OOM hint, upstream-error classification and secret-stderr redaction. These are real self-terminated subprocess fixtures, not an induced host OOM. Text contains no trusted row, confirmation, lifecycle, page-target or artifact receipts; use JSON for those fields. See [the output contract](TOOL_CONTRACT.md#wrapper-json).
104
106
 
105
107
  Browser evidence (RQ-0152) is covered by `test/agent-browser.browser-evidence.test.ts`, `test/agent-browser.read-confirmation-routing.test.ts`, `test/agent-browser.read-confirmation-capture-replay.test.ts`, `test/agent-browser.read-confirmation-capture-actions.test.ts`, `test/agent-browser.recording-receipts.test.ts` and `test/agent-browser.recording-recovery.test.ts`, alongside existing presentation, reservation/replay and lifecycle checks. They cover cold/shared/unknown/invalid/timeout reads, native-default and shared confirmation routing, capability absence and script identity boundaries, separate daemon/browser/Pi identity, sparse/legacy capture metrics, native failure retention, stale/same-path mismatches, one-query stop recovery, error exports and artifact aliases. Full live identity, receipt lookup and browser-independent native read/confirm handling require companion upstream fixes; missing fields remain unknown, and native receipts do not survive daemon exit. These source checks do not replace paired native/Pi runtime verification.
106
108
 
@@ -110,13 +112,13 @@ Electron diagnostics (RQ-0096, #128) keep list timeout rejection truthful, label
110
112
 
111
113
  Artifact diagnostics (#124/#127) use a shared pre-dispatch mkdir-error boundary, preserve raw batch argv/precedence, recommend absolute raw artifact paths, recognize image headers rather than filename MIME guesses, retain known requested/reported paths, and warn once about conservative ref invalidation after dispatched recording starts and URL-bearing restarts, on success or failure, without claiming an observed page change. `test/agent-browser.artifact-diagnostics.test.ts` covers registered filesystem failures, real image bytes and misleading suffixes, the inline bound, native macOS path aliases, recording/ref continuity and unreached-row negatives; `test/agent-browser.presentation-artifacts-batch.test.ts` retains artifact/persistence coverage. These source regressions do not qualify daemon-cwd differences or affected-filesystem timestamp behavior (#118), or replace native/Pi/package/live-site gates.
112
114
 
113
- Upstream 0.38.1 observation and input compatibility is covered by `test/agent-browser.upstream-038.test.ts` and the real-upstream `matches 0.38 observation and recording options` case: full/unchanged snapshots, persistent refs, direct/batched partial snapshot follow-ups, conditional screenshots without invented files, session pointer settings, timed mouse movement, and real cursor/contact-sheet recording, including companion-path collisions and reservation replay. Call-local WebMCP metadata collection preserves helper-only discovery updates without leaking between concurrent sessions or later calls. Native owns delta baselines, auth origin checks, input interpolation, and image comparisons; the wrapper adds no emulation. The 0.35.0 runtime floor is unchanged.
115
+ Upstream 0.38+ observation and input compatibility is covered by `test/agent-browser.upstream-038.test.ts` and the real-upstream `matches 0.38 observation and recording options` case: full/unchanged snapshots, persistent refs, direct/batched partial snapshot follow-ups, conditional screenshots without invented files, session pointer settings, timed mouse movement, and real cursor/contact-sheet recording, including companion-path collisions and reservation replay. Call-local WebMCP metadata collection preserves helper-only discovery updates without leaking between concurrent sessions or later calls. Native owns delta baselines, auth origin checks, input interpolation, and image comparisons; the wrapper adds no emulation. The 0.35.0 runtime floor is unchanged.
114
116
 
115
117
  Upstream 0.37 recording compatibility uses one command-local path/URL reader around numeric `--fps` pairs; direct, raw-batch and stdin-batch preflight reject destination collisions before native dispatch. FPS-only calls keep the intended pinned tab, and FPS-only restarts keep refs. Every dispatched start still requires fresh refs to protect older supported natives. `test/agent-browser.artifact-diagnostics.test.ts`, `test/agent-browser.batch-fidelity.test.ts` and presentation tests cover these boundaries. The native contract also checks positive/absent WebMCP hints and first-load header inheritance/clearing without custom tab setup. Short/cold native Ubuntu captures can fail to encode; the FPS fixture explicitly logs 12-second captures and verifies output rather than treating an empty file as a frame.
116
118
 
117
- Artifact argv and timeout recovery (#119, RQ-0076) use native operand positions, retain literal global-looking tokens inside batch rows, and select raw batch commands instead of ignored stdin. Timeout observations retain current page and artifact existence evidence while all unacknowledged planned rows stay unknown; neither a matching URL nor an existing file proves execution. Independent artifact paths overlap their own three-check, 25 ms retry windows, preserve native row and JSON field order, and settle before page probes; late files may remain missing after their own window. Multi-step timeouts offer inspection without inferring a failed/pending boundary. Executable retry candidates for a single retryable step preserve the original row in a one-row batch. Interleaved `wait --download` / `-d` timeout pairs keep the next retained path and its original index. Runtime, artifact-diagnostics, and timeout tests cover extraction, reservation, preparation, and presentation; `test/agent-browser.batch-fidelity.test.ts` adds real native saved-file, missing wait-download, reservation, and watchdog evidence under `npm run verify -- real-upstream`. Getter batching amortizes one extra ref-freshness snapshot per top-level call or batch when the existing checks apply. Direct `session info` timeouts stay status-only (`retry-session-info`), preserving page/ref/reopen state; cold-boundary and result tests cover this.
119
+ Artifact argv and timeout recovery (#119, RQ-0076) use native operand positions, retain literal global-looking tokens inside batch rows, and select raw batch commands instead of ignored stdin. Timeout observations retain current page and artifact existence evidence while all unacknowledged planned rows stay unknown; neither a matching URL nor an existing file proves execution. Independent artifact paths overlap their own three-check, 25 ms retry windows, preserve native row and JSON field order, and settle before page probes; late files may remain missing after their own window. Multi-step timeouts offer inspection without inferring a failed/pending boundary. Executable retry candidates for a single retryable step preserve the original row in a one-row batch. Interleaved `wait --download` / `-d` timeout pairs keep the next retained path and its original index. Runtime, artifact-diagnostics, and timeout tests cover extraction, reservation, preparation, and presentation; `test/agent-browser.batch-fidelity.test.ts` adds real native saved-file, completed wait-download (saved bytes on 0.39.4+, fail-closed `artifact-missing` on supported 0.35.0–0.39.3), reservation, and watchdog evidence under `npm run verify -- real-upstream`. Getter batching amortizes one extra ref-freshness snapshot per top-level call or batch when the existing checks apply. Direct `session info` timeouts stay status-only (`retry-session-info`), preserving page/ref/reopen state; cold-boundary and result tests cover this.
118
120
 
119
- Cold URL reopen is covered by `test/agent-browser.cold-resume.test.ts`, the daemon/page-boundary regressions in `test/agent-browser.cold-boundaries-session-policy.test.ts`, `test/agent-browser.cold-boundaries-page-reopen.test.ts` and `test/agent-browser.cold-boundaries-command-classification.test.ts`, and the opt-in `contract suite matches cold URL reopen after quit` case in `test/agent-browser.real-upstream-contract.test.ts`. Deterministic boundary tests cover non-page prefixes, fragment routes, history commands, explicit destinations, transcript replay, unreached navigation and unchanged native batch/error order. `test/agent-browser.destination-cancel.test.ts` covers direct/native-batch new-window and URL-diff follow-ups, redirected/unknown targets (including blank redirects with a remembered duplicate tab), ordered ref invalidation, reached versus unreached rows, and cancellation before or after a cold-reopen attempt with replay and process cleanup. Release acceptance requires the first page operation after confirmed shutdown to observe the remembered non-root URL with both empty and origin storage, including after non-page calls and on hash-routed pages, before any explicit open, with refreshed refs. Focused native Mac evidence does not replace actual Ubuntu, real Pi lifecycle, checkout, live-site, or final release gates.
121
+ Cold URL reopen is covered by `test/agent-browser.cold-resume.test.ts`, the daemon/page-boundary regressions in `test/agent-browser.cold-boundaries-session-policy.test.ts`, `test/agent-browser.cold-boundaries-page-reopen.test.ts` and `test/agent-browser.cold-boundaries-command-classification.test.ts`, and the opt-in `contract suite matches cold URL reopen after quit` case in `test/agent-browser.real-upstream-contract.test.ts`. Deterministic boundary tests cover non-page prefixes, fragment routes, history commands, explicit destinations, transcript replay, unreached navigation and unchanged native batch/error order. Flagged cold caller-owned cases require the requested launch to precede remembered-tab/page helpers while warm and flagless calls retain their checks; the native HTTPS lifecycle case also covers an actual transcript reload after fixture-only daemon shutdown and verifies the submitted form through an immediate ordinary follow-up, without reusing the stopped browser's physical tab identity. Cold-launch output retirement retains ref invalidation and unknown-target recovery. `test/agent-browser.destination-cancel.test.ts` covers direct/native-batch new-window and URL-diff follow-ups, redirected/unknown targets (including blank redirects with a remembered duplicate tab), ordered ref invalidation, reached versus unreached rows, and cancellation before or after a cold-reopen attempt with replay and process cleanup. Release acceptance requires the first page operation after confirmed shutdown to observe the remembered non-root URL with both empty and origin storage, including after non-page calls and on hash-routed pages, before any explicit open, with refreshed refs. Focused native Mac evidence does not replace actual Ubuntu, real Pi lifecycle, checkout, live-site, or final release gates.
120
122
 
121
123
  Batch/ref fidelity (#122/#123/#125/#126): tab recovery uses verified native selection under existing session serialization without reconstructing argv/stdin or changing caller batch control flow. Selector-only stale-ref checks cover `@eN`, `eN`, and `ref=eN`; literal operands and keyboard/mouse data remain native. `test/agent-browser.batch-fidelity.test.ts` runs paired pinned/unpinned real-upstream fixtures, including mixed failures, header/timeout flags, ignored stdin, current/stale refs, failed/wrong-target selection, sessionless commands, and explicit connection/state recovery with failed-batch negatives. It runs in `npm run verify -- real-upstream`; deterministic selector/shape checks also run in the default suite.
122
124
 
@@ -132,13 +134,13 @@ Browser correctness regressions cover credential-bearing filtered network detail
132
134
 
133
135
  ## Current 0.6.16 rollout
134
136
 
135
- On 2026-09-21 the owner explicitly instructed **“waive windows”** for this rollout, superseding older required-Windows/no-waiver guidance even where runners are available. Windows diagnostics remain visible but nonblocking; do not interpret a successful compatibility aggregate as a Windows pass. Follow-up: [#191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191).
137
+ On 2026-09-21 the owner explicitly instructed **“waive windows”** for that rollout, superseding older required-Windows/no-waiver guidance even where runners were available. Those diagnostics were nonblocking, not a Windows pass. The later [#191](https://github.com/fitchmultz/pi-agent-browser-native/issues/191) / PR291 automation restoration made official/fork Windows blocking at that time. On 2026-10-22 the owner decided **“Make native Windows explicitly a best effort.”** That current support policy supersedes restoration’s blocking requirement, not its failure evidence; the September waiver is historical, not current authority. Historical failures below remain unresolved observations unless a later native result demonstrates otherwise; a configuration change is not runtime qualification.
136
138
 
137
139
  At runtime source `3a9adf490883149e7f79ee070d1900877e17b891`, PR compatibility passed seven of eight lanes, including official Windows with its full consumer contract; fork Windows failed one restored Electron cleanup case. The private combined Windows run had two policy-lock failures (1,162 passed, 37 skipped, zero cancelled out of 1,201). One unchanged Electron repeat passed without a product patch; the original cause is unknown. Historical focused Windows passes below retain only their stated scope, not full Windows qualification.
138
140
 
139
141
  Fresh precommit evidence for that runtime passed real Pi checkout/live-site and supported disposable Electron smoke, configured-source lifecycle, packaged runtime-only SDK/CLI loading, real-upstream checks, native macOS and the canonical named Ubuntu target (Debian 12). Local macOS is the documented alternate, not an SSH pass. Docs/workflow-only delivery may reuse this runtime evidence only after all 104 rebuilt runtime files match the checked artifact; changed published docs require a newly checked retained tarball. No additional paid/live gate is implied by an otherwise byte-identical runtime.
140
142
 
141
- Linux/macOS, declared Node floors, official/fork host identities, required consumer artifacts and Native lifecycle Linux remain required. Routine GitHub Actions is enabled for PRs to `main` and manual dispatch; its focused results do not substitute for the release and platform gates. Retain all three final reviewer approvals before merge/release/activation. The unchanged composed `release`/`prepublishOnly` command still includes Windows and is not reported as passed under this waiver; see [release guidance](RELEASE.md#current-0616-rollout-waiver).
143
+ Linux/macOS, declared Node floors, official/fork host identities, required consumer artifacts and Native lifecycle Linux remain required. Routine GitHub Actions is enabled for PRs to `main` and manual dispatch; its focused results do not substitute for the release and platform gates. Retain all three final reviewer approvals before merge/release/activation. The current composed `release`/`prepublishOnly` and default platform doctor/run require macOS/Ubuntu only; explicit Windows still fails honestly when its selected setup or suites fail. The former Windows-inclusive composition was not reported as passed under the historical waiver; see [release guidance](RELEASE.md#current-0616-rollout-waiver).
142
144
 
143
145
  ## Verification evidence
144
146
 
@@ -162,8 +164,8 @@ Re-run the gates below before each release. Dated outcomes in this table are his
162
164
  | Deterministic dogfood smoke | `npm run verify -- dogfood` clean-builds, then `scripts/verify-agent-browser-dogfood.ts` drives the native wrapper against a loopback HTTP fixture through persistent code aggregation, advanced QA/actions, native batch, screenshot artifact verification, and session close with the real `agent-browser` on `PATH`. | **Earlier 0.36.0 / package 0.6.2 / Pi 0.84.4:** pass on 2026-09-01; QA, script branching/cleanup, fresh/current opens, semantic clicks, job screenshot verification, and close all passed. |
163
165
  | WebGPU and restore autosave | Live 0.31.2 feature probes validate the new upstream paths independently from ordinary browser dogfood. | **macOS:** `doctor --webgpu` passed Apple Metal render/readback and headless red-pixel screenshot checks; the official Hello Triangle sample exposed the Metal adapter and produced a verified non-black screenshot. **Ubuntu image:** `doctor --webgpu --headed --json` passed SwiftShader render/readback and red-pixel screenshot checks with the baked Vulkan/Mesa/Xvfb dependencies. **Restore autosave:** an idle headless page timer changed localStorage and the namespaced restore file contained the new value before close; test state was removed. Wrapper-owned headed launches default periodic autosave off to avoid upstream 0.33.2 visible temporary collector tabs; native close still saves, direct window close can lose newer state because headed browsers are exempt from idle shutdown, and explicit `AGENT_BROWSER_AUTOSAVE_INTERVAL_MS` opts in at daemon launch; its effective value persists across resume, and changing a running wrapper-owned headed daemon in either direction requires close plus a fresh launch. On 2026-08-06, a headed checkout dogfood run crossed `react.dev` → `example.com` → `react.dev`, idled past the autosave interval while recording, showed no temporary page switch in frame/contact-sheet review, and closed both sessions successfully; disposable evidence was removed. **Windows interactive desktop:** post-release validation on 2026-07-15 used a disposable clone of snapshot `57cc3c0d-7d7c-4a4c-9c57-8270d4174679`, a logged-in console session, `agent-browser 0.31.2`, and Edge 150. The headed doctor WebGPU render/readback subcheck passed in 0.99s and its decoded screenshot subcheck passed with `rgb(255,0,0)`; a separate `--webgpu --headed` launch opened the proof page and the Parallels console capture visibly recorded the red triangle (553,500 bright-red pixels; SHA-256 `f5a28f5336cbdfeb0ff557af9425458bddc6b266d3cc6b946de7b101a0b43288`). The full doctor remained nonzero only for the unrelated absence of a separately installed Chrome binary; the explicit Edge executable completed the launch and both WebGPU probes. Local evidence is under `.artifacts/windows-webgpu-interactive/20260715T150903Z/summary.json`; the disposable clone and temporary account were deleted afterward. |
164
166
  | Android/Termux local bring-up | Non-release-blocking source validation uses Termux system Chromium through upstream's Linux `which chromium` discovery, the packaged Linux-musl arm64 CLI, real Pi managed-session smoke, deterministic dogfood, and the default unit/package gate. Electron desktop lifecycle is not applicable. | **Historical 0.6 local evidence (not 0.7 code qualification):** Android 17 / arm64 Termux passed implicit, explicit, and namespaced fresh sessions, managed restore, script, QA, semantic action, job, click, eval/batch stdin, screenshot attachment, recording dependencies, and cleanup; Android is not yet a Crabbox release target. |
165
- | Crabbox platform smoke | `npm run check:platform-smoke` syntax-checks the harness and cheap invariants. `npm run smoke:platform:ubuntu-image` builds the project-owned Linux image, `npm run smoke:platform:doctor` checks Crabbox 0.26.0+ and local target readiness, and `npm run smoke:platform:all` runs doctor first, then fast target-local `platform-build` (`npm run verify -- platform-target`, pack, clean Pi install) plus `browser-dogfood-smoke` on Crabbox `macos`, `ubuntu`, and `windows-native`; see [`platform-smoke.md`](platform-smoke.md). Target artifacts include Crabbox/provider/work-root metadata, and release review also checks provider-specific `crabbox list` commands for leftover leases/clones. | **Earlier 0.36.0 / package 0.6.2 / Pi 0.84.4:** Ubuntu `platform-build` and `browser-dogfood-smoke` passed with 11/11 assertions each on 2026-09-01, including complete artifact manifests and lease cleanup. Under explicit GitHub-only release waivers, macOS SSH and native Windows were not run because localhost SSH and `prlctl` were unavailable. |
166
- | `verify -- release` / `prepublishOnly` | `npm run verify -- release` chains the default gate with the configured-source lifecycle harness, packaged Pi smoke, and the release-blocking Crabbox platform matrix (`verifySteps` `release` in [`scripts/project.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/project.mjs)). `package.json` `prepublishOnly` runs that compose before `npm pack --dry-run` during `npm publish`. It intentionally omits standalone real-upstream and host-only dogfood modes—see [`RELEASE.md`](RELEASE.md#pre-release-checks). | **Package 0.6.2:** on 2026-09-01 the default, lifecycle, package-Pi, startup, real-upstream, deterministic dogfood, harness, Ubuntu image, and Ubuntu target gates passed individually. The canonical full composition was not reported as passed because macOS SSH and native Windows were explicitly waived after doctor confirmed localhost SSH and `prlctl` were unavailable. That historical release created GitHub artifacts only; it did not authorize npm publishing. |
167
+ | Crabbox platform smoke | `npm run check:platform-smoke` syntax-checks the harness and cheap invariants. `npm run smoke:platform:ubuntu-image` builds the project-owned Linux image, `npm run smoke:platform:doctor` checks Crabbox 0.26.0+ and local target readiness, and `npm run smoke:platform:all` runs doctor first, then fast target-local `platform-build` (`npm run verify -- platform-target`, pack, clean Pi install) plus `browser-dogfood-smoke` on required Crabbox `macos` and `ubuntu`; optional best-effort `windows-native` remains explicitly selectable and nonzero on failure; see [`platform-smoke.md`](platform-smoke.md). Target artifacts include Crabbox/provider/work-root metadata, and release review also checks provider-specific `crabbox list` commands for leftover leases/clones. | **Earlier 0.36.0 / package 0.6.2 / Pi 0.84.4:** Ubuntu `platform-build` and `browser-dogfood-smoke` passed with 11/11 assertions each on 2026-09-01, including complete artifact manifests and lease cleanup. Under explicit GitHub-only release waivers, macOS SSH and native Windows were not run because localhost SSH and `prlctl` were unavailable. |
168
+ | `verify -- release` / `prepublishOnly` | `npm run verify -- release` chains the default gate with the configured-source lifecycle harness, packaged Pi smoke, and the release-blocking Crabbox platform matrix (`verifySteps` `release` in [`scripts/project.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/project.mjs)). Lifecycle options after `release` (`--model`, `--timeout-ms`, `--verbose`, `--keep-artifacts`) reach only the lifecycle step. `package.json` `prepublishOnly` runs that compose before `npm pack --dry-run` during `npm publish`. It intentionally omits standalone real-upstream and host-only dogfood modes—see [`RELEASE.md`](RELEASE.md#pre-release-checks). | **Package 0.6.2:** on 2026-09-01 the default, lifecycle, package-Pi, startup, real-upstream, deterministic dogfood, harness, Ubuntu image, and Ubuntu target gates passed individually. The canonical full composition was not reported as passed because macOS SSH and native Windows were explicitly waived after doctor confirmed localhost SSH and `prlctl` were unavailable. That historical release created GitHub artifacts only; it did not authorize npm publishing. |
167
169
  | Configured-source lifecycle | `npm run verify -- lifecycle` (`scripts/verify-lifecycle.mjs`) drives `/reload`, closes and relaunches Pi with the same exact `--session-id`, checks the JSONL session header id, session continuity, slash-command sentinel tokens (`v1` before reload and `v2` after full relaunch), persisted spill reachability, and native returned failure status and JSON preservation for a QA reclassification with a fake upstream on `PATH`. Default Pi model is `zai/glm-5.2`; default per-step wait is **180000 ms** (`DEFAULT_TIMEOUT_MS`); override model with `--model <id>` and waits with `--timeout-ms <ms>`. Passthrough flags in [`scripts/project.mjs`](https://github.com/fitchmultz/pi-agent-browser-native/blob/main/scripts/project.mjs): `--keep-artifacts`, `--model`, `--verbose`, and `--timeout-ms` plus a value (for example `npm run verify -- lifecycle --model openai-codex/gpt-5.5:minimal --keep-artifacts --verbose --timeout-ms 600000`). | **Pi 0.84.4 on 2026-09-01:** pass; `/reload`, exact-session relaunch, managed continuity, persisted spill reachability, and Pi failure status all verified. |
168
170
  | Quick isolated Pi smoke | `pi --approve --no-extensions --no-skills -e .` from trusted repo root; checkout-native browser tools only. | **Earlier 0.36.0 / package 0.6.2 / Pi 0.84.4:** isolated checkout tmux smoke passed on 2026-09-01; native `agent_browser` completed version, localhost open, WebMCP list/invoke, visible-text verification, and close. |
169
171
 
@@ -171,14 +173,14 @@ Runtime floor note: package metadata requires Node 24.21.0 or newer, keeps optio
171
173
 
172
174
  ## Baseline checklist by inventory section
173
175
 
174
- | Baseline section | Baseline items | Documentation | Runtime handling | Test coverage | Validation status |
175
- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
176
- | Built-in skills | 19 canonical tokens from baseline section `skills`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#built-in-skills). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#built-in-skills), generated baseline block, README proof section, release docs. | `needsManagedSession` keeps read-only skills inspection sessionless while preserving thin upstream passthrough; upstream `@agent-browser/sandbox` remains external package guidance, not a bundled wrapper dependency. | Runtime and extension-validation skills/provider matrix; real-upstream inspection/skills group. | Supported. |
177
- | Core page, element, navigation, and extraction commands | Canonical tokens from baseline section `core-commands`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#core-page-and-element-commands). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#core-page-and-element-commands), [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md), README quick start. | Thin passthrough with wrapper-owned JSON/session planning, ref guidance, artifact verification, page-change summaries, click-dispatch diagnostics only after native temporary-marker target identity readback (otherwise abstaining), inspection-only recovery for upstream overlay-blocked clicks, deterministic document scroll before wheel/no-op diagnostics and instant CSS-container movement only for complete recognized shim shapes (surplus operands remain native), shorthand compilers, and redaction. | Real-upstream core matrix (including snapshot-ref select) plus fake core matrix for passthrough, ordering, diagnostics, and compiler validation. | Supported. Upstream semantics remain upstream-owned. |
178
- | Sessions, state, tabs, frames, dialogs, and windows | 28 canonical tokens from baseline section `state-tabs-frames-dialogs`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#session-state-frames-dialogs-windows-and-inspection-commands). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#session-state-frames-dialogs-windows-and-inspection-commands), stateful workflow notes, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). | Stateful summaries redact credentials while preserving restore identifiers, every session/state list row, and ordinary `cookies set --curl` file operands in invocation echoes and failed batch diagnostics; explicit targets and paths pass through. Runtime retains state artifact verification, sessionless local command planning, automatic managed restore, native-CDP-ID tab recovery across duplicate URLs and transcript replay, reached failed-batch target invalidation/live verification, active-target refresh after tab close, and close alias cleanup. | Extension tab/ref tests, real-upstream stable-id/label tab lifecycle, runtime session/resume tests, presentation redaction tests, lifecycle harness. | Supported. External profile/auth state remains operator-owned. |
179
- | Network, storage, artifacts, diagnostics, and performance | Canonical tokens from baseline section `network-storage-artifacts-diagnostics`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#page-state-finding-mouse-settings-network-and-storage). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#page-state-finding-mouse-settings-network-and-storage), diagnostic sections, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). | Thin passthrough plus native-owned click/download execution for all downloads (including loopback, Blob exports, and redirects), compact diagnostics with identical credential redaction for page/origin/URL-filtered details and exports, route-mock warnings, useful-but-redacted storage output, stream idempotency normalization, FPS/cursor/contact-sheet-aware recording destinations/pinning and contact-sheet image verification, truthful ref-refresh and missing-ffmpeg warnings, positive WebMCP navigation hints and catalog updates, sensitive-data redaction, timeout bounds, and cleanup-pair guidance. | Fake non-core matrix and safe real-upstream coverage for network/HAR, diff, trace/profiler, console/errors/highlight, stream, vitals, React missing-renderer, native FPS recording path/page checks and WebMCP navigation hints. | Supported. Environment-sensitive operations need suitable local/browser state. |
180
- | Batch, auth, confirmations, setup, dashboard, devices, and AI commands | Canonical tokens from baseline section `batch-auth-setup-ai`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#batch-auth-confirmations-sessions-chat-dashboard-devices-and-setup). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#batch-auth-confirmations-sessions-chat-dashboard-devices-and-setup), README security notes, release docs. | Native-tool batch stdin, generated QA/lookup batch plans, auth/confirmation redaction, sessionless local auth/setup/dashboard/doctor/plugin planning, upgrade-only native text normalization with error precedence and explicit-JSON results, plugin list/show JSON envelope normalization, bare-`mcp` validation with `mcp --help` preserved, timeout/cleanup guidance. | Parser/runtime plugin and MCP unit coverage; fake-upstream plugin list/show and MCP help/blocking coverage; registered upgrade text/success/nonzero/timeout/abort/JSON controls in `test/agent-browser.upgrade-output.test.ts`; real-upstream plugin list shape probe; structured input-mode tests. | Supported. Interactive side-effecting setup/auth/chat remains upstream-owned. `plugin` is local/sessionless; `mcp` is external-client-only except help; `auth login --credential-provider` resolves credentials via a plugin; `install --with-deps` failures remain upstream-owned. |
181
- | Global flags, config, providers, policy, and environment | Canonical tokens from baseline section `options-and-env`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#important-global-flags-config-and-environment). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#important-global-flags-config-and-environment), README provider/setup notes, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#sessionmode), architecture/runtime docs. | Runtime preserves caller-requested JSON for early filters, scroll results, and preparation failures without output-file prose (help/version remains native text), and handles command discovery, value-flag prevalidation, launch-scoped flags, redacted echoes, fresh-session recovery hints, explicit sessions, provider/device launch-scoping, parent env forwarding with consistent managed idle-timeout/socket/operation-timeout overrides and per-call explicit policy/confirmation context on top-level and helper subprocesses, subprocess completion, and package-owned Pi-scoped config for optional companion features. | Runtime tests for flags/planning/redaction/session behavior; process/ref tests for env consistency and stdio-linger completion; config/web-search/CLI tests; fake provider/specialized-skill matrix; package doctor. | Supported. Provider clouds, iOS/Appium, proxies, profiles, and credentials require external setup. |
176
+ | Baseline section | Baseline items | Documentation | Runtime handling | Test coverage | Validation status |
177
+ | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
178
+ | Built-in skills | 19 canonical tokens from baseline section `skills`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#built-in-skills). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#built-in-skills), generated baseline block, README proof section, release docs. | `needsManagedSession` keeps read-only skills inspection sessionless while preserving thin upstream passthrough; upstream `@agent-browser/sandbox` remains external package guidance, not a bundled wrapper dependency. | Runtime and extension-validation skills/provider matrix; real-upstream inspection/skills group. | Supported. |
179
+ | Core page, element, navigation, and extraction commands | Canonical tokens from baseline section `core-commands`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#core-page-and-element-commands). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#core-page-and-element-commands), [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md), README quick start. | Thin passthrough with wrapper-owned JSON/session planning, ref guidance, artifact verification, page-change summaries, click-dispatch diagnostics only after native temporary-marker target identity readback (otherwise abstaining), inspection-only recovery for upstream overlay-blocked clicks, deterministic document scroll before wheel/no-op diagnostics and instant CSS-container movement only for complete recognized shim shapes (surplus operands remain native), shorthand compilers, and redaction. | Real-upstream core matrix (including snapshot-ref select) plus fake core matrix for passthrough, ordering, diagnostics, and compiler validation. | Supported. Upstream semantics remain upstream-owned. |
180
+ | Sessions, state, tabs, frames, dialogs, and windows | 30 canonical tokens from baseline section `state-tabs-frames-dialogs`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#session-state-frames-dialogs-windows-and-inspection-commands). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#session-state-frames-dialogs-windows-and-inspection-commands), stateful workflow notes, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). | Stateful summaries redact credentials while preserving restore identifiers, every session/state list row, and ordinary `cookies set --curl` file operands in invocation echoes and failed batch diagnostics; explicit targets and paths pass through. Runtime retains state artifact verification, sessionless local command planning, automatic managed restore, native-CDP-ID tab recovery across duplicate URLs and transcript replay, reached failed-batch target invalidation/live verification, active-target refresh after tab close, and close alias cleanup. | Extension tab/ref tests, real-upstream stable-id/label tab lifecycle, runtime session/resume tests, presentation redaction tests, lifecycle harness. | Supported. External profile/auth state remains operator-owned. |
181
+ | Network, storage, artifacts, diagnostics, and performance | Canonical tokens from baseline section `network-storage-artifacts-diagnostics`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#page-state-finding-mouse-settings-network-and-storage). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#page-state-finding-mouse-settings-network-and-storage), diagnostic sections, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#details). | Thin passthrough plus native-owned click/download execution for all downloads (including loopback, Blob exports, and redirects), compact diagnostics with identical credential redaction for page/origin/URL-filtered details and exports, route-mock warnings, useful-but-redacted storage output, stream idempotency normalization, FPS/cursor/contact-sheet-aware recording destinations/pinning and contact-sheet image verification, truthful ref-refresh and missing-ffmpeg warnings, positive WebMCP navigation hints and catalog updates, sensitive-data redaction, timeout bounds, and cleanup-pair guidance. | Fake non-core matrix and safe real-upstream coverage for network/HAR, diff, trace/profiler, console/errors/highlight, stream, vitals, React missing-renderer, native FPS recording path/page checks and WebMCP navigation hints. | Supported. Environment-sensitive operations need suitable local/browser state. |
182
+ | Batch, auth, confirmations, setup, dashboard, devices, and AI commands | Canonical tokens from baseline section `batch-auth-setup-ai`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#batch-auth-confirmations-sessions-chat-dashboard-devices-and-setup). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#batch-auth-confirmations-sessions-chat-dashboard-devices-and-setup), README security notes, release docs. | Native-tool batch stdin, generated QA/lookup batch plans, auth/confirmation redaction, sessionless local auth/setup/dashboard/doctor/plugin planning, upgrade-only native text normalization with error precedence and explicit-JSON results, plugin list/show JSON envelope normalization, `mcp --help` passthrough with existing rejection of every non-help MCP invocation, timeout/cleanup guidance. | Parser/runtime plugin and MCP unit coverage; fake-upstream plugin list/show and MCP help/blocking coverage; registered upgrade text/success/nonzero/timeout/abort/JSON controls in `test/agent-browser.upgrade-output.test.ts`; real-upstream plugin list shape probe; structured input-mode tests. | Supported except non-help MCP. Interactive side-effecting setup/auth/chat remains upstream-owned. `plugin` is local/sessionless; non-help `mcp` is not integrated in this wrapper (see [MCP boundary](TOOL_CONTRACT.md#native-mcp-boundary)); `auth login --credential-provider` resolves credentials via a plugin; `install --with-deps` failures remain upstream-owned. |
183
+ | Global flags, config, providers, policy, and environment | Canonical tokens from baseline section `options-and-env`; see [`scripts/agent-browser-capability-baseline.mjs`](../scripts/agent-browser-capability-baseline.mjs) and generated [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#important-global-flags-config-and-environment). | [`COMMAND_REFERENCE.md`](COMMAND_REFERENCE.md#important-global-flags-config-and-environment), README provider/setup notes, [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md#sessionmode), architecture/runtime docs. | Runtime preserves caller-requested JSON for early filters, scroll results, and preparation failures without output-file prose (help/version remains native text), and handles command discovery, value-flag prevalidation, launch-scoped flags, redacted echoes, fresh-session recovery hints, explicit sessions, provider/device launch-scoping, parent env forwarding with consistent managed idle-timeout/socket/operation-timeout overrides and per-call explicit policy/confirmation context on top-level and helper subprocesses, subprocess completion, and package-owned Pi-scoped config for optional companion features. | Runtime tests for flags/planning/redaction/session behavior; process/ref tests for env consistency and stdio-linger completion; config/web-search/CLI tests; fake provider/specialized-skill matrix; package doctor. | Supported. Provider clouds, iOS/Appium, proxies, profiles, and credentials require external setup. |
182
184
 
183
185
  ## Follow-up decision after closure
184
186