lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/shared-skills/skills/browser/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: browser
+description: "Drives a real browser through the omowright library from the js eval kernel: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, a human handoff for login, CAPTCHA or OTP, and a browser you own for scraping, bot-scored targets, network capture and QA traces. Use for any interactive browser task; not for a plain search or an unblocked static fetch."
+---
+
+# Browser
+
+One library, two engines. omowright ships inside this skill; choose the engine before you act:
+
+| You need | Engine | Entry point |
+|---|---|---|
+| A site the user is signed into, their open tabs, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser through BrowserSkill | `connectBrowserSkill()` |
+| A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control, headless runs | **owned** — a browser your code launches | `connectPipe()` / `connectCloakProfile()` — [references/owned-engine/README.md](references/owned-engine/README.md) |
+| Text out of a URL, a 403 bypass, a platform that blocks fetchers | neither | the `ultimate-browsing` skill |
+
+**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
+
+```js
+const { loadOmowright } = await import("<skill-root>/scripts/omowright.mjs")
+const { omowright } = await loadOmowright()          // { connectBrowserSkill, bskSnapshot, connectPipe, ... }
+```
+
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs" --json
+```
+
+| State | Meaning | Next |
+|---|---|---|
+| `ready` | CLI, daemon and a connected browser | start a session |
+| `no-cli` / `no-daemon` / `no-extension` | something is missing | `node "<skill-root>/scripts/browser-install.mjs" [--browser=<id>]` prepares everything it can for **the browser the user uses**, then prints the **single** step only the user can do (relaunch that browser and click **Enable**); relay it verbatim, wait, re-run the doctor |
+| `choose-browser` | the signals do not single out one browser (Safari/Firefox default, an idle default while another browser runs, several in use) | nothing was installed; take the browser from memory or ask the user, then `browser-install.mjs --browser=<id>` |
+| `no-browser-support` | no Chromium-family profile on this machine | say so and stop |
+
+**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=<id>` 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)
+
+```js
+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
+}
+```
+
+1. **Read before every action.** `bskSnapshot` refs and `observe` `@eN` refs are reissued on each
+   call; use a ref in the same cycle you read it.
+2. **Navigation and large DOM changes stale every ref.** Read again rather than reusing.
+3. **Two identical failures mean change approach, not retry.** A third identical attempt is a defect.
+4. **Borrow a user tab explicitly** (`tabList({ scope: "user" })`, `tabBorrow(id)`, `tabReturn(id)`).
+   Borrowing prompts the user; never invent tab ids and never repeat a denied borrow.
+5. **Always `stop()` the session,** on success and on failure.
+
+Every method, its options, and the failure codes are in [references/commands.md](references/commands.md).
+
+## When a human is the only way through
+
+Login, CAPTCHA, OTP, a payment confirmation, a consent dialog:
+
+```js
+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
+
+- **Never read credentials through the page.** No `evaluate` that extracts a password, token,
+  cookie or recovery code. The value of the attached engine is that the browser is already signed in.
+- **Never clear cookies, cache or site data.** It is the user's real profile; clearing it logs them
+  out everywhere. No flow here needs it.
+- **`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
+  capture on every tab it drives, which is a known automation signal; CloakBrowser through
+  `connectCloakProfile()` is the stealth path.
+
+## Where the rest lives
+
+| Topic | Read |
+|---|---|
+| Session methods, targets, options, error codes | [references/commands.md](references/commands.md) |
+| Installing: CLI, daemon, extension, the one human step, blocklisted extension | [references/install.md](references/install.md) |
+| Agent on one machine, browser on another | [references/remote.md](references/remote.md) |
+| Owned engine: launch, snapshot ladder, network, frames, human handoff | [references/owned-engine/README.md](references/owned-engine/README.md) |
+| Reading a 1Password vault the user has unlocked | [references/recipes/1password.md](references/recipes/1password.md) |

package/packages/shared-skills/skills/browser/references/commands.md

@@ -0,0 +1,105 @@
+# Session methods
+
+`connectBrowserSkill()` returns a `BskSession`. Every method is one call on the BrowserSkill
+daemon's tool surface; options are the daemon's parameter names in camelCase.
+
+## Sessions
+
+```js
+const session = await omowright.connectBrowserSkill({ name: "<task>", focused: false, browser: "<instance id>", width: 1200, height: 800 })
+session.sessionId            // four letters, e.g. "ckhg"
+session.browserInstanceId    // which connected browser owns the Agent Window
+await session.stop()         // ALWAYS, on success and failure
+```
+
+`browser` is needed only when more than one browser is connected (`bskDoctor()` lists them).
+`focused: false` keeps the Agent Window from stealing focus; drop it only when the user is watching
+on purpose. Throws `BskRpcError` `no_browser_connected` when no extension is attached — that is a
+stop, not a cue to launch something else.
+
+## Targets
+
+| Form | Meaning |
+|---|---|
+| `"@e3"` / `"e3"` | a ref from the last `observe()` / `snapshot()` |
+| `"#login > button"` | a CSS selector, resolved live |
+| `{ captureId, x, y }` | a point in a screenshot, from `screenshot()` |
+| `css.e3` from `bskSnapshot` | the light-DOM CSS path of an OmOWright ref (`null` inside shadow roots — use the daemon ref instead) |
+
+## Reading
+
+| Call | Returns |
+|---|---|
+| `bskSnapshot(session, { interactive, maxDepth })` | `{ tree, refs, css }` — the OmOWright accessibility tree with refs, computed in the page **without** leaving a global or touching the DOM |
+| `session.observe({ maxTokens, cursor, probeHover })` | the daemon's semantic tree (`@vom`) with `@eN` refs, layers and hover probes — **the default read for shadow DOM and iframes** |
+| `session.snapshot({ maxDepth, maxTokens })` | the daemon's plain accessibility tree |
+| `session.getHtml({ ref, maxBytes })` | exact markup |
+| `session.screenshot({ ref })` / `screenshot({ fullPage: true })` | `{ buffer, width, height, captureId }`; full-page captures stream back in chunks |
+| `session.evaluate(expression, { awaitPromise, timeoutMs })` | `{ ok, value, error }` — **check `.ok`**; a resolved promise does not mean the script succeeded |
+| `session.console({ since })` / `session.network({ since })` | buffered console entries / request metadata (no bodies) |
+
+**Refs are reissued by every read.** Read a ref and act on it in the same cycle. A ref captured
+two calls ago silently addresses a different element — this is how a click lands on the
+neighbouring row.
+
+## Acting
+
+| Need | Call |
+|---|---|
+| Click | `session.click(target, { button, clickCount, modifiers })` |
+| Fill | `session.fill(target, value, { clearBefore })` |
+| Select | `session.select(target, ["<option value>"])` |
+| Key | `session.press("Enter", { target, modifiers, holdMs })` |
+| Hover | `session.hover(target, { settleMs })` |
+| Scroll into view | `session.scrollTo(target)` |
+| Wheel | `session.wheel({ deltaY: 600, target })` |
+| Focus / blur | `session.focus(target)` / `session.blur(target)` |
+| Navigate | `session.navigate(url, { waitUntil: "load" \| "domcontentloaded" \| "networkidle" \| "commit", timeoutMs })`, `back()`, `forward()`, `reload({ hard })`, `waitForNavigation()` |
+| Window | `session.resize(width, height)`, `session.emulate({ overrides: { width, mobile } })` |
+
+Traps:
+
+- `select` takes the option's **value attribute**, not its visible label.
+- `press` without `target` goes to the focused node; `press` with a CSS selector is fine, but a
+  daemon ref must come from the current read.
+- A menu that a `click` opens can be toggled shut by that same click. `focus` then `press("Enter")`
+  opens it reliably.
+- Hover-only controls report `element not visible`: hover the trigger, read again, then act on the
+  revealed item's fresh ref. `observe({ probeHover: true })` finds one when no marker does, at the
+  cost of touching the live page.
+- The clipboard is unavailable in a window started `focused: false`, so read values out of the DOM.
+
+## Tabs
+
+```js
+const { tabs } = await session.tabList({ scope: "user" })   // "user" | "agent" | "all"
+await session.tabBorrow(tabId)                                // the user confirms in the browser (60 s)
+await session.tabReturn(tabId)                                // stop() returns anything still borrowed
+await session.tabCreate({ url }); await session.tabSelect(id); await session.tabClose(id)
+```
+
+Never invent tab ids and never repeat a denied borrow.
+
+## Humans
+
+```js
+const { outcome } = await session.requestHelp({ prompt, title, targets: ["@e4"], completionCriteria, timeoutMs })
+// outcome: "completed" | "continued" | "cancelled" | "timed_out" | "navigated" | "disabled"
+```
+
+## Errors
+
+Every refusal is a `BskRpcError` with the daemon's own `code`:
+
+| `code` | Meaning | Do |
+|---|---|---|
+| `no_browser_connected` | no extension attached | run the onboarding script, relay the human step, wait |
+| `not_found` | stale ref or unknown session | read again; if the session is gone, start a new one |
+| `invalid_params` | wrong option shape | fix the call, do not retry as-is |
+| `permission_denied` | `evaluate` on a tab outside the Agent Window, or a denied borrow | stop; the user said no |
+| `timeout` | the tool did not finish in its budget | read the page state before retrying once |
+| `user_aborted` | the user pressed Stop in the browser | stop the task and report |
+| `cdp_failed` | the page cannot be attached (restricted URL, DevTools open) | say which page and why |
+
+Long calls can be cancelled: `const h = session.client.callWithHandle("tool.navigate", {...})`
+then `await session.client.cancel(h.rpcId)`.

package/packages/shared-skills/skills/browser/references/install.md

@@ -0,0 +1,97 @@
+# Installing the attached engine
+
+Three pieces. The onboarding script prepares all three; a human finishes exactly one.
+
+| Piece | Channel | Automatable |
+|---|---|---|
+| `bsk` CLI + daemon | upstream installer, GitHub Releases | **yes** |
+| Browser extension | registered from the Web Store listing through Chrome's external-extension mechanism | **yes, up to one click** — the browser asks the user to enable it |
+| Daemon process | auto-starts on the first call | nothing to do |
+
+## Supported
+
+| | |
+|---|---|
+| Operating systems | macOS (Apple Silicon and Intel), Linux (x64, ARM64), Windows x64 |
+| Browsers | Chrome, Microsoft Edge, Brave, Chromium, Arc, Dia, Vivaldi, Opera, Comet, Naver Whale — whichever the doctor lists under `candidates` |
+
+## Which browser
+
+The extension goes into exactly one browser: the one the user works in. Installed is not the same as
+used — a Chrome launched once keeps its profile directory forever — so the scripts rank candidates by:
+
+| Signal | Where it comes from |
+|---|---|
+| Default browser | macOS LaunchServices `https` handler, Linux `xdg-settings`, Windows `UserChoice` ProgId |
+| Running now | the app in `/Applications` (macOS), the process table elsewhere |
+| Used in the last 7 days | the profile's `Local State` / `History` modification time |
+
+Order of authority:
+
+1. **Your memory.** If you recorded the user's browser before, pass it: `--browser=<id>`.
+2. **`--browser=<id>` / `OMOWRIGHT_BROWSER`** set by the user.
+3. **The default browser, when it is also in use** (or nothing else is).
+4. **The only browser in use** when no default can be read.
+
+Anything else is `choose-browser` (doctor) / `needsChoice: true` (install): nothing is registered and
+`candidates` lists every browser with its signals. Ask the user which one they use, run the install
+with `--browser=<id>`, and save the answer to memory so the next session does not ask again. When
+the default browser is Safari or Firefox, BrowserSkill cannot drive it — say so and ask which
+Chromium-family browser to use.
+
+The doctor also lists `registeredElsewhere`: browsers that still carry an entry from an older
+onboarding. They are not removed automatically (removing the entry uninstalls an extension the user
+may have enabled); remove one only when the user asks, with omowright's `unregisterExternalExtension`.
+
+## One command
+
+```bash
+node "<skill-root>/scripts/browser-install.mjs" [--browser=<id>] [--json] [--wait-ms=180000]
+```
+
+In order it: runs upstream's official `install.sh` / `install.ps1` into `~/.local/bin` (any PATH
+line the installer appends to a shell rc file is reverted — the library calls the binary by
+absolute path); starts the daemon with `bsk status`; and, for **the one browser the user actually
+uses**, registers the Web Store listing as an external extension:
+
+| Platform | Where the entry goes | The user's one step |
+|---|---|---|
+| macOS | `<user data dir>/External Extensions/<id>.json` | quit the browser completely, open it again, click **Enable** in the dialog |
+| Windows | `HKCU\Software\<vendor>\<browser>\Extensions\<id>` (`reg add`, no admin) | click **Enable** on the toolbar badge; no restart |
+| Linux (Chromium) | `<user data dir>/External Extensions/<id>.json` | relaunch; installs without a prompt |
+| Linux (Chrome / Edge / Brave) | `/opt/google/chrome/extensions/<id>.json` and siblings — root only | otherwise open the store link it prints and click **Add** |
+| Opera, and Vivaldi / Whale off macOS | no external-extension path | open the store link it prints in that browser and click **Add** |
+
+The script prints that step as `humanStep`. **Relay it verbatim and wait**; with `--wait-ms` it
+keeps polling the daemon until the extension connects. An empty `browsersConnected` afterwards is
+not a failure to work around — the browser is closed or the user has not clicked yet; say which
+and ask.
+
+If the user removed the extension from the browser before, Chrome blocklists its id for external
+installs. The script detects that (`reason: "blocklisted"`) and prints the store link instead:
+
+- Chrome: https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi
+- Edge: https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg
+
+Enterprise force-install policies are deliberately not used: they brand the browser "managed by
+your organization" and the user cannot remove the extension.
+
+## Do not install upstream's skill
+
+Upstream ships its own agent skill through `bsk install-skill`. **Do not run it here.** This
+package already provides the skill, and upstream's copy installs under a different name into the
+user skill directory, which takes precedence over a shipped skill — two descriptions of the same
+engine, one of them shadowing the one that knows about omowright and this package's scripts.
+
+## Diagnosing
+
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs" --json   # this package's view: cli, daemon, the user's browser + candidates, registrations, connections
+bsk doctor                                              # upstream's own checks
+bsk logs                                                # daemon log
+```
+
+The daemon exits about ten minutes after the last browser disconnects and is not a system
+service, so a reboot also stops it. Both heal on the next call — `connectBrowserSkill()` starts it
+unless `BSK_AUTO_START=0` (sandboxes that reap background processes keep the daemon on the host
+and share `BSK_HOME`; see upstream's sandboxed-agents guide).

package/packages/shared-skills/skills/browser/references/owned-engine/README.md

@@ -0,0 +1,62 @@
+# The owned engine
+
+A browser **your code launches and owns**, driven over CDP by omowright with its own profile. The
+opposite of the attached engine: no user logins, full control.
+
+```js
+const { omowright } = await loadOmowright()
+const profile = mkdtempSync(join(tmpdir(), "omowright-"))
+const browser = await omowright.connectPipe({
+  browserPath: "<CloakBrowser or chrome-headless-shell binary>",
+  browserArgs: ["--headless", "--no-first-run", `--user-data-dir=${profile}`],
+  storageRoot: profile,
+  dialogPolicy: { accept: true },
+})
+try {
+  const page = await browser.newTab("https://example.com/")
+  const tree = omowright.compactSnapshot(await page.snapshot())   // ALWAYS compact before a model reads it
+  await page.locator("e3").click()                                 // refs come straight from the snapshot
+  await Bun.write("shot.png", await page.screenshot())
+} finally {
+  await browser.close()
+  rmSync(profile, { recursive: true, force: true })                // paired: a leftover profile is a logged-in browser nobody watches
+}
+```
+
+`connectPipe` launches over `--remote-debugging-pipe`: no listening port, stdio drained, the
+process reaped on `close()`. `connect("http://127.0.0.1:<port>")` attaches to a browser something
+else launched. `connectCloakProfile({ profileDir })` launches CloakBrowser with a pinned
+fingerprint seed — the stealth path for WAF and bot-scored targets, where the attached engine's
+console capture would be a signal.
+
+## When it is the right engine
+
+| Reason | Why the attached engine cannot |
+|---|---|
+| A throwaway or pinned synthetic profile | the attached engine is the user's real profile |
+| Bot-scoring or fingerprint evasion | you do not get to configure the user's browser |
+| Solving a challenge widget programmatically | needs coordinate control and OCR |
+| Reading the network instead of the DOM | needs request interception on your own target |
+| A QA flight trace (steps, HAR, screenshots) | recording someone's real session is not acceptable |
+| Headless or unattended runs | the user's browser is on their desk |
+
+For anything that needs the user's login, the attached engine wins. For extracting text from a
+blocked URL, neither: use the `ultimate-browsing` skill.
+
+## The page
+
+`OmOPage` is Playwright-shaped: `goto`, `snapshot`, `locator(ref | css)`, `click`, `fill`,
+`press`, `hover`, `check`, `selectOption`, `dragTo`, `setInputFiles`, `screenshot`, `pdf`,
+`evaluate`, `waitForURL`, `keyboard`, `mouse`, `frameLocator`. A snapshot is an accessibility tree
+with virtual refs (`[ref=e3]`, cross-origin frames as `f1e3`); `compactSnapshot()` drops the refs
+map, about half the bytes. Readiness is a content probe (body plus interactive elements, landmarks
+or text), not a timer; `goto(url, { waitUntil: "commit" })` is the escape hatch for empty pages.
+
+## Reference
+
+- [ladder.md](ladder.md) — the escalation ladder, viewport pinning, `createCua`, `createCaptcha`
+- [network.md](network.md) — `createNetworkSnoop`, `collectWhileScrolling`, `createTrace`, `createRoutes`
+- [frames-and-humans.md](frames-and-humans.md) — `snapshotWithFrames`, `describeLayers`, dialog policy, `emulate`, `requestHuman`
+
+The library's own skill (`skills/omowright/SKILL.md` and `presets/*` in the omowright repository)
+is the authoritative, longer treatment of each; these pages are the routing summary.

package/packages/shared-skills/skills/browser/references/owned-engine/frames-and-humans.md

@@ -0,0 +1,52 @@
+# Frames, overlays, dialogs, and the human
+
+## Cross-origin frames and shadow DOM
+
+A cross-origin iframe is a separate target with its own snapshot. `snapshotWithFrames(page)`
+reconciles the child trees into the parent so one tree describes the whole page, and reports
+`missingFrames` for any it could not enter; address child elements through the page-level ref
+(`f1e3`) — never by fetching a frame handle first. Shadow roots are traversed by the snapshot
+engine; they are not a special case for you.
+
+## Overlays that swallow clicks
+
+Two identical misses on an element that is clearly visible usually means something invisible sits
+on top: a consent banner, a modal backdrop, a sticky header, a full-viewport tracking layer.
+`describeLayers(page)` names the topmost fixed or sticky element covering the viewport, and
+`snapshotWithLayers(page)` prefixes a snapshot with `@layers blocking=<role> "<name>"` when one
+exists. Either the overlay is named — dismiss it and continue — or `@layers none`, which means the
+miss has another cause and you climb the ladder instead.
+
+## Dialogs never block
+
+`alert`, `confirm`, `prompt`, and `beforeunload` are answered by the `dialogPolicy` passed to
+`connectPipe` (or `browser.setDialogPolicy`), at the protocol layer, before the page sees them.
+Default to accepting (`{ accept: true }`; a function receives `{ type, message }` and returns
+`{ accept, promptText }`). `page.on("dialog")` still fires for observability. A run that hangs on
+an unhandled dialog looks exactly like a hang with no cause, which is the most expensive kind to
+diagnose.
+
+## Device emulation
+
+`emulate(page, "iphone-14")` applies viewport, device scale factor, user agent and touch together;
+changing only the viewport produces a desktop page at a phone size, which is not what you are
+testing. `emulate(page, null)` restores. Re-read the viewport after emulating, and re-pin
+coordinates.
+
+## Handing the page to a human
+
+When every rung fails on a login, a one-time code, or a challenge you cannot clear, the human is
+the fallback, not the failure:
+
+```js
+const { outcome } = await omowright.requestHuman(page, {
+  prompt: "Please finish the sign-in in this window.",
+  until: { url: /\/dashboard/ },          // or { selector } or async (page) => boolean
+  timeoutMs: 300_000,
+})
+```
+
+It brings the window to the front, shows a banner with a Done button, and waits on a
+**condition** with a bounded timeout rather than a fixed delay. Respect the answer: `timed_out`
+or `cancelled` is a stop, and the correct response is to report which rung failed with what
+evidence. Working around the user's refusal is never correct.

package/packages/shared-skills/skills/browser/references/owned-engine/ladder.md

@@ -0,0 +1,61 @@
+# The escalation ladder
+
+**Two identical failures on the same target mean climb, not retry. A third identical attempt is a
+defect.** The failure itself selects the next rung; never pause to ask which.
+
+| Rung | Use | Climb when |
+|---|---|---|
+| 1. `page.snapshot()` + `page.locator(ref)` | anything with a usable ref | the ref is absent, stale, obscured, or the click lands on the wrong node twice |
+| 1b. `snapshotWithLayers(page)` / `describeLayers(page)` | a blocking overlay explains two identical misses | `@layers none`, or the overlay is gone and the click still misses |
+| 2. `createCua(page)` coordinates | canvas, extension popups, custom controls, drag surfaces | the click misses, or the screenshot and the coordinates disagree |
+| 3. pin the viewport (`emulate(page, "desktop-1440")` / `repinViewport`), redo rung 2 | coordinate drift after a resize, a DPI change, or a foreign tab | coordinates land correctly but the widget still refuses input |
+| 4. `createCaptcha(page)` | a challenge is the blocker | it clears and the flow still stalls |
+| 5. read the browser log (`browser.close()` surfaces the stdio tail) | a browser-level failure | the log names a cause outside the page |
+
+**Rung 5 ends in a written diagnosis, never a speculative code change.** A missing entitlement, a
+dead extension service worker, an unavailable authenticator — none of those is fixed by editing
+automation code.
+
+## Pin the viewport before trusting any coordinate
+
+`createCua(page)` acts in viewport pixels. When the render surface and the coordinate space
+disagree, every coordinate is off by the same constant and retrying just repeats the miss. Set the
+device metrics explicitly (`emulate` applies width, height, `deviceScaleFactor` and touch
+together), re-read the page's viewport size, then take a **fresh** `cua.getVisibleScreenshot()`.
+Coordinates read off an unpinned screenshot are stale. Pin every page you act on, including tabs
+you did not open (`createAgentTabs` re-pins on create).
+
+## Refs
+
+- Refs die on every new snapshot. Pass a ref straight from the latest snapshot; never reuse one
+  across snapshots and never put one in a CSS selector.
+- Refs stay page-level. A child-frame ref (`f1e3`) still resolves through `page.locator`, so you
+  never fetch a frame handle to click inside an iframe.
+- Always `compactSnapshot()` before sending a snapshot to a model.
+
+## Challenge widgets
+
+A challenge is an obstacle on the path, not a stop sign: clear it, confirm it cleared, continue.
+`createCaptcha(page)` gives three techniques:
+
+- **Checkbox** (the common embedded widgets): the control lives in a nested frame, so
+  `captcha.click(bounds)` addresses it by viewport coordinates.
+- **Slider / puzzle**: `captcha.drag(from, to, { steps })` with enough intermediate steps that the
+  motion reads as human. Raise the step count before you change the endpoints.
+- **Text or number**: `captcha.readText(bounds)` OCRs the region — the macOS Vision framework by
+  default, or pass your own `ocr` function or a vision model.
+- **Image grid**: annotate a screenshot, then click per cell with `createCua`.
+
+**Bounds measured against an unpinned viewport are wrong by a constant offset.** If clicks have
+been landing wrong, drop to rung 3 first, then re-read the bounds.
+
+Verify with a fresh snapshot that the challenge is gone. Verification is part of the action, not a
+separate optimistic assumption. When every technique fails on a page a real browser passes, the
+engine is the variable: relaunch through `connectCloakProfile()`.
+
+## Delegating the pixel loop
+
+Coordinate work and challenge solving are iterative: screenshot, reason, act, verify. When that
+loop would consume your own context, delegate the blocked page to a subagent armed with these
+references and have it return the post-solve state. Drive it yourself when the flow is short or
+the state is already in your hands.

package/packages/shared-skills/skills/browser/references/owned-engine/network.md

@@ -0,0 +1,62 @@
+# Read the network, not the DOM
+
+When a page renders a list, a table, or search results, the data almost always arrived as JSON one
+request earlier. That JSON is complete, typed, free of markup, and immune to the layout changing
+next week. Watching traffic costs nothing on a target you own, and the page cannot observe it.
+
+**Snoop before you scrape.** Scroll-and-parse is the fallback, not the default.
+
+```js
+const snoop = omowright.createNetworkSnoop(page, { maxBodyBytes: 512 * 1024 })
+await page.goto(url)
+const hit = await snoop.waitFor({ url: /\/api\/search/, mimeType: "application/json" }, { timeoutMs: 10_000 })
+const rows = snoop.popJson()                 // every buffered JSON body, drained
+console.log(snoop.summary({ max: 20 }))      // one line per request: method status mime size url
+snoop.dispose()
+```
+
+## Wait for a request, never for a clock
+
+A fixed sleep is a guess that fails on a slower machine and wastes time on a faster one.
+`snoop.waitFor(match)` subscribes to the response you expect **before** you trigger the action,
+then awaits it with a bounded timeout. This is the same rule that governs test code, for the same
+reason.
+
+## Collecting through infinite scroll
+
+```js
+for await (const batch of omowright.collectWhileScrolling(page, snoop, { minItems: 200, maxScrolls: 10, extract: (json) => json.items })) {
+  items.push(...batch)
+}
+```
+
+Scroll, collect what is new, stop on a target count or a scroll ceiling. Bound both, so a page
+that keeps producing cannot run forever.
+
+## Flight traces
+
+For QA evidence, `createTrace(page, { dir })` records one entry per `trace.step(name, fn)` with
+before/after screenshots, the network log and console output, written as `trace.jsonl` plus
+`trace.har` (`toHar` builds the HAR from snoop entries). That triple is what makes a failure
+reconstructable afterwards instead of re-runnable-in-theory. Call `trace.stop()` in `finally`.
+
+Cap recorded body sizes. An untrimmed trace of a media-heavy page is mostly bytes nobody reads.
+
+## Request interception
+
+`createRoutes(page)` matches by glob, regular expression, or predicate and lets a handler
+`continue`, `fulfill({ status, body })` or `abort()`: stub an endpoint, fail one request to test an
+error path, block third-party noise. Interception is enabled on the first route and disabled on
+`dispose()` — leaving it on slows every later navigation and changes the timing fingerprint, so
+prefer passive snooping on bot-scored targets.
+
+## Cookies
+
+`injectCookies(page, cookies)` sanitizes what it injects (drops expired entries, keeps
+host-prefixed cookies secure and root-scoped). Injecting an export into your own profile is
+legitimate for ordinary sessions and useless for the ones you most want: accounts whose risk
+engines bind a session to a device will invalidate it, and a password manager's session is
+tab-bound and never portable.
+
+**Never copy a session out of the user's real browser profile.** If you need their login, that is
+the attached engine's job.

package/packages/shared-skills/skills/browser/references/recipes/1password.md

@@ -0,0 +1,61 @@
+# Reading a 1Password vault the user has unlocked
+
+Scope: reading an item out of a vault **the user has already unlocked in their browser**. Signing
+in is the user's job; see "Not in scope" below.
+
+## The fact that shapes everything
+
+1Password web is zero-knowledge. The unlocked vault key lives in **one tab's `sessionStorage`**,
+not in a cookie. So:
+
+- A **new** tab pointed at the vault redirects to the sign-in page even while a signed-in tab sits
+  right beside it. Opening your own tab does not work and never will.
+- Navigating the authenticated tab away, or closing it, **destroys the session** until a human
+  signs in again.
+
+Therefore: borrow the existing tab, read, return it. Do not open, do not navigate away, do not
+"refresh to fix" anything.
+
+```js
+const { tabs } = await session.tabList({ scope: "user" })          // find the already-signed-in tab by URL
+const vault = tabs.find((t) => /my\.1password\.com\/(?:vaults|app)/.test(t.url))
+await session.tabBorrow(vault.tab_id)                               // the user confirms
+// ... read ...
+await session.tabReturn(vault.tab_id)
+```
+
+## Check liveness by URL, never by title
+
+The app mutates its URL hash without updating the document title, so a signed-in vault can still
+report a sign-in title. A live session's `location.href` contains the app path and never the
+sign-in path. Read the URL from `tabList`, or `session.evaluate("location.href")`.
+
+## The browser may be shared
+
+Other automation may be driving the same window.
+
+- **Clear the search box before typing** (`fill(target, value, { clearBefore: true })`). It often
+  holds someone else's query, and typing alone appends to it, returning confident results for the
+  wrong search.
+- **Read the autocomplete listbox, not the results grid.** The grid holds whatever query was last
+  committed, possibly by another actor. Scraping every option on the page silently merges two
+  different searches.
+- **Leave the tab on the item list** when you are done, so the next actor starts clean.
+
+## If it is locked
+
+```js
+await session.requestHelp({ prompt: "Please unlock 1Password in this tab, then continue." })
+```
+
+Then read the page again.
+
+## Not in scope
+
+- **Do not type a master password, and do not automate the sign-in form.** Only the account owner
+  signs in. If the vault is locked, hand it to them.
+- **Do not extract secrets through the page** beyond the single value the user asked for, and
+  report it masked (`abcd…9fb0 (len 37)`) unless they asked for the exact string.
+- **Do not copy, inject, or reuse session cookies.** The session is device- and tab-bound; cookie
+  reuse cannot work and trips account protections.
+- Clear the clipboard if you ever populate it.

package/packages/shared-skills/skills/browser/references/remote.md

@@ -0,0 +1,25 @@
+# Agent here, browser there
+
+The agent and the browser do not have to be the same machine. Upstream supports this directly;
+nothing in this package needs to bridge it.
+
+Shape:
+
+- The **browser machine** needs only the extension.
+- The **agent machine** runs the `bsk` daemon, omowright and this skill.
+- They are joined by a daemon in server mode plus a pairing link.
+
+```bash
+bsk daemon start --mode server      # on the machine the agent runs on; WSS is required off loopback
+```
+
+Then follow upstream's pairing guide, which owns the current flag surface and the TLS
+prerequisites: https://github.com/Tencent/BrowserSkill/blob/main/docs/remote-extension-connection.md
+
+Once paired, `connectBrowserSkill()` and every session method behave identically; screenshot
+buffers arrive on the machine that ran the call. Windows named pipes are not discovered
+automatically — pass `sockPath` to `connectBrowserSkill()`.
+
+If pairing is not configured, say so and ask. Do not substitute a browser on the agent machine:
+the point of the attached engine is the sessions that live in the user's browser, and a local
+browser has none of them.