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

package/packages/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/omo-codex/plugin/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/packages/omo-codex/plugin/test/sync-skills-test-support.mjs

@@ -6,6 +6,7 @@ export const CONTEXT_PRESSURE_SKILL_BUDGET_BYTES = 25_000;
 
 export const expectedSkills = [
 	"ast-grep",
+	"browser",
 	"coding-agent-sessions",
 	"comment-checker",
 	"data-scientist",

package/packages/omo-codex/scripts/install-dist/install-local.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// omo-codex-install:6df5dbbbb7ca9b9dce86fae98a525a9caa7de96caed85a4b77d4e8b4ab4d1501:fea0803f89d0a4a013652e8905ddb0c30456affbd1a7b833eb9092f49d9566dc
+// omo-codex-install:88ab1eaf77d9f58468ed3f04e9c7d6c7dbb32d7c87feee69f45401431352184f:6f7e0588dc9a653cf42c9b4466272eea05e8c081bc8dc62082c03c1e5562cc31
 var __esm = (fn, res, err) => () => {
   if (fn)
     try {
@@ -316,7 +316,7 @@ function shouldRetainLine(line, cutoffMs) {
 function parseDiagnosticLine(line) {
   try {
     const parsed = JSON.parse(line);
-    if (!isRecord9(parsed)) {
+    if (!isRecord10(parsed)) {
       return null;
     }
     return parsed;
@@ -327,7 +327,7 @@ function parseDiagnosticLine(line) {
     throw error;
   }
 }
-function isRecord9(value) {
+function isRecord10(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function trimToMaxBytes(lines) {
@@ -7817,7 +7817,7 @@ function coerceBool(value) {
 function coerceString(value) {
   return typeof value == "string" ? value : undefined;
 }
-function isRecord10(value) {
+function isRecord11(value) {
   return typeof value == "object" && value !== null && !Array.isArray(value);
 }
 function toRfc3339(timestamp) {
@@ -7839,7 +7839,7 @@ function relocateInto(properties, key, value) {
     properties[key] = value;
 }
 function buildV1Event(message) {
-  const sourceProperties = isRecord10(message.properties) ? message.properties : {};
+  const sourceProperties = isRecord11(message.properties) ? message.properties : {};
   const properties = {
     ...sourceProperties
   };
@@ -9984,7 +9984,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@oh-my-opencode/omo-codex",
-    version: "5.0.0-beta.81",
+    version: "5.0.0-beta.83",
     type: "module",
     private: true,
     description: "Codex harness adapter for oh-my-openagent. Vendored Codex plugin namespace (omo) + TypeScript installer + telemetry.",
@@ -16515,8 +16515,10 @@ var OmoGitMasterSettingsSchema = OmoGitMasterSettingsLayerSchema.extend({
 
 // packages/omo-config-core/src/schema/harness.ts
 var HARNESS_IDS = ["codex", "opencode", "omo"];
-var OMO_CONFIG_HARNESS_IDS = ["opencode", "senpi", "codex"];
+var OMO_CONFIG_HARNESS_IDS = ["opencode", "native", "codex"];
 var OmoHarnessIdSchema = _enum(OMO_CONFIG_HARNESS_IDS);
+var OMO_CONFIG_LEGACY_HARNESS_ALIASES = { senpi: "native" };
+var OMO_CONFIG_LEGACY_HARNESS_IDS = Object.keys(OMO_CONFIG_LEGACY_HARNESS_ALIASES);
 
 // packages/omo-config-core/src/schema/memory.ts
 var OmoMemoryReflectionTriggerSchema = object({
@@ -16758,6 +16760,31 @@ var OmoTaskTeamSettingsSchema = object({
 var OmoTaskWarningsSchema = object({
   unavailable_categories: boolean2().default(true)
 }).strict();
+var IsolationBackendKindSchema = _enum([
+  "auto",
+  "apfs",
+  "btrfs",
+  "zfs",
+  "reflink",
+  "overlayfs",
+  "block-clone",
+  "rcopy"
+]);
+var OmoTaskIsolationSchema = object({
+  enabled: boolean2().default(false),
+  backend: IsolationBackendKindSchema.default("auto"),
+  apply: boolean2().default(true),
+  merge: _enum(["patch", "branch"]).default("patch"),
+  commits: _enum(["generic", "ai"]).default("generic")
+}).strict();
+var isolationDefaults = OmoTaskIsolationSchema.parse({});
+var OmoTaskIsolationLayerSchema = object({
+  enabled: boolean2().optional(),
+  backend: IsolationBackendKindSchema.optional(),
+  apply: boolean2().optional(),
+  merge: _enum(["patch", "branch"]).optional(),
+  commits: _enum(["generic", "ai"]).optional()
+}).strict();
 var OmoTaskDagSettingsSchema = object({
   max_nodes_per_run: number2().int().positive().default(64),
   max_runs_per_session: number2().int().positive().default(16),
@@ -16769,6 +16796,7 @@ var OmoTaskDagSettingsSchema = object({
   max_prompt_bytes: number2().int().positive().default(262144)
 }).strict();
 var OmoTaskSettingsSchema = object({
+  isolation: OmoTaskIsolationSchema.default(isolationDefaults),
   default_execution_mode: _enum(["auto", "in-process", "process"]).default("auto"),
   process_runner: _enum(["host", "child-process"]).default("host"),
   host_engine_policy: _enum(["upgrade", "fallback"]).default("upgrade"),
@@ -16817,6 +16845,7 @@ var OmoTaskWarningsLayerSchema = object({
   unavailable_categories: boolean2().optional()
 }).strict();
 var OmoTaskSettingsLayerSchema = object({
+  isolation: OmoTaskIsolationLayerSchema.optional(),
   default_execution_mode: _enum(["auto", "in-process", "process"]).optional(),
   process_runner: _enum(["host", "child-process"]).optional(),
   host_engine_policy: _enum(["upgrade", "fallback"]).optional(),
@@ -16948,6 +16977,7 @@ var OmoConfigProfileSchema = object({
   telemetry: OmoTelemetrySettingsLayerSchema.optional(),
   disabled_skills: OmoDisabledSkillsSchema.optional(),
   "[opencode]": OmoOpenCodeHarnessConfigSchema.optional(),
+  "[native]": OmoTypedHarnessConfigSchema.optional(),
   "[senpi]": OmoTypedHarnessConfigSchema.optional(),
   "[codex]": OmoTypedHarnessConfigSchema.optional()
 }).strict();
@@ -16966,6 +16996,7 @@ var OmoConfigSchema = object({
   telemetry: OmoTelemetrySettingsSchema.optional(),
   disabled_skills: OmoDisabledSkillsSchema.optional(),
   "[opencode]": OmoOpenCodeHarnessConfigSchema.optional(),
+  "[native]": OmoTypedHarnessConfigSchema.optional(),
   "[senpi]": OmoTypedHarnessConfigSchema.optional(),
   "[codex]": OmoTypedHarnessConfigSchema.optional(),
   profiles: record(string2(), OmoConfigProfileSchema).default({}),
@@ -16987,6 +17018,7 @@ var OmoConfigLayerSchema = object({
   telemetry: OmoTelemetrySettingsLayerSchema.optional(),
   disabled_skills: OmoDisabledSkillsSchema.optional(),
   "[opencode]": OmoOpenCodeHarnessConfigSchema.optional(),
+  "[native]": OmoTypedHarnessConfigSchema.optional(),
   "[senpi]": OmoTypedHarnessConfigSchema.optional(),
   "[codex]": OmoTypedHarnessConfigSchema.optional(),
   profiles: record(string2(), OmoConfigProfileSchema).optional(),
@@ -17050,6 +17082,54 @@ function canonicalizeLegacyCategoryNames(document) {
   return { document: canonicalized, renames };
 }
 
+// packages/omo-config-core/src/schema/legacy-harness-names.ts
+function canonicalHarnessName(name) {
+  return Object.hasOwn(OMO_CONFIG_LEGACY_HARNESS_ALIASES, name) ? OMO_CONFIG_LEGACY_HARNESS_ALIASES[name] : name;
+}
+function harnessBlockKey(harness) {
+  return `[${harness}]`;
+}
+function legacyHarnessOfBlockKey(key) {
+  if (!key.startsWith("[") || !key.endsWith("]"))
+    return;
+  const harness = key.slice(1, -1);
+  return Object.hasOwn(OMO_CONFIG_LEGACY_HARNESS_ALIASES, harness) ? harness : undefined;
+}
+function isRecord7(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonicalizeBlocksIn(container, path, renames) {
+  const result = {};
+  for (const [key, value] of Object.entries(container)) {
+    const legacyHarness = legacyHarnessOfBlockKey(key);
+    if (legacyHarness === undefined) {
+      result[key] = value;
+      continue;
+    }
+    const canonical = harnessBlockKey(canonicalHarnessName(legacyHarness));
+    const dropped = Object.hasOwn(container, canonical);
+    renames.push({ canonical, dropped, legacy: key, path: [...path, key].join(".") });
+    if (!dropped)
+      result[canonical] = value;
+  }
+  return result;
+}
+function canonicalizeLegacyHarnessBlocks(document) {
+  if (!isRecord7(document))
+    return { document: {}, renames: [] };
+  const renames = [];
+  const canonicalized = canonicalizeBlocksIn(document, [], renames);
+  const profiles = canonicalized["profiles"];
+  if (isRecord7(profiles)) {
+    const canonicalProfiles = {};
+    for (const [name, profile] of Object.entries(profiles)) {
+      canonicalProfiles[name] = isRecord7(profile) ? canonicalizeBlocksIn(profile, ["profiles", name], renames) : profile;
+    }
+    canonicalized["profiles"] = canonicalProfiles;
+  }
+  return { document: canonicalized, renames };
+}
+
 // node_modules/.bun/jsonc-parser@3.3.1/node_modules/jsonc-parser/lib/esm/impl/scanner.js
 function createScanner(text, ignoreTrivia = false) {
   const len = text.length;
@@ -18025,7 +18105,7 @@ function resolveOmoConfigPaths(options) {
 }
 
 // packages/omo-config-core/src/loader/resolution.ts
-var HARNESS_KEYS = [...new Set([...HARNESS_IDS, ...OMO_CONFIG_HARNESS_IDS])].map((harness) => `[${harness}]`);
+var HARNESS_KEYS = [...new Set([...HARNESS_IDS, ...OMO_CONFIG_HARNESS_IDS, ...OMO_CONFIG_LEGACY_HARNESS_IDS])].map((harness) => harnessBlockKey(harness));
 function profileName(value) {
   return value === "" ? undefined : value;
 }
@@ -18054,7 +18134,13 @@ function withoutControlKeys(config) {
 function harnessLayer(config, harness) {
   if (harness === undefined)
     return {};
-  return toRecord(config[`[${harness}]`]) ?? {};
+  const canonical = canonicalHarnessName(harness);
+  const legacyKeys = Object.entries(OMO_CONFIG_LEGACY_HARNESS_ALIASES).filter(([, target]) => target === canonical).map(([legacy]) => harnessBlockKey(legacy));
+  let layer = {};
+  for (const key of [...legacyKeys, harnessBlockKey(canonical)]) {
+    layer = mergeOmoConfigRecords(layer, toRecord(config[key]) ?? {});
+  }
+  return layer;
 }
 function resolveOmoConfigView(options) {
   const profiles = toRecord(options.config["profiles"]);
@@ -18105,6 +18191,7 @@ var DEFAULT_RAW_CONFIG = {
 function stripResolutionControlKeys(config) {
   const {
     "[codex]": _codex,
+    "[native]": _native,
     "[opencode]": _opencode,
     "[senpi]": _senpi,
     profiles: _profiles,
@@ -18130,21 +18217,21 @@ function hasUnsafeUnrecognizedKey(issues) {
 function hasTamperedPrototype(value) {
   if (Array.isArray(value))
     return value.some((entry) => hasTamperedPrototype(entry));
-  if (!isRecord7(value))
+  if (!isRecord8(value))
     return false;
   const prototype = Object.getPrototypeOf(value);
   if (prototype !== Object.prototype && prototype !== null)
     return true;
   return Object.values(value).some((entry) => hasTamperedPrototype(entry));
 }
-function isRecord7(value) {
+function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function containerAt(record, path) {
   let container = record;
   for (const segment of path) {
     const next = container[segment];
-    if (!isRecord7(next))
+    if (!isRecord8(next))
       return null;
     container = next;
   }
@@ -18255,6 +18342,15 @@ function legacyCategoryDiagnostic(path, renames) {
     issuePaths: renames.map((rename) => rename.path)
   };
 }
+function legacyHarnessDiagnostic(path, renames) {
+  const detail = renames.map((rename) => rename.dropped ? `${rename.path} ignored because ${rename.canonical} is also configured` : `${rename.path} renamed to ${rename.canonical}`).join(", ");
+  return {
+    kind: "deprecated-keys",
+    message: `Deprecated harness block in ${path}: ${detail}. Rename it; the alias is removed in a future release.`,
+    path,
+    issuePaths: renames.map((rename) => rename.path)
+  };
+}
 function loadOmoConfig(options = {}) {
   const fileSystem = options.fileSystem ?? DEFAULT_READ_FILE_SYSTEM;
   const cwd = options.cwd ?? process.cwd();
@@ -18277,8 +18373,12 @@ function loadOmoConfig(options = {}) {
       if (canonicalized.renames.length > 0) {
         diagnostics.push(legacyCategoryDiagnostic(candidate.path, canonicalized.renames));
       }
-      layers.push({ config: canonicalized.document, source: loaded.source });
-      merged = mergeOmoConfigRecords(merged, canonicalized.document);
+      const harnessCanonicalized = canonicalizeLegacyHarnessBlocks(canonicalized.document);
+      if (harnessCanonicalized.renames.length > 0) {
+        diagnostics.push(legacyHarnessDiagnostic(candidate.path, harnessCanonicalized.renames));
+      }
+      layers.push({ config: harnessCanonicalized.document, source: loaded.source });
+      merged = mergeOmoConfigRecords(merged, harnessCanonicalized.document);
     }
   }
   const requestedProfile = resolveOmoProfileName({
@@ -20878,10 +20978,10 @@ function readCatalogMultiAgentVersion(model, cachePath) {
   } catch {
     return null;
   }
-  if (!isRecord8(cache) || !Array.isArray(cache.models))
+  if (!isRecord9(cache) || !Array.isArray(cache.models))
     return null;
   for (const entry of cache.models) {
-    if (!isRecord8(entry))
+    if (!isRecord9(entry))
       continue;
     if (entry.slug !== model && entry.id !== model)
       continue;
@@ -20906,7 +21006,7 @@ function readRootModelCatalogPath(config) {
   const single = config.match(/^\s*model_catalog_json\s*=\s*'([^']+)'/m);
   return single?.[1] ?? null;
 }
-function isRecord8(value) {
+function isRecord9(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function removeFeatureFlagSetting(config, featureName) {

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

@@ -0,0 +1,25 @@
+# ATTRIBUTION / NOTICE
+
+This skill (`browser`, part of `@oh-my-opencode/shared-skills`) is project-original documentation.
+It drives a third-party tool that it does **not** redistribute.
+
+## BrowserSkill — driven, not vendored
+
+The attached engine this skill documents is **BrowserSkill** by Tencent.
+
+- Upstream: https://github.com/Tencent/BrowserSkill
+- License: MIT
+- What ships here: documentation and two local helper scripts, authored by this project.
+- What does NOT ship here: the `bsk` CLI, the daemon, the browser extension, or any upstream
+  source. The user installs those from upstream's own installer and from the Chrome Web Store /
+  Edge Add-ons listings. This package never bundles a browser binary or an extension payload.
+
+MIT permits redistribution; we simply have no reason to, because upstream publishes signed
+per-platform releases and store builds that stay current on their own.
+
+## Owned-engine references
+
+`references/owned-engine/` documents a *contract* for a code-driven browser — the escalation
+ladder, viewport pinning, reading the network instead of the DOM, overlay and cross-origin
+handling — not any particular package. The techniques are generic CDP practice. No third-party
+source is reproduced.

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