agent-browser-runtime

Agent Browser Runtime

Use this skill when an agent needs a real, persistent browser runtime for page exploration, login-state reuse, screenshot/HTML evidence, session probes, or extractor execution.

Runtime

This skill expects the project stack to be running from the Agent Browser Runtime repository root:

cp .env.example .env
docker compose up --build -d
./scripts/smoke-test.sh

Endpoints:

• Broker: http://127.0.0.1:17890
• CDP: http://127.0.0.1:19223
• noVNC: http://127.0.0.1:16080/vnc.html?autoconnect=true&resize=remote

Operating Model

• The browser runtime is long-running and compose-managed.
• Before starting work, run ./cli/brs.js status; extensionConnected: true means the Chrome companion extension is ready.
• If extensionConnected stays false, restart with docker compose up --build -d.
• Agents must use broker leases; one lease maps to one real Chrome Tab Group.
• For continuous work on the same site/task, keep one lease and one tab: start with browse-start, then use browse-nav, browse-html, browse-screenshot, and browse-end. Repeated one-shot fetch calls create extra leases/tab groups and should be reserved for smoke checks or isolated single-page evidence.
• Broker persists state/artifacts and owns task-level pacing; the extension executes Chrome-native browser operations, including scripted humanized mouse/scroll/pause actions.
• Default browser identity mode is trusted-real-browser: persistent profile, noVNC, tab groups, artifacts, UI primitives, pacing, and no page-level UA/header/WebGL/canvas/audio spoofing or startup-level timezone/AutomationControlled overrides.
• ./cli/brs.js status should show extensionConnected: true, stealth.mode: trusted-real-browser, stealth.enabled: false, and platformPacing.
• Use BRS_STEALTH_MODE=legacy-js only as an explicit compatibility experiment; it enables the older extension-level UA/UA-CH headers, main-world stealth evasions, locale/timezone CDP overrides, and canvas/audio/WebGL patching.
• Use BRS_STEALTH_MODE=patched-browser when a mounted browser binary owns identity changes at the browser/backend layer; keep extension JS/CDP stealth off in that mode.
• Keep at least 70 ms between broker-driven browser requests. For unknown or sensitive platforms, serialize per target site and use seconds-to-minutes cooldowns.
• Use ./cli/brs.js probe-session <platform> to check persisted login/session state for linkedin, reddit, facebook, instagram, or generic; cookie values are omitted unless --include-cookies is passed.
• For direct CDP legacy/debug tasks, do not use context.pages()[0]; create a dedicated page for the task, keep ownership explicit, and close/release it when finished.

Browser Interaction Discipline

This rule applies to every target site, not only LinkedIn.

• Direct navigation is reserved for initial entry to an exact user-provided URL, platform/session probes, or returning to a previously captured exact URL for inspection.
• After entry, complete site workflows through the visible UI: type search terms and form values with keyboard input, move the cursor to controls before clicking, scroll/hover/pause naturally, and let the site update state through its normal front-end flow.
• For search, filters, pagination, profile/result selection, login, checkout, and account-safety flows, use real UI controls instead of synthesized destination/search URLs, querystring mutation, location jumps, dispatched DOM clicks, or backend/API shortcuts.
• Generated extractor scripts should use the runtime ui helper (ui.type, ui.click, ui.press, ui.scroll, ui.waitFor, ui.move, ui.uploadFile) for in-site workflows; keep direct URL navigation limited to the initial exact entry URL or an explicitly captured inspection URL.
• If the needed UI action is not exposed by the broker or extension yet, use noVNC manual handoff or add a real browser primitive before automating that workflow.

Quick Commands

From the project root:

./cli/brs.js status
./cli/brs.js fetch https://example.com --agent demo-agent --task smoke --screenshot --humanize enhanced
./cli/brs.js browse-start https://example.com --agent demo-agent --task research
./cli/brs.js browse-nav <leaseId> <tabId> https://example.com/page-2 --screenshot
./cli/brs.js browse-html <leaseId> <tabId>
./cli/brs.js browse-end <leaseId>
./cli/brs.js probe-session linkedin --humanize off --cooldown false
./cli/brs.js extract example.extract.js https://example.com --agent demo-agent --task extractor-smoke --screenshot --save-html
./cli/brs.js acquire --agentId demo-agent --taskId research --domain example.com
./cli/brs.js open <leaseId> https://example.com
./cli/brs.js release <leaseId>

Built-in Extractors

The runtime repo ships extractor scripts under extractors/; this local Codex skill also mirrors reusable scripts under /Users/zhi/.codex/skills/agent-browser-runtime/extractors/.

AliExpress product search extractor is available as extractors/aliexpress.extract.js. It uses one file with mode-specific params so image-based and text-based collection return the same products[] fields: product image URL, title, price, sales text/count, product URL, precision score, and match reason.

Image-search result collection:

./cli/brs.js extract aliexpress.extract.js \
  'https://www.aliexpress.com/' \
  --params '{"mode":"imageSearch","maxItems":30,"requireSales":true,"filter":"women blazer double breasted gold buttons"}' \
  --file /absolute/path/to/reference-image.png \
  --agent codex --task aliexpress-image-search --humanize standard --active true --save-html

Text-search collection:

./cli/brs.js extract aliexpress.extract.js \
  'https://www.aliexpress.com/' \
  --params '{"mode":"textSearch","query":"women double breasted blazer gold buttons","maxItems":30,"requireSales":true}' \
  --agent codex --task aliexpress-text-search --humanize standard --save-html

Modes:

• imageSearch: when --file / params.uploadFile is present, opens AliExpress image search, uploads the reference image with ui.uploadFile, waits for results, then extracts sales-backed product cards. It can also extract from an existing image-search results URL.
• textSearch: types params.query into the site search box with runtime UI helpers, submits it, scrolls, then extracts product cards.
• auto: infers textSearch when query is present, otherwise uses imageSearch for image-search URLs.

Taobao product search extractor is available as extractors/taobao.extract.js. It keeps the same product-search output contract as the AliExpress extractor: product image URL, title, price, sales text/count, shop name, product URL, precision score, and match reason.

Taobao image-search result collection:

./cli/brs.js extract taobao.extract.js \
  'https://www.taobao.com/' \
  --params '{"mode":"imageSearch","maxItems":40,"requireSales":true,"filter":"女士 双排扣 金扣 西装外套"}' \
  --file /absolute/path/to/reference-image.png \
  --agent codex --task taobao-image-search --humanize standard --active true --save-html

Taobao text-search result collection:

./cli/brs.js extract taobao.extract.js \
  'https://www.taobao.com/' \
  --params '{"mode":"textSearch","query":"女士 双排扣 金扣 西装外套","maxItems":40,"requireSales":true}' \
  --agent codex --task taobao-text-search --humanize standard --active true --save-html

Taobao extractor modes:

• imageSearch: opens the visible Taobao image-search upload flow with runtime UI helpers, uploads the reference image with ui.uploadFile, waits for results, scrolls, then extracts sales-backed product cards.
• textSearch: types params.query into Taobao search with runtime UI helpers, submits it, scrolls, then extracts product cards.
• auto: infers textSearch when query is present, otherwise uses imageSearch when an upload file or image-search URL is present.
• If Taobao shows login, captcha, or safety verification, use noVNC for manual handoff and rerun in the same persisted browser profile.

Modes

1. explore: agent uses a leased tab group to understand a new site.
2. record: save selectors, screenshots, HTML, network hints, and failure states.
3. run: execute a stable extractor script in a leased workspace.

MVP implements shared-context-tab-group. Use dedicated-runtime conceptually for risky targets that should not share profile/IP/session. Humanization profiles are minimal, standard, enhanced, or off.

Safety

• Runtime profile, artifacts, and SQLite state are gitignored.
• Do not commit cookies, credentials, screenshots with secrets, raw harvested content, or .env.
• If login/Captcha appears, use noVNC for manual handoff.
• Runtime upgrades preserve the persisted browser profile by default. Use BRS_RESET_PROFILE_ON_SIGNATURE_CHANGE=1 only for an intentional profile wipe.
• Google, LinkedIn, JD, and GitHub are excluded from legacy JS stealth by default because high-trust login flows are sensitive to spoofed browser identity.

More Detail

Read docs/SPEC.md for architecture/API specifics.