agentic-browser 2.6.1 → 2.7.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.
Files changed (10) hide show
  1. package/AGENTS.md +25 -19
  2. package/README.md +16 -1
  3. package/dist/cli/index.mjs +300 -54
  4. package/dist/index.d.mts +158 -99
  5. package/dist/index.mjs +1 -2
  6. package/dist/mcp/index.d.mts +1 -4
  7. package/dist/mcp/index.mjs +47 -18
  8. package/dist/{runtime-BzdbtFF4.mjs → runtime-CfQ0xGAm.mjs} +1055 -207
  9. package/dist/{setup-DUAjdbQ3.mjs → setup-DwFaZOPf.mjs} +13 -6
  10. package/package.json +21 -19
package/AGENTS.md CHANGED
@@ -3,14 +3,14 @@
3
3
  ## Quick Reference
4
4
 
5
5
  ```bash
6
- npm run build # tsdown (~20ms)
7
- npm run typecheck # tsc --noEmit
8
- npm run lint # oxlint
9
- npm run lint:fix # oxlint --fix
10
- npm run format # oxfmt --write
11
- npm test # vitest run
12
- npm run test:watch # vitest
13
- npm run docs:dev # vocs dev server
6
+ pnpm build # tsdown (~20ms)
7
+ pnpm typecheck # tsc --noEmit
8
+ pnpm lint # oxlint
9
+ pnpm lint:fix # oxlint --fix
10
+ pnpm format # oxfmt --write
11
+ pnpm test # vitest run
12
+ pnpm test:watch # vitest
13
+ pnpm docs:dev # vocs dev server
14
14
  ```
15
15
 
16
16
  ## Architecture
@@ -29,7 +29,7 @@ src/
29
29
  commands/agent.ts — Stateful agent commands (auto-restart, retry, session persistence)
30
30
  commands/*.ts — Low-level CLI command handlers
31
31
  mcp/
32
- index.ts — MCP server (stdio transport, 7 tools wrapping AgenticBrowserCore)
32
+ index.ts — MCP server (stdio transport, tools wrapping AgenticBrowserCore)
33
33
  session/
34
34
  browser-controller.ts — BrowserController interface + ChromeCdpBrowserController (CDP WebSocket)
35
35
  session-manager.ts — Orchestrates sessions, commands, memory recording
@@ -68,7 +68,7 @@ AgenticBrowserCore → ControlApi → SessionManager → BrowserController (CDP)
68
68
 
69
69
  - **ESM-only**: `"type": "module"`, use `.js` extensions in all TypeScript imports
70
70
  - **Zod v4**: `import { z } from "zod"` — `z.record()` requires key+value args
71
- - **Commander.js v14**: colon-namespaced commands (`session:start`, `memory:search`)
71
+ - **Commander.js v15**: colon-namespaced commands (`session:start`, `memory:search`)
72
72
  - **CLI output**: exactly one JSON line to `stdout`, errors to `stderr`
73
73
  - **Types**: interfaces for public contracts, type aliases for unions/inferred
74
74
  - **No console.log in MCP server**: use `process.stderr.write()` for debug output
@@ -111,21 +111,27 @@ AgenticBrowserCore → ControlApi → SessionManager → BrowserController (CDP)
111
111
  - `AGENTIC_BROWSER_DIR` — base dir for sessions/memory/events (default: `~/.agentic-browser`)
112
112
  - `AGENTIC_BROWSER_CHROME_EXECUTABLE_PATH` — explicit Chrome path (auto-discovered if not set)
113
113
  - `AGENTIC_BROWSER_CDP_URL` — connect to an already-running Chrome via CDP (e.g. `http://127.0.0.1:9222`)
114
+ - `AGENTIC_BROWSER_ALLOW_FILE_URLS` — allow `file:` URLs in navigate (`true` or `1`); default is http(s) and about:blank only
114
115
  - `AGENTIC_BROWSER_USER_PROFILE` — use real Chrome profile (`default`, `true`, or absolute path)
116
+ - `AGENTIC_BROWSER_CHROME_PATH` — alias of `AGENTIC_BROWSER_CHROME_EXECUTABLE_PATH`
117
+ - `AGENTIC_BROWSER_HEADLESS` — `true` or `1` to launch Chrome headless
118
+ - `AGENTIC_BROWSER_USER_AGENT` — override the browser user agent
115
119
 
116
120
  ## MCP Server
117
121
 
118
122
  Subcommand: `agentic-browser mcp` (stdio transport). Setup: `agentic-browser setup`. Tools:
119
123
 
120
- | Tool | Purpose |
121
- | ----------------------- | --------------------------------------------------------------------------------------------------------- |
122
- | `browser_start_session` | Start Chrome, return sessionId |
123
- | `browser_navigate` | Navigate to URL |
124
- | `browser_interact` | click / type / press / waitFor / scroll / hover / select / toggle / goBack / goForward / refresh / dialog |
125
- | `browser_get_content` | Get page title / text / html |
126
- | `browser_get_elements` | Discover interactive elements |
127
- | `browser_search_memory` | Search task memory |
128
- | `browser_stop_session` | Stop Chrome session |
124
+ | Tool | Purpose |
125
+ | ------------------------- | --------------------------------------------------------------------------------------------------------- |
126
+ | `browser_start_session` | Start Chrome, return sessionId |
127
+ | `browser_navigate` | Navigate to URL |
128
+ | `browser_interact` | click / type / press / waitFor / scroll / hover / select / toggle / goBack / goForward / refresh / dialog |
129
+ | `browser_get_content` | Get page title / text / html |
130
+ | `browser_get_elements` | Discover interactive elements |
131
+ | `browser_search_memory` | Search task memory |
132
+ | `browser_stop_session` | Stop Chrome session |
133
+ | `browser_dismiss_cookies` | Dismiss cookie or consent banner |
134
+ | `browser_screenshot` | Screenshot as base64 (jpeg or png, optional full page) |
129
135
 
130
136
  ## For Browser Automation Tasks
131
137
 
package/README.md CHANGED
@@ -13,7 +13,7 @@ CLI and MCP server to control a local Chrome session for AI agents.
13
13
 
14
14
  ## Requirements
15
15
 
16
- - Node.js 20+
16
+ - Node.js 22+
17
17
  - Installed Chrome
18
18
 
19
19
  ## Install
@@ -113,10 +113,21 @@ agentic-browser agent start --user-agent "MyBot/1.0"
113
113
  agentic-browser agent status
114
114
  agentic-browser agent navigate https://example.com
115
115
  agentic-browser agent click "#login"
116
+ agentic-browser agent click --text "Accept all" --frame "#sp_message_iframe_123"
117
+ agentic-browser agent type --frame "iframe#checkout" "#card" "4242..."
118
+ agentic-browser agent wait --url "*/dashboard*" --load --timeout 10000
119
+ agentic-browser agent wait --text "Welcome back"
120
+ agentic-browser agent eval "document.querySelectorAll('article').length"
121
+ agentic-browser agent tabs
122
+ agentic-browser agent tab-new https://example.org
123
+ agentic-browser agent tab <id-or-prefix>
124
+ agentic-browser agent tab-close <id-or-prefix>
116
125
  agentic-browser agent content --mode summary
117
126
  agentic-browser agent content --mode html --selector main
118
127
  agentic-browser agent elements
119
128
  agentic-browser agent elements --roles button,link --limit 20
129
+ agentic-browser agent elements --href /news/ --text "gta"
130
+ agentic-browser agent screenshot --out ./page.png --full-page
120
131
  agentic-browser agent memory-search "navigate:example.com" --domain example.com
121
132
  agentic-browser agent stop
122
133
  agentic-browser agent cleanup --dry-run --max-age-days 7
@@ -156,6 +167,10 @@ MCP responses are compact — `visible`, `actions`, and `tagName` are omitted to
156
167
 
157
168
  When an element lives inside an open shadow root or a same-origin iframe, discovery returns a composed locator using `>>>` to cross boundaries, for example `iframe[name="checkout"] >>> button[aria-label="Pay"]`. The same locator string works with `agent click`, `agent type`, MCP `browser_interact`, and fallback selectors.
158
169
 
170
+ Cross-origin iframes (consent managers, payment forms) cannot be read from the page. `agent elements` lists them under `crossOriginFrames`; pass one of those selectors as `--frame` to `elements`, `click`, `type`, `hover`, `select`, `toggle`, `wait` and `eval` to run inside it, or compose it directly: `#sp_message_iframe_123 >>> text=Accept all`. A `text=Foo` segment matches by visible text, label or placeholder (`text="Foo"` for an exact match).
171
+
172
+ `agent status`, `navigate` and interaction commands report the current `url`. `agent cookies` also handles cross-origin consent iframes and, when nothing was dismissed, explains why in `detail`.
173
+
159
174
  `agent content` and MCP `browser_get_content` now default to `summary`, which returns a low-token overview with `title`, `headings`, `landmarks`, `primaryActions`, `inputs`, `alerts`, and iframe metadata. Use `a11y` when you need the deeper accessibility structure, and `text` or `html` only when you need raw content.
160
175
 
161
176
  ````