pi-agent-browser-native 0.1.6 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.2.1 - 2026-04-12
+
+### Fixed
+- the GitHub source trial docs now use `pi --no-extensions -e https://github.com/fitchmultz/pi-agent-browser-native` so published-package users do not hit duplicate `agent_browser` registration conflicts during source-path testing
+- successful unnamed `sessionMode: "fresh"` launches now rotate the extension-managed session to the new browser, and later default `sessionMode: "auto"` calls keep following that fresh session instead of silently snapping back to the older one
+- mixed-success `batch` failures now preserve per-step rendering, include the first failing step in the visible output and structured details, and still mark the overall tool call as an error so agents can recover from partial progress
+- implicit `piab-*` session names now include a stable cwd hash in addition to the `pi` session id so same-named checkouts and worktrees no longer collide onto the same browser session
+- value-taking flags like `--session`, `--profile`, `--session-name`, and `--cdp` now fail locally with direct validation errors when the value is missing or replaced by another flag, instead of producing confusing downstream JSON parse failures
+- the bash guard now catches wrapped `agent-browser` invocations such as `env agent-browser ...`, `npx --yes agent-browser ...`, `pnpm dlx agent-browser ...`, `yarn dlx agent-browser ...`, `bunx agent-browser ...`, and absolute-path execution, reducing accidental bypasses of the native-tool path
+
+## 0.2.0 - 2026-04-12
+
+### Changed
+- `batch` now reuses the richer standalone renderers, so batched snapshots keep the compact main-content-first view and batched screenshots keep inline image attachments instead of degrading to raw JSON-ish text
+- the tool schema now uses `sessionMode: "auto" | "fresh"` instead of the old implicit-session boolean so agents have a first-class way to request a fresh profiled/debug launch, and blocked startup-scoped reuse errors now include structured recovery hints
+- plain-text inspection commands like `agent_browser --help` and `--version` are now always allowed, removing the old prompt-dependent inspection gate and making the inspection contract local and predictable
+- navigation actions like `click`, `dblclick`, `back`, `forward`, and `reload` now include lightweight post-action title/url summaries when the wrapper can address the active session, reducing guess-and-check follow-up snapshots
+- compact snapshot rendering is leaner by default: fewer additional sections, fewer refs, smaller role summaries, and the raw spill path now stays in `details.fullOutputPath` instead of dominating the visible snapshot body
+- README and injected tool guidance now include a compact agent quick start with the core call shapes for `open` + `snapshot`, `click` + re-snapshot, `batch`, `eval --stdin`, and fresh profiled launches
+
+### Migration notes
+- replace any use of `useActiveSession` with `sessionMode`
+- use `sessionMode: "fresh"` when you need a new `--profile`, `--session-name`, or `--cdp` launch after the implicit session is already active
+
 ## 0.1.6 - 2026-04-12
 
 ### Changed

package/README.md

@@ -69,12 +69,14 @@ For the source install path, prefer the repository URL:
 pi install https://github.com/fitchmultz/pi-agent-browser-native
 ```
 
-To try the GitHub source without installing it permanently:
+To try the GitHub source without installing it permanently, isolate that temporary source extension from your normal installed package set:
 
 ```bash
-pi -e https://github.com/fitchmultz/pi-agent-browser-native
+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
 
 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:
@@ -87,6 +89,69 @@ This avoids duplicate `agent_browser` registrations if you also have the publish
 
 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
+
+## Agent quick start
+
+### Mental model
+
+- `args` — exact CLI args after `agent-browser`
+- `stdin` — raw stdin only for `batch` and `eval --stdin`
+- `sessionMode`
+  - `"auto"` — default, reuse the extension-managed `pi`-scoped session
+  - `"fresh"` — switch that managed session to a new profile/debug launch
+
+### Common call shapes
+
+Open a page, then take an interactive snapshot:
+
+```json
+{ "args": ["open", "https://example.com"] }
+{ "args": ["snapshot", "-i"] }
+```
+
+Click a ref, then re-snapshot after navigation or a major DOM change:
+
+```json
+{ "args": ["click", "@e2"] }
+{ "args": ["snapshot", "-i"] }
+```
+
+Run a multi-step browser flow in one tool call:
+
+```json
+{ "args": ["batch"], "stdin": "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }
+```
+
+Evaluate page JavaScript via stdin:
+
+```json
+{ "args": ["eval", "--stdin"], "stdin": "document.title" }
+```
+
+Start a fresh profiled launch after you already used the implicit session:
+
+```json
+{ "args": ["--profile", "Default", "open", "https://example.com/account"], "sessionMode": "fresh" }
+```
+
+After a successful unnamed fresh launch, later `sessionMode: "auto"` calls follow that new browser automatically.
+
+Name a new upstream session explicitly when you want to keep reusing it yourself:
+
+```json
+{ "args": ["--session", "auth-flow", "open", "https://example.com"] }
+```
+
+### First useful prompt in a fresh `pi` session
+
+```text
+Use the agent_browser tool to open https://react.dev and then take an interactive snapshot.
+```
+
 ## Local development
 
 Do not track or rely on a repo-local `.pi/extensions/agent-browser.ts` autoload shim for this package. When the package is also installed globally, that creates a duplicate `agent_browser` registration and blocks `pi` startup from this working directory.
@@ -116,13 +181,42 @@ Validated workflow examples:
 - run `batch` with JSON via `stdin`
 - run `eval --stdin`
 - take a screenshot with inline attachment support
-- inspect `agent_browser --help` and `--version`
+- inspect `agent_browser --help` and `--version` via the tool's plain-text inspection fallback
+
+Inspection commands like `agent_browser --help` and `--version` are always supported. They return plain text and are useful for debugging or capability checks, but they are not required for normal browsing workflows.
 
 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, the extension returns a validation error instead of silently letting upstream ignore those flags
+- 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 are best-effort closed on `pi` shutdown, get an idle timeout to reduce stale background daemons, and clean up private temp spill artifacts on shutdown
-- explicit upstream sessions like `--session`, `--profile`, `--session-name`, and `--cdp` are treated as user-managed and are not auto-closed by the extension
+- `sessionMode: "fresh"` without an explicit `--session` rotates that extension-managed session to the new browser so later auto calls keep using it
+- explicit caller-provided `--session` values are treated as user-managed and are not auto-closed by the extension
+
+### Switching from public browsing to a fresh profile/debug launch
+
+A common agent workflow is:
+
+1. browse a public page with the default implicit session
+2. then switch to a fresh authenticated/profile/debug launch
+
+Use `sessionMode: "fresh"` for that transition instead of relying on the implicit session:
+
+```json
+{
+  "args": ["--profile", "Default", "open", "https://example.com/account"],
+  "sessionMode": "fresh"
+}
+```
+
+After that call succeeds, later default `sessionMode: "auto"` calls continue in the new fresh browser.
+
+If you want to name the new upstream session yourself, pass an explicit session instead:
+
+```json
+{
+  "args": ["--session", "auth-flow", "--profile", "Default", "open", "https://example.com/account"]
+}
+```
 
 ## Docs
 

package/docs/ARCHITECTURE.md

@@ -59,29 +59,33 @@ The published package should exclude agent-only and superseded repo materials su
 
 ### Default
 
-If the caller does not provide `--session`, the extension should use an implicit session name derived from the current `pi` session id.
+If the caller does not provide `--session`, the extension should default to `sessionMode: "auto"` and use an implicit session name derived from the current `pi` session id plus a hash of the absolute cwd.
 
 Why:
 - works out of the box
 - gives continuity across calls
 - avoids forcing the agent to invent session names for basic browsing
 
-### Explicit upstream sessions
+### Explicit upstream sessions and fresh launches
 
 If the caller provides `--session`, `--profile`, `--cdp`, or similar upstream flags, the extension should respect them with minimal interference.
 
+The tool should also expose a first-class `sessionMode: "fresh"` escape hatch so agents can intentionally rotate the extension-managed session to a fresh upstream launch without inventing a fixed explicit session name.
+
 ### Ownership
 
 V1 ownership rule:
 - implicit auto-generated sessions are extension-managed convenience sessions
+- unnamed `sessionMode: "fresh"` launches rotate that extension-managed session to a new upstream browser
 - explicit/user-managed sessions are not auto-managed by default
-- implicit sessions should be reusable during an active `pi` session, but should still be cleaned up predictably
+- extension-managed sessions should be reusable during an active `pi` session, but should still be cleaned up predictably
 
 Practical policy:
-- on normal `pi` shutdown, best-effort close the implicit session
-- also set an idle timeout on implicit sessions so abandoned daemons self-clean after inactivity
-- clean up private temp spill artifacts owned by the implicit session on shutdown
-- leave explicit upstream sessions like `--session`, `--profile`, `--session-name`, and `--cdp` alone unless the caller closes them explicitly
+- on normal `pi` shutdown, best-effort close the current extension-managed session
+- also set an idle timeout on extension-managed sessions so abandoned daemons self-clean after inactivity
+- clean up private temp spill artifacts owned by the extension-managed session on shutdown
+- if an unnamed fresh launch replaces an active extension-managed session, best-effort close the old managed session after the switch succeeds
+- leave explicit caller-provided `--session` choices alone unless the caller closes them explicitly
 
 This is primarily about ownership clarity and avoiding surprise, not adding a heavy safety wrapper. If the extension invented the session, the extension should clean it up. If the caller explicitly chose the upstream session model, the extension should stay out of the way.
 
@@ -92,7 +96,11 @@ The extension should surface that clearly and avoid hidden restart behavior in v
 
 That means explicit startup-scoping flags like `--profile`, `--session-name`, and `--cdp` should remain explicit upstream choices instead of being wrapped in extra hidden restart or cloning logic.
 
-If the implicit session is already active and one of those startup-scoped flags appears again, the extension should fail clearly instead of silently sending a command shape that upstream would ignore.
+If the implicit session is already active and one of those startup-scoped flags appears again while `sessionMode` is still `"auto"`, the extension should fail clearly instead of silently sending a command shape that upstream would ignore.
+
+That failure should include a structured recovery hint pointing to `sessionMode: "fresh"` as the first-line fix, while still allowing an explicit `--session` when the caller wants to name the new upstream session.
+
+A successful unnamed `sessionMode: "fresh"` launch should become the new extension-managed session so later default calls follow that browser instead of silently snapping back to the older managed session.
 
 ## Preferring the native tool
 

package/docs/TOOL_CONTRACT.md

@@ -32,7 +32,7 @@ The tool also needs an operating playbook, not just a capability list. The model
 {
   "args": ["open", "https://example.com"],
   "stdin": "optional raw stdin content",
-  "useActiveSession": true
+  "sessionMode": "auto"
 }
 ```
 
@@ -69,15 +69,20 @@ Examples:
 { "args": ["batch"], "stdin": "[[\"open\",\"https://example.com\"],[\"snapshot\",\"-i\"]]" }
 ```
 
-### `useActiveSession`
+### `sessionMode`
 
-- type: `boolean`
+- type: `"auto" | "fresh"`
 - optional
-- default: `true`
+- default: `"auto"`
 
 Behavior:
 - if `args` already include `--session`, upstream session choice wins
-- otherwise the extension prepends its implicit active session when `useActiveSession` is `true`
+- `"auto"` prepends the current extension-managed active session when appropriate
+- `"fresh"` rotates that managed session to a fresh upstream launch so startup-scoped flags like `--profile`, `--session-name`, or `--cdp` apply and later default calls follow the new browser
+
+Recommended use:
+- use `"auto"` for the common browse/snapshot/click flow inside one `pi` session
+- use `"fresh"` when switching from an already-active implicit session to a new profile/debug/auth launch without inventing a fixed explicit session name
 
 ## Wrapper behavior
 
@@ -87,8 +92,8 @@ The extension should:
 - parse JSON output into tool details
 - handle observed JSON result shapes, including the array returned by `batch --json`
 - allow plain-text fallback for inspection commands like `--help` and `--version`
-- discourage exploratory inspection calls unless the user explicitly asks or debugging requires them
-- deflect normal-task `--help` inspection back into the standard browser workflow instead of letting the model relearn the tool from scratch each session
+- support those inspection commands unconditionally so the tool contract stays local and predictable
+- still describe normal browser workflows in guidance so models do not overuse inspection for routine tasks
 - surface stderr and non-zero exits clearly
 - attach images when the result points to a screenshot-like artifact
 
@@ -104,7 +109,8 @@ Primary content should be:
 
 Examples:
 - small `snapshot` results should include the actual snapshot text
-- oversized `snapshot` results should switch to a compact view that preserves the primary content, nearby sections, high-value refs, and a path to the spilled full raw snapshot
+- oversized `snapshot` results should switch to a compact view that preserves the primary content, nearby sections, and a trimmed set of high-value refs, while exposing the full raw snapshot path via `details.fullOutputPath`
+- successful navigation actions like `click`, `back`, `forward`, and `reload` should include a lightweight post-action title/url summary when the wrapper can address the active session
 - `tab list` should include a readable tab summary
 - `screenshot` should include the saved-path summary plus the inline image attachment when available
 
@@ -116,6 +122,7 @@ Recommended details:
 {
   "args": ["snapshot", "-i"],
   "effectiveArgs": ["--session", "pi-abc123", "--json", "snapshot", "-i"],
+  "sessionMode": "auto",
   "sessionName": "pi-abc123",
   "usedImplicitSession": true,
   "data": {
@@ -136,7 +143,8 @@ For oversized snapshots, details should switch to a compact metadata object and
 
 Worth doing in v1:
 - screenshots → inline image attachment
-- snapshots → origin + ref count + main-content-first compact preview, with full raw snapshot spill files when the inline result would otherwise be too large
+- snapshots → origin + ref count + main-content-first compact preview, with the raw snapshot spill path kept in `details.fullOutputPath` when the inline result would otherwise be too large
+- navigation actions like `click`, `back`, `forward`, and `reload` → lightweight post-action title/url summary when available
 - tab lists → compact summary/table
 - stream status → enabled/connected/port summary
 
@@ -149,16 +157,18 @@ If `agent-browser` is not on `PATH`, fail with a message that:
 
 ## Session behavior
 
-- maintain one implicit active session per `pi` session for the common path
-- derive that implicit session from the official `pi` session id
+- maintain one extension-managed active session per `pi` session for the common path
+- derive the base implicit session name from the official `pi` session id plus a cwd hash so same-named checkouts do not collide
 - respect explicit upstream `--session` with minimal interference
-- treat the implicit session as extension-managed convenience state
-- on normal `pi` shutdown, best-effort close the implicit session
-- set an idle timeout on implicit sessions so abandoned daemons eventually self-clean
-- clean up private temp spill artifacts owned by the implicit session on shutdown
-- treat explicit upstream session choices like `--session`, `--profile`, `--session-name`, and `--cdp` as user-managed
+- treat the extension-managed session as convenience state owned by the wrapper
+- on normal `pi` shutdown, best-effort close the current extension-managed session
+- set an idle timeout on extension-managed sessions so abandoned daemons eventually self-clean
+- clean up private temp spill artifacts owned by the extension-managed session on shutdown
+- when an unnamed `sessionMode: "fresh"` launch succeeds, make it the new extension-managed session so later default calls keep using it
+- if that unnamed fresh launch replaced an already-active managed session, best-effort close the old managed session after the switch succeeds
+- treat explicit caller-provided `--session` choices as user-managed
 - pass explicit `--profile` straight through to upstream `agent-browser`; no profile-cloning or isolation layer is added in v1
-- if startup-scoped flags like `--profile`, `--session-name`, or `--cdp` are supplied after the implicit session is already active, return a validation error instead of silently relying on upstream to ignore them
+- if startup-scoped flags like `--profile`, `--session-name`, or `--cdp` are supplied after the implicit session is already active while `sessionMode` is `"auto"`, return a validation error with a structured recovery hint that recommends `sessionMode: "fresh"`
 
 ## Non-goals