pi-agent-browser-native 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## 0.1.1 - 2026-04-11
+
+### Changed
+- startup-scoped flags like `--profile`, `--session-name`, and `--cdp` now fail clearly when reused against an already-active implicit session instead of silently relying on upstream to ignore them
+- prompt-based bash/help allowances are now derived from the current user prompt instead of mutable extension-global booleans, and the inspection allowance only triggers for tool-specific requests
+- oversized subprocess stdout is now bounded in memory and spilled to private temp files before JSON parsing, reducing unbounded buffering risk without breaking large snapshot handling
+- snapshot spill files now live under private temp directories with restrictive permissions and are cleaned up on shutdown
+- failed upstream envelopes now synthesize clearer fallback error text when no simple top-level `error` string is present
+- package/release verification now has a documented maintainer workflow, a tarball verifier script, a tracked repo-local `.pi` development shim, and a published tarball that excludes agent-only or superseded docs while including `LICENSE`
+- npm publish prep now uses the available package name `pi-agent-browser-native`, adds author and gallery-friendly keywords, and updates README install guidance to show npm first and GitHub second
+
+## 0.1.0 - 2026-04-09
+
+### Added
+- initial package scaffold for `pi-agent-browser`
+- native `agent_browser` extension tool that wraps upstream `agent-browser --json`
+- thin implicit-session support for the common path
+- lightweight extension-level guards to keep direct bash `agent-browser` usage from becoming the primary path
+- plain-text fallback for native `agent_browser --help` and `--version` inspection
+- support for observed `batch --json` array output
+- local TypeScript typecheck and unit-test setup
+- concise product and implementation docs
+
+### Changed
+- removed the shipped skill override; extension hooks are the primary mechanism for preferring the native tool
+- implicit `piab-*` sessions are now best-effort closed on `pi` shutdown and get an idle timeout so abandoned background daemons do not accumulate as easily
+- tightened tool guidance so agents avoid falling back to osascript or other generic browser-driving bash commands when the native tool should be used
+- taught the tool a clearer browser operating playbook so agents do not need to rediscover core `open` / `snapshot -i` / auth / tab-management patterns from `--help` on routine tasks
+- refined the authenticated-content playbook to prefer `--profile Default` on the first browser call while reusing the extension-managed implicit session for normal personal feeds/dashboards; this avoids stale cross-run browser state from fixed explicit session names
+- refined read-only browsing guidance so agents prefer extracting from the current snapshot, ref labels, or page-state eval before navigating away, and clarified that extraction evals should return values instead of relying on `console.log`
+- generalized recovery guidance so unexpected `open` failures now point agents to inspect and recover tab/session state before retrying alternate URLs or fallback strategies
+- improved native error presentation so upstream JSON error messages are shown to the agent instead of a generic `agent-browser exited with code 1.` when the CLI already reported a specific failure
+- oversized `snapshot -i` results now switch to a browser-aware compact view for the model and spill the full raw snapshot JSON to a temp file referenced from tool details instead of always inlining the full snapshot tree
+- refined compact snapshots to be main-content-first: prefer the primary content block and nearby sections over top-of-page chrome, ads, and unrelated sidebars when the snapshot structure makes that distinction possible

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitch Fultz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,139 @@
+# pi-agent-browser
+
+Native `pi` integration for [`agent-browser`](https://agent-browser.dev/).
+
+## Status
+
+Early working scaffold.
+
+The package scaffold, native `agent_browser` tool, local typecheck/test setup, tracked repo-local development entrypoint, and release/package verification workflow are in place.
+
+## Goal
+
+Expose `agent-browser` to `pi` as a native tool so agents can automate the browser without going through a bash-backed skill.
+
+## Product stance
+
+- **Not bundled**: users install `agent-browser` separately and keep it on `PATH`
+- **Latest-version only**: no backward-compatibility support or shims for older `agent-browser` versions
+- **Thin wrapper**: stay close to upstream `agent-browser` instead of re-implementing its CLI
+- **Agent-invoked first**: the main UX is the agent calling the tool directly, like `read` or `write`
+- **Global-install first**: package behavior matters more than repo-local development wiring
+
+Upstream install/docs:
+- https://agent-browser.dev/
+- https://github.com/vercel-labs/agent-browser
+
+## Why this exists
+
+A native `pi` integration can improve on the current skill by adding:
+
+- structured tool calls instead of shell strings
+- parsed results instead of bash stdout
+- compact model-facing snapshot shaping with full raw spill files for oversized pages
+- main-content-first snapshot previews so the model sees the important page region before unrelated chrome or sidebar noise
+- inline screenshots and artifacts
+- lightweight session convenience inside `pi`
+- a better base for serious browser automation
+
+## Example use cases
+
+- UI testing and exploratory QA
+- web research
+- driving web UIs for ChatGPT, Grok, Gemini, and Claude
+- authenticated browser sessions and persistent profiles
+
+## Install and try
+
+The product direction is package-first. Prefer the package source once a release exists, while keeping the local-checkout flow for current development and pre-release validation.
+
+### Preferred package install
+
+Install `agent-browser` separately, then install this package into `pi`:
+
+```bash
+pi install npm:pi-agent-browser-native
+```
+
+To try a published package without installing it permanently:
+
+```bash
+pi -e npm:pi-agent-browser-native
+```
+
+### GitHub install
+
+For the source install path, prefer the repository URL:
+
+```bash
+pi install https://github.com/fitchmultz/pi-agent-browser
+```
+
+To try the GitHub source without installing it permanently:
+
+```bash
+pi -e https://github.com/fitchmultz/pi-agent-browser
+```
+
+### Current practical local-checkout flow
+
+Until you are using a published package release, install from a checkout:
+
+```bash
+pi install /absolute/path/to/pi-agent-browser
+```
+
+Or try it for one session only:
+
+```bash
+pi -e /absolute/path/to/pi-agent-browser
+```
+
+The native tool exposed to the agent is named `agent_browser`.
+
+## Local development
+
+This repository now tracks `.pi/extensions/agent-browser.ts` as a thin development entrypoint that re-exports the real extension from `extensions/agent-browser/index.ts`. That keeps repo-root `pi` launches working without changing the published package layout.
+
+1. Install `agent-browser` separately via the upstream project.
+2. Run `npm install`.
+3. Launch `pi` from this repository root.
+4. Prompt the agent to use `agent_browser`.
+
+Example prompt:
+
+```text
+Use the agent_browser tool to open https://react.dev and then take an interactive snapshot.
+```
+
+Validated workflow examples:
+
+- open a page and snapshot it
+- click a link and confirm the destination title
+- use an explicit `--session` across multiple tool calls
+- use an explicit `--profile` and verify persisted browser storage across restarts
+- run `batch` with JSON via `stdin`
+- run `eval --stdin`
+- take a screenshot with inline attachment support
+- inspect `agent_browser --help` and `--version`
+
+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
+- 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
+
+## Docs
+
+- [`docs/REQUIREMENTS.md`](docs/REQUIREMENTS.md) — product requirements and constraints
+- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — current architecture decision
+- [`docs/TOOL_CONTRACT.md`](docs/TOOL_CONTRACT.md) — proposed v1 tool shape
+- [`docs/RELEASE.md`](docs/RELEASE.md) — maintainer release and package verification workflow
+
+## Documentation rule
+
+When requirements change in chat:
+
+1. update `docs/REQUIREMENTS.md`
+2. update the affected design docs
+3. update this README if user-facing expectations changed

package/docs/ARCHITECTURE.md

@@ -0,0 +1,158 @@
+# Architecture
+
+Related docs:
+- [`../README.md`](../README.md)
+- [`REQUIREMENTS.md`](REQUIREMENTS.md)
+- [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md)
+
+## Decision
+
+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. Repo-local `.pi/` wiring exists only as a thin tracked development shim, while package-manifest behavior and packaged contents matter more.
+
+## Chosen shape
+
+### One primary tool
+
+V1 should expose one native tool:
+
+- `agent_browser`
+
+Why:
+- lowest maintenance cost
+- lowest drift risk as upstream changes
+- preserves full upstream power
+- avoids overengineering
+
+### Direct subprocess execution
+
+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`
+
+### Agent-first UX
+
+The primary UX is the agent calling the tool directly.
+
+That means:
+- no command-heavy slash-command interface
+- no manual user orchestration as the main workflow
+- any future slash commands should be minimal and secondary
+
+### Package layout versus repo-local development
+
+The published package should load from the `pi` manifest in `package.json`.
+
+Repo-local development should use one thin tracked shim at `.pi/extensions/agent-browser.ts` that re-exports `extensions/agent-browser/index.ts`.
+
+Why:
+- keeps repo-root `pi` launches working during development
+- avoids making local `.pi/` wiring the product contract
+- 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.
+
+## Session model
+
+### Default
+
+If the caller does not provide `--session`, the extension should use an implicit session name derived from the current `pi` session id.
+
+Why:
+- works out of the box
+- gives continuity across calls
+- avoids forcing the agent to invent session names for basic browsing
+
+### Explicit upstream sessions
+
+If the caller provides `--session`, `--profile`, `--cdp`, or similar upstream flags, the extension should respect them with minimal interference.
+
+### Ownership
+
+V1 ownership rule:
+- implicit auto-generated sessions are extension-managed convenience sessions
+- 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
+
+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
+
+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.
+
+### Launch flags
+
+`agent-browser` startup flags are sticky once a session is already running.
+The extension should surface that clearly and avoid hidden restart behavior in v1.
+
+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.
+
+## Preferring the native tool
+
+Keep the handling simple:
+- prefer the native tool through extension guidance and tool-call guards
+- do not rely on package skill overrides as the primary solution
+
+This keeps the product centered on native tool usage instead of auxiliary skill wiring.
+
+## Responsibility split
+
+### `pi-agent-browser` owns
+
+- tool registration and schema
+- subprocess execution and JSON parsing
+- clear missing-binary errors
+- compact result summaries
+- inline screenshots/images
+- lightweight session convenience
+- docs
+
+### Upstream `agent-browser` owns
+
+- browser automation semantics
+- command vocabulary
+- session/profile behavior
+- auth/profile mechanics
+- feature evolution
+
+## Not the right design
+
+V1 should avoid:
+- a wide family of bespoke browser tools
+- compatibility layers for old `agent-browser` versions
+- deep embedded SDK-style integration
+- embedding a human-browsable browser UI inside `pi`
+- a slash-command-heavy UX
+
+## V1 priorities
+
+### Must have
+
+- one native `agent_browser` tool
+- direct `--json` execution
+- optional stdin support
+- implicit-session convenience
+- screenshot/image attachment
+- clear install and missing-binary messaging
+- solid docs
+
+### Nice to have
+
+- compact renderers for snapshots and tab lists
+- lightweight status display
+
+## Summary
+
+The architecture should stay:
+- thin
+- latest-only
+- close to upstream
+- native where it matters
+- low-maintenance

package/docs/RELEASE.md

@@ -0,0 +1,86 @@
+# Release and package verification
+
+Related docs:
+- [`../README.md`](../README.md)
+- [`REQUIREMENTS.md`](REQUIREMENTS.md)
+- [`ARCHITECTURE.md`](ARCHITECTURE.md)
+- [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md)
+
+## Purpose
+
+Provide one concrete maintainer workflow for validating repo state, package contents, and install guidance before publishing `pi-agent-browser`.
+
+## Pre-release checks
+
+From the repository root:
+
+```bash
+npm install
+npm run verify:release
+```
+
+`npm run verify:release` runs:
+
+1. `npm run verify` for TypeScript and unit coverage
+2. `npm run verify:package` for package-content validation via `npm pack --json --dry-run`
+
+## What package verification checks
+
+`npm run verify:package` confirms that:
+
+- the tracked repo-local development entrypoint exists at `.pi/extensions/agent-browser.ts`
+- `LICENSE` exists in the repo and the packed tarball
+- canonical published docs are present
+- extension source files are present
+- agent-only and superseded docs are absent from the tarball
+
+Current forbidden packed files include:
+
+- `AGENTS.md`
+- `docs/IMPLEMENTATION_PLAN.md`
+- `docs/native-integration-design.md`
+- `docs/v1-tool-contract.md`
+- `.pi/extensions/agent-browser.ts`
+- test and repo-only maintenance files
+
+For a full packed file listing:
+
+```bash
+node scripts/verify-package.mjs --list-files
+```
+
+## Local development validation
+
+Before publishing, also validate the repo-local development path:
+
+1. Install `agent-browser` separately.
+2. Launch `pi` from this repository root.
+3. Confirm the tracked `.pi/extensions/agent-browser.ts` shim loads the current extension code.
+4. Run a smoke prompt that exercises `agent_browser`.
+
+Example prompt:
+
+```text
+Use the agent_browser tool to open https://react.dev and then take an interactive snapshot.
+```
+
+## Post-publish install validation
+
+After publishing a release, validate the package-first install path explicitly:
+
+```bash
+pi install npm:pi-agent-browser-native@<version>
+pi -e npm:pi-agent-browser-native@<version>
+```
+
+Then confirm `pi` exposes the native `agent_browser` tool and that a basic `open` + `snapshot -i` flow works.
+
+## Release notes checklist
+
+Before publishing:
+
+- update `CHANGELOG.md`
+- confirm README install guidance still leads with the package-first flow
+- confirm local-checkout instructions still work for pre-release validation
+- rerun `npm run verify:release`
+- publish only after the tarball contents match expectations

package/docs/REQUIREMENTS.md

@@ -0,0 +1,101 @@
+# Requirements
+
+Related docs:
+- [`../README.md`](../README.md)
+- [`ARCHITECTURE.md`](ARCHITECTURE.md)
+- [`TOOL_CONTRACT.md`](TOOL_CONTRACT.md)
+- [`RELEASE.md`](RELEASE.md)
+
+## Purpose
+
+Define the product requirements and constraints for `pi-agent-browser`.
+
+## Product requirements
+
+### Dependency model
+
+- `agent-browser` is an external dependency.
+- This project does **not** bundle `agent-browser`.
+- Users install `agent-browser` separately and keep it available on `PATH`.
+- User-facing install guidance should point to the upstream `agent-browser` project/docs.
+
+### Version policy
+
+- Target the current locally installed `agent-browser` version.
+- Do **not** support a broad range of older `agent-browser` versions.
+- Do **not** add backward-compatibility shims.
+- Keep the wrapper close to current upstream behavior as `agent-browser` evolves.
+
+### Design philosophy
+
+- Do **not** overengineer.
+- Do **not** reduce usability.
+- Keep the integration thin and close to upstream `agent-browser`.
+- Give `pi` agents the power they need for practical browser automation.
+- Prefer official `pi` mechanisms over bespoke custom integration patterns.
+- Do **not** solve hypothetical problems that are not backed by observed behavior.
+
+### Primary UX
+
+- The main UX is the agent invoking the native tool directly, similar to built-in tools like `read` or `write`.
+- Do **not** rely on a large set of user-facing slash commands as the main interface.
+- This project is not trying to embed a human-browsable browser UI inside `pi`.
+
+### Install priority
+
+- Prioritize the package install path first.
+- User-facing install docs should lead with `pi install npm:pi-agent-browser-native` and `pi -e npm:pi-agent-browser-native` once releases exist.
+- User-facing install docs should also include the GitHub source path `pi install https://github.com/fitchmultz/pi-agent-browser`.
+- Keep the current local-checkout path documented as the practical pre-release and development flow.
+- Most users will install this extension globally rather than as a project-local extension.
+- Repo-local `.pi/` wiring is for development convenience only and should not drive the product design.
+- The tracked repo-local development entrypoint should stay a thin re-export, not a second implementation path.
+
+### Native-tool preference
+
+- When this native extension is available, the native `agent_browser` tool should be the preferred path for browser automation.
+- Keep the handling simple and global-install-friendly.
+- Do not rely on package skill overrides as the primary answer.
+
+### Documentation standard
+
+- Documentation is a core product artifact.
+- Docs must be structured, concise, well-linked, and written for humans first.
+- Someone opening the repo should quickly understand the goal, purpose, install model, and usage.
+- Documents should read as complete documents, not iterative logs, unless they are explicitly meant to be iterative, such as a changelog.
+- Requirements, expectations, and durable rules from user conversations should be reflected in the appropriate docs.
+- Published package contents should include the canonical user-facing docs plus `LICENSE`.
+- Published package contents should exclude agent-only and superseded docs such as `AGENTS.md`, `docs/v1-tool-contract.md`, and `docs/native-integration-design.md`.
+
+### Testing guidance
+
+- The primary confidence path is a real `pi` session driven in `tmux`.
+- Launch `pi` from the repository root for local development so the tracked `.pi` development entrypoint loads.
+- Prefer full `pi` restart over `/reload` when validating extension changes.
+- Use `/resume` when needed after restart.
+- Keep testing broader than a single smoke site like `example.com`.
+- Maintain a concrete release/package verification workflow in `docs/RELEASE.md` and matching repository scripts.
+
+## Representative use cases
+
+The design should comfortably support workflows such as:
+
+- UI testing and exploratory QA
+- web research
+- using browser UIs for other LLMs such as ChatGPT, Grok, Gemini, and Claude
+- isolated authenticated browser sessions
+- cloned-profile workflows similar to the patterns used in `pi-oracle`
+
+## Implications for the implementation
+
+- Package-manifest behavior matters more than repo-local development wiring.
+- The extension should use official `pi` hooks and package resources where possible.
+- The wrapper should stay thin, with upstream `agent-browser` remaining the source of truth for command semantics.
+- User-facing docs belong in `README.md` and the canonical published files under `docs/`.
+- Agent workflow and deeper testing procedures can stay in `AGENTS.md`, but published docs must not depend on that file being present.
+- Keep mitigations for legacy-skill coexistence simple; do not add extra moving parts unless observed behavior justifies them.
+
+## Open design questions
+
+- How much session convenience should the extension add by default versus leaving explicit session naming entirely to upstream `agent-browser` semantics?
+- Exactly which high-value result renderers belong in v1 beyond screenshots/images and a few compact summaries?