@kana-ai/edgar-ext-browserbase 0.0.0-stage → 0.1.0
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/LICENSE +202 -0
- package/README.md +114 -2
- package/dist/src/api/client.d.ts +17 -0
- package/dist/src/api/client.js +40 -0
- package/dist/src/api/failures.d.ts +10 -0
- package/dist/src/api/failures.js +36 -0
- package/dist/src/index.d.ts +93 -0
- package/dist/src/index.js +16 -0
- package/dist/src/schemas/browserbase.d.ts +83 -0
- package/dist/src/schemas/browserbase.js +46 -0
- package/dist/src/schemas/config.d.ts +20 -0
- package/dist/src/schemas/config.js +10 -0
- package/dist/src/schemas/tools.d.ts +148 -0
- package/dist/src/schemas/tools.js +76 -0
- package/dist/src/tools/contexts.d.ts +14 -0
- package/dist/src/tools/contexts.js +35 -0
- package/dist/src/tools/evidence.d.ts +37 -0
- package/dist/src/tools/evidence.js +70 -0
- package/dist/src/tools/sessions.d.ts +60 -0
- package/dist/src/tools/sessions.js +110 -0
- package/edgar-extension.json +129 -0
- package/package.json +41 -3
- package/schemas/config.json +25 -0
- package/schemas/create_context.in.json +10 -0
- package/schemas/create_context.out.json +10 -0
- package/schemas/create_session.in.json +24 -0
- package/schemas/create_session.out.json +19 -0
- package/schemas/delete_context.in.json +11 -0
- package/schemas/delete_context.out.json +13 -0
- package/schemas/end_session.in.json +11 -0
- package/schemas/end_session.out.json +26 -0
- package/schemas/list_sessions.in.json +10 -0
- package/schemas/list_sessions.out.json +35 -0
- package/schemas/session_downloads.in.json +11 -0
- package/schemas/session_downloads.out.json +33 -0
- package/schemas/session_logs.in.json +11 -0
- package/schemas/session_logs.out.json +32 -0
- package/schemas/session_replay.in.json +11 -0
- package/schemas/session_replay.out.json +35 -0
- package/schemas/session_state.in.json +11 -0
- package/schemas/session_state.out.json +26 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Kana.ai
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
|
202
|
+
|
package/README.md
CHANGED
|
@@ -1,3 +1,115 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kana-ai/edgar-ext-browserbase
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Browserbase extension of EDGAR. It starts, reads and ends cloud browser sessions, reads their logs, replay and downloads as evidence, and keeps signed-in state in contexts. A stage calls its tools as `browserbase__<tool>`. The extension is opt-in: `edgar init` does not turn it on, because it needs a key.
|
|
4
|
+
|
|
5
|
+
The extension calls the REST API with `fetch`, as the GitHub extension does. The `@browserbasehq/sdk` package would add a dependency and save no lines.
|
|
6
|
+
|
|
7
|
+
## Tools
|
|
8
|
+
|
|
9
|
+
| Tool | Input | Output | Endpoint |
|
|
10
|
+
| ------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------- |
|
|
11
|
+
| `create_session` | optional `context_id`, `keep_alive`, `timeout_seconds`, `record`, `proxies` | `session_id`, `connect_url_file`, `live_view_url`, `expires_at` | `POST /v1/sessions`, `GET /v1/sessions/{id}/debug` |
|
|
12
|
+
| `session_state` | `session_id` | `session_id`, `status`, `started_at`, `ended_at`, `expires_at`, `context_id` | `GET /v1/sessions/{id}` |
|
|
13
|
+
| `end_session` | `session_id` | the same as `session_state` | `POST /v1/sessions/{id}` with `REQUEST_RELEASE` |
|
|
14
|
+
| `list_sessions` | optional `status` | `sessions`: each as `session_state` | `GET /v1/sessions` |
|
|
15
|
+
| `session_logs` | `session_id` | `count`, `logs`: `method`, `page_id`, `timestamp` | `GET /v1/sessions/{id}/logs` |
|
|
16
|
+
| `session_replay` | `session_id` | `url`, `pages`: `page_id`, `url`, `start_ms`, `end_ms` | `GET /v1/sessions/{id}/replays` |
|
|
17
|
+
| `session_downloads` | `session_id` | `total`, `downloads`: `id`, `filename`, `mime_type`, `size` | `GET /v1/downloads?sessionId=` |
|
|
18
|
+
| `create_context` | optional `name` | `context_id` | `POST /v1/contexts` |
|
|
19
|
+
| `delete_context` | `context_id` | `context_id`, `deleted` | `DELETE /v1/contexts/{id}` |
|
|
20
|
+
|
|
21
|
+
- `create_session` is a side effect with no undo. A session ends at its timeout, or sooner with `end_session`. Each session costs at least one browser minute.
|
|
22
|
+
- The CDP URL of the browser is not in the output. Anyone who has it controls the browser until the session ends, and EDGAR stores each output, shows it on the run page and gives it to the next stage. The tool writes the URL to the file `connect_url_file` in the run's sandbox, `/tmp/browserbase/<session_id>.cdp`, which is not in the repository. A command in the same run reads the file, such as a Playwright script that calls `chromium.connectOverCDP(readFileSync(path, "utf8"))`. Do not print the URL, and do not put it in a comment, a card or a log line.
|
|
23
|
+
- `create_session` holds `sandbox:write` for that one file. `connect_url_file` is `null` when the sandbox refuses the write, such as a call with no sandbox. The tool still returns `done` with `session_id`, so the stage can end the session with `end_session`.
|
|
24
|
+
- `live_view_url` opens a live view of the browser for a person. It is `null` when the read of `GET /v1/sessions/{id}/debug` fails (an error answer, a network error, or an answer with no URL). The tool still returns `done` with `session_id`, because the session is billed once the POST answers: the stage can end it with `end_session`, and a retry does not start a second session.
|
|
25
|
+
- With `keep_alive` off, the session ends when the last CDP client disconnects. In the smoke test, the session was `COMPLETED` five seconds after its start.
|
|
26
|
+
- `end_session` on a session that already ended answers its current status.
|
|
27
|
+
- `list_sessions` reads the one page that the API answers.
|
|
28
|
+
- `session_logs` returns the CDP method of each entry, at most 200. The full entries hold request and response bodies, which can hold page data.
|
|
29
|
+
- `session_replay` returns the dashboard URL of the replay, and the HLS playlist URL of each page. A playlist URL needs the key in `X-BB-API-Key`.
|
|
30
|
+
- `session_downloads` reads up to 100 downloads.
|
|
31
|
+
- `delete_context` is a side effect with no undo: the cookies and storage of the context are gone.
|
|
32
|
+
- The REST API has no screenshot call. To take one, drive the browser through the URL in `connect_url_file`.
|
|
33
|
+
|
|
34
|
+
## Configuration
|
|
35
|
+
|
|
36
|
+
```toml
|
|
37
|
+
[extensions.browserbase]
|
|
38
|
+
timeout_seconds = 300 # the default session timeout, from 60 to 21600; a tool input can set its own
|
|
39
|
+
keep_alive = false # keep the session after the last CDP client disconnects
|
|
40
|
+
record = true # record the session for session_replay
|
|
41
|
+
region = "us-west-2" # optional: us-west-2, us-east-1, eu-central-1 or ap-southeast-1
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
A stage that opens a browser for the next stage, which drives it through the file `connect_url_file`:
|
|
45
|
+
|
|
46
|
+
```toml
|
|
47
|
+
[stages.browser]
|
|
48
|
+
needs = ["investigate"]
|
|
49
|
+
tool = "browserbase__create_session"
|
|
50
|
+
input = { context_id = "stages.investigate.output.context_id" }
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## Secrets
|
|
54
|
+
|
|
55
|
+
- `BROWSERBASE_API_KEY`: a key from the Browserbase settings page. It goes in the `X-BB-API-Key` header and reaches only `api.browserbase.com`.
|
|
56
|
+
- `BROWSERBASE_PROJECT_ID`: the project that owns the sessions and contexts. `GET /v1/projects` lists the projects of a key.
|
|
57
|
+
|
|
58
|
+
## Errors
|
|
59
|
+
|
|
60
|
+
One table in `src/api/failures.ts` maps each answer to an outcome. `cause` holds the HTTP status, Browserbase's `code` or `error` name, and its `message`. Each failure text has the key and the project id removed.
|
|
61
|
+
|
|
62
|
+
| Answer | Outcome |
|
|
63
|
+
| ---------------------- | -------------------------------------------------------- |
|
|
64
|
+
| 400, 422 | `invalid` |
|
|
65
|
+
| 401 | `unauthenticated` |
|
|
66
|
+
| 402, 403 | `forbidden` |
|
|
67
|
+
| 404, 410 | `not_found` |
|
|
68
|
+
| 429 | `rate_limited`; waits for `Retry-After`, else one minute |
|
|
69
|
+
| 5xx and network errors | `provider_unavailable` |
|
|
70
|
+
| Any other status | `tool_error` |
|
|
71
|
+
|
|
72
|
+
A 429 comes when the project has all its concurrent browsers, or made too many sessions in one minute. `x-ratelimit-reset` counts seconds from now, so the table reads `Retry-After` only.
|
|
73
|
+
|
|
74
|
+
## Limits
|
|
75
|
+
|
|
76
|
+
A 429 reads `Retry-After` with the SDK's `retry_after` scheme, and reports a used-up limit for the source `api.browserbase.com` until the time it names, else for one minute. A success reports no limit, because Browserbase sends no count of the calls left. The operator sees the source on the console's Limits page and on `GET /api/limits`. While the source has none left, EDGAR does not start a stage whose tool has `network:api.browserbase.com`, and records `waited_for_limit` until the reset.
|
|
77
|
+
|
|
78
|
+
## Build and test
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
pnpm build # writes edgar-extension.json and schemas/
|
|
82
|
+
pnpm test # unit tests with a mock Browserbase, no network
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The tests replay answers recorded from the real API. The CDP, Selenium and live view URLs, the signing key and the key are not in them. `edgar-extension.json` and `schemas/` are committed: a change to them in a diff is a change to what a person approves.
|
|
86
|
+
|
|
87
|
+
## Validation
|
|
88
|
+
|
|
89
|
+
These commands ran on 2026-11-10, from the repository root unless a step says otherwise.
|
|
90
|
+
|
|
91
|
+
| Command | Exit | Result |
|
|
92
|
+
| ----------------------------------------------------------------------------------------------------------------------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------ |
|
|
93
|
+
| `pnpm install` | 0 | The lockfile lists `@kana-ai/edgar-ext-browserbase`. |
|
|
94
|
+
| `pnpm -C packages/extensions/ext-browserbase build` | 0 | Wrote `edgar-extension.json` and 19 schema files. |
|
|
95
|
+
| `pnpm -C packages/extensions/ext-browserbase check-types` | 0 | |
|
|
96
|
+
| `pnpm -C packages/extensions/ext-browserbase lint` | 0 | 0 warnings, 0 errors. |
|
|
97
|
+
| `pnpm -C packages/extensions/ext-browserbase format:check` | 0 | |
|
|
98
|
+
| `pnpm -C packages/extensions/ext-browserbase test` | 0 | 58 tests, 0 failures. Each test failed once with its behavior removed. |
|
|
99
|
+
| `set -a; . ~/.edgar-secrets/browserbase.env; set +a`, `GET /v1/projects` for the project id, then one call of each tool's `execute` | 0 | All 9 tools `done` against the real API, with a page opened over the CDP URL; 401, 404 and 400 answers recorded for the tests. |
|
|
100
|
+
| `edgar extensions approve demo browserbase --project <scratch project>` | 0 | |
|
|
101
|
+
| `edgar check --project <scratch project>` | 0 | 0 errors. |
|
|
102
|
+
| `edgar start --project <scratch project>`, stopped with SIGINT | 0 | A card started a workflow whose one stage called `browserbase__list_sessions` through the runtime; the run ended `done`. |
|
|
103
|
+
|
|
104
|
+
## Not in this version
|
|
105
|
+
|
|
106
|
+
- Uploads: a file for a session comes from the sandbox, and a tool cannot send it yet.
|
|
107
|
+
- Browser extensions: an uploaded Chrome extension is set up once by a person.
|
|
108
|
+
- Projects: one project per key is enough for a stage; the project id is a secret.
|
|
109
|
+
- Fetch and Search: the TinyFish extension has these tools.
|
|
110
|
+
- Agents and runs: the TinyFish extension runs a web agent on a goal.
|
|
111
|
+
- Agent Identity, Functions and the Model Gateway: they run code and models on Browserbase, not a browser for a stage.
|
|
112
|
+
|
|
113
|
+
## Shortcuts
|
|
114
|
+
|
|
115
|
+
- shortcut: the host is fixed, so a test or self-hosted endpoint is not configurable; the network policy refuses any host outside the manifest. `[extensions.browserbase] hosts` can add a host, but the extension has no setting for its endpoint. Upgrade with such a setting.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
import { type Ctx, type Failure, type Result } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import type { z } from "zod";
|
|
3
|
+
/** The secret every Browserbase call sends, as `X-BB-API-Key`. */
|
|
4
|
+
export declare const KEY = "BROWSERBASE_API_KEY";
|
|
5
|
+
/** The project that owns the sessions and contexts. */
|
|
6
|
+
export declare const PROJECT = "BROWSERBASE_PROJECT_ID";
|
|
7
|
+
/** The host every Browserbase call goes to. */
|
|
8
|
+
export declare const HOST: "api.browserbase.com";
|
|
9
|
+
/** The secrets and the capability of each tool. */
|
|
10
|
+
export declare const apiAccess: {
|
|
11
|
+
readonly secrets: readonly ["BROWSERBASE_API_KEY", "BROWSERBASE_PROJECT_ID"];
|
|
12
|
+
readonly capabilities: readonly ["network:api.browserbase.com"];
|
|
13
|
+
};
|
|
14
|
+
/** The answer of one Browserbase call: the parsed body, or the failure it maps to. */
|
|
15
|
+
export type Reply<T> = Result<T, Failure>;
|
|
16
|
+
/** Calls the Browserbase API with the call's key and parses the answer with `schema`; an empty answer parses as `null`. */
|
|
17
|
+
export declare function browserbase<T>(ctx: Ctx<typeof KEY | typeof PROJECT>, method: "GET" | "POST" | "DELETE", path: string, schema: z.ZodType<T>, body?: Readonly<Record<string, unknown>>): Promise<Reply<T>>;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
import { attemptAsync, err, failure, fetchFailure, ok, unwrapOr, } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { limits, mapFailure, redact } from "#api/failures";
|
|
3
|
+
/** The secret every Browserbase call sends, as `X-BB-API-Key`. */
|
|
4
|
+
export const KEY = "BROWSERBASE_API_KEY";
|
|
5
|
+
/** The project that owns the sessions and contexts. */
|
|
6
|
+
export const PROJECT = "BROWSERBASE_PROJECT_ID";
|
|
7
|
+
/** The host every Browserbase call goes to. */
|
|
8
|
+
export const HOST = limits.source;
|
|
9
|
+
/** The secrets and the capability of each tool. */
|
|
10
|
+
export const apiAccess = {
|
|
11
|
+
secrets: [KEY, PROJECT],
|
|
12
|
+
capabilities: [`network:${HOST}`],
|
|
13
|
+
};
|
|
14
|
+
/** Calls the Browserbase API with the call's key and parses the answer with `schema`; an empty answer parses as `null`. */
|
|
15
|
+
export async function browserbase(ctx, method, path, schema, body) {
|
|
16
|
+
const key = ctx.secrets.get(KEY);
|
|
17
|
+
const secrets = [key, ctx.secrets.get(PROJECT)];
|
|
18
|
+
const context = `browserbase ${method} ${path.split("?")[0] ?? ""}`;
|
|
19
|
+
const sent = await attemptAsync(async () => await fetch(`https://${HOST}${path}`, {
|
|
20
|
+
method,
|
|
21
|
+
signal: ctx.signal,
|
|
22
|
+
headers: {
|
|
23
|
+
"x-bb-api-key": key,
|
|
24
|
+
"user-agent": "edgar",
|
|
25
|
+
...(body === undefined ? {} : { "content-type": "application/json" }),
|
|
26
|
+
},
|
|
27
|
+
...(body === undefined ? {} : { body: JSON.stringify(body) }),
|
|
28
|
+
}), (caught) => redact(fetchFailure(caught, ctx.signal, context), secrets));
|
|
29
|
+
if (!sent.ok)
|
|
30
|
+
return sent;
|
|
31
|
+
const response = sent.value;
|
|
32
|
+
const json = unwrapOr(await attemptAsync(async () => await response.json(), () => null), null);
|
|
33
|
+
if (!response.ok)
|
|
34
|
+
return err(redact(mapFailure(response.status, response.headers, json, context), secrets));
|
|
35
|
+
const parsed = schema.safeParse(json);
|
|
36
|
+
if (parsed.success)
|
|
37
|
+
return ok(parsed.data);
|
|
38
|
+
const fields = parsed.error.issues.map((issue) => issue.path.join(".")).join(", ");
|
|
39
|
+
return err(failure("tool_error", `${context}: unexpected answer`, { cause: `fields: ${fields}` }));
|
|
40
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import { type Failure } from "@kana-ai/edgar-sdk";
|
|
2
|
+
/** Browserbase answers a rate limit with `Retry-After`; its `x-ratelimit-reset` counts seconds from now, so only `Retry-After` is read. */
|
|
3
|
+
export declare const limits: {
|
|
4
|
+
readonly scheme: "retry_after";
|
|
5
|
+
readonly source: "api.browserbase.com";
|
|
6
|
+
};
|
|
7
|
+
/** Maps a Browserbase error answer to a failure, with the status, the vendor `code` or `error` name, and the `message` in `cause`; a rate limit reads only `Retry-After`, because `x-ratelimit-reset` counts seconds from now. */
|
|
8
|
+
export declare function mapFailure(status: number, headers: Headers, body: unknown, context: string, now?: number): Failure;
|
|
9
|
+
/** `failure` with every copy of each secret removed from its message and cause. */
|
|
10
|
+
export declare function redact(value: Failure, secrets: readonly string[]): Failure;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { vendorFailure } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { errorBody } from "#schemas/browserbase";
|
|
3
|
+
/** Browserbase answers a rate limit with `Retry-After`; its `x-ratelimit-reset` counts seconds from now, so only `Retry-After` is read. */
|
|
4
|
+
export const limits = {
|
|
5
|
+
scheme: "retry_after",
|
|
6
|
+
source: "api.browserbase.com",
|
|
7
|
+
};
|
|
8
|
+
const statusKinds = new Map([
|
|
9
|
+
[400, "invalid"],
|
|
10
|
+
[401, "unauthenticated"],
|
|
11
|
+
[402, "forbidden"],
|
|
12
|
+
[403, "forbidden"],
|
|
13
|
+
[404, "not_found"],
|
|
14
|
+
[410, "not_found"],
|
|
15
|
+
[422, "invalid"],
|
|
16
|
+
[429, "rate_limited"],
|
|
17
|
+
]);
|
|
18
|
+
/** Maps a Browserbase error answer to a failure, with the status, the vendor `code` or `error` name, and the `message` in `cause`; a rate limit reads only `Retry-After`, because `x-ratelimit-reset` counts seconds from now. */
|
|
19
|
+
export function mapFailure(status, headers, body, context, now = Date.now()) {
|
|
20
|
+
const vendor = errorBody.safeParse(body);
|
|
21
|
+
const name = vendor.success ? (vendor.data.code ?? vendor.data.error ?? "") : "";
|
|
22
|
+
const message = vendor.success ? (vendor.data.message ?? "") : "";
|
|
23
|
+
const head = `${String(status)} ${name}`.trim();
|
|
24
|
+
const cause = message === "" ? head : `${head}: ${message}`;
|
|
25
|
+
const kind = status >= 500 ? "provider_unavailable" : (statusKinds.get(status) ?? "tool_error");
|
|
26
|
+
return vendorFailure(kind, context, cause, headers, limits, now);
|
|
27
|
+
}
|
|
28
|
+
/** `failure` with every copy of each secret removed from its message and cause. */
|
|
29
|
+
export function redact(value, secrets) {
|
|
30
|
+
const clean = (text) => secrets.reduce((out, secret) => (secret === "" ? out : out.replaceAll(secret, "[redacted]")), text);
|
|
31
|
+
return {
|
|
32
|
+
...value,
|
|
33
|
+
message: clean(value.message),
|
|
34
|
+
...(value.cause === undefined ? {} : { cause: clean(value.cause) }),
|
|
35
|
+
};
|
|
36
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
/** Every tool of the Browserbase extension, by the name the manifest gives it. */
|
|
2
|
+
export declare const tools: {
|
|
3
|
+
create_context: import("@kana-ai/edgar-sdk").Tool<{
|
|
4
|
+
name?: string | undefined;
|
|
5
|
+
}, {
|
|
6
|
+
context_id: string;
|
|
7
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
8
|
+
delete_context: import("@kana-ai/edgar-sdk").Tool<{
|
|
9
|
+
context_id: string;
|
|
10
|
+
}, {
|
|
11
|
+
context_id: string;
|
|
12
|
+
deleted: boolean;
|
|
13
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
14
|
+
create_session: import("@kana-ai/edgar-sdk").Tool<{
|
|
15
|
+
context_id?: string | undefined;
|
|
16
|
+
keep_alive?: boolean | undefined;
|
|
17
|
+
timeout_seconds?: number | undefined;
|
|
18
|
+
record?: boolean | undefined;
|
|
19
|
+
proxies?: boolean | undefined;
|
|
20
|
+
}, {
|
|
21
|
+
session_id: string;
|
|
22
|
+
connect_url_file: string | null;
|
|
23
|
+
live_view_url: string | null;
|
|
24
|
+
expires_at: string;
|
|
25
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
26
|
+
session_state: import("@kana-ai/edgar-sdk").Tool<{
|
|
27
|
+
session_id: string;
|
|
28
|
+
}, {
|
|
29
|
+
session_id: string;
|
|
30
|
+
status: "COMPLETED" | "ERROR" | "PENDING" | "RUNNING" | "TIMED_OUT";
|
|
31
|
+
started_at: string;
|
|
32
|
+
ended_at: string | null;
|
|
33
|
+
expires_at: string;
|
|
34
|
+
context_id: string | null;
|
|
35
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
36
|
+
end_session: import("@kana-ai/edgar-sdk").Tool<{
|
|
37
|
+
session_id: string;
|
|
38
|
+
}, {
|
|
39
|
+
session_id: string;
|
|
40
|
+
status: "COMPLETED" | "ERROR" | "PENDING" | "RUNNING" | "TIMED_OUT";
|
|
41
|
+
started_at: string;
|
|
42
|
+
ended_at: string | null;
|
|
43
|
+
expires_at: string;
|
|
44
|
+
context_id: string | null;
|
|
45
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
46
|
+
list_sessions: import("@kana-ai/edgar-sdk").Tool<{
|
|
47
|
+
status?: "COMPLETED" | "ERROR" | "PENDING" | "RUNNING" | "TIMED_OUT" | undefined;
|
|
48
|
+
}, {
|
|
49
|
+
sessions: {
|
|
50
|
+
session_id: string;
|
|
51
|
+
status: "COMPLETED" | "ERROR" | "PENDING" | "RUNNING" | "TIMED_OUT";
|
|
52
|
+
started_at: string;
|
|
53
|
+
ended_at: string | null;
|
|
54
|
+
expires_at: string;
|
|
55
|
+
context_id: string | null;
|
|
56
|
+
}[];
|
|
57
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
58
|
+
session_logs: import("@kana-ai/edgar-sdk").Tool<{
|
|
59
|
+
session_id: string;
|
|
60
|
+
}, {
|
|
61
|
+
count: number;
|
|
62
|
+
logs: {
|
|
63
|
+
method: string;
|
|
64
|
+
page_id: number;
|
|
65
|
+
timestamp: number | null;
|
|
66
|
+
}[];
|
|
67
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
68
|
+
session_replay: import("@kana-ai/edgar-sdk").Tool<{
|
|
69
|
+
session_id: string;
|
|
70
|
+
}, {
|
|
71
|
+
url: string;
|
|
72
|
+
pages: {
|
|
73
|
+
page_id: string;
|
|
74
|
+
url: string;
|
|
75
|
+
start_ms: number;
|
|
76
|
+
end_ms: number;
|
|
77
|
+
}[];
|
|
78
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
79
|
+
session_downloads: import("@kana-ai/edgar-sdk").Tool<{
|
|
80
|
+
session_id: string;
|
|
81
|
+
}, {
|
|
82
|
+
total: number;
|
|
83
|
+
downloads: {
|
|
84
|
+
id: string;
|
|
85
|
+
filename: string;
|
|
86
|
+
mime_type: string;
|
|
87
|
+
size: number;
|
|
88
|
+
}[];
|
|
89
|
+
}, "BROWSERBASE_API_KEY" | "BROWSERBASE_PROJECT_ID">;
|
|
90
|
+
};
|
|
91
|
+
/** The Browserbase extension: cloud browser sessions, their evidence, and contexts. */
|
|
92
|
+
declare const _default: import("@kana-ai/edgar-sdk").Extension;
|
|
93
|
+
export default _default;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { defineExtension } from "@kana-ai/edgar-sdk";
|
|
2
|
+
import { HOST, KEY, PROJECT, apiAccess } from "#api/client";
|
|
3
|
+
import { config } from "#schemas/config";
|
|
4
|
+
import { contextTools } from "#tools/contexts";
|
|
5
|
+
import { evidenceTools } from "#tools/evidence";
|
|
6
|
+
import { sessionTools } from "#tools/sessions";
|
|
7
|
+
/** Every tool of the Browserbase extension, by the name the manifest gives it. */
|
|
8
|
+
export const tools = { ...sessionTools, ...evidenceTools, ...contextTools };
|
|
9
|
+
/** The Browserbase extension: cloud browser sessions, their evidence, and contexts. */
|
|
10
|
+
export default defineExtension({
|
|
11
|
+
name: "browserbase",
|
|
12
|
+
config,
|
|
13
|
+
secrets: { [KEY]: { hosts: [HOST] }, [PROJECT]: { hosts: [HOST] } },
|
|
14
|
+
capabilities: [...apiAccess.capabilities, "sandbox:write"],
|
|
15
|
+
tools,
|
|
16
|
+
});
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/** The status of a session. */
|
|
3
|
+
export declare const sessionStatus: z.ZodEnum<{
|
|
4
|
+
COMPLETED: "COMPLETED";
|
|
5
|
+
ERROR: "ERROR";
|
|
6
|
+
PENDING: "PENDING";
|
|
7
|
+
RUNNING: "RUNNING";
|
|
8
|
+
TIMED_OUT: "TIMED_OUT";
|
|
9
|
+
}>;
|
|
10
|
+
/** A session as the API answers it, with the fields the tools read. */
|
|
11
|
+
export declare const session: z.ZodObject<{
|
|
12
|
+
id: z.ZodString;
|
|
13
|
+
status: z.ZodEnum<{
|
|
14
|
+
COMPLETED: "COMPLETED";
|
|
15
|
+
ERROR: "ERROR";
|
|
16
|
+
PENDING: "PENDING";
|
|
17
|
+
RUNNING: "RUNNING";
|
|
18
|
+
TIMED_OUT: "TIMED_OUT";
|
|
19
|
+
}>;
|
|
20
|
+
startedAt: z.ZodString;
|
|
21
|
+
endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
22
|
+
expiresAt: z.ZodString;
|
|
23
|
+
keepAlive: z.ZodBoolean;
|
|
24
|
+
contextId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
25
|
+
region: z.ZodString;
|
|
26
|
+
}, z.core.$strip>;
|
|
27
|
+
/** The answer of `POST /v1/sessions`: the session and its CDP URL. */
|
|
28
|
+
export declare const createdSession: z.ZodObject<{
|
|
29
|
+
id: z.ZodString;
|
|
30
|
+
status: z.ZodEnum<{
|
|
31
|
+
COMPLETED: "COMPLETED";
|
|
32
|
+
ERROR: "ERROR";
|
|
33
|
+
PENDING: "PENDING";
|
|
34
|
+
RUNNING: "RUNNING";
|
|
35
|
+
TIMED_OUT: "TIMED_OUT";
|
|
36
|
+
}>;
|
|
37
|
+
startedAt: z.ZodString;
|
|
38
|
+
endedAt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
39
|
+
expiresAt: z.ZodString;
|
|
40
|
+
keepAlive: z.ZodBoolean;
|
|
41
|
+
contextId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
|
|
42
|
+
region: z.ZodString;
|
|
43
|
+
connectUrl: z.ZodString;
|
|
44
|
+
}, z.core.$strip>;
|
|
45
|
+
/** The answer of `GET /v1/sessions/{id}/debug`. */
|
|
46
|
+
export declare const liveUrls: z.ZodObject<{
|
|
47
|
+
debuggerFullscreenUrl: z.ZodString;
|
|
48
|
+
}, z.core.$strip>;
|
|
49
|
+
/** The answer of `GET /v1/sessions/{id}/logs`. */
|
|
50
|
+
export declare const logs: z.ZodArray<z.ZodObject<{
|
|
51
|
+
method: z.ZodString;
|
|
52
|
+
pageId: z.ZodNumber;
|
|
53
|
+
timestamp: z.ZodOptional<z.ZodNumber>;
|
|
54
|
+
}, z.core.$strip>>;
|
|
55
|
+
/** The answer of `GET /v1/sessions/{id}/replays`. */
|
|
56
|
+
export declare const replay: z.ZodObject<{
|
|
57
|
+
pages: z.ZodArray<z.ZodObject<{
|
|
58
|
+
pageId: z.ZodString;
|
|
59
|
+
url: z.ZodString;
|
|
60
|
+
startTimeMs: z.ZodNumber;
|
|
61
|
+
endTimeMs: z.ZodNumber;
|
|
62
|
+
}, z.core.$strip>>;
|
|
63
|
+
}, z.core.$strip>;
|
|
64
|
+
/** The answer of `GET /v1/downloads`. */
|
|
65
|
+
export declare const downloads: z.ZodObject<{
|
|
66
|
+
downloads: z.ZodArray<z.ZodObject<{
|
|
67
|
+
id: z.ZodString;
|
|
68
|
+
filename: z.ZodString;
|
|
69
|
+
mimeType: z.ZodString;
|
|
70
|
+
size: z.ZodNumber;
|
|
71
|
+
}, z.core.$strip>>;
|
|
72
|
+
total: z.ZodNumber;
|
|
73
|
+
}, z.core.$strip>;
|
|
74
|
+
/** The answer of `POST /v1/contexts`. */
|
|
75
|
+
export declare const createdContext: z.ZodObject<{
|
|
76
|
+
id: z.ZodString;
|
|
77
|
+
}, z.core.$strip>;
|
|
78
|
+
/** The body of an error answer. */
|
|
79
|
+
export declare const errorBody: z.ZodObject<{
|
|
80
|
+
code: z.ZodOptional<z.ZodString>;
|
|
81
|
+
error: z.ZodOptional<z.ZodString>;
|
|
82
|
+
message: z.ZodOptional<z.ZodString>;
|
|
83
|
+
}, z.core.$strip>;
|