@53able/pi-agent-browser 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.1.1
+
+### Changed
+
+- Reworked README for package users: benefits, workflows, safety guidance, and troubleshooting.
+- Removed maintainer-specific publishing instructions from the npm-facing README.
+
 ## 0.1.0
 
 ### Added

package/README.md

@@ -1,8 +1,17 @@
 # pi-agent-browser
 
-Pi extension wrapping [`vercel-labs/agent-browser`](https://github.com/vercel-labs/agent-browser) for browser automation, rendered-page interaction, screenshots, saved browser state, and agent-readable context extraction.
+Typed browser automation tools for Pi, powered by [`agent-browser`](https://github.com/vercel-labs/agent-browser).
 
-This package exposes `agent-browser` CLI capabilities as typed Pi tools, so Pi can use browser sessions without hand-writing shell commands.
+Use this package when Pi needs to operate real web pages, extract rendered context, keep login sessions, or capture visual evidence without falling back to ad-hoc shell commands.
+
+## What you get
+
+- **Rendered-page context extraction** — read text from public pages or the active authenticated browser tab.
+- **Reliable interaction handles** — use accessibility snapshots with stable `@ref` targets for clicks and form fills.
+- **Evidence capture** — save screenshots and extracted text to predictable artifact paths.
+- **Session persistence** — reuse login state with named `agent-browser` sessions and restore support.
+- **Safer browsing controls** — constrain work with `allowedDomains`, `maxOutput`, and explicit state management.
+- **Typed Pi tools** — each browser action has its own schema instead of one free-form command string.
 
 ## Requirements
 
@@ -10,13 +19,13 @@ This package exposes `agent-browser` CLI capabilities as typed Pi tools, so Pi c
 - [`agent-browser`](https://github.com/vercel-labs/agent-browser) installed and available on `PATH`
 - Chrome for Testing installed through `agent-browser install`
 
-Quick check:
+Check your local setup:
 
 ```bash
 agent-browser doctor
 ```
 
-If `agent-browser` is not on `PATH`, set:
+If `agent-browser` is installed outside `PATH`, set:
 
 ```bash
 export AGENT_BROWSER_BIN=/absolute/path/to/agent-browser
@@ -24,39 +33,29 @@ export AGENT_BROWSER_BIN=/absolute/path/to/agent-browser
 
 ## Installation
 
-From GitHub:
+Install from npm:
 
 ```bash
-pi install https://github.com/53able/pi-agent-browser
+pi install npm:@53able/pi-agent-browser
 ```
 
-From npm after publish:
+Install from GitHub:
 
 ```bash
-pi install npm:@53able/pi-agent-browser
+pi install https://github.com/53able/pi-agent-browser
 ```
 
-From a local checkout:
+Install from a local checkout:
 
 ```bash
 git clone https://github.com/53able/pi-agent-browser.git
 pi install ./pi-agent-browser
 ```
 
-Or add the package source to Pi settings manually:
-
-```json
-{
-  "packages": ["npm:@53able/pi-agent-browser"]
-}
-```
-
-## Tools
-
-The extension registers these Pi tools:
+## Registered tools
 
 - `agent_browser_open` — open a URL or launch `about:blank`
-- `agent_browser_read` — extract agent-readable text or JSON from a URL or active rendered tab
+- `agent_browser_read` — extract text or JSON from a URL or active rendered tab
 - `agent_browser_snapshot` — get accessibility tree refs for interaction
 - `agent_browser_click` — click by `@ref` or CSS selector
 - `agent_browser_fill` — fill an input by `@ref` or CSS selector
@@ -66,15 +65,17 @@ The extension registers these Pi tools:
 - `agent_browser_close` — close a browser session
 - `agent_browser_doctor` — run `agent-browser doctor`
 
-## Basic usage
+## Common workflows
+
+### Read a page and save the extracted source
 
-Ask Pi naturally:
+Ask Pi:
 
 ```text
-https://example.com を browser 経由で読んで、outputs/browser/example.md に保存して
+https://example.com をブラウザ経由で読み、outputs/browser/example.md に保存して
 ```
 
-Equivalent tool arguments for `agent_browser_read`:
+Equivalent `agent_browser_read` arguments:
 
 ```json
 {
@@ -84,9 +85,9 @@ Equivalent tool arguments for `agent_browser_read`:
 }
 ```
 
-## Browser interaction workflow
+### Interact with a rendered page
 
-1. Open or navigate:
+1. Open the page.
 
 ```json
 {
@@ -98,12 +99,12 @@ Equivalent tool arguments for `agent_browser_read`:
 
 2. Call `agent_browser_snapshot` to get fresh `@ref` values.
 3. Use `agent_browser_click` or `agent_browser_fill` with those refs.
-4. Use `agent_browser_read` for text extraction or `agent_browser_screenshot` for visual evidence.
+4. Call `agent_browser_read` for text or `agent_browser_screenshot` for visual evidence.
 5. Close the session with `agent_browser_close` when finished.
 
-## Login/session state
+### Keep login state across runs
 
-To keep login state automatically, use a stable `session` and `restore: true` on `agent_browser_open`:
+Use a stable session name and `restore: true`:
 
 ```json
 {
@@ -114,6 +115,10 @@ To keep login state automatically, use a stable `session` and `restore: true` on
 }
 ```
 
+After logging in once, future opens with the same `session` and `restore` can reuse saved browser state.
+
+### Inspect or clear saved state
+
 List saved states:
 
 ```json
@@ -131,7 +136,7 @@ Clear one saved session state:
 }
 ```
 
-Clear all saved states only when explicitly intended:
+Clear all saved states only when intentionally resetting everything:
 
 ```json
 {
@@ -140,52 +145,32 @@ Clear all saved states only when explicitly intended:
 }
 ```
 
-## Safety notes
+## Safety guidance
 
-- Prefer `allowedDomains` for task-scoped browsing.
-- Use `outputPath` for durable source artifacts that support reports.
-- Take a fresh snapshot after navigation, form submission, modal dismissal, or failed clicks.
+- Pass `allowedDomains` whenever the browsing scope is known.
+- Use `outputPath` when extracted content supports a report, audit, or later verification.
+- Take a fresh snapshot after navigation, form submission, modal dismissal, or a failed click.
 - Prefer `agent_browser_read` for textual evidence and `agent_browser_screenshot` for visual evidence.
-- Use `agent_browser_eval` only when `read`/`snapshot` cannot expose the required state.
+- Use `agent_browser_eval` only when `read` or `snapshot` cannot expose the required state.
+- Review saved browser state before clearing broadly.
 
-## Development
+## Troubleshooting
 
-Dry-run the npm package contents:
+Run:
 
 ```bash
-npm run pack:dry
+agent-browser doctor
 ```
 
-Local Pi test example:
+Or ask Pi to run `agent_browser_doctor`.
+
+Common fixes:
 
 ```bash
-PI_OFFLINE=1 pi --no-builtin-tools --tools agent_browser_doctor -p "Use agent_browser_doctor and report output"
+npm install -g agent-browser
+agent-browser install
 ```
 
 ## License
 
 MIT
-
-## Publishing
-
-This repository is intended to publish through npm Trusted Publishing from GitHub Actions, not through long-lived npm tokens.
-
-### npm Trusted Publisher setup
-
-In npm, configure a trusted publisher for the package:
-
-- Package: `@53able/pi-agent-browser`
-- Publisher type: GitHub Actions
-- GitHub owner: `53able`
-- Repository: `pi-agent-browser`
-- Workflow filename: `publish.yml`
-- Allowed action: `npm publish`
-
-Then publish a release by pushing a semver tag:
-
-```bash
-git tag v0.1.0
-git push origin v0.1.0
-```
-
-The workflow uses GitHub OIDC with `id-token: write`, so no `NPM_TOKEN` secret is required.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@53able/pi-agent-browser",
-  "version": "0.1.0",
-  "description": "Pi extension wrapping vercel-labs/agent-browser for browser automation and context extraction.",
+  "version": "0.1.1",
+  "description": "Typed Pi tools for browser automation, rendered-page context extraction, screenshots, and saved session state via agent-browser.",
   "type": "module",
   "license": "MIT",
   "keywords": [