pi-browser-use 0.4.0 → 0.4.2
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.
- package/README.md +71 -16
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -34,36 +34,65 @@ Settings key is `pi-browser-use` in `~/.pi/agent/settings.json` (user) or `.pi/s
|
|
|
34
34
|
|
|
35
35
|
| Mode | Config | Behavior |
|
|
36
36
|
| --------------- | --------------------------------------- | ------------------------------------------------------ |
|
|
37
|
-
| Fresh (default) | `isolated` + `headless: true` | Ephemeral profile, no window
|
|
37
|
+
| Fresh (default) | `isolated` + `headless: true` | Ephemeral profile, no window, never steals focus |
|
|
38
38
|
| Authenticated | `sessionMode: persistent` | Shared profile, log in once, headed windows pop |
|
|
39
39
|
| Existing | `sessionMode: existing` + `autoConnect` | Drives your daily Chrome — intrusive, avoid by default |
|
|
40
40
|
|
|
41
|
-
|
|
41
|
+
All browser behavior plus the policy skill in one install; `.pi/settings.json` is purely for overrides.
|
|
42
|
+
|
|
43
|
+
### Full option reference
|
|
44
|
+
|
|
45
|
+
| Option | Type | Default | Description |
|
|
46
|
+
| ---------------------- | ---------- | ---------- | ------------------------------------------------------------------------------ |
|
|
47
|
+
| `sessionMode` | `string` | `isolated` | `persistent`, `isolated`, or `existing` |
|
|
48
|
+
| `headless` | `boolean` | `true` | No window at all (the only true hide on macOS) |
|
|
49
|
+
| `channel` | `string` | — | `canary`, `dev`, `beta`, `stable` |
|
|
50
|
+
| `browserUrl` | `string` | — | Attach to a running debuggable Chrome via HTTP URL |
|
|
51
|
+
| `wsEndpoint` | `string` | — | Attach via DevTools WebSocket endpoint |
|
|
52
|
+
| `executablePath` | `string` | — | Custom Chrome executable |
|
|
53
|
+
| `viewport` | `string` | — | Initial viewport, e.g. `1280x720` |
|
|
54
|
+
| `userDataDir` | `string` | — | Custom profile dir (persistent mode defaults to `~/.pi/browser-profile`) |
|
|
55
|
+
| `autoConnect` | `boolean` | `false` | Auto-attach to a local running Chrome (implies `existing`) |
|
|
56
|
+
| `chromeArgs` | `string[]` | — | First-class Chrome flags, forwarded as `--chrome-arg=` |
|
|
57
|
+
| `extraArgs` | `string[]` | — | Raw escape hatch, forwarded verbatim to `chrome-devtools-mcp` |
|
|
58
|
+
| `visionModel` | `object` | — | `{ provider, model }` from Pi's registry; enables `browser_analyze_screenshot` |
|
|
59
|
+
| `allowedUrlPattern` | `string[]` | — | Cage navigation to matching URL patterns |
|
|
60
|
+
| `blockedUrlPattern` | `string[]` | — | Block matching URL patterns (mutually exclusive with allow) |
|
|
61
|
+
| `redactNetworkHeaders` | `boolean` | `true` | Strip sensitive headers from network results |
|
|
62
|
+
| `acceptInsecureCerts` | `boolean` | `false` | Ignore self-signed/expired certificates |
|
|
63
|
+
|
|
64
|
+
First-class `chromeArgs` only apply when `chrome-devtools-mcp` launches Chrome itself — never with `autoConnect`/`browserUrl`. On macOS `--start-minimized` is ignored; only `headless: true` truly hides the window.
|
|
42
65
|
|
|
43
66
|
Hosts where `process.execPath` is not a directly executable Node runtime can set `PI_BROWSER_USE_NODE` to the Node command used for the MCP subprocess.
|
|
44
67
|
|
|
45
|
-
##
|
|
68
|
+
## Tools
|
|
46
69
|
|
|
47
|
-
|
|
70
|
+
Upstream `chrome-devtools-mcp` tools are proxied as `browser_*` (navigation, snapshot, click/fill/hover/drag/type, emulation, console, network, screenshots, dialogs, uploads, waits). Noisy, slow, or privileged ones (`lighthouse_audit`, performance traces, screencast, extension management) are excluded. On top, this package adds:
|
|
48
71
|
|
|
49
|
-
|
|
72
|
+
### `browser_save_artifact`
|
|
50
73
|
|
|
51
|
-
|
|
74
|
+
Writes a screenshot or the rendered HTML to disk (default `~/.pi/browser-artifacts/`) and returns the path. Prefer it over inline captures for evidence, visual QA, and artifact sharing.
|
|
52
75
|
|
|
53
|
-
|
|
76
|
+
With `annotate: true`, screenshots get numbered badges over interactive elements plus a coordinate map for coordinate click tools — badges are removed after capture:
|
|
54
77
|
|
|
55
|
-
|
|
78
|
+
|
|
56
79
|
|
|
57
|
-
|
|
80
|
+
```text
|
|
81
|
+
browser_save_artifact({ "pageId": 1, "kind": "screenshot", "annotate": true })
|
|
82
|
+
# Saved screenshot to ~/.pi/browser-artifacts/page-....png
|
|
83
|
+
# Annotated elements:
|
|
84
|
+
# 1: (342, 49) a "Home"
|
|
85
|
+
# 2: (394, 49) a "Docs"
|
|
86
|
+
# 6: (394, 298) button "Create workspace"
|
|
87
|
+
```
|
|
58
88
|
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
-
|
|
62
|
-
- `visual-qa` — viewport matrix and canvas/WebGL discipline.
|
|
89
|
+
### `browser_doctor`
|
|
90
|
+
|
|
91
|
+
Self-diagnostics: effective mode, whether this session launches its own Chrome, profile health, and upstream tool availability. Run it first when browser tools misbehave — it touches no pages.
|
|
63
92
|
|
|
64
|
-
|
|
93
|
+
### `browser_analyze_screenshot`
|
|
65
94
|
|
|
66
|
-
|
|
95
|
+
Vision analysis for canvas/WebGL scenes and coordinate clicks the accessibility tree cannot describe. Enabled only when `visionModel` is configured (see below); credentials resolve from Pi's model registry automatically.
|
|
67
96
|
|
|
68
97
|
```json
|
|
69
98
|
{
|
|
@@ -73,12 +102,38 @@ Enable `browser_analyze_screenshot` by referencing a model already configured in
|
|
|
73
102
|
}
|
|
74
103
|
```
|
|
75
104
|
|
|
76
|
-
|
|
105
|
+
## Page-scoped tools
|
|
106
|
+
|
|
107
|
+
Call `browser_list_pages` first, then pass its numeric `pageId` to page-scoped tools. Click-family calls blocked by an overlay are retried once automatically after dismissing it with Escape; stale element references get a refresh hint. See `skills/browser-policy/SKILL.md` for the full agent policy.
|
|
77
108
|
|
|
78
109
|
## Browser profile
|
|
79
110
|
|
|
80
111
|
On startup the default persistent profile is checked for accessibility. A root-owned or unreadable default (typically from running under `sudo`) is moved aside to `~/.pi/browser-profile.inaccessible-<timestamp>` so Chrome starts fresh instead of showing a preferences dialog. An explicit custom `userDataDir` in the same state fails fast with an ownership remediation hint. Never run the agent (or anything launching this browser) via `sudo`.
|
|
81
112
|
|
|
113
|
+
## Performance
|
|
114
|
+
|
|
115
|
+
`npm run bench` times the tool stack headless over 5 iterations (fixture setup excluded, matching vercel-labs/agent-browser's scenario set). Baseline on Apple Silicon: navigate ~1ms, snapshot ~3ms, screenshot ~37ms, evaluate ~206ms, full agent-loop cycle ~422ms. Re-run on your hardware before quoting numbers.
|
|
116
|
+
|
|
117
|
+
## Bundled skills
|
|
118
|
+
|
|
119
|
+
- `browser-policy` — CLI-first decision order, session modes, bot-wall and safety rules.
|
|
120
|
+
- `playwright-handoff` — when to stop clicking and run a repo Playwright spec instead (npm-first, bun alternatives, no repo changes required).
|
|
121
|
+
- `triage-console` — snapshot → console errors → failed network → screenshot.
|
|
122
|
+
- `visual-qa` — viewport matrix and canvas/WebGL discipline, including the annotate flow.
|
|
123
|
+
- `derive-client` — turn repeated flows into standalone fetch clients; stop driving solved problems.
|
|
124
|
+
- `dogfood` — charter-based exploratory bug hunts with severity discipline.
|
|
125
|
+
|
|
126
|
+
## Troubleshooting
|
|
127
|
+
|
|
128
|
+
| Symptom | Likely cause | Fix |
|
|
129
|
+
| ---------------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
|
|
130
|
+
| Chrome windows pop and steal focus | Headed mode (`headless: false`, `persistent`, or `existing`) | Switch to fresh headless defaults; on macOS no flag hides a headed window |
|
|
131
|
+
| `--chrome-arg` has no effect | Attached session (`autoConnect`/`browserUrl`) — flags only apply to MCP-launched Chrome | Move to `isolated`/`persistent` mode |
|
|
132
|
+
| Login wall / Turnstile loop | Bot check needs a human | Solve once in the persistent profile, then continue; never retry-loop a challenge |
|
|
133
|
+
| `profile is already in use` | Two sessions sharing one `userDataDir` | Use isolated mode or separate dirs per session |
|
|
134
|
+
| Stale uid errors | Page re-rendered after your snapshot | Take a fresh snapshot; ids invalidate on every action |
|
|
135
|
+
| Vision tool missing | No `visionModel` configured | Add it; otherwise use tree uids, or the global `vision` skill for vision-less models |
|
|
136
|
+
|
|
82
137
|
## License
|
|
83
138
|
|
|
84
139
|
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-browser-use",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "Opinionated browser-use for the Pi coding agent, powered by chrome-devtools-mcp (not Playwright). Fresh headless by default, authenticated persistent profile opt-in, CLI-first policy bundled.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|