oh-my-opencode 5.0.0-beta.9 → 5.0.0-beta.90

package/packages/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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.