pi-agent-browser-native 0.2.12 → 0.2.14

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## Unreleased
 
+## 0.2.14 - 2026-05-01
+
+### Changed
+- updated the local pi development baseline to `@mariozechner/pi-coding-agent` `0.71.1`
+- regenerated the npm lockfile against the current stable dependency graph
+
+### Compatibility
+- reviewed the pi `0.71.1` changelog and confirmed the extension is compatible with the current TypeBox 1.x package guidance, session-replacement safety rules, and latest package install/update behavior
+
+
+## 0.2.13 - 2026-04-30
+
+### Fixed
+- improved model-facing redaction across generic output, scalar extraction summaries, diagnostics, console/error previews, and compacted spill files so nested, multiline, and prefixed structured secrets are masked before entering tool content or summaries
+- adapted upstream `agent-browser skills get` output for Pi's native `agent_browser` tool by removing bash-oriented allowlist hints and translating quoted and heredoc CLI examples into native tool-call examples
+- reduced artifact-retention noise for routine explicit saved files while preserving retention metadata in details, and fixed explicit artifact manifest deduplication for same relative paths in different working directories
+
+### Changed
+- documented that oversized spill files contain redacted upstream payloads rather than raw secret-bearing output
+- added command-reference guidance for converting upstream standalone CLI examples into native `agent_browser` tool calls
+
 ## 0.2.12 - 2026-04-23
 
 ### Changed

package/README.md

@@ -55,12 +55,34 @@ Install `agent-browser` separately, then install this package into `pi`:
 pi install npm:pi-agent-browser-native
 ```
 
-To try a published package without installing it permanently:
+To try a published package without installing it permanently, isolate that temporary package source from any configured checkout or global install:
 
 ```bash
-pi -e npm:pi-agent-browser-native
+pi --no-extensions -e npm:pi-agent-browser-native
 ```
 
+For a specific published version:
+
+```bash
+pi --no-extensions -e npm:pi-agent-browser-native@<version>
+```
+
+### First-run doctor
+
+Run the package doctor before first use or when `agent_browser` is missing or duplicated:
+
+```bash
+pi-agent-browser-doctor
+# one-off without installing the package source permanently:
+npm exec --package pi-agent-browser-native -- pi-agent-browser-doctor
+# from a checkout:
+npm run doctor
+```
+
+The doctor is read-only. It checks that upstream `agent-browser` is on `PATH`, that `agent-browser --version` matches the wrapper's capability baseline, and that Pi settings do not point at multiple active `pi-agent-browser-native` sources. It does not run upstream `agent-browser doctor --fix` or edit Pi settings.
+
+If it reports duplicate sources, keep exactly one active source. For normal use, keep `pi install npm:pi-agent-browser-native` and remove checkout paths from Pi settings. For temporary package or checkout trials, use `pi --no-extensions -e npm:pi-agent-browser-native[@<version>]` or `pi --no-extensions -e /path/to/checkout` so configured sources are bypassed.
+
 ### GitHub install
 
 For the source install path, prefer the repository URL:
@@ -77,31 +99,35 @@ pi --no-extensions -e https://github.com/fitchmultz/pi-agent-browser-native
 
 This avoids duplicate `agent_browser` registrations when you already have `pi-agent-browser-native` installed globally.
 
-### Current practical local-checkout flow
+### Current practical local-checkout flows
 
-Until you are using a published package release, prefer an explicit checkout-only run instead of installing the checkout into your normal `pi` package set:
+This repository's `package.json` is itself a publishable pi package manifest that points at `extensions/agent-browser/index.ts`. That file is the real extension entrypoint for both the checkout and the published package.
 
-```bash
-pi --no-extensions -e /absolute/path/to/pi-agent-browser-native
-```
+Use two local-checkout modes intentionally:
+
+- **Quick isolated smoke test:** run the checkout explicitly with `-e` and disable extension discovery:
+
+  ```bash
+  pi --no-extensions -e /absolute/path/to/pi-agent-browser-native
+  ```
 
-This keeps the checkout isolated from any other active package source for the same extension.
+  This bypasses Pi settings and any configured checkout/global package sources, so it avoids duplicate `agent_browser` registrations. After editing extension code, restart this `pi` process to validate the new source; do not use this mode as proof that configured-source `/reload` works.
 
-This repository's `package.json` is itself a publishable pi package manifest that points at `extensions/agent-browser/index.ts`. That file is the real extension entrypoint for both the checkout and the published package. Keep exactly one active source for this extension in Pi settings at a time: either this checkout path or the published npm package.
+- **Configured-source lifecycle validation:** run `npm run verify -- lifecycle` for the opt-in automated tmux harness, or keep exactly one active source for this extension in Pi settings and launch plain `pi` for manual checks. Use this mode when validating `/reload`, full restart, and `/resume` behavior because Pi's reload flow operates on discovered/configured resources.
 
 The native tool exposed to the agent is named `agent_browser`.
 
 The primary session control parameter is `sessionMode`:
 
 - `"auto"` (default) reuses the extension-managed `pi`-scoped session when possible
-- `"fresh"` switches that managed session to a fresh upstream launch so startup-scoped flags like `--profile`, `--session-name`, and `--cdp` apply and later auto calls follow the new browser
+- `"fresh"` switches that managed session to a fresh upstream launch so launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, and `--auto-connect` apply and later auto calls follow the new browser
 
 ## Agent quick start
 
 ### Mental model
 
 - `args` — exact CLI args after `agent-browser`
-- `stdin` — raw stdin only for `batch` and `eval --stdin`
+- `stdin` — raw stdin only for `batch` and `eval --stdin` (other command/stdin combinations are rejected before `agent-browser` is launched)
 - `sessionMode`
   - `"auto"` — default, reuse the extension-managed `pi`-scoped session
   - `"fresh"` — switch that managed session to a new profile/debug launch
@@ -134,12 +160,25 @@ Evaluate page JavaScript via stdin:
 { "args": ["eval", "--stdin"], "stdin": "document.title" }
 ```
 
-Download a file to an explicit path instead of relying on `click` alone:
+Download a file from a known link/control directly:
 
 ```json
 { "args": ["download", "@e5", "/tmp/report.pdf"] }
 ```
 
+For dashboards that start an export asynchronously after a click or navigation, click first and then wait for the download. The wrapper reports `Download completed: /tmp/report.csv` and exposes upstream-reported `details.savedFilePath` plus `details.savedFile` for the `wait` result; with upstream `agent-browser 0.26.0`, confirm `details.artifacts[].exists` before relying on a requested `wait --download <path>` file being present on disk (tracked upstream at [vercel-labs/agent-browser#1300](https://github.com/vercel-labs/agent-browser/issues/1300)):
+
+```json
+{ "args": ["click", "@export"] }
+{ "args": ["wait", "--download", "/tmp/report.csv"] }
+```
+
+Batch flows preserve the same saved-file metadata on the wait step:
+
+```json
+{ "args": ["batch"], "stdin": "[[\"click\",\"@export\"],[\"wait\",\"--download\",\"/tmp/report.csv\"]]" }
+```
+
 Start a fresh profiled launch after you already used the implicit session:
 
 ```json
@@ -164,19 +203,19 @@ Use the agent_browser tool to open https://react.dev and then take an interactiv
 
 Do not track or rely on a repo-local `.pi/extensions/agent-browser.ts` autoload shim for this package. That creates an unnecessary second registration path.
 
-The published entrypoint lives at `extensions/agent-browser/index.ts` and is referenced directly from this repo's `package.json`. While developing this repo, keep the checkout path enabled in Pi settings and disable or uninstall `npm:pi-agent-browser-native` so Pi has only one active source for this extension.
+The published entrypoint lives at `extensions/agent-browser/index.ts` and is referenced directly from this repo's `package.json`.
 
 Recommended local development setup:
 1. Install `agent-browser` separately via the upstream project.
 2. Run `npm install`.
-3. Keep the checkout path enabled in Pi settings and disable or uninstall `npm:pi-agent-browser-native` while developing this repo.
-4. Launch `pi` from this repository root with only the checkout extension loaded:
+3. For a quick checkout-only smoke test, launch `pi` from this repository root with discovery disabled:
 
 ```bash
 pi --no-extensions -e .
 ```
 
-5. Prompt the agent to use `agent_browser`.
+4. Prompt the agent to use `agent_browser`.
+5. For hot-reload or resume validation, run `npm run verify -- lifecycle` or configure exactly one active source for this extension in Pi settings, launch plain `pi`, and exercise `/reload` plus restart/`/resume`. Settings matter only in this configured-source mode; they are bypassed by `--no-extensions -e .`. See [`docs/RELEASE.md`](docs/RELEASE.md) for the automated harness behavior, cleanup, and transcript retention details.
 
 Example prompt:
 
@@ -184,7 +223,14 @@ Example prompt:
 Use the agent_browser tool to open https://react.dev and then take an interactive snapshot.
 ```
 
-For installed-package validation after a release, temporarily do the reverse: disable/remove the checkout path from Pi settings and validate the published npm package, or use an isolated ephemeral run such as `pi --no-extensions -e npm:pi-agent-browser-native@<version>`.
+For installed-package validation after a release, use exactly one active source. The canonical isolated validation sequence is:
+
+```bash
+npm run verify -- package-pi
+pi --no-extensions -e npm:pi-agent-browser-native@<version>
+```
+
+Only use plain `pi` for installed-package validation after disabling or removing the checkout source from Pi settings.
 
 Validated workflow examples:
 
@@ -193,27 +239,41 @@ Validated workflow examples:
 - use an explicit `--session` across multiple tool calls
 - use an explicit `--profile` and verify persisted browser storage across restarts
 - open `chat.com` or `chatgpt.com` headlessly with `--profile Default` without forcing `--headed` or `--auto-connect`
-- verify `/reload` and full restart + `/resume` keep following the same implicit managed browser session
+- in configured-source lifecycle mode, verify `/reload` and full restart + `/resume` keep following the same implicit managed browser session
 - run `batch` with JSON via `stdin`
 - run `eval --stdin`
 - take a screenshot with inline attachment support
-- inspect `agent_browser --help` and `--version` via the tool's stateless plain-text inspection fallback
-- use `download <selector> <path>` for attachment/file-save workflows instead of trying to infer downloads from generic clicks or large eval dumps
+- inspect upstream help/version through native tool calls like `{ "args": ["--help"] }` and `{ "args": ["--version"] }` via the tool's stateless plain-text inspection fallback
+- use `download <selector> <path>` for direct attachment/file-save workflows instead of trying to infer downloads from generic clicks or large eval dumps
+- use `click` plus `wait --download <path>` for asynchronous export flows, confirm `details.savedFilePath`/`details.savedFile` are present on the wait result or batch wait step, and check `details.artifacts[].exists` before relying on requested-path persistence
 - confirm oversized outputs show the actual spill file path directly in tool content, not just a details key name
+- inspect `details.artifactManifest` / `details.artifactRetentionSummary` during artifact-heavy flows to recover recent saved files, spill files, and visible eviction state after reload/resume
+
+<!-- agent-browser-playbook:start inspection -->
+<!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
+Native inspection calls use the `agent_browser` tool shape, not shell-like direct-binary commands:
+
+- { "args": ["--help"] }
+- { "args": ["--version"] }
 
-Inspection commands like `agent_browser --help` and `--version` are always supported. They return plain text, are useful for debugging or capability checks, and stay stateless: the extension does not inject its implicit session for them and they do not consume the managed-session slot needed for a later `--profile`, `--session-name`, or `--cdp` launch.
+These calls return plain text and stay stateless: the extension does not inject its implicit session and does not let inspection consume the managed-session slot needed for later profile, session, CDP, state, or auto-connect launches.
+<!-- agent-browser-playbook:end inspection -->
 
 Current cautions:
 - passing `--profile` is an explicit upstream choice; this extension does not add its own profile-cloning or isolation layer
-- startup-scoped flags like `--profile`, `--session-name`, and `--cdp` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
-- implicit `piab-*` sessions are extension-managed convenience sessions; they stay alive across `pi` shutdown/reload so later default calls can keep following the active managed browser on `/reload` or `/resume`, rely on the configured idle timeout to reduce stale background daemons, store persisted-session large snapshot spill files under a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` survives reload/resume without unbounded growth, and still clean up process-private temp spill artifacts on shutdown
+- launch-scoped flags like `--profile`, `--session-name`, `--cdp`, `--state`, and `--auto-connect` are for the first command that launches a session; if the implicit session is already active, retry that call with `sessionMode: "fresh"` or provide an explicit `--session ...` for the new launch
+- implicit `piab-*` sessions are extension-managed convenience sessions; they stay alive across `pi` shutdown/reload so later default calls can keep following the active managed browser on `/reload` or `/resume`, rely on the configured idle timeout to reduce stale background daemons, store persisted-session large snapshot spill files under a private session-scoped artifact directory with a bounded per-session budget so `details.fullOutputPath` and metadata-only `details.artifactManifest` survive reload/resume without unbounded growth, and still clean up process-private temp spill artifacts on shutdown
 - `sessionMode: "fresh"` without an explicit `--session` rotates that extension-managed session to the new browser so later auto calls keep using it
 - for local Unix launches, the wrapper uses a short private socket directory under `/tmp` so extension-generated session names do not trip upstream Unix socket-path limits in longer cwd/session-name combinations
 - for direct headless local Chrome launches to `chat.com`, `chatgpt.com`, and `chat.openai.com`, the extension injects a normal Chrome user agent when the caller did not explicitly provide `--user-agent`; this keeps the default headless workflow usable without forcing `--headed` or `--auto-connect`
-- after profiled `open` calls, the extension best-effort re-selects the tab that matches the returned page URL when restored profile tabs steal focus during launch
-- after a target tab is known, later active-tab commands best-effort pin that same tab inside the same upstream invocation when a reconnect would otherwise drift to a restored tab
-- after a successful command, the extension also best-effort restores that intended tab when a restored/background tab steals focus after the command completes
-- oversized snapshots and oversized generic outputs compact inline content and print the actual spill file path directly in the tool result when a spill file exists
+<!-- agent-browser-playbook:start wrapper-tab-recovery -->
+<!-- Generated from extensions/agent-browser/lib/playbook.ts. Run `npm run docs -- playbook write` to update. -->
+- After launch-scoped open/goto/navigate calls that can restore existing tabs (for example --profile, --session-name, or --state), agent_browser best-effort re-selects the tab whose URL matches the returned page when restored tabs steal focus during launch.
+- After a target tab is known for a session, later active-tab commands best-effort pin that tab inside the same upstream invocation when reconnect drift would otherwise move the command to a restored/background tab.
+- After a successful command on a known target tab, agent_browser also best-effort restores that intended tab if a restored/background tab steals focus after the command completes.
+- If a known session target unexpectedly reports about:blank, agent_browser preserves the prior intended target, best-effort re-selects it when it still exists, and reports exact recovery guidance when it cannot be re-selected.
+<!-- agent-browser-playbook:end wrapper-tab-recovery -->
+- oversized snapshots and oversized generic outputs compact inline content and print the actual spill file path directly in the tool result when a spill file exists; recent spills and explicit saved artifacts are also summarized in `details.artifactManifest`, including `evicted` entries when retention budgets remove older persisted files
 - explicit caller-provided `--session` values are treated as user-managed and are not auto-closed by the extension
 - explicit caller-provided `--user-agent` values win over the ChatGPT/OpenAI compatibility workaround
 - tool progress/details redact sensitive invocation values such as `--headers`, proxy credentials, and auth-bearing URL parameters before echoing them back into Pi

package/docs/ARCHITECTURE.md

@@ -9,7 +9,7 @@ Related docs:
 
 Build this as a **thin `pi` extension/package** that exposes `agent-browser` as one native tool while keeping upstream `agent-browser` as the source of truth.
 
-The package install path is the primary product path. Local checkout development should use explicit CLI loading, while package-manifest behavior and packaged contents matter more.
+The package install path is the primary product path. Local checkout development should use explicit CLI loading for isolated smoke tests and configured-source plain `pi` runs for lifecycle validation, while package-manifest behavior and packaged contents matter more.
 
 ## Chosen shape
 
@@ -31,7 +31,7 @@ The extension should:
 - resolve `agent-browser` from `PATH`
 - invoke it directly, not through a shell
 - inject `--json`
-- support optional stdin for commands like `eval --stdin` and `batch`
+- support optional stdin only for `eval --stdin` and `batch`, rejecting other command/stdin combinations before launch
 
 ### Agent-first UX
 
@@ -46,11 +46,17 @@ That means:
 
 The published package should load from the `pi` manifest in `package.json`.
 
-Local checkout development should use explicit CLI loading such as `pi --no-extensions -e .` from the repository root instead of repo-local `.pi/extensions/` auto-discovery.
+Local checkout validation has two intentional modes:
+
+- **Quick isolated mode:** use explicit CLI loading such as `pi --no-extensions -e .` from the repository root. This bypasses Pi settings and extension discovery, avoids duplicate `agent_browser` registrations when another source is installed globally, and is the right mode for checkout smoke tests.
+- **Configured-source lifecycle mode:** configure exactly one active checkout or package source in Pi settings and launch plain `pi`. This is the right mode for validating `/reload`, restart, and `/resume` behavior because those lifecycle checks exercise discovered/configured resources.
+
+The repo should not add a repo-local `.pi/extensions/` autoload shim as the documented checkout path.
 
 Why:
 - avoids duplicate `agent_browser` registrations when the package is also installed globally
 - keeps the product contract centered on the package manifest instead of repo-local autoload wiring
+- keeps reload and resume validation tied to Pi's configured-source lifecycle instead of an isolated quick-test path
 - keeps the published tarball focused on the package manifest, extension code, canonical docs, and license
 
 The published package should exclude agent-only and superseded repo materials such as `AGENTS.md`, `docs/v1-tool-contract.md`, `docs/native-integration-design.md`, and other internal planning notes.