oh-my-opencode 5.0.0-beta.85 → 5.0.0-beta.87

package/dist/skills/browser/references/owned-engine/ladder.md

@@ -5,12 +5,12 @@ defect.** The failure itself selects the next rung; never pause to ask which.
 
 | Rung | Use | Climb when |
 |---|---|---|
-| 1. snapshot + locator(ref) | anything with a usable ref | the ref is absent, stale, obscured, or the click lands on the wrong node twice |
-| 1b. layer description | a blocking overlay explains two identical misses | no overlay is reported, or it is gone and the click still misses |
-| 2. coordinates | canvas, extension popups, custom controls, drag surfaces | the click misses, or the screenshot and the coordinates disagree |
-| 3. pin the viewport, 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. the challenge widget | a challenge is the blocker | it clears and the flow still stalls |
-| 5. read the browser log | a browser-level failure | the log names a cause outside the page |
+| 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
@@ -18,38 +18,40 @@ automation code.
 
 ## Pin the viewport before trusting any coordinate
 
-Coordinate input acts in viewport pixels. When the render surface and the coordinate space
+`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 (width, height, `deviceScaleFactor`, and a matching viewport), re-read
-the page's viewport size, then take a **fresh** screenshot. Coordinates read off an unpinned
-screenshot are stale. Pin every page you act on, including tabs you did not open.
+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 still resolves through the page, so you never fetch a
-  frame handle to click inside an iframe.
-- Always compact a snapshot before sending it to a model.
+- 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.
-Three shapes, three techniques:
+`createCaptcha(page)` gives three techniques:
 
-- **Checkbox** (the common embedded widgets): the control lives in a nested frame, so address it
-  by viewport coordinates.
-- **Slider / puzzle**: drag along a path with enough intermediate steps that the motion reads as
-  human. Raise the step count before you change the endpoints.
-- **Text or number**: OCR the region. On macOS the system vision framework is the cheapest
-  accurate option; elsewhere pass your own OCR function or a vision model.
-- **Image grid**: annotate a screenshot, then click per cell.
+- **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.
+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
 

package/dist/skills/browser/references/owned-engine/network.md

@@ -6,37 +6,57 @@ next week. Watching traffic costs nothing on a target you own, and the page cann
 
 **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. Subscribe
-to the response you expect **before** triggering the action, then await that signal with a bounded
-timeout. This is the same rule that governs test code, for the same reason.
+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
 
-Drive scroll and extraction as a generator: 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.
+```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, record a trace: one entry per step with before/after screenshots, the network
-log, and console output, written as a line-delimited log plus an HAR. That triple is what makes a
-failure reconstructable afterwards instead of re-runnable-in-theory.
+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
 
-Route matching by glob, regular expression, or predicate lets you stub an endpoint, fail one
-request to test an error path, or block third-party noise. Enable interception on the first route
-and disable it on dispose — leaving it on slows every later navigation.
+`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
 
-Injecting a cookie 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. Sanitize what you do inject
-(drop expired entries, keep host-prefixed cookies secure and root-scoped).
+`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/dist/skills/browser/references/recipes/1password.md

@@ -16,25 +16,27 @@ not in a cookie. So:
 Therefore: borrow the existing tab, read, return it. Do not open, do not navigate away, do not
 "refresh to fix" anything.
 
-```bash
-bsk tab list --scope user           # find the already-signed-in tab
-bsk tab borrow <tab-id>
-# ... read ...
-bsk tab return <tab-id>
+```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.
+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.** It often holds someone else's query, and typing alone
-  appends to it, returning confident results for the wrong search.
+- **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.
@@ -42,11 +44,11 @@ Other automation may be driving the same window.
 
 ## If it is locked
 
-```bash
-bsk request-help --session <id> --prompt "Please unlock 1Password in this tab, then continue."
+```js
+await session.requestHelp({ prompt: "Please unlock 1Password in this tab, then continue." })
 ```
 
-Then observe again.
+Then read the page again.
 
 ## Not in scope
 

package/dist/skills/browser/references/remote.md

@@ -6,18 +6,19 @@ nothing in this package needs to bridge it.
 Shape:
 
 - The **browser machine** needs only the extension.
-- The **agent machine** runs the `bsk` CLI and this skill.
+- 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
+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, every command in `commands.md` behaves identically; `--out` paths still resolve on
-the machine that ran the command.
+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