browser skill

Browser

One library, two engines. omowright ships inside this skill; choose the engine before you act:

Attached is the default, because it is the only engine carrying the user's logins and the only one where a human is a single call away. Never substitute one engine for the other silently: if the attached engine is not set up, run the onboarding script and tell the user its one remaining step.

Step 0 — load omowright and prove the stack

const { loadOmowright } = await import("<skill-root>/scripts/omowright.mjs")
const { omowright } = await loadOmowright()          // { connectBrowserSkill, bskSnapshot, connectPipe, ... }

node "<skill-root>/scripts/browser-doctor.mjs" --json

Install into the browser the user actually uses, never into whatever happens to be on disk. Before installing, check your memory for the user's browser; otherwise read the doctor's browser (picked from the OS default browser, running apps and recent use — candidates shows the evidence). If memory and the doctor disagree, or the doctor says choose-browser, ask the user. Pass the answer as --browser= and record it in memory. A Chrome that is merely installed is not their browser.

Never launch a headless browser because the attached one is missing. It has none of the user's sessions, so every login turns into a ladder you should not be climbing. Say which state you hit and ask.

The loop (attached)

const session = await omowright.connectBrowserSkill({ name: "<task>", focused: false })
try {
  await session.navigate("https://example.com/", { waitUntil: "load" })
  const { tree, refs, css } = await omowright.bskSnapshot(session, { interactive: true })  // OmOWright tree + refs, no trace in the page
  await session.click({ selector: css.e3 })                                                 // css[ref] is null inside shadow roots:
  const vom = await session.observe({ maxTokens: 4000 })                                    //   then read the daemon's own tree ...
  await session.click("@e7")                                                                //   ... and click its @eN ref
  await session.fill(css.e5, "hello")
  await session.press("Enter")
  await session.waitForNavigation({ waitUntil: "load" })
  const shot = await session.screenshot()                                                   // { buffer, width, height, captureId }
} finally {
  await session.stop()                                                                      // success AND failure; returns borrowed tabs
}

call; use a ref in the same cycle you read it.

1. Read before every action. bskSnapshot refs and observe @eN refs are reissued on each

Borrowing prompts the user; never invent tab ids and never repeat a denied borrow.

1. Navigation and large DOM changes stale every ref. Read again rather than reusing.
2. Two identical failures mean change approach, not retry. A third identical attempt is a defect.
3. Borrow a user tab explicitly (tabList({ scope: "user" }), tabBorrow(id), tabReturn(id)).

1. Always stop() the session, on success and on failure.

Every method, its options, and the failure codes are in references/commands.md.

When a human is the only way through

Login, CAPTCHA, OTP, a payment confirmation, a consent dialog:

const outcome = await session.requestHelp({ prompt: "<what you need done>", targets: ["@e4"], timeoutMs: 300_000 })

Then read the page again. Respect a cancelled or timed_out outcome; do not work around it by changing the extension's automation settings.

Rules

cookie or recovery code. The value of the attached engine is that the browser is already signed in.

• Never read credentials through the page. No evaluate that extracts a password, token,

out everywhere. No flow here needs it.

• Never clear cookies, cache or site data. It is the user's real profile; clearing it logs them

capture on every tab it drives, which is a known automation signal; CloakBrowser through connectCloakProfile() is the stealth path.

• focused: false by default. The browser belongs to someone who is probably using it.
• One short, named session per task, always stopped.
• Bot-scored or WAF targets go to the owned engine. The attached engine's daemon enables console

Where the rest lives