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

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";

package/dist/cli/senpi-edition-hint.d.ts

@@ -1,10 +0,0 @@
-import type { InstallConfig } from "./types";
-export declare const SENPI_EDITION_INSTALL_COMMAND = "bun add -g omo-ai@beta";
-export declare const SENPI_EDITION_GUIDE_URL = "https://github.com/code-yeongyu/oh-my-openagent/blob/dev/docs/guide/installation.md#senpi-edition-beta-omo-via-omo-ai";
-export declare const SENPI_EDITION_HINT_TITLE = "Standalone Senpi edition (beta)";
-export type SenpiEditionHintPaint = {
-    readonly command: (text: string) => string;
-    readonly link: (text: string) => string;
-};
-export declare function shouldShowSenpiEditionHint(config: Pick<InstallConfig, "hasSenpi">): boolean;
-export declare function senpiEditionHintLines(paint?: SenpiEditionHintPaint): readonly string[];

package/dist/cli/senpi-platform-flag.d.ts

@@ -1,4 +0,0 @@
-import type { InstallPlatform } from "./types";
-export declare const SENPI_PLATFORM_ENV_FLAG = "OMO_ENABLE_SENPI_PLATFORM";
-export declare function isSenpiPlatformEnabled(env?: NodeJS.ProcessEnv): boolean;
-export declare function availableInstallPlatforms(env?: NodeJS.ProcessEnv): InstallPlatform[];