@parcha/pi-browser 0.0.0-stage → 0.1.0-beta.14
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/CHANGELOG.md +23 -0
- package/LICENSE +202 -0
- package/NOTICE +33 -0
- package/README.md +348 -2
- package/dist/coding-agent-local.d.ts +16 -0
- package/dist/coding-agent-local.js +138 -0
- package/dist/coding-agent.d.ts +79 -0
- package/dist/coding-agent.js +448 -0
- package/dist/core/contract.d.ts +26 -0
- package/dist/core/contract.js +154 -0
- package/dist/core/custody.d.ts +117 -0
- package/dist/core/custody.js +126 -0
- package/dist/core/decisions.d.ts +43 -0
- package/dist/core/decisions.js +4 -0
- package/dist/core/downloads.d.ts +35 -0
- package/dist/core/downloads.js +131 -0
- package/dist/core/effects.d.ts +63 -0
- package/dist/core/effects.js +256 -0
- package/dist/core/evidence.d.ts +43 -0
- package/dist/core/evidence.js +6 -0
- package/dist/core/failures.d.ts +36 -0
- package/dist/core/failures.js +68 -0
- package/dist/core/find.d.ts +32 -0
- package/dist/core/find.js +179 -0
- package/dist/core/guard.d.ts +6 -0
- package/dist/core/guard.js +25 -0
- package/dist/core/host.d.ts +328 -0
- package/dist/core/host.js +2 -0
- package/dist/core/images.d.ts +37 -0
- package/dist/core/images.js +60 -0
- package/dist/core/lease.d.ts +16 -0
- package/dist/core/lease.js +30 -0
- package/dist/core/receipts.d.ts +19 -0
- package/dist/core/receipts.js +22 -0
- package/dist/core/redact.d.ts +13 -0
- package/dist/core/redact.js +83 -0
- package/dist/core/session-control.d.ts +25 -0
- package/dist/core/session-control.js +75 -0
- package/dist/core/sites.d.ts +33 -0
- package/dist/core/sites.js +102 -0
- package/dist/core/tools.d.ts +72 -0
- package/dist/core/tools.js +200 -0
- package/dist/core/uri.d.ts +11 -0
- package/dist/core/uri.js +37 -0
- package/dist/core/usage.d.ts +19 -0
- package/dist/core/usage.js +44 -0
- package/dist/core/web.d.ts +98 -0
- package/dist/core/web.js +327 -0
- package/dist/driver/extension-worker.d.ts +6 -0
- package/dist/driver/extension-worker.js +121 -0
- package/dist/driver/stagehand.d.ts +25 -0
- package/dist/driver/stagehand.js +91 -0
- package/dist/durable-result.d.ts +6 -0
- package/dist/durable-result.js +2 -0
- package/dist/durable.d.ts +79 -0
- package/dist/durable.js +582 -0
- package/dist/index.d.ts +19 -0
- package/dist/index.js +20 -0
- package/dist/providers/browserbase-net.d.ts +13 -0
- package/dist/providers/browserbase-net.js +96 -0
- package/dist/providers/browserbase.d.ts +152 -0
- package/dist/providers/browserbase.js +262 -0
- package/dist/providers/cdp-call.d.ts +6 -0
- package/dist/providers/cdp-call.js +25 -0
- package/dist/providers/cdp.d.ts +55 -0
- package/dist/providers/cdp.js +423 -0
- package/dist/providers/http.d.ts +2 -0
- package/dist/providers/http.js +21 -0
- package/dist/providers/kernel.d.ts +49 -0
- package/dist/providers/kernel.js +246 -0
- package/dist/providers/shared.d.ts +47 -0
- package/dist/providers/shared.js +82 -0
- package/dist/recorder/credential.d.ts +9 -0
- package/dist/recorder/credential.js +49 -0
- package/dist/recorder/follow.d.ts +26 -0
- package/dist/recorder/follow.js +138 -0
- package/dist/recorder/frames.d.ts +80 -0
- package/dist/recorder/frames.js +309 -0
- package/dist/recorder/index.d.ts +4 -0
- package/dist/recorder/index.js +7 -0
- package/dist/recorder/jpeg.d.ts +8 -0
- package/dist/recorder/jpeg.js +70 -0
- package/dist/recorder/track.d.ts +107 -0
- package/dist/recorder/track.js +259 -0
- package/dist/store.d.ts +56 -0
- package/dist/store.js +196 -0
- package/dist/testing/backend.d.ts +231 -0
- package/dist/testing/backend.js +414 -0
- package/dist/testing/driver.d.ts +28 -0
- package/dist/testing/driver.js +32 -0
- package/dist/testing/index.d.ts +4 -0
- package/dist/testing/index.js +4 -0
- package/dist/testing/pages.d.ts +3 -0
- package/dist/testing/pages.js +10 -0
- package/dist/testing/sentinels.d.ts +29 -0
- package/dist/testing/sentinels.js +38 -0
- package/dist/vendor/stagehand-facade/contract.d.ts +348 -0
- package/dist/vendor/stagehand-facade/contract.js +155 -0
- package/dist/vendor/stagehand-facade/runtime.d.ts +90 -0
- package/dist/vendor/stagehand-facade/runtime.js +1640 -0
- package/dist/vendor/stagehand-facade/screenshot-transport.d.ts +15 -0
- package/dist/vendor/stagehand-facade/screenshot-transport.js +51 -0
- package/dist/vendor/stagehand-facade/tools.d.ts +31 -0
- package/dist/vendor/stagehand-facade/tools.js +139 -0
- package/dist/web.d.ts +41 -0
- package/dist/web.js +38 -0
- package/package.json +123 -4
- package/src/vendor/stagehand-facade/UPSTREAM.json +24 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## Unreleased
|
|
4
|
+
|
|
5
|
+
## 0.1.0-beta.14 (2026-10-16)
|
|
6
|
+
|
|
7
|
+
- Accept pi 1.3: the `@earendil-works/pi-durable` and `@earendil-works/chord` peer ranges now end below 1.4, with the floors unchanged (1.0.4, and 1.1.0 for `@parcha/pi-browser`). pi 1.3.0 pins its own packages to exact versions, so an install is all 1.2 or all 1.3; CI runs every package's whole suite on a 1.3.0 family as well as on 1.2.0.
|
|
8
|
+
- On pi-ai 1.3, a tool call whose arguments are not a JSON object reaches no tool: pi-durable refuses it and shows the model the text it sent. A durable node's `submit` then spends none of its submissions. Before 1.3 the tool ran with `{}`, so `submit` answered with the schema's violations and counted one submission.
|
|
9
|
+
- `@parcha/pi-browser/recorder`: `exportFrameTracks` turns the recorded frames into one `frame.track` line per session: a WebM (VP9, constant `fps`, default 10) plus an index that maps run time to video time across gaps, with a slate while a gap lasts. `handle.drain(harness, ctx, signal?)` on the pi-durable adapter's handle resolves once no browser release is still running, so a host waits for it before it closes the harness. The index exports custody's vocabulary by name (`CustodyPort`, `AttachedSession`, `ToolOutput`, `BrowserFailureError`, `BrowserDriver`, `DriverFactory`, `DriverOptions`, `Overrides`) so a host can write its own tool.
|
|
10
|
+
- `@parcha/pi-browser`: a `cdp` kill never signals pid 1, pid 0, its own pid, or a process group the pid does not lead. A session's record and `browser_relaunch`'s answer name only the settings the provider applied (Browserbase applies proxies, verified, geolocation, region and context; Kernel and local Chrome none). A screenshot's `ask` comes back in `details.media.ask`. A classified failure names the browser provider, not Browserbase. A conversation's close evicts its repeat guard and idle entry. A page action's journal entry outlives its answer, and an identical retry waits for a look. Stagehand's extension losing its own CDP connection is a dropped browser, not the model's code error: a read reconnects and runs once more, a run is not repeated. A held Stagehand runtime is freed through its own close and never by closing its service worker, which under load was sometimes never restarted. Every Chrome the `cdp` provider starts gets a temporary directory of its own, removed with the lease, so Chrome's leftover entries no longer land in the host's `TMPDIR`.
|
|
11
|
+
|
|
12
|
+
## 0.1.0-beta.13 (2026-10-14)
|
|
13
|
+
|
|
14
|
+
First release of `@parcha/pi-browser`. It is versioned with the other packages of the repository it is published from; the release PR dates this section and gives it the workspace version.
|
|
15
|
+
|
|
16
|
+
- A browser for pi agents: `snapshot`, `run`, `screenshot`, `browser_read`, `browser_relaunch`, `browser_release`, `web_fetch` and `web_search`, with session custody that survives a crash, evidence filed with its SHA-256, typed failures, and credentials kept out of anything a model, a document or a log can see.
|
|
17
|
+
- Entries: `.` (the host-neutral core), `./durable` (the pi-durable adapter), `./coding-agent` (the pi coding agent's extension, what `pi install` loads), `./providers/browserbase`, `./providers/kernel`, `./providers/cdp`, `./driver/stagehand`, and `./testing` (a fake provider and driver, public on purpose).
|
|
18
|
+
- It depends on Stagehand, undici, zod and two HTML packages. `@earendil-works/pi-coding-agent`, `@earendil-works/pi-durable`, `@earendil-works/chord` and `@browserbasehq/sdk` are optional peers.
|
|
19
|
+
- `examples/live-grid`: one pi agent fans a task out to up to ten child agents, each in its own browser, and a local page shows them all live (a CDP screencast of a local Chrome, or a cloud provider's live view). The Kernel provider now gives a live view, and `./coding-agent` exports `findChrome`.
|
|
20
|
+
- pi versions: the pi-durable adapter runs on pi-durable 1.1 and 1.2. pi-durable 1.2 reads a tool result's `output` and treats a result with only `content` as empty, so every durable tool result (browser, web and site tools) carries the model's text under both keys; the pi coding agent's results are `content` in every version and are unchanged. Peer ranges: `@earendil-works/pi-durable` and `chord` `>=1.1.0 <1.3.0` (1.0.4 cannot build the adapter: `use_website` reads a child's last report by scanning entries in descending order, which 1.1 added); `@earendil-works/pi-coding-agent` stays `*`, as pi's package guidance asks. A test on pi 1.2 checks that no tool result reaches the model without its text.
|
|
21
|
+
- `use_website` (listed when the host passes `sites`): a model hands a task to an agent that works one granted website in its own browser, through a `SiteRunPort`. Only the declared answer, a started run or a report, reaches the model. `localSites()` runs each task as a child agent: a pi session in the coding agent, a task-owned conversation in pi-durable, with the browser tools and never `use_website`, and its browser released when it reports. `examples/use-website` is a runnable demo.
|
|
22
|
+
- `@parcha/pi-browser/recorder`: `frameRecorder` screencasts each browser session over DevTools (a local Chrome, Browserbase and Kernel all speak it) and hands `agentrun.recording/1` `frame` and `frame.gap` lines, with their JPEGs, to a sink you pass. It is read-only beside the session's own connections and writes nothing itself. Capture is JPEG at quality 60, at most 800 px wide and 10 frames a second per session. A gap is written, never filled (`process_killed`, `session_released`, `credential_on_page`). No frame is kept while a credential or a one-time code is on the page, and a live-view URL is never recorded.
|
|
23
|
+
- `@parcha/pi-browser`: `web_fetch` percent-encodes the characters RFC 3986 refuses before the provider sees the URL, and the redactor scrubs a registered secret in every spelling `web_fetch` can give it, including the half-encoded `#` form and a trailing `%` the URL completes. A `cdp` release that cannot remove the session's profile directory tries again when files arrive in it (ENOTEMPTY), and when it still cannot it names every directory left behind. A `cdp` release whose lease names a browser it does not own leaves the profile a live Chrome still runs on. A browser released with its directory left behind is over: the coding agent never reuses it, and retries the directory removal as cleanup.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
|
|
2
|
+
Apache License
|
|
3
|
+
Version 2.0, January 2004
|
|
4
|
+
http://www.apache.org/licenses/
|
|
5
|
+
|
|
6
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
7
|
+
|
|
8
|
+
1. Definitions.
|
|
9
|
+
|
|
10
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
11
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
12
|
+
|
|
13
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
14
|
+
the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
17
|
+
other entities that control, are controlled by, or are under common
|
|
18
|
+
control with that entity. For the purposes of this definition,
|
|
19
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
20
|
+
direction or management of such entity, whether by contract or
|
|
21
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
22
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
23
|
+
|
|
24
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
25
|
+
exercising permissions granted by this License.
|
|
26
|
+
|
|
27
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
28
|
+
including but not limited to software source code, documentation
|
|
29
|
+
source, and configuration files.
|
|
30
|
+
|
|
31
|
+
"Object" form shall mean any form resulting from mechanical
|
|
32
|
+
transformation or translation of a Source form, including but
|
|
33
|
+
not limited to compiled object code, generated documentation,
|
|
34
|
+
and conversions to other media types.
|
|
35
|
+
|
|
36
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
37
|
+
Object form, made available under the License, as indicated by a
|
|
38
|
+
copyright notice that is included in or attached to the work
|
|
39
|
+
(an example is provided in the Appendix below).
|
|
40
|
+
|
|
41
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
42
|
+
form, that is based on (or derived from) the Work and for which the
|
|
43
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
44
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
45
|
+
of this License, Derivative Works shall not include works that remain
|
|
46
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
47
|
+
the Work and Derivative Works thereof.
|
|
48
|
+
|
|
49
|
+
"Contribution" shall mean any work of authorship, including
|
|
50
|
+
the original version of the Work and any modifications or additions
|
|
51
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
52
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
53
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
54
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
55
|
+
means any form of electronic, verbal, or written communication sent
|
|
56
|
+
to the Licensor or its representatives, including but not limited to
|
|
57
|
+
communication on electronic mailing lists, source code control systems,
|
|
58
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
59
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
60
|
+
excluding communication that is conspicuously marked or otherwise
|
|
61
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
62
|
+
|
|
63
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
64
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
65
|
+
subsequently incorporated within the Work.
|
|
66
|
+
|
|
67
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
68
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
69
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
70
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
71
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
72
|
+
Work and such Derivative Works in Source or Object form.
|
|
73
|
+
|
|
74
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
75
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
76
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
77
|
+
(except as stated in this section) patent license to make, have made,
|
|
78
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
79
|
+
where such license applies only to those patent claims licensable
|
|
80
|
+
by such Contributor that are necessarily infringed by their
|
|
81
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
82
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
83
|
+
institute patent litigation against any entity (including a
|
|
84
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
85
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
86
|
+
or contributory patent infringement, then any patent licenses
|
|
87
|
+
granted to You under this License for that Work shall terminate
|
|
88
|
+
as of the date such litigation is filed.
|
|
89
|
+
|
|
90
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
91
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
92
|
+
modifications, and in Source or Object form, provided that You
|
|
93
|
+
meet the following conditions:
|
|
94
|
+
|
|
95
|
+
(a) You must give any other recipients of the Work or
|
|
96
|
+
Derivative Works a copy of this License; and
|
|
97
|
+
|
|
98
|
+
(b) You must cause any modified files to carry prominent notices
|
|
99
|
+
stating that You changed the files; and
|
|
100
|
+
|
|
101
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
102
|
+
that You distribute, all copyright, patent, trademark, and
|
|
103
|
+
attribution notices from the Source form of the Work,
|
|
104
|
+
excluding those notices that do not pertain to any part of
|
|
105
|
+
the Derivative Works; and
|
|
106
|
+
|
|
107
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
108
|
+
distribution, then any Derivative Works that You distribute must
|
|
109
|
+
include a readable copy of the attribution notices contained
|
|
110
|
+
within such NOTICE file, excluding those notices that do not
|
|
111
|
+
pertain to any part of the Derivative Works, in at least one
|
|
112
|
+
of the following places: within a NOTICE text file distributed
|
|
113
|
+
as part of the Derivative Works; within the Source form or
|
|
114
|
+
documentation, if provided along with the Derivative Works; or,
|
|
115
|
+
within a display generated by the Derivative Works, if and
|
|
116
|
+
wherever such third-party notices normally appear. The contents
|
|
117
|
+
of the NOTICE file are for informational purposes only and
|
|
118
|
+
do not modify the License. You may add Your own attribution
|
|
119
|
+
notices within Derivative Works that You distribute, alongside
|
|
120
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
121
|
+
that such additional attribution notices cannot be construed
|
|
122
|
+
as modifying the License.
|
|
123
|
+
|
|
124
|
+
You may add Your own copyright statement to Your modifications and
|
|
125
|
+
may provide additional or different license terms and conditions
|
|
126
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
127
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
128
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
129
|
+
the conditions stated in this License.
|
|
130
|
+
|
|
131
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
132
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
133
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
134
|
+
this License, without any additional terms or conditions.
|
|
135
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
136
|
+
the terms of any separate license agreement you may have executed
|
|
137
|
+
with Licensor regarding such Contributions.
|
|
138
|
+
|
|
139
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
140
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
141
|
+
except as required for reasonable and customary use in describing the
|
|
142
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
143
|
+
|
|
144
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
145
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
146
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
147
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
148
|
+
implied, including, without limitation, any warranties or conditions
|
|
149
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
150
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
151
|
+
appropriateness of using or redistributing the Work and assume any
|
|
152
|
+
risks associated with Your exercise of permissions under this License.
|
|
153
|
+
|
|
154
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
155
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
156
|
+
unless required by applicable law (such as deliberate and grossly
|
|
157
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
158
|
+
liable to You for damages, including any direct, indirect, special,
|
|
159
|
+
incidental, or consequential damages of any character arising as a
|
|
160
|
+
result of this License or out of the use or inability to use the
|
|
161
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
162
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
163
|
+
other commercial damages or losses), even if such Contributor
|
|
164
|
+
has been advised of the possibility of such damages.
|
|
165
|
+
|
|
166
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
167
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
168
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
169
|
+
or other liability obligations and/or rights consistent with this
|
|
170
|
+
License. However, in accepting such obligations, You may act only
|
|
171
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
172
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
173
|
+
defend, and hold each Contributor harmless for any liability
|
|
174
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
175
|
+
of your accepting any such warranty or additional liability.
|
|
176
|
+
|
|
177
|
+
END OF TERMS AND CONDITIONS
|
|
178
|
+
|
|
179
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
180
|
+
|
|
181
|
+
To apply the Apache License to your work, attach the following
|
|
182
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
183
|
+
replaced with your own identifying information. (Don't include
|
|
184
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
185
|
+
comment syntax for the file format. We also recommend that a
|
|
186
|
+
file or class name and description of purpose be included on the
|
|
187
|
+
same "printed page" as the copyright notice for easier
|
|
188
|
+
identification within third-party archives.
|
|
189
|
+
|
|
190
|
+
Copyright [yyyy] [name of copyright owner]
|
|
191
|
+
|
|
192
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
193
|
+
you may not use this file except in compliance with the License.
|
|
194
|
+
You may obtain a copy of the License at
|
|
195
|
+
|
|
196
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
197
|
+
|
|
198
|
+
Unless required by applicable law or agreed to in writing, software
|
|
199
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
200
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
201
|
+
See the License for the specific language governing permissions and
|
|
202
|
+
limitations under the License.
|
package/NOTICE
ADDED
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
AgentRun
|
|
2
|
+
Copyright 2026 Parcha Labs, Inc.
|
|
3
|
+
|
|
4
|
+
This package contains two pieces of Stagehand 4.1.0 (https://github.com/browserbase/stagehand), both under its MIT license,
|
|
5
|
+
whose text follows:
|
|
6
|
+
|
|
7
|
+
- The Chrome launch flags in src/providers/cdp.ts, copied from packages/sdk-ts/src/browser/localBrowser.ts
|
|
8
|
+
(DEFAULT_CHROME_FLAGS).
|
|
9
|
+
- The files in src/vendor/stagehand-facade (compiled to dist/vendor/stagehand-facade), copied from
|
|
10
|
+
packages/integrations/core/src/facade at commit cd7b230778cf92269e4cb90e80d97f5113781c51. UPSTREAM.json, shipped
|
|
11
|
+
beside them as src/vendor/stagehand-facade/UPSTREAM.json, records each file's upstream blob and SHA-256.
|
|
12
|
+
|
|
13
|
+
MIT License
|
|
14
|
+
|
|
15
|
+
Copyright (c) 2024 Browserbase Inc.
|
|
16
|
+
|
|
17
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
18
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
19
|
+
in the Software without restriction, including without limitation the rights
|
|
20
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
21
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
22
|
+
furnished to do so, subject to the following conditions:
|
|
23
|
+
|
|
24
|
+
The above copyright notice and this permission notice shall be included in all
|
|
25
|
+
copies or substantial portions of the Software.
|
|
26
|
+
|
|
27
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
28
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
29
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
30
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
31
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
32
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
33
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,349 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @parcha/pi-browser
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A browser for [pi](https://github.com/earendil-works/pi) agents that survives crashes. The package records a session
|
|
4
|
+
before it calls the provider and releases it with a durable task. After a crash it reruns reads and never reruns actions.
|
|
5
|
+
It files every page the agent reads as evidence with its SHA-256, gives each failure a typed code, and keeps credentials out
|
|
6
|
+
of anything the model, a document or a log can see.
|
|
7
|
+
|
|
8
|
+
Part of [AgentRun](https://github.com/Parcha-ai/agentrun). Node `>=22.19.0`, pi 1.1 and 1.2 (the
|
|
9
|
+
coding-agent entry also runs on pi 1.0.4). ESM only: the
|
|
10
|
+
package has `import` entries and no `require` entry.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
pi install npm:@parcha/pi-browser # the pi coding agent's extension
|
|
16
|
+
npm install @parcha/pi-browser # the library: providers, driver, durable adapter
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Until it is published, build it from a checkout and `pi install ./packages/pi-browser`.
|
|
20
|
+
|
|
21
|
+
Stagehand, undici, zod and the two HTML packages are dependencies. Four optional peers cover the rest. Install only the ones you use:
|
|
22
|
+
|
|
23
|
+
| Peer | Needed for |
|
|
24
|
+
|---|---|
|
|
25
|
+
| `@earendil-works/pi-coding-agent` | `/coding-agent`. `pi install` supplies it. |
|
|
26
|
+
| `@earendil-works/pi-durable` and `@earendil-works/chord` | `/durable`, the adapter for a pi-durable Harness. |
|
|
27
|
+
| `@browserbasehq/sdk` | the Browserbase provider. Kernel needs no SDK. |
|
|
28
|
+
|
|
29
|
+
The pi peers are `@earendil-works/pi-durable` and `chord` `>=1.1.0 <1.4.0`, and `@earendil-works/pi-coding-agent` at any version, as pi's package guidance asks of the packages it supplies. The suite passes on pi 1.1, 1.2 and 1.3, and the coding-agent entry's tests also pass on a pi 1.0.4 family.
|
|
30
|
+
|
|
31
|
+
## Quick start
|
|
32
|
+
|
|
33
|
+
A local Chrome, one page, one snapshot. It needs Chrome or Chromium; `CHROME_PATH` names it.
|
|
34
|
+
|
|
35
|
+
```js
|
|
36
|
+
import { mkdtemp, rm } from "node:fs/promises";
|
|
37
|
+
import { tmpdir } from "node:os";
|
|
38
|
+
import { join } from "node:path";
|
|
39
|
+
import { cdpProvider } from "@parcha/pi-browser/providers/cdp";
|
|
40
|
+
import { stagehandDriver } from "@parcha/pi-browser/driver/stagehand";
|
|
41
|
+
|
|
42
|
+
const profileRoot = await mkdtemp(join(tmpdir(), "pi-browser-"));
|
|
43
|
+
const provider = cdpProvider({ chrome: { executablePath: process.env.CHROME_PATH ?? "/usr/bin/google-chrome", profileRoot } });
|
|
44
|
+
const signal = AbortSignal.timeout(60_000);
|
|
45
|
+
const session = await provider.create({ tag: "quick-start", maxLifetimeS: 600, idleTimeoutS: 60, proxies: false, verified: false, captcha: false, viewport: { width: 1000, height: 700 }, metadata: {} }, signal);
|
|
46
|
+
try {
|
|
47
|
+
const driver = await stagehandDriver()(await provider.attach(session), signal);
|
|
48
|
+
await driver.run({ code: `await page.goto(${JSON.stringify(process.argv[2] ?? "https://example.com")})` });
|
|
49
|
+
console.log(await driver.snapshot());
|
|
50
|
+
await driver.close();
|
|
51
|
+
} finally {
|
|
52
|
+
await provider.release(session);
|
|
53
|
+
await rm(profileRoot, { recursive: true, force: true });
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## Try it without a key or a Chrome
|
|
58
|
+
|
|
59
|
+
The Quick start's provider, driver and snapshot, on the package's fake backend: no browser, no key and no network. Paste it into a shell in a directory where the package is installed.
|
|
60
|
+
|
|
61
|
+
```sh
|
|
62
|
+
node --input-type=module <<'EOF'
|
|
63
|
+
import { FakeBackend, fakeDriver, fixturePage } from "@parcha/pi-browser/testing";
|
|
64
|
+
|
|
65
|
+
const start = "https://example.test/";
|
|
66
|
+
const backend = new FakeBackend({ start, pages: { [start]: fixturePage(start, "The answer is forty-two.", "Example") } });
|
|
67
|
+
const signal = AbortSignal.timeout(30_000);
|
|
68
|
+
const session = await backend.provider.create({ tag: "no-key", maxLifetimeS: 60, idleTimeoutS: 30, proxies: false, verified: false, captcha: false, viewport: { width: 1000, height: 700 }, metadata: {} }, signal);
|
|
69
|
+
const driver = await fakeDriver(backend)(await backend.provider.attach(session), signal);
|
|
70
|
+
console.log(await driver.snapshot());
|
|
71
|
+
await driver.close();
|
|
72
|
+
await backend.provider.release(session);
|
|
73
|
+
EOF
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
It prints the page's accessibility tree, the same text `snapshot` gives a model:
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
[0] main
|
|
80
|
+
[1] text: The answer is forty-two.
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## Demos
|
|
84
|
+
|
|
85
|
+
Four runnable demos live in `examples/` in the repository. They are not in the npm package. Build once with `npm ci && npm run build`, then run one from the repository root. Each needs Chrome or Chromium (`CHROME_PATH` names it) except where it says otherwise.
|
|
86
|
+
|
|
87
|
+
| Demo | Run | What it shows |
|
|
88
|
+
|---|---|---|
|
|
89
|
+
| [`examples/one-script-three-providers.mjs`](examples/one-script-three-providers.mjs) | `node packages/pi-browser/examples/one-script-three-providers.mjs https://example.com` | The same script on a local Chrome, Browserbase or Kernel. `PI_BROWSER_PROVIDER=browserbase` needs `BROWSERBASE_API_KEY` and the Browserbase SDK; `kernel` needs `KERNEL_API_KEY`. The tests run the local Chrome path only. |
|
|
90
|
+
| [`examples/hold-an-irreversible-action.mjs`](examples/hold-an-irreversible-action.mjs) | `node packages/pi-browser/examples/hold-an-irreversible-action.mjs` | Under the `ask` policy a form post is held until a person approves it. The demo refuses, and the local server it posts to counts zero requests. |
|
|
91
|
+
| [`examples/crash-and-resume.mjs`](examples/crash-and-resume.mjs) | `node packages/pi-browser/examples/crash-and-resume.mjs`, twice | The first run sets a page title and kills itself with SIGKILL between two tool calls. The second recovers the same Chrome from the run's own store and reads the title back. A scripted model stands in for a real one. It uses the pi-durable packages the repository already installs. Delete `$TMPDIR/pi-browser-crash-demo` to start over. |
|
|
92
|
+
| [`examples/read-a-pdf.mjs`](examples/read-a-pdf.mjs) | `node packages/pi-browser/examples/read-a-pdf.mjs` | `web_fetch` on a PDF the fetch service cannot convert. It fetches the file raw and hands the bytes to your extractor, here poppler's `pdftotext` (needs poppler installed). The fetch service is a stand-in that answers HTTP 400 for a PDF, as Browserbase does. It does not need Chrome. |
|
|
93
|
+
|
|
94
|
+
## Entries
|
|
95
|
+
|
|
96
|
+
- `@parcha/pi-browser`: the host-neutral core. The model contract (tool names, descriptions, JSON schemas, effect and
|
|
97
|
+
replay classes, the `browser` and `web` prompt sections), the typed failure envelope, the redactor, the screenshot
|
|
98
|
+
budget, the repeat guard, evidence and decision-hook types, usage and prices, `find` (chunking and ranking a long page),
|
|
99
|
+
`browser_downloads`, the opt-in request observer, and the provider interface. It imports nothing outside Node's builtins.
|
|
100
|
+
- `/durable`: the pi-durable adapter. `createBrowserExtension` is session custody in the run's own store (a create is
|
|
101
|
+
committed before the provider is called, release is a durable task, reconcile runs at run open). `createWebExtension` is
|
|
102
|
+
`web_fetch` and `web_search`.
|
|
103
|
+
- `/coding-agent`: the pi coding agent's extension, described under [For pi users](#for-pi-users). `pi install` loads it.
|
|
104
|
+
- `/driver/stagehand`: `stagehandDriver()`, Stagehand v4 over upstream's facade, vendored unedited in
|
|
105
|
+
`src/vendor/stagehand-facade/`. `UPSTREAM.json` names the commit and each file's blob id and SHA-256;
|
|
106
|
+
`node scripts/vendor-facade.mjs --check` verifies them and `--commit SHA --release NAME` re-vendors. Stagehand is created
|
|
107
|
+
sealed: no inference, no cache, its trace exporter pointed at a closed loopback port.
|
|
108
|
+
- `/providers/browserbase`, `/providers/kernel`, `/providers/cdp`: where browsers come from. Browserbase through its SDK,
|
|
109
|
+
with the credential-proxy dial and the connect-URL rewrite. Kernel through its REST API on the package's own HTTP agent.
|
|
110
|
+
Any CDP endpoint, or a local Chrome the provider starts and kills by exact pid.
|
|
111
|
+
- `/testing`: the shared test fake. A provider backend with a ledger of every call, a credential broker, an HTTP face so the
|
|
112
|
+
ledger outlives a killed child process, a driver over in-memory pages, and sentinel credentials. A host's composition
|
|
113
|
+
test and this package's crash matrix use the same one.
|
|
114
|
+
|
|
115
|
+
## The tools
|
|
116
|
+
|
|
117
|
+
| Tool | Does | Replay after a crash |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| `snapshot` | The page's accessibility tree with bracketed ids: a working view for the next `run`. Never filed, so it is not citable evidence. | Reruns. |
|
|
120
|
+
| `screenshot`, `browser_read` | Read the page. Each read is filed as evidence with its URL, SHA-256 and the offset into the session's recording. A screenshot is held to 2,000 px on its long edge. | Reruns. A read whose session was lost answers `session_replaced`. |
|
|
121
|
+
| `browser_downloads` | Copy what the session downloaded into the host's workspace, with a manifest of SHA-256 sums. Listed only when the host gives a `workspace` and the provider can list downloads. | Reruns; files already there are skipped. |
|
|
122
|
+
| `run` | Act: code, or a batch of ref actions. | Never reruns. The model is told the call may have taken effect and where the page was, and the identical code is refused once (`effect_unknown`). |
|
|
123
|
+
| `browser_release`, `browser_relaunch` | End the session; end it and open another. | Idempotent. A create carries a tag, so a rerun finds its session. |
|
|
124
|
+
| `web_fetch`, `web_search` | Fetch a page or search, through the provider's services. | Reruns. |
|
|
125
|
+
|
|
126
|
+
`web_fetch` and `web_search` results carry their price as pi usage (the Browserbase provider's list prices). Session
|
|
127
|
+
minutes are charged by the session meter (`core/usage.ts`, wired into custody): every session tool's result carries the
|
|
128
|
+
time since the last charge, and each released session's record carries its total.
|
|
129
|
+
|
|
130
|
+
Every failure is one envelope: `ok: false`, a `code`, `retryable`, `effect` (`none` or `possibly_effected`) and a message
|
|
131
|
+
that names the way out.
|
|
132
|
+
|
|
133
|
+
## For pi users
|
|
134
|
+
|
|
135
|
+
The pi coding agent gets `snapshot`, `run`, `screenshot`, `browser_read`, `browser_relaunch`, `browser_release` and
|
|
136
|
+
`web_fetch` (plus `web_search` when the provider offers one). It opens a Chrome of its own on first use, reads and drives
|
|
137
|
+
pages through Stagehand, files every page and screenshot with the page's URL and a SHA-256, and closes the Chrome when you
|
|
138
|
+
release it, after three idle minutes, or when the session ends. Nothing starts until the model's first browser call.
|
|
139
|
+
|
|
140
|
+
The local browser needs Chrome or Chromium: the one named by `--browser-chrome` or `PI_BROWSER_CHROME`, else `CHROME_PATH`,
|
|
141
|
+
else the first of `google-chrome`, `chromium` and the usual install locations (`/opt/google/chrome/chrome`, Chrome in
|
|
142
|
+
`/Applications`, Chrome in `Program Files`). It is tested on Linux; macOS and Windows are not verified.
|
|
143
|
+
|
|
144
|
+
| Setting | Meaning |
|
|
145
|
+
|---|---|
|
|
146
|
+
| `--browser-chrome PATH`, `PI_BROWSER_CHROME` | The Chrome to start. A path that does not exist is refused by name, never replaced. |
|
|
147
|
+
| `--browser-headed`, `PI_BROWSER_HEADED=1` | Show the window instead of running headless. |
|
|
148
|
+
| `--browser-no-sandbox`, `PI_BROWSER_NO_SANDBOX=1` | Start Chrome without its sandbox. Needed as root, in a container, or where user namespaces are restricted. Use it only for pages you trust. |
|
|
149
|
+
| `--browser-endpoint URL`, `PI_BROWSER_ENDPOINT` | Attach to a Chrome you already run (`http://host:port` or `ws://`) instead of starting one. Releasing leaves it running. |
|
|
150
|
+
| `--browser-provider browserbase`, `PI_BROWSER_PROVIDER` | Use Browserbase. Needs `BROWSERBASE_API_KEY` (`BB_API_KEY` also works); a missing key is refused by name. `PI_BROWSER_PROXIES=1` turns on its proxies. |
|
|
151
|
+
| `--browser-provider kernel`, `PI_BROWSER_PROVIDER` | Use Kernel. Needs `KERNEL_API_KEY`; a missing key is refused by name. `KERNEL_BASE_URL` points at another Kernel API. `PI_BROWSER_STEALTH=1` turns on Kernel's stealth mode. |
|
|
152
|
+
|
|
153
|
+
What it does with your machine and your data:
|
|
154
|
+
|
|
155
|
+
- The Chrome it starts has its own profile directory under a temporary root and a free debugging port, never your browser's
|
|
156
|
+
profile and never port 9222. The profile is deleted when the browser is released.
|
|
157
|
+
- Pages and screenshots are filed under `<project>/.pi/browser/evidence/`, each as a receipt (`tool`, `args`, `status`, the
|
|
158
|
+
page's final URL and title, `sha256`, then the body). A credential-shaped query parameter in a URL, a Bearer value and a
|
|
159
|
+
key of the shapes Stagehand knows are replaced by `[redacted]` before anything is filed, shown to the model or stored.
|
|
160
|
+
- Each browser session is appended to the pi session file (`browser.session` entries; the model never sees them). The coding
|
|
161
|
+
agent has no mid-turn resume, so a resumed session gets a fresh browser: cookies and page state do not carry over. A Chrome
|
|
162
|
+
that a crashed pi left running is closed when that session is next started, never adopted.
|
|
163
|
+
- Stagehand's trace export is pointed at a closed loopback port, so nothing you browse goes to a third party.
|
|
164
|
+
- `browser_relaunch` with `verified` or `geolocation` changes nothing on a local Chrome or on Kernel; they are Browserbase features.
|
|
165
|
+
|
|
166
|
+
Providers and `web_fetch`:
|
|
167
|
+
|
|
168
|
+
- Without a fetch service, `web_fetch` reads public hosts only. It refuses loopback, private and link-local addresses at every
|
|
169
|
+
redirect hop, anything over 5 MiB, and non-text, and it sends no cookies or credentials.
|
|
170
|
+
- A PDF the fetch service will not convert to markdown (Browserbase answers HTTP 400) is fetched once more as the raw file.
|
|
171
|
+
The coding agent has no PDF text extractor, so `web_fetch` says the URL is a PDF and that `format: "raw"` returns its
|
|
172
|
+
bytes, base64-encoded. A host with an extractor passes `pdf: { text(bytes, url, signal) }` to `createWebExtension`; the text
|
|
173
|
+
it returns is answered and filed as the page (`extractor: pdf-text`, judged by `classifyPage` like any page). A PDF over
|
|
174
|
+
32 MiB is not handed to it, and it gets 120 s (`maxBytes`, `timeoutMs`); a PDF with no text says so.
|
|
175
|
+
- On Kernel, each session is tagged with its run and lease tag, so a crashed pi's session is found again by tag. It is
|
|
176
|
+
created with an idle timeout equal to the idle release (three minutes), so Kernel ends a browser nobody is connected to if
|
|
177
|
+
pi dies, and a release deletes it and waits until Kernel shows it gone. Stagehand's extension must be stored in your Kernel
|
|
178
|
+
project: a stored extension with the same bytes (Kernel's checksum) is used whatever its name and never changed, and
|
|
179
|
+
otherwise the first session uploads it once as `agentrun-stagehand-<sha256 prefix>`. A plan with no room for it fails the
|
|
180
|
+
launch naming `insufficient_plan`. Kernel's live view is not offered, because its API has no read-only form of it. Kernel
|
|
181
|
+
calls go direct, never through `HTTP(S)_PROXY`, as Browserbase's do; a host behind a proxy passes its own `fetch` to `kernelProvider`.
|
|
182
|
+
|
|
183
|
+
Limits: a crash loses the in-flight turn and the browser with it. `pi install` pulls Stagehand, about 40 MB and 52 packages
|
|
184
|
+
with its dependencies.
|
|
185
|
+
|
|
186
|
+
## For hosts
|
|
187
|
+
|
|
188
|
+
Any pi-durable `Harness` can install the extensions. A local Chrome is the default provider and costs nothing.
|
|
189
|
+
|
|
190
|
+
```js
|
|
191
|
+
import { createRegistry, Harness } from "@earendil-works/pi-durable";
|
|
192
|
+
import { createBrowserExtension } from "@parcha/pi-browser/durable";
|
|
193
|
+
import { stagehandDriver } from "@parcha/pi-browser/driver/stagehand";
|
|
194
|
+
import { cdpProvider } from "@parcha/pi-browser/providers/cdp";
|
|
195
|
+
|
|
196
|
+
const provider = cdpProvider({ chrome: { executablePath: "/usr/bin/google-chrome", profileRoot: "/var/lib/my-app/browser-profiles" } });
|
|
197
|
+
const browser = createBrowserExtension({
|
|
198
|
+
provider: () => provider,
|
|
199
|
+
driver: stagehandDriver(),
|
|
200
|
+
evidence: { file: async (label, record) => /* write record.body somewhere; return { path } or null */ null },
|
|
201
|
+
});
|
|
202
|
+
const registry = createRegistry();
|
|
203
|
+
registry.install(browser.extension); // before the Harness resumes anything
|
|
204
|
+
const harness = await Harness.open(storage, { models, registry }, context);
|
|
205
|
+
// `isActive` says whether a conversation will continue in this process; a session of one that will not is released.
|
|
206
|
+
await browser.reconcile(harness, () => true, context); // settles what a dead process left
|
|
207
|
+
// A conversation selects the extension and writes its BrowserConfig in its creating commit (`browser.docs.Config`);
|
|
208
|
+
// when it ends: `await browser.release(conversation, "close", context)`.
|
|
209
|
+
// Before `harness.close()`: `await browser.drain(harness, context)`, so the releases reach the provider.
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
`createBrowserExtension` takes no key and sends nothing anywhere but the provider you give it. The options:
|
|
213
|
+
|
|
214
|
+
- `driver`: `stagehandDriver()`, or your own `DriverFactory`.
|
|
215
|
+
- `provider`: for example Browserbase from the run's env (`BROWSERBASE_API_KEY` or `BB_API_KEY`, the proxy URLs and the
|
|
216
|
+
project id), with your own metadata stamped on every session.
|
|
217
|
+
- `evidence`: a sink that files each read where your receipts already are.
|
|
218
|
+
- `onSession`: the host channel. It receives each session's row and, only there, the live-view URLs. Nothing in the run log, a
|
|
219
|
+
result or a log line carries them.
|
|
220
|
+
- `decisions`: `classifyPage` and `rankChunks`, answered with your judge. Absent, no page is classified and no find is ranked.
|
|
221
|
+
- `redact.values`: exact strings to scrub besides the built-in shapes.
|
|
222
|
+
- `section.addendum`: your text after the package's prompt section.
|
|
223
|
+
- `workspace`: where `browser_downloads` writes. Absent, that tool is not listed.
|
|
224
|
+
- `prices`: your session price (for example from `BROWSERBASE_USD_PER_MINUTE`). It prices the session meter, so each session
|
|
225
|
+
tool's result and each released session's record carry dollars. Without it the minutes are recorded unpriced.
|
|
226
|
+
|
|
227
|
+
Per conversation, the host writes a `BrowserConfig` (`label`, `run`, and the policy: proxies, verified, captcha, geolocation,
|
|
228
|
+
region, a raw context id, the session timeout, the idle release and the batch timeout; `DEFAULT_BROWSER_POLICY` holds the
|
|
229
|
+
package's defaults to spread and override) in the conversation's creating commit,
|
|
230
|
+
selects the extensions for it, and calls `handle.release(conversation, "close", ctx)` when the conversation ends. Releases run
|
|
231
|
+
as background tasks, which `waitForIdle` skips and closing the harness aborts: before it closes, a host calls
|
|
232
|
+
`handle.drain(harness, ctx, signal?)`, which resolves once none is live. At run open, after the extensions are installed and
|
|
233
|
+
before anything resumes, it calls `handle.reconcile(harness, isActive, ctx)`, and every session a dead process left is bound,
|
|
234
|
+
kept or released. The host wraps the tools (`handle.tools`) with its own policy: pause, call records, a result cap, media for
|
|
235
|
+
the route.
|
|
236
|
+
|
|
237
|
+
A host with its own provider implements `BrowserProvider`: `name`, `caps`, `create` (at most once, the tag stamped on the
|
|
238
|
+
provider's side), `findByTag`, `status`, `attach`, `release`, and optionally `liveView`, `recordings`, `downloads`, `fetch`
|
|
239
|
+
and `search`.
|
|
240
|
+
|
|
241
|
+
Two things to know before you give a model a browser:
|
|
242
|
+
|
|
243
|
+
- **What a model may reach is your decision.** `web_fetch` takes only absolute `http(s)` URLs with no credentials, and the
|
|
244
|
+
coding agent's built-in fetch refuses private addresses, but a provider's fetch service and a driven browser go wherever
|
|
245
|
+
their network goes. A host that must not let a model reach internal addresses restricts that network or the URLs it passes.
|
|
246
|
+
- **The Browserbase provider changes the process.** Its first call that needs the Browserbase client adds Browserbase's hosts to `NO_PROXY` and `no_proxy`, and
|
|
247
|
+
the first attach replaces `globalThis.WebSocket` with a wrapper that dials a bound credential proxy instead of the raw
|
|
248
|
+
connect URL. Both are process-wide. The wrapper passes every other URL through unchanged. Importing the package does
|
|
249
|
+
neither.
|
|
250
|
+
|
|
251
|
+
### Recording what the browsers show
|
|
252
|
+
|
|
253
|
+
`@parcha/pi-browser/recorder` screencasts each session over DevTools (a local Chrome, Browserbase and Kernel all speak it) and hands
|
|
254
|
+
`agentrun.recording/1`'s `frame` and `frame.gap` lines, with their JPEGs, to a sink you pass. It is read-only beside the session's own
|
|
255
|
+
connections, and it writes nothing itself.
|
|
256
|
+
|
|
257
|
+
```js
|
|
258
|
+
import { frameRecorder } from "@parcha/pi-browser/recorder";
|
|
259
|
+
|
|
260
|
+
const frames = frameRecorder({
|
|
261
|
+
clock: () => Date.now() - started, // ms since the recording started: every line's `t`
|
|
262
|
+
gen: () => generation, // optional: this process's generation, on every line
|
|
263
|
+
lastFrameAt: (session) => lastFrameT(session), // optional: where an earlier process's frames for a session stopped
|
|
264
|
+
sink: (line, blobs = {}) => { // blobs: sha256 hex -> JPEG bytes; the sink keeps blobs/<sha256>.jpg and adds `seq`
|
|
265
|
+
for (const [sha, bytes] of Object.entries(blobs)) fs.writeFileSync(`blobs/${sha}.jpg`, bytes);
|
|
266
|
+
events.write(JSON.stringify({ ...line, seq: seq++ }) + "\n");
|
|
267
|
+
},
|
|
268
|
+
});
|
|
269
|
+
const browser = createBrowserExtension({ provider: ({ conversationId }) => frames.watch(provider, conversationId), driver, evidence });
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
A session is captured from the moment it is created or reattached (so after a kill the same session resumes by itself). The lines:
|
|
273
|
+
|
|
274
|
+
```json
|
|
275
|
+
{"channel":"live","source":"browser","kind":"frame","gen":1,"t":20123,"conv":3,"data":{"session":"bb_4e1a","provider":"browserbase","w":800,"h":500,"mime":"image/jpeg"},"blobs":["9c0e..."]}
|
|
276
|
+
{"channel":"live","source":"browser","kind":"frame.gap","gen":2,"t":26004,"conv":3,"data":{"session":"bb_4e1a","from":21004,"reason":"process_killed"}}
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
- Capture is JPEG at quality 60, at most 800 px wide and 10 frames a second per session (the newest frame wins), of the page the agent is using.
|
|
280
|
+
Every line carries the `conv` of the conversation that owns the session (given to `watch`, or read from the lease tag); a session whose
|
|
281
|
+
conversation cannot be told is not recorded.
|
|
282
|
+
- A gap is written, never filled: `process_killed` when a session this process did not create is taken up and `lastFrameAt` knows its last
|
|
283
|
+
frame, `session_released` when the session is released, `credential_on_page` while a credential is on the page.
|
|
284
|
+
- **No frame is kept while a credential or a code is on the page**, and anything the recorder cannot read counts as one being there. A frame is
|
|
285
|
+
judged against the page the moment it arrives (one check, standing for the page at its capture) and again when its turn to be kept comes (both
|
|
286
|
+
checks go through one pace per session: each is sent at least 50 ms after the last, so a session sends at most 20 `Runtime.evaluate` in any
|
|
287
|
+
second, however fast frames arrive); a credential seen in either drops it, and a frame held across a navigation or a move to another page is not kept. The check looks at password
|
|
288
|
+
fields, `one-time-code` fields and fields named like a code (name, id, `<label>`, `aria-labelledby`, `aria-label` or placeholder says otp, totp,
|
|
289
|
+
2fa, passcode, ...) that hold a value, in the page, open shadow roots and same-origin frames; a value typed and cleared between two checks is
|
|
290
|
+
still seen (the page keeps a flag, `window.__piFramesSecret`, set by the fields' own `input` events). A page that nests deeper than the check
|
|
291
|
+
reads (eight shadow roots or frames) and a visible frame whose content it cannot reach (another origin: a payment or sign-in widget) count as
|
|
292
|
+
a credential present; a frame with no area, or not displayed, is not a picture of anything and does not. A page that cannot be checked at all
|
|
293
|
+
is not recorded. The pause lasts until the page navigates and the check is clean; the gap says why in `data.detail` (`field`, `typed`,
|
|
294
|
+
`too_deep`, `unreadable_frame` or `host`). What no script in the page can see (a closed shadow root, a value set by script with no event) is the
|
|
295
|
+
host's to pause with `frames.pause(session)` (lifted with `frames.resume(session)`).
|
|
296
|
+
- A live-view URL is never recorded or asked for: the recorder reads only the session's DevTools socket and never writes its address.
|
|
297
|
+
- Lines reach the sink one at a time, in order. A sink that throws, rejects or does not answer within `sinkTimeoutMs` (5 s) cannot fail a browser
|
|
298
|
+
call: that line is dropped and counted in `frames.stats()`, and a frame that was not saved never becomes the point a later gap starts from.
|
|
299
|
+
- `frames.watch(...).release` ends the capture, and writes the `session_released` gap, once the provider has released the session: a release it
|
|
300
|
+
refuses leaves the capture running.
|
|
301
|
+
- **`frame.track`** (a WebM per session with an index) is made at export, from the recorded frames, by `exportFrameTracks`:
|
|
302
|
+
|
|
303
|
+
```js
|
|
304
|
+
import { exportFrameTracks } from "@parcha/pi-browser/recorder";
|
|
305
|
+
const tracks = await exportFrameTracks({ lines, readBlob: (sha256) => bytesOfBlob(sha256), endAt: recordingEndMs, fps: 10 });
|
|
306
|
+
for (const { line, blobs } of tracks) { /* line is the frame.track line; blobs holds the WebM and its index by sha256 */ }
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
One track per session that has a frame. The video is VP9 at a constant `fps` (default 10) on one canvas, the largest frame in even numbers (a smaller
|
|
310
|
+
frame is centred on it); each frame is shown until the next one, and while a gap lasts the video shows a slate: from the moment a
|
|
311
|
+
`credential_on_page` or `session_released` gap was written, and from the last frame the earlier process saved for a `process_killed` gap (nothing is
|
|
312
|
+
known after it). The track runs from the session's first frame to `endAt` (default: the last line, a lone frame lasting one frame's time). The line is
|
|
313
|
+
`{ kind: "frame.track", t: <the track's end>, conv, data: { session, fps, from, to }, blobs: [<webm sha256>, <index sha256>] }`; the index (JSON) lists every
|
|
314
|
+
frame with its `t` and its `ms` offset into the video, and every gap with `from`, `to`, `reason` and `detail`, so a viewer maps a time in the recording to a
|
|
315
|
+
time in the video (`t - from`). A frame whose blob is missing, does not hash to its name or is not a JPEG shows the slate and is reported in `skipped`.
|
|
316
|
+
The step starts `ffmpeg` (`ffmpeg` option: a path; default the one on the PATH) in a private temporary directory with `PATH`, `LANG`, `LC_ALL` and `HOME`
|
|
317
|
+
only, with fixed arguments and no URL, a timeout (`timeoutMs`, 120 s) and an `AbortSignal`; a failure is a `TrackExportError` (`ffmpeg_missing`,
|
|
318
|
+
`ffmpeg_failed`, `ffmpeg_timeout`, `aborted`) and writes nothing.
|
|
319
|
+
|
|
320
|
+
## How it compares
|
|
321
|
+
|
|
322
|
+
Our own bench, run by this package's authors with `gpt-6-luna` only, 3 samples per case, against `pi-agent-browser-native`
|
|
323
|
+
0.9.3 on the same prompts and model. Five cases are public-registry lookups (two behind walls, where abstaining is the right
|
|
324
|
+
answer); three are loopback fixtures. Treat it as ours, not independent.
|
|
325
|
+
|
|
326
|
+
- Local Chrome, 48 runs: no wrong answers from either; median $0.0013 a run against $0.0024, 6 tool calls against 9, 7 tool
|
|
327
|
+
errors in 180 calls against 85 in 260, and no process left running after a run, against a browser daemon left after each one.
|
|
328
|
+
- Browserbase, 30 runs: a tie on outcomes (5 correct, 10 abstentions, 0 wrong for each). This package's median was $0.0034 a
|
|
329
|
+
run against $0.0046, with more tool calls on the walled cases (16 against 12).
|
|
330
|
+
- A crash in the middle of a form submit is covered by neither: with a scripted model both submitted twice, and a resumed
|
|
331
|
+
model that was not told about the cut call repeated the submit in 0 of 10 runs for each.
|
|
332
|
+
- Much of the other arm's tool-error count is how luna calls that tool, not the extension. Another model may give other numbers.
|
|
333
|
+
|
|
334
|
+
## Development
|
|
335
|
+
|
|
336
|
+
```sh
|
|
337
|
+
npm run build -w @parcha/pi-browser
|
|
338
|
+
npm test -w @parcha/pi-browser # everything but the real-Chrome suites
|
|
339
|
+
CHROME_PATH=/path/to/chrome npm run test:chrome -w @parcha/pi-browser
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
The real-Chrome suites (`stagehand_real_chrome`, `cdp_local_chrome`, `effects-chrome`, `coding_agent_real_chrome`,
|
|
343
|
+
`readme_example`) skip with a typed reason where no Chrome can load Stagehand's extension, and fail instead under
|
|
344
|
+
`AGENTRUN_REQUIRE_LOCAL_CHROME=1`, which CI sets. The crash matrix (`test/custody.test.mjs`) SIGKILLs a child process at each
|
|
345
|
+
cut point of a session's life against the shared fake and reopens the run's SQLite file. The wire checks (`test/wire/`) plant
|
|
346
|
+
sentinel credentials in a fake provider and scan every byte a run produced. The suites run on Node 22 and 24.
|
|
347
|
+
|
|
348
|
+
Apache-2.0. Copyright 2026 Parcha Labs, Inc. `NOTICE` records the Stagehand (MIT) code this package copies: the Chrome launch
|
|
349
|
+
flags and the vendored facade.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import type { EvidenceSink } from "./core/evidence.js";
|
|
2
|
+
import type { WebBackup } from "./core/web.js";
|
|
3
|
+
export declare function findChrome(env?: NodeJS.ProcessEnv, exists?: (file: string) => boolean): string | null;
|
|
4
|
+
export declare function fileEvidenceSink(root: string, relativeTo: string): EvidenceSink;
|
|
5
|
+
/** Loopback, private, link-local, carrier-grade and multicast addresses, v4 and v6, v4-mapped included. */
|
|
6
|
+
export declare function isPrivateAddress(ip: string): boolean;
|
|
7
|
+
/** Answers `address` for any name: the address a request was checked against is the one it connects to. */
|
|
8
|
+
export declare const pinnedLookup: (address: string) => (_host: string, options: {
|
|
9
|
+
all?: boolean;
|
|
10
|
+
}, callback: (...args: any[]) => void) => void;
|
|
11
|
+
/** Public hosts only, so a page-steered agent never reaches the owner's private network: each redirect hop is resolved
|
|
12
|
+
* once, checked and dialled at that address. No cookies or credentials; at most 5 MiB. */
|
|
13
|
+
export declare function httpBackup(options?: {
|
|
14
|
+
lookup?: (host: string) => Promise<string[]>;
|
|
15
|
+
fetchImpl?: (url: URL, init: Record<string, unknown>) => Promise<Response>;
|
|
16
|
+
}): WebBackup;
|