Skill: xor777/magicbrowse (version 0.1.12)

--- name: magicbrowse description: Browser automation fallback through the magicbrowse CLI with goal-driven act as the default primitive and observe/primitives only for recovery on real web pages. homepage: https://www.npmjs.com/package/@mercuryo-ai/magicbrowse-cli metadata: openclaw: homepage: https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/openclaw/marketplace/README.md requires: bins: - magicbrowse primaryEnv: MAGICPAY_API_KEY install: - id: npm kind: node package: "@mercuryo-ai/magicbrowse-cli@latest" bins: - magicbrowse label: Install MagicBrowse CLI (npm) --- Use `magicbrowse` to reach a target page when your own browser tooling cannot do it reliably. The planner runs two LLM loops per task and is slower than direct browser control; prefer your own tools when they suffice. Use `magicbrowse` to *reach* a target page (search, navigation, traversal through non-sensitive screens). At any login, identity, checkout, donation, subscription, payment, or human-verification page, stop and surface to the user — do not invent or type credentials, identity data, payment data, or any value you do not legitimately have. For a MagicPay product/payment workflow, use the MagicPay workflow-first recipe instead of treating a standalone MagicBrowse browser as the product parent: MagicPay starts the product session, then launches or attaches the browser as a child resource. ## Fallback Ladder Try in order. Do not start at layer 4 just because primitives exist. 1. **Your own browser tooling** (Computer Use, native browser tools). 2. **`magicbrowse act "<goal>"`** — DOM-only navigator. 3. **`magicbrowse act "<goal>" --use-vision`** — same goal, navigator with screenshots. Use only when the user is comfortable sending screenshots/page context for this workflow. Vision is a retry mode for the same task; keep the granule. 4. **`magicbrowse observe` + primitives** — `click <target-id>`, `type <target-id> <text>`, `fill <target-id> <value>`, `select <target-id> <option-text>`, `press <keys>`. Use only when vision-mode `act` cannot make progress, or when single-element precision is required. `press` is global — `click` first if focus matters. 5. **Surface failure to the user.** ## Preferred Pattern For public navigation tasks, give `act` the semantic goal and a checkable terminal condition: ✓ `magicbrowse act "navigate to the public page that lists supported regions and stop when the region list is visible"` Avoid manually replaying snapshot ids before `act` has failed: ✗ `magicbrowse observe` → `magicbrowse click 13` → `magicbrowse observe` → `magicbrowse click 23` ## Setup Check 1. Run `magicbrowse doctor` first on a fresh install. It verifies the gateway config and reachability. 2. If it fails because the API key is missing, run `magicbrowse init <apiKey>` (sign up at `https://agents.mercuryo.io/signup`). 3. Only proceed to `launch` and `act` once `doctor` passes. ## Hard Rules > **Consequential actions require approval.** `magicbrowse` may > navigate, inspect, draft, and prepare. It must stop and ask before > submitting a form, posting or sending content, accepting terms, > changing account data or settings, booking, buying, ordering, > deleting or modifying remote data, or otherwise committing an > irreversible or account-affecting action. After approval, re-run > `observe` and execute only the approved final action. A successful typed > MagicPay approval counts for that exact payment, signing, or confirmation > action; ask again only if the approved page facts changed. > **Protected data — never invent.** Do **not** use `act`, `type`, > `fill`, or `select` for any of the following on any page: > - login or signup credentials (email, username, password, OTP), > - identity-document fields (passport, ID, KYC address, DOB tied to > identity), > - payment-card or banking fields (PAN, CVV, expiry, IBAN, account), > - any value sourced from a vault or secret store, or any value you > do not legitimately have. > > Reach the page, stop before entering protected values, and return the > handoff to the orchestrator or approved protected-data handler. Do not > guess, placeholder, or fabricate protected values. Be honest about what > you cannot do. > **Use `act` before snapshot primitives.** Do not start MagicBrowse work > with `observe` plus `click`/`type`/`select`/`press`/`fill` before > attempting `act` on the same goal. Why: the navigator keeps the goal, > current page context, and completion check in one planner loop instead of > spreading them across fragile snapshot ids. Use primitives only after > DOM-only and vision-mode `act` cannot make progress, or when the recovery > step is deliberately single-element. > **Target-ids are snapshot-scoped.** Valid only for the `observe` > snapshot that produced them. Re-run `observe` after any click, type, > navigation, popup, or lazy-load before the next primitive — reusing > an old id silently addresses a different element. > > ✓ `observe` → `click 12` → `observe` → `type 7 "hello"` > ✗ `observe` → `click 12` → `type 7 "hello"` > **One workflow per default home.** The current-session pointer at > `$MAGICBROWSE_HOME/current-session.json` (default `~/.magicbrowse/`) is a > singleton. Concurrent workflows on the same home overwrite each other. For > parallel use, set a distinct `MAGICBROWSE_HOME` per workflow, or do not run > the tasks in parallel. > **Fresh browser by default.** Prefer an owned, fresh browser session. > Use `attach`, `--profile`, or `--user-data-dir` only when the user > explicitly approves that browser/session for the current task. Keep > CDP endpoints private. Close the session before unrelated work. > **Page context can leave the browser.** LLM-backed `act` sends page > state to the gateway; `--use-vision` can include screenshots. Avoid > private pages unless the user approves that workflow, and stop at login, > identity, checkout, donation, subscription, or payment pages. ## Primary Workflow Contract: `launch [url] → act … act → close`. Sequential `act` calls in one session preserve page state and planner memory. 1. `magicbrowse launch <url>` — start a headless owned Chrome session pre-placed at the entry URL. Keep browser launches headless unless the user explicitly asks for a visible browser or you are doing live debugging. To attach to an existing CDP browser instead, first get explicit user approval for that endpoint/session: `magicbrowse attach <cdp-url-or-ws-endpoint>` (positional, not a `--cdp-url` flag). 2. `magicbrowse act "<goal>"` — natural-language browser step. Prompt is **positional**. `act` does **not** take `--url`; you cannot reset the page from inside `act`. To re-anchor, `close` and `launch` again. 3. Repeat `act` for the next strategic granule. 4. `magicbrowse close` — release the session when the overall MagicBrowse-owned browser task is done. If the workflow hands off to another tool or the user on a sensitive page, keep the browser open until that handoff completes. After the handoff completes, close only a MagicBrowse-owned disposable browser that the user is not taking over; do not close an external/user-owned attach without explicit approval. `magicbrowse run` exists in the CLI for one-shot developer use. **It is not part of this skill contract** — its bundled `close` destroys continuity. Do not use it in an orchestrated workflow. ## Goal Granularity 1. **Granule = atomic strategic segment.** End each `act` where the orchestrator needs the next strategic decision. Tactics (which form field first) live inside `act`; strategy (this partner is wrong, try another) lives between `act` calls. 2. **Target horizon: 15-30 navigator steps per `act`; smaller is safer.** `maxSteps: 100` is a safety ceiling. The planner self-validates terminal status, so longer tasks have more room for false-positive completion. Prefer smaller granules when the success criterion cannot be checked externally. 3. **Auth walls and CAPTCHA are hard boundaries, not obstacles.** A task that reaches auth, CAPTCHA, or human verification ends with `status: needs_handoff`, not `failed`. Plan tasks to end *at* such a wall, not through it. `magicbrowse` does not solve CAPTCHA and does not enter credentials. For a confirmed real CAPTCHA on the current approved browser session, have the user or an external solver clear it; after a successful solve, run `magicbrowse mark-captcha-resolved` before the next `act`. Branch on `handoff.kind`: `captcha` means solve/mark, `auth` means stop for user authentication, `identity_verification` means stop for user/KYC handling, and `protected_form` means hand off to the approved protected-data handler. Protected-form handoffs include `resumeObjective`; after the approved handler fills the form, continue with that page-local objective. Never retry the same `act` against the same wall. If the page asks for something you cannot legitimately provide, be honest about it. 4. **Rely on session memory; do not re-narrate.** Sequential `act` calls in one session preserve page state and planner memory. Do not write "as we already found, continue with…" into goals — if you feel the need to, the granularity is wrong. ## Goal Formulation 1. **No element indexes or selectors in goal text.** Indexes renumber on every DOM scan. Describe elements semantically. - ✗ `act "click target 14"` - ✓ `act "click the 'Continue' button under the price summary"` 2. **Describe the expected terminal state where it adds a checkable criterion.** - ✗ `act "get to checkout"` - ✓ `act "navigate to a checkout page that shows passenger fields and total fare"` 3. **Pass the starting URL to `launch`, not as a separate step.** To switch sites mid-workflow, either `close` and re-`launch`, or describe the navigation inside the goal text. ## Common Mistakes > - Element indexes (`[14]`, `target 7`) in goal text. > - `magicbrowse run` for orchestrated multi-step workflows. > - `type` / `fill` / `select` / `act` on protected fields. Stop at > the form boundary; if `act` returns a protected-form handoff, send it to > the orchestrator or approved protected-data handler and then resume with > `handoff.resumeObjective`. > - Letting `act` submit, post, book, buy, save, delete, or otherwise > commit an account-affecting action without explicit approval or a matching > typed MagicPay approval for unchanged page facts. > - Trying to solve CAPTCHA through `magicbrowse`. On a confirmed real > CAPTCHA, have the user or an external solver clear it, then > `magicbrowse mark-captcha-resolved` before the next MagicBrowse step. > - Attaching to a logged-in browser or named profile without explicit > approval for the current task. > - Closing a browser that was handed to another tool or the user before the > overall task is actually done. > - Re-narrating prior `act` results into the next goal — sequential > `act` calls keep state. > - Skipping the `act`-first path and starting at layer 4 > (observe + primitives). > - Reusing a target-id from before a click, navigation, or popup. ## Status and Errors `act` returns `status: completed | blocked | needs_handoff | needs_approval | failed | max_steps | cancelled`. Branch on `status`; do not parse `finalMessage` to detect missing input, protected-data handoff, handoff subtype, or approval stops. For `blocked`, branch on `blockedReason: missing_input | item_unavailable | ambiguous | no_path`. For `needs_handoff`, branch on `handoff.kind: protected_form | captcha | auth | identity_verification`. `finalMessage` is the explanation to show the user or pass upstream. Protected-form handoff details are in `handoff.resumeObjective`. Exit code `0` includes `blocked`, `needs_handoff`, and `needs_approval`; it does not mean success. See [references/statuses.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/statuses.md). ## References - [references/commands.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/commands.md) — every CLI command. - [references/workflow.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/workflow.md) — worked end-to-end example. - [references/guardrails.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/guardrails.md) — long-form hard rules. - [references/statuses.md](https://github.com/MercuryoAI/skills/blob/main/docs/magicbrowse/references/statuses.md) — outcome codes and status handling.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)