lazycodex-ai 5.0.0-beta.82 → 5.0.0-beta.84

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

@@ -0,0 +1,89 @@
+---
+name: browser
+description: "Drives a real browser: sites the user is already signed into, forms and clicks, JS-rendered pages, screenshots, web QA, extension popups, and a human handoff for login, CAPTCHA or OTP. Works through the BrowserSkill extension and its bsk CLI, inside the user's own browser, in a separate Agent Window. Use for any interactive browser task; not for a plain search or an unblocked static fetch."
+---
+
+# Browser
+
+Two engines live behind this skill. Choose before you act:
+
+| You need | Engine | Where |
+|---|---|---|
+| A site the user is signed into, a form, a click-through, a screenshot, web QA, an extension popup | **attached** — the user's own browser | this file |
+| A throwaway profile, bot-scoring evasion, a CAPTCHA, network interception, a QA flight trace, coordinate control | **owned** — a browser your code launches | [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 command away. The owned engine is an opt-in local install, not part
+of this package.
+
+## Step 0 — prove the stack before you drive it
+
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs"
+```
+
+It reports one of four states and what to do next:
+
+| State | Meaning | Next |
+|---|---|---|
+| `ready` | CLI, daemon and a connected browser | start a session |
+| `no-extension` | CLI works, no browser is connected | give the user the store link the doctor printed, wait, re-run |
+| `no-cli` | `bsk` is not installed | `node "<skill-root>/scripts/browser-install.mjs"`, then re-run |
+| `no-browser-support` | the platform has no supported browser | say so and stop |
+
+**Never substitute another browser for a missing one.** A headless browser you launch yourself has
+none of the user's sessions, so every login turns into a ladder you should not be climbing. If the
+attached engine is unavailable, say which state you hit and ask the user.
+
+## The loop
+
+```bash
+bsk session start --json --no-focus --name "<task>"     # keep session_id
+bsk navigate https://example.com --session <id> --json
+bsk observe --session <id>                              # @eN refs live here
+bsk click @e1 --session <id> --json
+bsk screenshot --session <id> --out ./shot.png --json
+bsk session stop <id> --json                            # success AND failure
+```
+
+1. **Observe before every action.** `observe` returns a semantic tree whose `@eN` refs are reissued
+   on each call. Read a ref and use it in the same cycle; a ref from two calls ago points somewhere
+   else now.
+2. **Navigation and large DOM changes stale every ref.** Observe 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** (`tab list --scope user`, `tab borrow <id>`, `tab return <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. Stopping also returns borrowed tabs.
+
+Command semantics, the flags that behave differently than they read, and the failure table 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:
+
+```bash
+bsk request-help --session <id> --prompt "<what you need done>" [--target @eN]
+```
+
+Then observe again. Respect a `cancelled` or `timed_out` answer; 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 this 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.
+- **`--no-focus` by default.** The browser belongs to someone who is probably using it.
+- **One short, named session per task,** always stopped.
+- Do not toggle the extension's automation settings, and do not restart the browser to fix a state.
+
+## More
+
+- [references/install.md](references/install.md) — installing the CLI and the extension, per OS
+- [references/commands.md](references/commands.md) — command semantics, refs, failure table
+- [references/remote.md](references/remote.md) — agent on one machine, browser on another
+- [references/recipes/1password.md](references/recipes/1password.md) — reading a vault the user has unlocked
+- [references/owned-engine/README.md](references/owned-engine/README.md) — the code-driven engine

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

@@ -0,0 +1,90 @@
+# Command semantics
+
+Everything here cost a failed attempt to learn. Read it before improvising.
+
+## Sessions
+
+```bash
+bsk session start --json --no-focus --name "<task>"   # keep session_id
+bsk session list
+bsk session stop <id> --json                          # positional id, not --session
+```
+
+Every session-scoped command needs `--session <id>`. `--no-focus` keeps the Agent Window from
+stealing focus; drop it only when the user is watching on purpose.
+
+## Reading
+
+| Command | Returns |
+|---|---|
+| `observe --session <id>` | semantic tree with `@eN` refs and perception probes — **the default read** |
+| `snapshot --session <id>` | static accessibility tree |
+| `get-html --session <id>` | exact markup, hidden metadata |
+| `screenshot --session <id> --out <path>` | PNG; add `--full-page` for a long capture |
+| `evaluate "<js>" --session <id> --json` | `{ok, value}` — **check `.ok`; exit code 0 does not mean the script succeeded** |
+| `console` / `network` | buffered log lines and responses |
+
+**Refs are reissued by every `observe` and `snapshot`.** 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.
+
+`observe --max-tokens <n>` bounds a large page. There is no default cap.
+
+## Acting
+
+| Need | Command |
+|---|---|
+| Click | `click @e3 --session <id>` |
+| Fill | `fill @e3 --value "text" --session <id>` |
+| Select | `select @e3 --value "<option value>" --session <id>` |
+| Key | `press Enter --ref @e3 --session <id>` |
+| Hover | `hover @e3 --session <id>` |
+| Scroll into view | `scroll-to @e3 --session <id>` |
+| Wheel | `wheel --delta-y 600 --session <id>` |
+| Focus / blur | `focus @e3` / `blur @e3` |
+| Upload / download | `upload --file <path>` / `download --out <path>` |
+
+Traps:
+
+- `select` takes the option's **value attribute**, not its visible label.
+- `fill` and `click` accept a CSS selector; **`press --ref` does not** — it answers
+  `ref_not_found` for a selector. `press` without `--ref` goes to the focused node.
+- 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, observe, then act on the
+  revealed item's fresh ref. Markers like `[has-submenu]` and `[expanded]` identify triggers;
+  `observe --probe-hover` finds one when no marker does, at the cost of touching the live page.
+- The clipboard is unavailable in a window started `--no-focus` (no document focus), so read
+  values out of the DOM instead.
+
+## Borrowing a user tab
+
+```bash
+bsk tab list --scope user
+bsk tab borrow <tab-id>
+bsk tab return <tab-id>
+```
+
+Borrowing asks the user to confirm. Never invent a tab id, never repeat a denied borrow, and
+always return what you borrowed (`session stop` also returns them).
+
+## Failures
+
+| Symptom | Meaning | Response |
+|---|---|---|
+| `browsers: []` | extension not connected | ask the user to open the browser / enable the extension |
+| daemon missing | idle exit or reboot | none; the next call restarts it |
+| `cdp_failed: Cannot access a chrome-extension:// URL of different extension` | another extension injected a frame, so the debugger cannot attach to that tab | transient and page-specific; collapse the work into one `evaluate` and retry, or navigate away and back |
+| `permission_denied: element not visible` | hover-gated or clipped control | drive its menu instead |
+| `ref_not_found` | stale ref, or a selector passed to `press` | observe again; use a real ref |
+| version skew warning | CLI and extension disagree | `bsk update` after finishing sessions; the extension updates through its store |
+
+**Two identical failures select a different approach. A third identical attempt is a defect.**
+
+## Sandboxed hosts
+
+If the host kills background children after each command, the daemon cannot survive between calls.
+Set `BSK_AUTO_START=0`, share one `BSK_HOME` across every call, and start
+`bsk daemon start --foreground` in the host's persistent background task. Check readiness with
+`bsk status --json` in a separate call before continuing. Do not loop on launches, delete runtime
+files, or restart a daemon another task is using.

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

@@ -0,0 +1,71 @@
+# Installing the attached engine
+
+Three pieces. The agent can install exactly one of them.
+
+| Piece | Channel | Automatable |
+|---|---|---|
+| `bsk` CLI + daemon | upstream installer, GitHub Releases | **yes** |
+| Browser extension | Chrome Web Store / Edge Add-ons | **no — a human clicks Install** |
+| Daemon process | auto-starts on any `bsk` call | nothing to do |
+
+## Supported
+
+| | |
+|---|---|
+| Operating systems | macOS (Apple Silicon and Intel), Linux (x64, ARM64), Windows x64 |
+| Browsers | Chrome, Microsoft Edge. Other Chromium browsers work where they accept store builds. |
+
+## 1. The CLI
+
+```bash
+node "<skill-root>/scripts/browser-install.mjs"
+```
+
+That wraps upstream's official installer:
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh
+export PATH="${BSK_INSTALL_DIR:-$HOME/.local/bin}:$PATH"
+
+# Windows (PowerShell)
+irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex
+```
+
+The Unix installer cannot change its parent shell's `PATH`. A shell opened before the install may
+still miss it, so either re-export in each call or use the absolute path (`$HOME/.local/bin/bsk`,
+`bsk.exe` on Windows). Verify with `bsk --version`.
+
+## 2. The extension
+
+Give the user the listing for their browser and wait:
+
+- Chrome: https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi
+- Edge: https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg
+
+Then confirm it landed:
+
+```bash
+bsk status --json     # a non-empty "browsers" array means connected
+```
+
+An empty `browsers` list is not a failure to work around. Either the browser is closed or the
+extension is not enabled; say which and ask.
+
+## 3. 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
+CLI, one of them shadowing the one that knows about this package's recipes and helper scripts.
+
+## Diagnosing
+
+```bash
+node "<skill-root>/scripts/browser-doctor.mjs"          # this package's view
+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 `bsk` call — no repair needed.

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

@@ -0,0 +1,42 @@
+# The owned engine
+
+A browser **your code launches and owns**, driven over CDP, with its own profile. The opposite of
+the attached engine: no user logins, full control.
+
+**This package ships no such engine.** These documents describe the contract and the technique, so
+that a locally installed CDP library — or a script you write against one — is driven correctly.
+If no owned engine is installed, say so and stay on the attached engine.
+
+## 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 |
+
+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.
+
+## What an owned engine must give you
+
+1. A transport that opens no listening port (launch over a pipe), or an explicit local CDP endpoint.
+2. An accessibility snapshot with stable in-page refs, and a **compact** form that drops the ref
+   map before the tree reaches a model — on a real page that map is roughly half the bytes and the
+   client never reads it.
+3. Locators that resolve those refs in-page, including refs inside cross-origin frames.
+4. Coordinate input, for what locators cannot address.
+5. A dialog policy, so `alert` / `confirm` / `beforeunload` can never block a run.
+
+## Reference
+
+- [ladder.md](ladder.md) — the escalation ladder, viewport pinning, coordinate control, challenge widgets
+- [network.md](network.md) — read the network instead of the DOM; traces and request interception
+- [frames-and-humans.md](frames-and-humans.md) — cross-origin frames, overlays, dialogs, human handoff
+
+## Cleanup is paired
+
+Close the browser and remove the profile directory in the same `finally`. A profile left behind is
+a logged-in browser nobody is watching.

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

@@ -0,0 +1,39 @@
+# Frames, overlays, dialogs, and the human
+
+## Cross-origin frames and shadow DOM
+
+A cross-origin iframe is a separate target with its own snapshot. Reconcile the child trees into
+the parent so one tree describes the whole page, and address child elements through the page-level
+ref — 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.
+Describe the layers at the click point before you retry. Either the overlay is named — dismiss it
+and continue — or nothing is reported, which means the miss has another cause and you climb the
+ladder instead.
+
+## Dialogs never block
+
+`alert`, `confirm`, `prompt`, and `beforeunload` must be answered by a policy set when the
+browser is created, not by a listener you hope registers in time. Default to accepting
+(`confirm` true, `prompt` empty). 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
+
+Emulating a device is viewport plus user agent plus touch, applied together. Changing only the
+viewport produces a desktop page at a phone size, which is not what you are testing. 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. Bring the tab to the front, state plainly what needs doing, and
+wait on a **condition** — the URL changed, the element appeared — with a bounded timeout, rather
+than on a fixed delay.
+
+Respect the answer. A cancelled or timed-out handoff 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,59 @@
+# 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. 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 |
+
+**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
+
+Coordinate input 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.
+
+## 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.
+
+## Challenge widgets
+
+A challenge is an obstacle on the path, not a stop sign: clear it, confirm it cleared, continue.
+Three shapes, 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.
+
+**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.
+
+## 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,42 @@
+# 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+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.
+
+## 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).
+
+**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,59 @@
+# 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.
+
+```bash
+bsk tab list --scope user           # find the already-signed-in tab
+bsk tab borrow <tab-id>
+# ... read ...
+bsk tab return <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.
+
+## 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.
+- **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
+
+```bash
+bsk request-help --session <id> --prompt "Please unlock 1Password in this tab, then continue."
+```
+
+Then observe 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,24 @@
+# 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` CLI 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
+```
+
+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.
+
+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.

package/packages/shared-skills/skills/browser/scripts/browser-doctor.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { platform } from "node:os"
+import { connectedBrowsers, readStatus, resolveCli, STORE_LISTINGS, SUPPORTED_PLATFORMS } from "./browser-env.mjs"
+
+const REMEDIES = {
+  ready: "Start a session: bsk session start --json --no-focus --name \"<task>\"",
+  "no-extension": `Ask the user to install and enable the extension, then re-run this doctor.\n  Chrome: ${STORE_LISTINGS.chrome}\n  Edge:   ${STORE_LISTINGS.edge}`,
+  "no-cli": "Install the CLI: node \"<skill-root>/scripts/browser-install.mjs\", then re-run this doctor.",
+  "no-browser-support": "This platform has no supported browser. Say so and stop; do not substitute another engine.",
+}
+
+async function diagnose() {
+  if (!SUPPORTED_PLATFORMS.has(platform())) {
+    return { state: "no-browser-support", platform: platform() }
+  }
+  const cli = await resolveCli()
+  if (cli === undefined) return { state: "no-cli", platform: platform() }
+
+  let status
+  try {
+    status = await readStatus(cli)
+  } catch (error) {
+    return { state: "no-extension", platform: platform(), cli, detail: `status failed: ${error.message}` }
+  }
+  const browsers = connectedBrowsers(status)
+  if (browsers.length === 0) return { state: "no-extension", platform: platform(), cli }
+  return { state: "ready", platform: platform(), cli, browsers: browsers.length }
+}
+
+const report = await diagnose()
+const json = process.argv.includes("--json")
+if (json) {
+  console.log(JSON.stringify({ ...report, remedy: REMEDIES[report.state] }, null, 2))
+} else {
+  console.log(`state: ${report.state}`)
+  if (report.cli) console.log(`cli:   ${report.cli}`)
+  if (report.browsers) console.log(`browsers connected: ${report.browsers}`)
+  if (report.detail) console.log(`detail: ${report.detail}`)
+  console.log(`\n${REMEDIES[report.state]}`)
+}
+process.exit(report.state === "ready" ? 0 : 1)

package/packages/shared-skills/skills/browser/scripts/browser-env.mjs

@@ -0,0 +1,41 @@
+import { execFile } from "node:child_process"
+import { existsSync } from "node:fs"
+import { homedir, platform } from "node:os"
+import { join } from "node:path"
+import { promisify } from "node:util"
+
+const run = promisify(execFile)
+
+export const STORE_LISTINGS = {
+  chrome: "https://chromewebstore.google.com/detail/hhcmgoofomhgciiibhipgmgkgnoenaoi",
+  edge: "https://microsoftedge.microsoft.com/addons/detail/browserskill/emacgiaaaiojkkpkddmmdfhmokgmnikg",
+}
+
+export const SUPPORTED_PLATFORMS = new Set(["darwin", "linux", "win32"])
+
+export function localBinCandidates() {
+  const bin = join(homedir(), ".local", "bin")
+  return platform() === "win32" ? [join(bin, "bsk.exe"), join(bin, "bsk")] : [join(bin, "bsk")]
+}
+
+export async function resolveCli() {
+  for (const candidate of localBinCandidates()) {
+    if (existsSync(candidate)) return candidate
+  }
+  try {
+    await run("bsk", ["--version"], { timeout: 15000, windowsHide: true })
+    return "bsk"
+  } catch {
+    return undefined
+  }
+}
+
+export async function readStatus(cli) {
+  const { stdout } = await run(cli, ["status", "--json"], { timeout: 30000, windowsHide: true })
+  return JSON.parse(stdout)
+}
+
+export function connectedBrowsers(status) {
+  const browsers = status?.browsers
+  return Array.isArray(browsers) ? browsers : []
+}

package/packages/shared-skills/skills/browser/scripts/browser-install.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { spawn } from "node:child_process"
+import { platform } from "node:os"
+import { resolveCli, STORE_LISTINGS, SUPPORTED_PLATFORMS } from "./browser-env.mjs"
+
+const UNIX_INSTALL = "curl -fsSL https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.sh | sh"
+const WINDOWS_INSTALL = "irm https://raw.githubusercontent.com/Tencent/BrowserSkill/main/install.ps1 | iex"
+
+function installCommand() {
+  return platform() === "win32"
+    ? { file: "powershell", args: ["-NoProfile", "-Command", WINDOWS_INSTALL], display: WINDOWS_INSTALL }
+    : { file: "sh", args: ["-c", UNIX_INSTALL], display: UNIX_INSTALL }
+}
+
+function spawnInstaller({ file, args }) {
+  return new Promise((resolve) => {
+    const child = spawn(file, args, { stdio: "inherit", windowsHide: true })
+    child.on("error", () => resolve(1))
+    child.on("close", (code) => resolve(code ?? 1))
+  })
+}
+
+if (!SUPPORTED_PLATFORMS.has(platform())) {
+  console.error(`unsupported platform: ${platform()}. macOS, Linux and Windows x64 only.`)
+  process.exit(1)
+}
+
+if (await resolveCli()) {
+  console.log("bsk is already installed; run browser-doctor.mjs to check the extension.")
+  process.exit(0)
+}
+
+const command = installCommand()
+console.log(`installing the bsk CLI with the upstream installer:\n  ${command.display}\n`)
+const code = await spawnInstaller(command)
+if (code !== 0) {
+  console.error(`\ninstaller exited ${code}. Report this instead of retrying blindly.`)
+  process.exit(code)
+}
+
+console.log([
+  "",
+  "CLI installed. Two things remain, and only the user can do the first:",
+  "",
+  "1. Install the browser extension from the store, then enable it:",
+  `     Chrome: ${STORE_LISTINGS.chrome}`,
+  `     Edge:   ${STORE_LISTINGS.edge}`,
+  "2. Re-run: node \"<skill-root>/scripts/browser-doctor.mjs\"",
+  "",
+  "If PATH does not pick up the CLI in this shell, use its absolute path under ~/.local/bin.",
+].join("\n"))

package/dist/cli/install-senpi/index.d.ts

@@ -1 +0,0 @@
-export * from "@oh-my-opencode/omo-senpi/install";