@tangle-network/browser-agent-driver 0.36.2 → 0.36.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +72 -359
- package/dist/design/audit/score-types.d.ts +2 -1
- package/dist/design/audit/score-types.d.ts.map +1 -1
- package/dist/design/audit/score-types.js +2 -1
- package/dist/design/audit/score-types.js.map +1 -1
- package/package.json +3 -27
- package/skills/domain/amazon.com/SKILL.md +14 -0
- package/skills/domain/github.com/SKILL.md +15 -0
- package/skills/domain/linkedin.com/SKILL.md +14 -0
- package/skills/domain/stackoverflow.com/SKILL.md +13 -0
- package/skills/domain/wikipedia.org/SKILL.md +15 -0
- package/skills/macros/dismiss-cookie-banner.json +11 -0
- package/skills/macros/search-and-submit.json +13 -0
package/README.md
CHANGED
|
@@ -2,73 +2,41 @@
|
|
|
2
2
|
|
|
3
3
|
General-purpose agentic browser automation. Completes real user outcomes on any website — search, extract, fill forms, compare prices, navigate complex UIs.
|
|
4
4
|
|
|
5
|
-
**91.3% on WebVoyager (590 tasks, 15 sites) at $0.09/task.** 100% on held-out competitive bench. 95.7% on WebbBench-50 (excl. DataDome sites). Default model: `gpt-5.4`.
|
|
6
|
-
|
|
7
5
|
## Table of Contents
|
|
8
6
|
|
|
9
7
|
- [Install](#install)
|
|
10
8
|
- [Quick Start](#quick-start)
|
|
11
9
|
- [How It Works](#how-it-works)
|
|
12
10
|
- [Features](#features)
|
|
13
|
-
- [Vision + DOM Hybrid](#vision--dom-hybrid)
|
|
14
|
-
- [Stealth & Anti-Bot](#stealth--anti-bot)
|
|
15
|
-
- [CAPTCHA Solving](#captcha-solving)
|
|
16
|
-
- [Parallel Tab Execution](#parallel-tab-execution)
|
|
17
|
-
- [Multi-Model Orchestration](#multi-model-orchestration)
|
|
18
|
-
- [Design Audit](#design-audit)
|
|
19
|
-
- [Wallet & DeFi Testing](#wallet--defi-testing)
|
|
20
11
|
- [Configuration](#configuration)
|
|
21
12
|
- [CLI Reference](#cli-reference)
|
|
22
13
|
- [SDK / Library Usage](#sdk--library-usage)
|
|
23
|
-
- [
|
|
24
|
-
- [Drivers](#drivers)
|
|
14
|
+
- [Examples](#examples)
|
|
25
15
|
- [Benchmarks](#benchmarks)
|
|
16
|
+
- [Drivers](#drivers)
|
|
26
17
|
- [GitHub Action](#github-action)
|
|
18
|
+
- [Session Viewer](#session-viewer)
|
|
19
|
+
- [Agent Discovery](#agent-discovery)
|
|
27
20
|
- [Development](#development)
|
|
21
|
+
- [License](#license)
|
|
28
22
|
|
|
29
23
|
## Install
|
|
30
24
|
|
|
31
|
-
### CLI (recommended)
|
|
32
|
-
|
|
33
25
|
```bash
|
|
26
|
+
# CLI installer — installs the `bad` command, downloads Chromium, adds PATH (Node.js 20+)
|
|
34
27
|
curl -fsSL https://raw.githubusercontent.com/tangle-network/browser-agent-driver/main/scripts/install.sh | sh
|
|
35
|
-
```
|
|
36
28
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
Or via npm:
|
|
40
|
-
|
|
41
|
-
```bash
|
|
29
|
+
# or via npm
|
|
42
30
|
npm install -g @tangle-network/browser-agent-driver
|
|
43
31
|
npx playwright install chromium
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
Do not install the unscoped `bad` package from npm. It is unrelated to Tangle. The `bad` command is installed by `@tangle-network/browser-agent-driver`.
|
|
47
|
-
|
|
48
|
-
## Agent Discovery
|
|
49
|
-
|
|
50
|
-
Agents should read the product manifest before generating Browser Agent integration code:
|
|
51
|
-
|
|
52
|
-
- Manifest: https://tangle.tools/.well-known/tangle-browser-agent.json
|
|
53
|
-
- Product page: https://tangle.tools/services/browser-agent
|
|
54
|
-
- Scoped npm package: `@tangle-network/browser-agent-driver`
|
|
55
|
-
- CLI binary: `bad`
|
|
56
|
-
|
|
57
|
-
Safe discovery commands:
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
bad --help
|
|
61
|
-
bad run --help
|
|
62
|
-
bad snapshot --help
|
|
63
|
-
```
|
|
64
32
|
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
```bash
|
|
33
|
+
# as a library
|
|
68
34
|
pnpm add @tangle-network/browser-agent-driver
|
|
69
35
|
pnpm add -D playwright
|
|
70
36
|
```
|
|
71
37
|
|
|
38
|
+
Do not install the unscoped `bad` package from npm. It is unrelated to Tangle. The `bad` command is installed by `@tangle-network/browser-agent-driver`.
|
|
39
|
+
|
|
72
40
|
## Quick Start
|
|
73
41
|
|
|
74
42
|
### CLI
|
|
@@ -84,14 +52,6 @@ bad run --goal "Compare MacBook Air prices" --url https://apple.com \
|
|
|
84
52
|
|
|
85
53
|
# Test suite from case file
|
|
86
54
|
bad run --cases ./my-tests.json --concurrency 4
|
|
87
|
-
|
|
88
|
-
# Authenticated session
|
|
89
|
-
bad run --goal "Check account settings" --url https://app.example.com \
|
|
90
|
-
--storage-state .auth/session.json
|
|
91
|
-
|
|
92
|
-
# With proxy (residential or SOCKS5)
|
|
93
|
-
bad run --goal "Search hotels in Tokyo" --url https://booking.com \
|
|
94
|
-
--proxy http://user:pass@proxy.example.com:port
|
|
95
55
|
```
|
|
96
56
|
|
|
97
57
|
### SDK
|
|
@@ -107,7 +67,8 @@ const driver = new PlaywrightDriver(page)
|
|
|
107
67
|
const agent = new BrowserAgent({
|
|
108
68
|
driver,
|
|
109
69
|
config: {
|
|
110
|
-
model: '
|
|
70
|
+
model: 'gemini-2.5-flash',
|
|
71
|
+
provider: 'google',
|
|
111
72
|
observationMode: 'hybrid', // vision + DOM
|
|
112
73
|
plannerEnabled: true, // plan-then-execute
|
|
113
74
|
},
|
|
@@ -122,44 +83,6 @@ console.log(result.success, result.reason)
|
|
|
122
83
|
await browser.close()
|
|
123
84
|
```
|
|
124
85
|
|
|
125
|
-
### Config File
|
|
126
|
-
|
|
127
|
-
Create `bad.config.ts` (or `.js`, `.mjs`) in your project root:
|
|
128
|
-
|
|
129
|
-
```typescript
|
|
130
|
-
import { defineConfig } from '@tangle-network/browser-agent-driver'
|
|
131
|
-
|
|
132
|
-
export default defineConfig({
|
|
133
|
-
provider: 'openai',
|
|
134
|
-
model: 'gpt-5.4',
|
|
135
|
-
observationMode: 'hybrid',
|
|
136
|
-
plannerEnabled: true,
|
|
137
|
-
headless: true,
|
|
138
|
-
concurrency: 4,
|
|
139
|
-
maxTurns: 30,
|
|
140
|
-
outputDir: './test-results',
|
|
141
|
-
|
|
142
|
-
// Per-role model routing (Gen 28)
|
|
143
|
-
models: {
|
|
144
|
-
planner: { model: 'claude-opus-4-6', provider: 'anthropic' },
|
|
145
|
-
executor: { model: 'gpt-4.1-mini' },
|
|
146
|
-
verifier: { model: 'gpt-4.1-mini' },
|
|
147
|
-
supervisor: { model: 'gpt-5.4' },
|
|
148
|
-
},
|
|
149
|
-
|
|
150
|
-
// Parallel tabs for compound goals (Gen 21)
|
|
151
|
-
parallelTabs: { enabled: true, maxTabs: 3 },
|
|
152
|
-
|
|
153
|
-
// Proxy for anti-bot bypass
|
|
154
|
-
proxy: 'http://user:pass@proxy:port', // or set BAD_PROXY_URL env
|
|
155
|
-
|
|
156
|
-
// Supervisor for stuck detection
|
|
157
|
-
supervisor: { enabled: true, useVision: true },
|
|
158
|
-
})
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
Auto-detected by CLI and SDK. CLI flags override config values.
|
|
162
|
-
|
|
163
86
|
## How It Works
|
|
164
87
|
|
|
165
88
|
```
|
|
@@ -178,90 +101,27 @@ Recovery is automatic: cookie consent, modal blockers, A-B-A-B oscillation loops
|
|
|
178
101
|
|
|
179
102
|
## Features
|
|
180
103
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
- **`dom`** — a11y tree only (fastest, cheapest)
|
|
187
|
-
- **`vision`** — screenshot + coordinates only
|
|
188
|
-
- **`hybrid`** — both (default for benchmarks, most reliable)
|
|
189
|
-
|
|
190
|
-
### Stealth & Anti-Bot
|
|
191
|
-
|
|
192
|
-
Built-in evasion for Cloudflare, Akamai, and most WAF systems:
|
|
193
|
-
|
|
194
|
-
- **System Chrome** (`channel: 'chrome'`) — real TLS/JA3/HTTP2 fingerprint, not bundled Chromium
|
|
195
|
-
- **Patchright** — Playwright fork that patches CDP protocol leaks
|
|
196
|
-
- **Mouse humanization** — Bezier curve movement (8-15 points), gaussian click offset
|
|
197
|
-
- **Browser fingerprint** — navigator.webdriver, plugins, languages, WebGL, canvas noise, screenX/Y fix
|
|
198
|
-
- **GPU rendering** — `--use-gl=desktop` for real WebGL fingerprint
|
|
199
|
-
- **Resource blocking** — 99+ analytics/tracking domains blocked
|
|
200
|
-
|
|
201
|
-
Unblocks 9/13 previously-blocked sites on WebbBench-50 with zero configuration.
|
|
202
|
-
|
|
203
|
-
### CAPTCHA Solving
|
|
204
|
-
|
|
205
|
-
Automatic CAPTCHA detection and solving during runs:
|
|
206
|
-
|
|
207
|
-
- **reCAPTCHA v2** — checkbox click + image grid solver (LLM vision-based)
|
|
208
|
-
- **Cloudflare Turnstile** — checkbox behavioral click
|
|
209
|
-
- **Google "unusual traffic"** — detected and solver attempted
|
|
210
|
-
|
|
211
|
-
```typescript
|
|
212
|
-
// Enabled by default. To configure:
|
|
213
|
-
{ captcha: { enabled: true, maxAttempts: 5 } }
|
|
214
|
-
```
|
|
215
|
-
|
|
216
|
-
### Parallel Tab Execution
|
|
217
|
-
|
|
218
|
-
For compound goals ("compare X vs Y", "find 5 items matching criteria"), the agent decomposes the goal and runs sub-tasks in parallel browser tabs.
|
|
219
|
-
|
|
220
|
-
```typescript
|
|
221
|
-
{
|
|
222
|
-
parallelTabs: { enabled: true, maxTabs: 3 },
|
|
223
|
-
}
|
|
224
|
-
```
|
|
225
|
-
|
|
226
|
-
The GoalDecomposer (1 cheap LLM call) classifies goals as simple or compound. Simple goals run as before. Compound goals get split into sub-goals, each running in its own tab via `Promise.all`, with results merged by the EvidenceMerger.
|
|
227
|
-
|
|
228
|
-
### Multi-Model Orchestration
|
|
229
|
-
|
|
230
|
-
Different agent roles can use different models for optimal cost/quality:
|
|
231
|
-
|
|
232
|
-
```typescript
|
|
233
|
-
{
|
|
234
|
-
models: {
|
|
235
|
-
planner: { model: 'claude-opus-4-6', provider: 'anthropic' }, // best reasoning
|
|
236
|
-
executor: { model: 'gpt-4.1-mini' }, // cheap, follows plans
|
|
237
|
-
verifier: { model: 'gpt-4.1-mini' }, // structured yes/no
|
|
238
|
-
supervisor: { model: 'gpt-5.4' }, // strategic recovery
|
|
239
|
-
},
|
|
240
|
-
}
|
|
241
|
-
```
|
|
242
|
-
|
|
243
|
-
Each role falls back to the main `model` when not configured. The planner needs top-tier reasoning; the executor just follows instructions.
|
|
104
|
+
- **Vision + DOM Hybrid** — the agent sees both a screenshot (SoM-labeled interactive elements) and the a11y tree (precise `@ref` IDs). Observation modes: `dom` (fastest), `vision`, `hybrid` (most reliable).
|
|
105
|
+
- **Stealth & Anti-Bot** — system Chrome (`channel: 'chrome'`, real TLS/JA3 fingerprint), Patchright (CDP leak patches), Bezier mouse humanization, fingerprint hardening (webdriver, WebGL, canvas noise, screenX/Y), 99+ analytics domains blocked. Unblocks most Cloudflare/Akamai WAF setups with zero configuration.
|
|
106
|
+
- **CAPTCHA Solving** — reCAPTCHA v2 (checkbox + vision-based grid solver), Cloudflare Turnstile, Google "unusual traffic". On by default: `{ captcha: { enabled: true, maxAttempts: 5 } }`.
|
|
107
|
+
- **Parallel Tab Execution** — compound goals ("compare X vs Y") are split by the GoalDecomposer (1 cheap LLM call) into sub-goals running in parallel tabs, merged by the EvidenceMerger: `{ parallelTabs: { enabled: true, maxTabs: 3 } }`.
|
|
108
|
+
- **Multi-Model Orchestration** — per-role model routing (`planner` / `executor` / `verifier` / `supervisor`) across `openai`, `anthropic`, `google`, `claude-code`, `codex-cli`, `zai-coding-plan`, `cli-bridge`, `sandbox-backend`. Roles fall back to the main `model` when not configured.
|
|
244
109
|
|
|
245
110
|
### Design Audit
|
|
246
111
|
|
|
247
112
|
Vision-powered design quality analysis with closed-loop improvement:
|
|
248
113
|
|
|
249
114
|
```bash
|
|
250
|
-
#
|
|
251
|
-
bad design-audit --url https://your-app.com
|
|
252
|
-
|
|
253
|
-
# Multi-page crawl with cross-page systemic detection
|
|
254
|
-
bad design-audit --url https://your-app.com --pages 10
|
|
255
|
-
|
|
256
|
-
# Auto-fix: dispatch findings to a coding agent
|
|
257
|
-
bad design-audit --url http://localhost:3000 --evolve claude-code --project-dir ~/my-app
|
|
115
|
+
bad design-audit --url https://your-app.com # audit any URL
|
|
116
|
+
bad design-audit --url https://your-app.com --pages 10 # multi-page crawl, systemic detection
|
|
117
|
+
bad design-audit --url http://localhost:3000 --evolve claude-code --project-dir ~/my-app # auto-fix
|
|
258
118
|
```
|
|
259
119
|
|
|
260
|
-
Reports rank **Top Fixes by ROI** — the highest-leverage changes scored by `(impact * blast / effort)`.
|
|
120
|
+
Reports rank **Top Fixes by ROI** — the highest-leverage changes scored by `(impact * blast / effort)`.
|
|
261
121
|
|
|
262
|
-
### Wallet & DeFi Testing
|
|
122
|
+
### Wallet & DeFi Testing (specialized niche)
|
|
263
123
|
|
|
264
|
-
|
|
124
|
+
A built-in MetaMask workflow for teams testing DeFi apps — a deliberate specialization, not the general-purpose path:
|
|
265
125
|
|
|
266
126
|
```bash
|
|
267
127
|
pnpm wallet:setup # download MetaMask
|
|
@@ -270,26 +130,40 @@ pnpm wallet:anvil # start Anvil mainnet fork (100 ETH + 10 WETH + 10k USDC)
|
|
|
270
130
|
pnpm wallet:validate # run wallet test suite
|
|
271
131
|
```
|
|
272
132
|
|
|
273
|
-
Supports connect, swap, supply workflows across Uniswap, Aave, SushiSwap, 1inch.
|
|
133
|
+
Supports connect, swap, supply workflows across Uniswap, Aave, SushiSwap, 1inch. See [the wallet guide](./docs/guides/wallet.md).
|
|
274
134
|
|
|
275
135
|
## Configuration
|
|
276
136
|
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
137
|
+
Create `bad.config.ts` (or `.js`, `.mjs`) in your project root:
|
|
138
|
+
|
|
139
|
+
```typescript
|
|
140
|
+
import { defineConfig } from '@tangle-network/browser-agent-driver'
|
|
141
|
+
|
|
142
|
+
export default defineConfig({
|
|
143
|
+
model: 'gemini-2.5-flash',
|
|
144
|
+
provider: 'google',
|
|
145
|
+
observationMode: 'hybrid',
|
|
146
|
+
plannerEnabled: true,
|
|
147
|
+
headless: true,
|
|
148
|
+
concurrency: 4,
|
|
149
|
+
maxTurns: 30,
|
|
150
|
+
outputDir: './test-results',
|
|
151
|
+
})
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
Auto-detected by CLI and SDK. CLI flags override config values.
|
|
155
|
+
|
|
156
|
+
The **default provider is credential-aware**: with no explicit `provider`, `bad` uses OpenAI when `OPENAI_API_KEY` is set and otherwise falls back to the keyless `claude-code` provider. The bench-validated default model is `gemini-2.5-flash` (Google) — see [Benchmarks](#benchmarks). Key options:
|
|
157
|
+
|
|
158
|
+
| Option | Default | Description |
|
|
159
|
+
|--------|---------|-------------|
|
|
160
|
+
| `provider` | credential-aware | `openai` if `OPENAI_API_KEY` set, else `claude-code` |
|
|
161
|
+
| `model` | per-provider | LLM model (`gemini-2.5-flash` is the bench-validated choice) |
|
|
162
|
+
| `observationMode` | `'dom'` | `'dom'`, `'vision'`, or `'hybrid'` |
|
|
163
|
+
| `plannerEnabled` | `false` | Plan-then-execute mode |
|
|
164
|
+
| `maxTurns` | `30` | Max turns per task |
|
|
165
|
+
| `proxy` | — | Proxy URL (also `BAD_PROXY_URL` env) |
|
|
166
|
+
| `models` | — | Per-role model overrides |
|
|
293
167
|
|
|
294
168
|
See [Configuration Reference](./docs/guides/configuration.md) for all options.
|
|
295
169
|
|
|
@@ -303,134 +177,39 @@ bad view <run-dir> # Open session viewer
|
|
|
303
177
|
bad competitive [options] # Head-to-head framework comparison
|
|
304
178
|
```
|
|
305
179
|
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
Deterministic, no-LLM DOM dump. Loads a URL, dismisses consent dialogs, waits for
|
|
309
|
-
the chosen network state, emits the accessibility-tree snapshot. Intended for CI
|
|
310
|
-
and downstream quality pipelines where the agentic loop is overkill.
|
|
311
|
-
|
|
312
|
-
```bash
|
|
313
|
-
bad snapshot --url https://example.com --json --out snap.json
|
|
314
|
-
bad snapshot --url http://localhost:3000 --wait domcontentloaded
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
| Flag | Description |
|
|
318
|
-
|------|-------------|
|
|
319
|
-
| `--url URL` | URL to snapshot (required) |
|
|
320
|
-
| `--json` | Emit structured JSON instead of human-readable text |
|
|
321
|
-
| `--out FILE` | Write to file instead of stdout |
|
|
322
|
-
| `--wait load\|domcontentloaded\|networkidle\|commit` | Playwright waitUntil. Default `networkidle` |
|
|
323
|
-
| `--timeout MS` | Per-action timeout. Default `15000` |
|
|
324
|
-
| `--no-dismiss-modals` | Skip consent/cookie dialog dismissal |
|
|
325
|
-
| `--headed` | Show the browser window (default headless) |
|
|
326
|
-
|
|
327
|
-
JSON shape: `{ schemaVersion, url, finalUrl, title, snapshot, timing, dismissed, errors }`.
|
|
328
|
-
Exits non-zero on navigation failure or aria-snapshot error.
|
|
329
|
-
|
|
330
|
-
### Report schema
|
|
331
|
-
|
|
332
|
-
`<sink>/report.json` carries a top-level `schemaVersion` field. The current
|
|
333
|
-
version is `"1"`. Consumers should verify this before destructuring. Adding an
|
|
334
|
-
optional field is non-breaking; the version bumps only on removed fields,
|
|
335
|
-
renamed fields, or changed value semantics.
|
|
336
|
-
|
|
337
|
-
### Run options
|
|
338
|
-
|
|
339
|
-
| Flag | Description |
|
|
340
|
-
|------|-------------|
|
|
341
|
-
| `--goal "..."` | Natural language goal |
|
|
342
|
-
| `--url URL` | Starting URL |
|
|
343
|
-
| `--cases file.json` | Test case file |
|
|
344
|
-
| `--mode fast-explore\|full-evidence` | Run mode |
|
|
345
|
-
| `--model MODEL` | LLM model |
|
|
346
|
-
| `--provider openai\|anthropic\|google` | LLM provider |
|
|
347
|
-
| `--observation-mode dom\|vision\|hybrid` | Observation mode |
|
|
348
|
-
| `--headless` | Run headless (default) |
|
|
349
|
-
| `--proxy URL` | Residential/SOCKS5/HTTP proxy |
|
|
350
|
-
| `--profile default\|stealth\|benchmark-webvoyager` | Launch profile |
|
|
351
|
-
| `--concurrency N` | Parallel cases |
|
|
352
|
-
| `--show-cursor` | Animated cursor overlay in screenshots |
|
|
353
|
-
| `--live` | Real-time SSE viewer |
|
|
180
|
+
Full flag reference (run modes, execution profiles, auth sessions, adaptive model routing): [docs/guides/cli.md](./docs/guides/cli.md).
|
|
354
181
|
|
|
355
182
|
## SDK / Library Usage
|
|
356
183
|
|
|
357
184
|
```typescript
|
|
358
185
|
import {
|
|
359
|
-
// Core
|
|
360
186
|
BrowserAgent,
|
|
361
187
|
PlaywrightDriver,
|
|
362
188
|
SteelDriver,
|
|
363
189
|
TestRunner,
|
|
364
|
-
|
|
365
|
-
// Config
|
|
190
|
+
MultiActorSession,
|
|
366
191
|
defineConfig,
|
|
367
|
-
|
|
368
|
-
|
|
192
|
+
DesignAuditor,
|
|
193
|
+
detectCaptcha,
|
|
194
|
+
solveCaptcha,
|
|
369
195
|
type AgentConfig,
|
|
370
196
|
type Scenario,
|
|
371
197
|
type AgentResult,
|
|
372
|
-
type Turn,
|
|
373
|
-
|
|
374
|
-
// Multi-actor (parallel users)
|
|
375
|
-
MultiActorSession,
|
|
376
|
-
|
|
377
|
-
// Design audit
|
|
378
|
-
runDesignAudit,
|
|
379
|
-
|
|
380
|
-
// CAPTCHA
|
|
381
|
-
detectCaptcha,
|
|
382
|
-
solveCaptcha,
|
|
383
198
|
} from '@tangle-network/browser-agent-driver'
|
|
384
199
|
```
|
|
385
200
|
|
|
386
|
-
|
|
201
|
+
## Examples
|
|
387
202
|
|
|
388
|
-
|
|
389
|
-
import { MultiActorSession } from '@tangle-network/browser-agent-driver'
|
|
203
|
+
Runnable recipes live in [`examples/`](./examples/README.md): SDK quickstart, authoring a bench task, replay-cache CI, the GitHub Action, and shareable run videos.
|
|
390
204
|
|
|
391
|
-
|
|
392
|
-
actors: {
|
|
393
|
-
admin: { storageState: '.auth/admin.json' },
|
|
394
|
-
user: {},
|
|
395
|
-
},
|
|
396
|
-
agentConfig: { model: 'gpt-5.4', observationMode: 'hybrid' },
|
|
397
|
-
})
|
|
398
|
-
|
|
399
|
-
// Sequential
|
|
400
|
-
await session.actor('admin').run({ goal: 'Create project', startUrl: '/admin' })
|
|
401
|
-
|
|
402
|
-
// Parallel
|
|
403
|
-
await session.parallel(
|
|
404
|
-
['admin', { goal: 'Monitor dashboard', startUrl: '/admin' }],
|
|
405
|
-
['user', { goal: 'Submit form', startUrl: '/app' }],
|
|
406
|
-
)
|
|
407
|
-
|
|
408
|
-
await session.close()
|
|
409
|
-
```
|
|
410
|
-
|
|
411
|
-
## Test Suites
|
|
205
|
+
## Benchmarks
|
|
412
206
|
|
|
413
|
-
|
|
414
|
-
import { TestRunner } from '@tangle-network/browser-agent-driver'
|
|
207
|
+
Current bench (2026-10-11, gemini-2.5-flash, headless, external oracle, 5-task competitive corpus × 3 reps + n=5 variance arm): **15/15 main + 10/10 arm, $0.0223/run, 17.9s wall, 30% replay-cache hit rate.** browser-use on the same corpus: 12/15 @ $0.0126/run. Cost ratio 1.8×, accepted asymptote 1.3–1.6× (1.0× would sacrifice extraction accuracy and the replay moat). Replay-cache reruns cost ~10–20% of a live run with zero decide calls. Full methodology: [docs/bench-2026-10-11-hillclimb-program.md](./docs/bench-2026-10-11-hillclimb-program.md); competitive evaluation: [docs/COMPETITIVE-EVAL.md](./docs/COMPETITIVE-EVAL.md).
|
|
415
208
|
|
|
416
|
-
|
|
417
|
-
driver,
|
|
418
|
-
config: { model: 'gpt-5.4', observationMode: 'hybrid' },
|
|
419
|
-
concurrency: 4,
|
|
420
|
-
})
|
|
209
|
+
Run it:
|
|
421
210
|
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
id: 'login',
|
|
425
|
-
goal: 'Log in with test@example.com / password123',
|
|
426
|
-
startUrl: 'https://app.example.com/login',
|
|
427
|
-
},
|
|
428
|
-
{
|
|
429
|
-
id: 'create-project',
|
|
430
|
-
goal: 'Create a new project called "Test Project"',
|
|
431
|
-
startUrl: 'https://app.example.com/projects',
|
|
432
|
-
},
|
|
433
|
-
])
|
|
211
|
+
```bash
|
|
212
|
+
pnpm bench:compete
|
|
434
213
|
```
|
|
435
214
|
|
|
436
215
|
## Drivers
|
|
@@ -451,40 +230,6 @@ const driver = await SteelDriver.create({
|
|
|
451
230
|
const agent = new BrowserAgent({ driver, config })
|
|
452
231
|
```
|
|
453
232
|
|
|
454
|
-
## Benchmarks
|
|
455
|
-
|
|
456
|
-
| Benchmark | Score | Cost | Notes |
|
|
457
|
-
|-----------|-------|------|-------|
|
|
458
|
-
| **WebVoyager** (590 tasks, 15 sites) | 91.3% | $0.09/task | Full run, Gen 25 |
|
|
459
|
-
| **Competitive** (10 real-web sites) | 100% | $0.03/task | Held-out, never optimized |
|
|
460
|
-
| **WebbBench-50** (50 diverse sites) | 88% raw, 95.7% excl. DataDome | — | Held-out generalization |
|
|
461
|
-
|
|
462
|
-
### Competitive position
|
|
463
|
-
|
|
464
|
-
| Agent | WebVoyager | Cost/task |
|
|
465
|
-
|-------|-----------|-----------|
|
|
466
|
-
| Surfer-2 | 97.1% | $1-5 |
|
|
467
|
-
| Magnitude | 93.9% | ~$0.10 |
|
|
468
|
-
| **bad** | **91.3%** | **$0.09** |
|
|
469
|
-
| OpenAI Operator | 87% | ChatGPT Pro |
|
|
470
|
-
|
|
471
|
-
### Running benchmarks
|
|
472
|
-
|
|
473
|
-
```bash
|
|
474
|
-
# WebVoyager full 590
|
|
475
|
-
node scripts/run-scenario-track.mjs \
|
|
476
|
-
--cases bench/external/webvoyager/cases.json \
|
|
477
|
-
--config bench/scenarios/configs/vision-hybrid.mjs \
|
|
478
|
-
--model gpt-5.4 --modes fast-explore --concurrency 5 \
|
|
479
|
-
--out agent-results/webvoyager-full
|
|
480
|
-
|
|
481
|
-
# Multi-rep validation (≥3 reps required for any claim)
|
|
482
|
-
node scripts/run-multi-rep.mjs \
|
|
483
|
-
--cases bench/scenarios/cases/my-cases.json \
|
|
484
|
-
--config bench/scenarios/configs/vision-hybrid.mjs \
|
|
485
|
-
--reps 3 --out agent-results/my-validation
|
|
486
|
-
```
|
|
487
|
-
|
|
488
233
|
## GitHub Action
|
|
489
234
|
|
|
490
235
|
```yaml
|
|
@@ -494,10 +239,9 @@ node scripts/run-multi-rep.mjs \
|
|
|
494
239
|
pages: 5
|
|
495
240
|
fail-on-score-below: '6.5'
|
|
496
241
|
evolve: claude-code
|
|
497
|
-
openai-api-key: ${{ secrets.OPENAI_API_KEY }}
|
|
498
242
|
```
|
|
499
243
|
|
|
500
|
-
Posts Top Fixes as a PR comment, uploads full report as artifact, optionally fails on score regressions.
|
|
244
|
+
Posts Top Fixes as a PR comment, uploads the full report as an artifact, optionally fails on score regressions.
|
|
501
245
|
|
|
502
246
|
## Session Viewer
|
|
503
247
|
|
|
@@ -505,53 +249,22 @@ Posts Top Fixes as a PR comment, uploads full report as artifact, optionally fai
|
|
|
505
249
|
bad view audit-results/stripe.com-1775502457141
|
|
506
250
|
```
|
|
507
251
|
|
|
508
|
-
Web UI with per-turn screenshots, action JSON, reasoning, element highlights.
|
|
509
|
-
|
|
510
|
-
### Shareable run videos
|
|
511
|
-
|
|
512
|
-
A run's `report.json` is a complete trace — per-turn screenshot, action, and reasoning — so it renders directly into a shareable video via [`run-capsule`](https://github.com/tangle-network/run-capsule), no extra capture step:
|
|
513
|
-
|
|
514
|
-
```bash
|
|
515
|
-
npx run-capsule --playwright agent-results/report.json --no-upload
|
|
516
|
-
# → screen.mp4 (real product frames, each captioned with the agent's 💭 reasoning + action + URL)
|
|
517
|
-
# → replay.mp4 (the unified storyboard)
|
|
518
|
-
```
|
|
519
|
-
|
|
520
|
-
For the **animated cursor**, run with `--show-cursor` (bakes the cursor + reasoning overlay into the run's own `recording.webm`) and hand that recording to `run-capsule` as the screen capsule — it's reused as-is rather than rebuilt, so the real cursor motion survives, with the reasoning storyboard rendered from the trace alongside:
|
|
252
|
+
Web UI with per-turn screenshots, action JSON, reasoning, element highlights. A run's `report.json` is also a complete trace that renders into a shareable video via [`run-capsule`](https://github.com/tangle-network/run-capsule) — see [examples/run-capsule.md](./examples/run-capsule.md).
|
|
521
253
|
|
|
522
|
-
|
|
523
|
-
bad run --goal "…" --url https://… --show-cursor
|
|
524
|
-
npx run-capsule --playwright agent-results/report.json \
|
|
525
|
-
--video agent-results/cli-task/recording.webm --no-upload
|
|
526
|
-
# → screen.mp4 (the real run recording — animated cursor + overlay)
|
|
527
|
-
# → replay.mp4 (reasoning storyboard from the trace)
|
|
528
|
-
```
|
|
529
|
-
|
|
530
|
-
Needs a `run-capsule` whose Playwright adapter understands this driver's suite-shaped `report.json` ([tangle-network/run-capsule#4](https://github.com/tangle-network/run-capsule/pull/4); earlier versions read a bare `TestResult` and render an empty capsule for a suite) and, for `--video`, the recording-ingest path ([#5](https://github.com/tangle-network/run-capsule/pull/5)). Without `--video`, the `screen` capsule replays the per-turn screenshots — real frames only when the run captured them (vision is on by default unless you pass `--no-vision` or a vision-off benchmark profile, which blocks images for speed). Drop `--no-upload` for a temporary public link.
|
|
531
|
-
|
|
532
|
-
## Guides
|
|
254
|
+
## Agent Discovery
|
|
533
255
|
|
|
534
|
-
|
|
535
|
-
- [CLI Reference](./docs/guides/cli.md)
|
|
536
|
-
- [Design Audit](./docs/guides/design-audit.md)
|
|
537
|
-
- [Memory System](./docs/guides/memory.md)
|
|
538
|
-
- [Benchmarks & Experiments](./docs/guides/benchmarks.md)
|
|
539
|
-
- [Wallet & EVM Apps](./docs/guides/wallet.md)
|
|
540
|
-
- [Providers](./docs/guides/providers.md)
|
|
541
|
-
- [Custom Drivers](./docs/guides/custom-drivers.md)
|
|
256
|
+
Agents integrating Browser Agent should start from the live manifest at https://browser.tangle.tools/llms.txt. The same discovery manifest (`llms.txt` + `tangle-agent.json`) ships in the npm package under `discovery/`.
|
|
542
257
|
|
|
543
258
|
## Development
|
|
544
259
|
|
|
545
260
|
```bash
|
|
546
261
|
pnpm build # TypeScript → dist/
|
|
547
|
-
pnpm test #
|
|
262
|
+
pnpm test # vitest suite (~2,000 assertions across 174 files)
|
|
548
263
|
pnpm lint # type-check
|
|
549
264
|
pnpm check:boundaries # architecture boundaries
|
|
550
265
|
```
|
|
551
266
|
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
Automated via [Changesets](https://github.com/changesets/changesets) + OIDC trusted publishing. Add a changeset with `pnpm changeset`, merge the auto-generated release PR, and npm publish fires automatically with provenance attestation.
|
|
267
|
+
Publishing is automated via [Changesets](https://github.com/changesets/changesets) + OIDC trusted publishing: add a changeset with `pnpm changeset`, merge the release PR, npm publish fires with provenance attestation.
|
|
555
268
|
|
|
556
269
|
## License
|
|
557
270
|
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* design audit — type contract for the 8-layer architecture.
|
|
3
3
|
*
|
|
4
|
-
* RFC: docs/rfc/design-audit-world-class.md
|
|
4
|
+
* RFC: docs/rfc/design-audit-world-class.md (removed from the tree in the
|
|
5
|
+
* 2026-10 repo slimming; consult git history)
|
|
5
6
|
*
|
|
6
7
|
* This file is the stable contract that every layer's implementation
|
|
7
8
|
* builds against. It exists to let parallel implementation work proceed
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"score-types.d.ts","sourceRoot":"","sources":["../../../src/design/audit/score-types.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"score-types.d.ts","sourceRoot":"","sources":["../../../src/design/audit/score-types.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* design audit — type contract for the 8-layer architecture.
|
|
3
3
|
*
|
|
4
|
-
* RFC: docs/rfc/design-audit-world-class.md
|
|
4
|
+
* RFC: docs/rfc/design-audit-world-class.md (removed from the tree in the
|
|
5
|
+
* 2026-10 repo slimming; consult git history)
|
|
5
6
|
*
|
|
6
7
|
* This file is the stable contract that every layer's implementation
|
|
7
8
|
* builds against. It exists to let parallel implementation work proceed
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"score-types.js","sourceRoot":"","sources":["../../../src/design/audit/score-types.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"score-types.js","sourceRoot":"","sources":["../../../src/design/audit/score-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AA4BH,MAAM,CAAC,MAAM,UAAU,GAAyB;IAC9C,gBAAgB;IAChB,cAAc;IACd,eAAe;IACf,UAAU;IACV,YAAY;CACJ,CAAA"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tangle-network/browser-agent-driver",
|
|
3
|
-
"version": "0.36.
|
|
3
|
+
"version": "0.36.3",
|
|
4
4
|
"description": "LLM-driven browser agent and bad CLI for UI automation, testing, and evaluation",
|
|
5
5
|
"packageManager": "pnpm@10.33.3",
|
|
6
6
|
"publishConfig": {
|
|
@@ -20,6 +20,7 @@
|
|
|
20
20
|
},
|
|
21
21
|
"files": [
|
|
22
22
|
"dist",
|
|
23
|
+
"skills",
|
|
23
24
|
"discovery",
|
|
24
25
|
"scripts/postinstall-provider-patches.mjs",
|
|
25
26
|
"README.md",
|
|
@@ -39,32 +40,16 @@
|
|
|
39
40
|
"changeset": "changeset",
|
|
40
41
|
"version-packages": "changeset version && pnpm install --lockfile-only --no-frozen-lockfile",
|
|
41
42
|
"release-tag": "node ./scripts/release-tag.mjs",
|
|
42
|
-
"skills:install": "node ./scripts/install-skills.mjs",
|
|
43
43
|
"auth:save-state": "node ./scripts/save-storage-state.mjs",
|
|
44
44
|
"auth:check-state": "node ./scripts/check-storage-state.mjs",
|
|
45
45
|
"bench:validate": "node ./scripts/run-multi-rep.mjs",
|
|
46
46
|
"bench:compete": "node ./scripts/run-competitive.mjs",
|
|
47
|
-
"bench:master": "node ./scripts/run-master-comparison.mjs",
|
|
48
|
-
"ab:experiment": "node ./scripts/run-ab-experiment.mjs",
|
|
49
|
-
"research:pipeline": "node ./scripts/run-research-pipeline.mjs",
|
|
50
47
|
"macro:promote": "node ./scripts/run-macro-promotion.mjs",
|
|
51
|
-
"research:cycle": "node ./scripts/run-research-cycle.mjs",
|
|
52
48
|
"research:webvoyager:agent-eval": "node ./bench/research/webvoyager-agent-eval-loop.mjs",
|
|
53
49
|
"research:webvoyager:extract-google-flights": "node ./bench/research/extract-google-flights-corpus.mjs",
|
|
54
|
-
"bench:tier1:gate": "node ./scripts/run-tier1-gate.mjs",
|
|
55
|
-
"bench:tier2:gate": "node ./scripts/run-tier2-gate.mjs",
|
|
56
|
-
"bench:tier2:repeat": "node ./scripts/run-tier2-repeat-gate.mjs",
|
|
57
|
-
"bench:tier3:gate": "node ./scripts/run-tier3-gate.mjs",
|
|
58
|
-
"bench:local:smoke": "node ./scripts/run-local-reliability.mjs --profile smoke",
|
|
59
|
-
"bench:local:tier1": "node ./scripts/run-local-reliability.mjs --profile tier1",
|
|
60
|
-
"bench:local:tier2": "node ./scripts/run-local-reliability.mjs --profile tier2",
|
|
61
|
-
"bench:local:nightly": "node ./scripts/run-local-reliability.mjs --profile nightly",
|
|
62
50
|
"baseline:modes": "node ./scripts/run-mode-baseline.mjs",
|
|
63
|
-
"baseline:track": "node ./scripts/run-scenario-track.mjs",
|
|
64
51
|
"reliability:scorecard": "node ./scripts/reliability-scorecard.mjs",
|
|
65
52
|
"reliability:trend": "node ./scripts/reliability-trend.mjs",
|
|
66
|
-
"bench:scoreboard": "node ./scripts/benchmark-scoreboard.mjs",
|
|
67
|
-
"webbench:import": "node ./scripts/import-webbench-cases.mjs",
|
|
68
53
|
"design:bench": "pnpm tsx bench/design/run-design-bench.ts",
|
|
69
54
|
"design:bench:calibrate": "pnpm tsx bench/design/run-design-bench.ts --tier world-class --reproducibility",
|
|
70
55
|
"design:eval": "pnpm tsx bench/design/eval/run.ts",
|
|
@@ -82,16 +67,7 @@
|
|
|
82
67
|
"wallet:proxy:stop": "node ./bench/wallet/rpc-proxy.mjs --stop",
|
|
83
68
|
"wallet:validate": "node ./bench/wallet/run-wallet-validation.mjs",
|
|
84
69
|
"wallet:validate:tangle": "node ./bench/wallet/run-wallet-validation.mjs --suite tangle",
|
|
85
|
-
"wallet:validate:defi": "node ./bench/wallet/run-wallet-validation.mjs --suite defi"
|
|
86
|
-
"bench:webvoyager": "node ./bench/external/webvoyager/run.mjs",
|
|
87
|
-
"bench:webvoyager:estimate": "node ./bench/external/webvoyager/run.mjs --estimate",
|
|
88
|
-
"bench:webvoyager:eval": "node ./bench/external/webvoyager/evaluate.mjs",
|
|
89
|
-
"bench:webarena:setup": "node ./bench/external/webarena/setup.mjs",
|
|
90
|
-
"bench:webarena:convert": "node ./bench/external/webarena/convert-tasks.mjs",
|
|
91
|
-
"bench:webarena:eval": "node ./bench/external/webarena/evaluate.mjs",
|
|
92
|
-
"bench:observe": "tsx bench/observe-bench.ts",
|
|
93
|
-
"bench:agent": "tsx bench/agent-bench.ts",
|
|
94
|
-
"bench:captcha": "tsx bench/captcha-bench.ts"
|
|
70
|
+
"wallet:validate:defi": "node ./bench/wallet/run-wallet-validation.mjs --suite defi"
|
|
95
71
|
},
|
|
96
72
|
"keywords": [
|
|
97
73
|
"agent",
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
host: amazon.com
|
|
3
|
+
aliases: [www.amazon.com, smile.amazon.com]
|
|
4
|
+
title: Amazon product search and extraction
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
On amazon.com:
|
|
8
|
+
|
|
9
|
+
- Prefer the search box at the top. It's a `searchbox` role with ref near the page header. After typing the query, press Enter rather than clicking the "Go" button — the button is often hidden behind the keyboard and Enter submits reliably.
|
|
10
|
+
- Cookie/consent banners only appear on EU/UK domains (`.co.uk`, `.de`). If present, click the "Accept" or "Customize" button before any other interaction — Amazon's layout shifts after consent and `@ref` values change.
|
|
11
|
+
- Product search results live under the "Search results" landmark. Each card has a link whose accessible name is the product title. Use `click` on the title link, not the image, to reach the product detail page.
|
|
12
|
+
- On product detail pages, the canonical price is inside the `#corePrice_feature_div` block. Read `#priceblock_ourprice`, `#priceblock_dealprice`, or the a-price-whole spans — the field varies by category. Extract using `extractWithIndex` with the `offscreen` filter off; Amazon renders price twice (once with aria-hidden) and the accessible version is what you want.
|
|
13
|
+
- Ratings appear as `4.5 out of 5 stars` in an `[aria-label]`. Parse the numeric portion before "out of".
|
|
14
|
+
- Be aware of sponsored vs organic results: sponsored cards have "Sponsored" in small text above the title. Most tasks want the first organic result; filter accordingly.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
host: github.com
|
|
3
|
+
aliases: [www.github.com]
|
|
4
|
+
title: GitHub navigation, repo discovery, and PR/issue extraction
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
On github.com:
|
|
8
|
+
|
|
9
|
+
- The top search bar is `role="combobox"` with `aria-label="Search GitHub"`. Typing a query and pressing Enter runs the global search. For in-repo search, use the "Go to file" shortcut: press `t` on a repo page and type the filename.
|
|
10
|
+
- Repo pages have stable URL structure: `/OWNER/REPO`, `/OWNER/REPO/pulls`, `/OWNER/REPO/issues`, `/OWNER/REPO/blob/BRANCH/PATH`. Prefer direct URL navigation over clicking through the UI when the owner/repo is known — it's faster and avoids sidebar ambiguity.
|
|
11
|
+
- PR and issue lists use infinite scroll but the first ~25 fit on one page. Don't scroll unless the task requires more than 25 results.
|
|
12
|
+
- PR/issue counts: the tab badges ("Pull requests 42", "Issues 7") carry the exact number. Extract from the tab's accessible name, not from scrolling the list.
|
|
13
|
+
- File browsing: blob pages render the code inside a `<table>` with `role="presentation"`. Line numbers are in a separate column; use the `#L<n>` URL fragment to jump to a specific line rather than scrolling.
|
|
14
|
+
- For star/fork counts on a repo, the values are in the top-right action bar with accessible labels like "42 stars" and "3 forks".
|
|
15
|
+
- Login state matters: logged-in users see private repos in search; logged-out users don't. Don't assume visibility equals existence.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
host: linkedin.com
|
|
3
|
+
aliases: [www.linkedin.com]
|
|
4
|
+
title: LinkedIn navigation and profile extraction
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
On linkedin.com:
|
|
8
|
+
|
|
9
|
+
- The site aggressively detects automation. If you see an authwall ("Join now to see"), the account is not logged in — abort unless the task explicitly expects this. Do not try to sign up programmatically.
|
|
10
|
+
- Profile pages use dynamic React rendering. Wait for `heading` role with the person's name to appear before extracting — snapshot on first load is often skeleton UI.
|
|
11
|
+
- The search bar is `role="combobox"` with placeholder "Search". After typing, press Enter; the dropdown suggestions can lead to unrelated pages if clicked.
|
|
12
|
+
- Job listings: use `extractWithIndex` on the search results container (class `jobs-search-results-list` or role `list`). Each item's title, company, and location are distinct children — don't flatten them into a single blob.
|
|
13
|
+
- LinkedIn rate-limits heavy scraping. If the page shows "You've reached the weekly limit", abort the run — retries will not help.
|
|
14
|
+
- When logged in via attach mode, respect the user's real account: never send connection requests, InMails, or messages unless the task explicitly requests it.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
---
|
|
2
|
+
host: stackoverflow.com
|
|
3
|
+
title: Stack Overflow question and answer extraction
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
On stackoverflow.com:
|
|
7
|
+
|
|
8
|
+
- Question pages have a stable structure: question body, then answers sorted by vote count (accepted answer floats to the top). The accepted answer has a green checkmark and `aria-label="Accepted answer"`.
|
|
9
|
+
- Answer count appears in the sidebar sub-header ("3 Answers"). Extract from that heading, not from counting `<article>` elements — pinned/deleted answers can throw off the DOM count.
|
|
10
|
+
- Code blocks inside answers are `<pre><code>` — their text content is preserved verbatim. If the task is "extract the code from the top answer", grab the first `<pre>` inside the answer body.
|
|
11
|
+
- Vote counts are in a `.js-vote-count` or `[itemprop="upvoteCount"]` element next to each post. Use the accessible label ("23 votes") rather than parsing the class.
|
|
12
|
+
- Tags appear below the question title as a list of `role="link"` with `tag` in the URL. Good proxy for topic when the question title is ambiguous.
|
|
13
|
+
- Stack Overflow requires JS to render vote counts and comments. Wait for the "Show X more comments" expander to resolve before extracting comment text.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
host: wikipedia.org
|
|
3
|
+
aliases: [en.wikipedia.org]
|
|
4
|
+
title: Wikipedia article extraction
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
On wikipedia.org:
|
|
8
|
+
|
|
9
|
+
- Article content is inside `#mw-content-text`. Infoboxes are the table at the top-right of the article — use them for structured facts (birth/death dates, coordinates, population, founding year) rather than parsing prose.
|
|
10
|
+
- The article lead (first paragraph after the infobox) is the highest-density summary; for one-fact queries it usually contains the answer.
|
|
11
|
+
- When extracting a numeric fact for a goal like "what year was X founded", emit the number in the exact shape the goal asks for. If the goal implies a JSON object, wrap: `{"year": 1815}`, not the bare string "1815". Wikipedia extraction goals are the most common site where this formatting detail decides pass/fail.
|
|
12
|
+
- The search box is at the top-right. Pressing Enter after typing runs the search; the dropdown suggestions lead to disambiguation pages which can be wrong — prefer pressing Enter.
|
|
13
|
+
- Disambiguation pages: if the search resolves to a "X may refer to:" list, the correct entry is usually the one matching the goal's context (place, person, company). Scan the list before clicking.
|
|
14
|
+
- References and citations use superscripts like `[1]`. Do not include them in extracted prose — strip the `<sup>` elements or their text content.
|
|
15
|
+
- For facts, prefer the English Wikipedia (`en.wikipedia.org`) over other language editions unless the task specifies a different language.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "dismiss-cookie-banner",
|
|
3
|
+
"description": "Accept/dismiss a standard cookie consent banner by clicking the 'Accept' button, then give the page 500ms to settle so the next snapshot sees the dismissed layout. Use when the snapshot contains a role=dialog with cookie/consent text and a visible Accept button ref.",
|
|
4
|
+
"params": [
|
|
5
|
+
{ "name": "acceptRef", "description": "The ref of the Accept/Accept all/OK button inside the banner", "required": true }
|
|
6
|
+
],
|
|
7
|
+
"steps": [
|
|
8
|
+
{ "action": "click", "selector": "${acceptRef}" },
|
|
9
|
+
{ "action": "wait", "ms": 500 }
|
|
10
|
+
]
|
|
11
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "search-and-submit",
|
|
3
|
+
"description": "Focus a searchbox, type the query, and press Enter to submit. Use on pages with a top-level search affordance — avoids clicking a 'Go' button whose ref may shift under the keyboard.",
|
|
4
|
+
"params": [
|
|
5
|
+
{ "name": "searchRef", "description": "Ref of the searchbox/combobox to type into", "required": true },
|
|
6
|
+
{ "name": "query", "description": "Query text to type", "required": true }
|
|
7
|
+
],
|
|
8
|
+
"steps": [
|
|
9
|
+
{ "action": "click", "selector": "${searchRef}" },
|
|
10
|
+
{ "action": "type", "selector": "${searchRef}", "text": "${query}" },
|
|
11
|
+
{ "action": "press", "selector": "${searchRef}", "key": "Enter" }
|
|
12
|
+
]
|
|
13
|
+
}
|