oh-my-opencode 4.12.1 → 4.14.0

package/packages/omo-codex/plugin/skills/teammode/scripts/team-worktree.mjs

@@ -0,0 +1,113 @@
+// team-worktree.mjs - git worktree provisioning + merge integration for teammode.
+//
+// Shells out to `git` through node:child_process so the leader never hand-runs worktree or
+// merge commands and never improvises a branch name. Zero npm dependencies, like the rest of
+// the skill. team-state.mjs stays the pure state model; this file owns the git side only.
+
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+// A member id that also names a directory and a branch segment: no "/", no "..", no leading dot.
+const MEMBER_ID_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+// Compare two on-disk paths regardless of OS. realpathSync canonicalizes separators, Windows
+// 8.3 short names (RUNNER~1) and drive-letter case, and the macOS /var -> /private/var symlink -
+// none of which plain resolve() reconciles. Returns false if either side no longer exists.
+function samePath(a, b) {
+	try {
+		return realpathSync(a) === realpathSync(b);
+	} catch {
+		return false;
+	}
+}
+
+function git(cwd, args) {
+	const result = spawnSync("git", args, { cwd, encoding: "utf8" });
+	if (result.error) throw new Error(`git ${args.join(" ")} could not run: ${result.error.message}`);
+	return result;
+}
+
+function gitOrThrow(cwd, args) {
+	const result = git(cwd, args);
+	if (result.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${(result.stderr || result.stdout || "").trim()}`);
+	return result.stdout ?? "";
+}
+
+export function deriveMemberBranch(team, member) {
+	if (member.worktree?.branch) return member.worktree.branch;
+	return `team/${team.sessionId ?? team.teamId}/${member.id}`;
+}
+
+// Confine a member worktree to <worktree.root>/<member id>; reject any id that would escape it.
+export function memberWorktreePath(team, member) {
+	if (!MEMBER_ID_SEGMENT.test(member.id ?? "")) throw new Error(`unsafe member id for a worktree path: "${member.id}"`);
+	const root = team.worktree?.root;
+	if (!root) throw new Error("team has no worktree root; re-init the team");
+	const path = join(root, member.id);
+	const rel = relative(root, path);
+	if (rel !== member.id || rel.startsWith("..") || isAbsolute(rel)) throw new Error(`refused: worktree path escapes ${root}`);
+	return path;
+}
+
+export function listWorktrees(cwd) {
+	const out = gitOrThrow(cwd, ["worktree", "list", "--porcelain"]);
+	const worktrees = [];
+	let current = null;
+	for (const line of out.split("\n")) {
+		if (line.startsWith("worktree ")) {
+			current = { path: line.slice("worktree ".length) };
+			worktrees.push(current);
+		} else if (line.startsWith("branch ") && current) {
+			current.branch = line.slice("branch ".length);
+		}
+	}
+	return worktrees;
+}
+
+function branchExists(cwd, branch) {
+	return git(cwd, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]).status === 0;
+}
+
+function currentBranch(cwd) {
+	return gitOrThrow(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+}
+
+export function addMemberWorktree(cwd, team, member, { baseBranch } = {}) {
+	const base = baseBranch || team.worktree?.baseBranch || "dev";
+	const branch = deriveMemberBranch(team, member);
+	const path = memberWorktreePath(team, member);
+	// Idempotent: skip if a worktree is already checked out on this member's branch (matched on the
+	// branch ref, which is OS-agnostic) or already lives at this path (matched on realpath, so a
+	// Windows 8.3 git path vs an 8.3-or-long script path still compares equal). Plain string/resolve
+	// comparison missed the 8.3-vs-canonical case and re-`git worktree add`-ed into a fatal error.
+	if (listWorktrees(cwd).some((w) => w.branch === `refs/heads/${branch}` || samePath(resolve(cwd, w.path), resolve(cwd, path)))) {
+		return { path, branch, base, created: false };
+	}
+	const add = branchExists(cwd, branch)
+		? ["worktree", "add", path, branch]
+		: ["worktree", "add", "-b", branch, path, base];
+	gitOrThrow(cwd, add);
+	return { path, branch, base, created: true };
+}
+
+export function removeMemberWorktree(cwd, team, member, { force = false } = {}) {
+	const path = memberWorktreePath(team, member);
+	gitOrThrow(cwd, ["worktree", "remove", ...(force ? ["--force"] : []), path]);
+	return { path };
+}
+
+// Land a member branch with a MERGE COMMIT (--no-ff). Never squash, never rebase (repo policy).
+// On conflict the working tree is left mid-merge so the leader can resolve and re-run.
+export function integrateMemberBranch(cwd, branch) {
+	const result = git(cwd, ["merge", "--no-ff", "--no-edit", branch]);
+	if (result.status === 0) return { branch, merged: true, into: currentBranch(cwd) };
+	const conflicts = gitOrThrow(cwd, ["diff", "--name-only", "--diff-filter=U"]).trim();
+	return {
+		branch,
+		merged: false,
+		into: currentBranch(cwd),
+		conflicts: conflicts ? conflicts.split("\n") : [],
+		message: (result.stderr || result.stdout || "").trim(),
+	};
+}

package/packages/omo-codex/plugin/skills/teammode/scripts/team.mjs

@@ -7,7 +7,7 @@
 // macOS, Linux, and Windows.
 //
 //   node "<skill-root>/scripts/team.mjs" init        --name "<team>" --session-name "<sess>" [--session <id>] [--worktree] [--base-branch dev]
-//   node "<skill-root>/scripts/team.mjs" add-member  --team <id> --id A --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <b>]
+//   node "<skill-root>/scripts/team.mjs" add-member  --team <id> --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>" [--branch <b>]
 //   node "<skill-root>/scripts/team.mjs" bind-thread  --team <id> --id A --thread <thread-id> [--cwd <path>]
 //   node "<skill-root>/scripts/team.mjs" member-prompt --team <id> --id A
 //   node "<skill-root>/scripts/team.mjs" set-status   --team <id> --id A --status reported|blocked|active|archived [--note "<...>"]
@@ -20,23 +20,25 @@ import { randomUUID } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { buildGuide, buildMemberPrompt } from "./team-guide.mjs";
+import { buildGuide, buildMemberPrompt, codexThreadLink } from "./team-guide.mjs";
 import {
 	addMember,
 	archive,
 	assertSafeTeamDir,
 	bindThread,
 	buildTeam,
+	clearMemberWorktree,
 	ensureTeamDir,
 	isUnderstaffed,
 	MIN_MEMBERS,
 	readTeam,
-	resolveTeamDir,
 	setMemberStatus,
+	setMemberWorktree,
 	teamExists,
 	writeGuideAtomic,
 	writeTeamAtomic,
 } from "./team-state.mjs";
+import { addMemberWorktree, integrateMemberBranch, removeMemberWorktree } from "./team-worktree.mjs";
 
 function parseFlags(args) {
 	const flags = { _: [] };
@@ -69,6 +71,12 @@ async function loadTeam(cwd, sessionId) {
 	return { dir, team: await readTeam(dir) };
 }
 
+function memberOrThrow(team, id) {
+	const member = team.members.find((m) => m.id === id);
+	if (!member) throw new Error(`no member with id "${id}"`);
+	return member;
+}
+
 async function persist(team, dir) {
 	await writeTeamAtomic(team, dir);
 	await writeGuideAtomic(team, buildGuide(team), dir);
@@ -95,7 +103,7 @@ const handlers = {
 		await persist(team, dir);
 		process.stdout.write(`created: ${dir}\n`);
 		process.stdout.write(`team.json + guide.md written; artifacts/ ready. session id: ${sessionId}\n`);
-		process.stdout.write(`next: add-member --team ${sessionId} --id A --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>"\n`);
+		process.stdout.write(`next: add-member --team ${sessionId} --id A --name "<short role>" --focus "<part/ownership/perspective>" --lens area|ownership|perspective --deliverable "<...>"\n`);
 	},
 
 	async "add-member"(cwd, flags) {
@@ -104,13 +112,15 @@ const handlers = {
 		const memberId = requireFlag(flags, "id").trim();
 		addMember(team, {
 			id: memberId,
+			name: typeof flags.name === "string" ? flags.name : null,
 			focus: requireFlag(flags, "focus"),
 			lens: requireFlag(flags, "lens"),
 			deliverable: typeof flags.deliverable === "string" ? flags.deliverable : "",
 			branch: typeof flags.branch === "string" ? flags.branch : null,
 		});
 		await persist(team, dir);
-		process.stdout.write(`added member ${memberId} to team ${sessionId}.\n\nSend this as the new thread's first message (title it "${team.threadTitleConvention}"):\n---\n${buildMemberPrompt(team, memberId)}\n---\n`);
+		const member = team.members.find((m) => m.id === memberId);
+		process.stdout.write(`added member ${memberId} to team ${sessionId}.\n\nSend this as the new thread's first message (title the thread "${member.threadTitle}"):\n---\n${buildMemberPrompt(team, memberId)}\n---\n`);
 	},
 
 	async "bind-thread"(cwd, flags) {
@@ -144,6 +154,58 @@ const handlers = {
 		process.stdout.write(`member ${flags.id} -> ${flags.status}\n`);
 	},
 
+	async "worktree-add"(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { dir, team } = await loadTeam(cwd, sessionId);
+		const member = memberOrThrow(team, requireFlag(flags, "id"));
+		const result = addMemberWorktree(cwd, team, member, {
+			baseBranch: typeof flags["base-branch"] === "string" ? flags["base-branch"] : null,
+		});
+		setMemberWorktree(team, { id: member.id, path: result.path, branch: result.branch });
+		await persist(team, dir);
+		const note = result.created ? "" : " (already exists)";
+		const thread = member.threadId
+			? `\nMember thread: ${codexThreadLink(member.threadId)}\nTell that member to: cd "${result.path}"`
+			: "\nMember thread is not bound yet; wait for the real Codex thread id, then bind-thread before sending bootstrap. After binding, send the member this worktree path.";
+		process.stdout.write(
+			`worktree for member ${member.id}${note}: ${result.path} on branch ${result.branch} (off ${result.base}).${thread}\n`,
+		);
+	},
+
+	async "worktree-remove"(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { dir, team } = await loadTeam(cwd, sessionId);
+		const member = memberOrThrow(team, requireFlag(flags, "id"));
+		removeMemberWorktree(cwd, team, member, { force: flags.force === true });
+		clearMemberWorktree(team, { id: member.id });
+		await persist(team, dir);
+		process.stdout.write(`removed worktree for member ${member.id}\n`);
+	},
+
+	async integrate(cwd, flags) {
+		const sessionId = requireFlag(flags, "team");
+		const { team } = await loadTeam(cwd, sessionId);
+		const targets = typeof flags.id === "string" ? [memberOrThrow(team, flags.id)] : team.members.filter((m) => m.worktree?.branch);
+		if (targets.length === 0) throw new Error("no member has a worktree branch to integrate; run worktree-add first");
+		for (const member of targets) {
+			const result = integrateMemberBranch(cwd, member.worktree.branch);
+			if (!result.merged) {
+				if (result.conflicts.length > 0) {
+					process.stdout.write(`member ${member.id} (${member.worktree.branch}): CONFLICT into ${result.into}\n`);
+					throw new Error(
+						`merge conflict integrating member ${member.id} (branch ${member.worktree.branch}). Resolve the conflict, commit the merge, then re-run integrate. Conflicting files: ${result.conflicts.join(", ")}`,
+					);
+				}
+				process.stdout.write(`member ${member.id} (${member.worktree.branch}): could not start merge into ${result.into}\n`);
+				throw new Error(
+					`could not integrate member ${member.id} (branch ${member.worktree.branch}): ${result.message || "git merge failed; see git status"}`,
+				);
+			}
+			process.stdout.write(`member ${member.id} (${member.worktree.branch}): merged into ${result.into}\n`);
+		}
+		process.stdout.write(`integrated ${targets.length} member branch(es) with merge commits\n`);
+	},
+
 	async archive(cwd, flags) {
 		const sessionId = requireFlag(flags, "team");
 		const { dir, team } = await loadTeam(cwd, sessionId);
@@ -173,7 +235,8 @@ const handlers = {
 		const { team } = await loadTeam(cwd, sessionId);
 		process.stdout.write(`Team ${team.teamName} [${team.status}] - leader: main session - ${team.members.length} member(s)\n`);
 		for (const m of team.members) {
-			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${m.threadId ? ` thread=${m.threadId}` : ""}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
+			const thread = m.threadId ? ` thread=${m.threadId} link=${codexThreadLink(m.threadId)}` : "";
+			process.stdout.write(`  ${m.id} (${m.lens}) ${m.focus} -> ${m.deliverable || "(no deliverable)"} [${m.status}]${thread}${m.cwd ? ` cwd=${m.cwd}` : ""}\n`);
 		}
 		if (isUnderstaffed(team)) {
 			process.stdout.write(

package/packages/omo-codex/plugin/skills/ultimate-browsing/ATTRIBUTION.md

@@ -0,0 +1,105 @@
+# ATTRIBUTION / NOTICE
+
+This skill (`ultimate-browsing`, part of `@oh-my-opencode/shared-skills`) ships
+project-original content plus two third-party tools that it installs at runtime
+(it does NOT vendor their source). Each runtime tool's license and required
+notices are reproduced below.
+
+---
+
+## 1. Project-original content (no third-party source vendored)
+
+The following are authored by the oh-my-openagent project and carry no third-party
+license obligation:
+
+- `engine/**` — the insane-search Tier-1 fetch engine (curl_cffi grid, WAF
+  detection, Playwright fallback templates, `bias_check.py` no-site-name gate).
+- `references/insane-search/**` and `references/agent-reach/**` — the Tier-1 and
+  Tier-1.5 reference docs.
+- `scripts/extract_cookies.py`, `scripts/cookie_paths.py`, `scripts/cookie_crypto.py`
+  and their tests — the cross-platform cookie module.
+- `SKILL.md`, `references/chrome-stealth.md`.
+
+These reference platform-native CLIs and public APIs by name (e.g. `xhs`, `yt-dlp`,
+`agent-reach`, `mcporter`, Jina Reader, V2EX public API). Those are external tools the
+user installs separately; this skill includes none of their source.
+
+---
+
+## 2. CloakBrowser (CloakHQ) — Tier-2 stealth Chromium (runtime dependency)
+
+The Tier-2 stealth browser is **CloakBrowser**, installed at runtime via `pip`
+(`pip install cloakbrowser`). No CloakBrowser source is vendored in this repository.
+
+- Source: https://github.com/CloakHQ/CloakBrowser
+- Pinned runtime version: **0.4.0** (documented in `references/chrome-stealth.md`;
+  this is a documented version string, not an automated drift check).
+- Wrapper source license: MIT License.
+- Binary license: the compiled CloakBrowser Chromium binary downloaded by
+  `cloakbrowser.ensure_binary()` is governed by the separate CloakBrowser
+  Binary License:
+  https://github.com/CloakHQ/CloakBrowser/blob/main/BINARY-LICENSE.md
+- Redistribution note: this npm package does not redistribute the CloakBrowser
+  binary, does not repackage it, and does not include it in `skills/` or
+  `dist/skills`. Users who run the Tier-2 setup download the binary directly
+  from CloakHQ's official distribution channels and must comply with that
+  binary license.
+
+MIT wrapper source license:
+
+```
+MIT License
+
+Copyright (c) 2026 CloakHQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+---
+
+## 3. agent-browser (vercel-labs) — Tier-2 CDP automation CLI (runtime dependency)
+
+The Tier-2 automation CLI is **agent-browser**, installed at runtime via `npm`
+(`npm i -g agent-browser`). No agent-browser source is vendored in this repository.
+
+- Source: https://github.com/vercel-labs/agent-browser
+- Pinned runtime version: **0.29.1** (documented in `references/chrome-stealth.md`;
+  documented version string, no automated drift check).
+- Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+  these files except in compliance with the License. You may obtain a copy of the
+  License at:
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software distributed under
+  the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied. See the License for the specific language governing
+  permissions and limitations under the License.
+
+- **Changes (Apache-2.0 §4(b)):** none. agent-browser is installed unmodified at
+  runtime; no agent-browser source file is copied, modified, or redistributed by this
+  skill. This skill only documents how to invoke the upstream CLI.
+
+- **NOTICE:** the upstream agent-browser distribution may include a `NOTICE` file. As
+  this skill redistributes no agent-browser source, no upstream NOTICE content is
+  bundled here; consult the upstream repository for its `NOTICE` file when present.
+
+- **Trademark notice:** "agent-browser" and "Vercel" are referenced by name for
+  identification only. No trademark license is granted under the Apache License 2.0
+  (Section 6).

package/packages/omo-codex/plugin/skills/ultimate-browsing/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: ultimate-browsing
+description: "Escalation skill for blocked or hard-to-reach web access — load it when a normal browse/fetch is blocked (WAF, 403, Cloudflare, JS-only render, login-gated, or a platform a generic fetcher cannot read). Tiered router: TIER 1 insane-search (headless extraction + WAF bypass via curl_cffi TLS impersonation, yt-dlp, Jina Reader, public APIs, Playwright real-Chrome fallback); TIER 1.5 agent-reach (platform-native readers for Chinese and social platforms: Xiaohongshu, Douyin, Weibo, Bilibili, V2EX, WeChat, plus Twitter/Reddit/LinkedIn/GitHub); TIER 2 Chrome stealth (CloakBrowser stealth Chromium + agent-browser CDP for clicks, forms, screenshots, video, cookie login). Triggers: blocked site, bypass bot detection, cloudflare/WAF bypass, scrape, stealth browser, import cookies, fill form, screenshot, play youtube, xiaohongshu, douyin, weibo, bilibili, v2ex, wechat article, podcast transcript. NOT for simple searches (use web-search) or plain fetches (use webfetch)."
+---
+
+# Ultimate Browsing
+
+Escalation web access for tasks a normal browse or fetch cannot complete. Reach for this skill the moment a page is blocked (WAF / 403 / Cloudflare), needs JS rendering, hides behind a login, or lives on a platform a generic fetcher cannot read. Escalate only when the cheaper tier cannot do the job:
+
+**Tier 1 — insane-search** (headless extraction + WAF bypass) -> **Tier 1.5 — agent-reach** (platform-native APIs, esp. Chinese platforms) -> **Tier 2 — Chrome stealth** (real interaction via CloakBrowser + agent-browser).
+
+## PHASE 0 — ROUTE FIRST (MANDATORY)
+
+```
+User request
+  |
+  +- extract text/data from a URL --------------------- TIER 1  insane-search
+  +- URL blocked / 403 / Cloudflare / WAF ------------- TIER 1  insane-search
+  +- YouTube/Vimeo/TikTok subtitles or metadata ------- TIER 1  insane-search (yt-dlp)
+  +- read an article / blog / Reddit / HN / arXiv ----- TIER 1  insane-search
+  |
+  +- Chinese platform (xhs/douyin/weibo/bilibili/v2ex/wechat)  TIER 1.5 agent-reach
+  +- podcast transcript / stock forum ----------------- TIER 1.5 agent-reach
+  +- Twitter feed / LinkedIn profile / GitHub via CLI - TIER 1.5 agent-reach
+  |
+  +- Tier 1/1.5 returned empty or partial ------------- TIER 2  Chrome stealth
+  +- click / fill form / scroll / interact ------------ TIER 2  Chrome stealth
+  +- screenshot / render / play video ----------------- TIER 2  Chrome stealth
+  +- login session across pages / inject cookies ------ TIER 2  Chrome stealth
+  +- test web app / QA / dogfood ---------------------- TIER 2  Chrome stealth
+  |
+  +- simple search query ------------------------------ NOT this skill (use web-search)
+```
+
+Read the matching reference before acting: [`references/insane-search/README.md`](references/insane-search/README.md), [`references/agent-reach/README.md`](references/agent-reach/README.md), or [`references/chrome-stealth.md`](references/chrome-stealth.md).
+
+## Tier 1 — insane-search (headless extraction)
+
+**When**: content extraction, blocked-URL bypass, media metadata — no browser UI needed.
+**Why first**: ~10x faster than a browser, no process spin-up; handles most "fetch this blocked page" requests via curl_cffi TLS impersonation, yt-dlp (1858 sites), Jina Reader, official public APIs, mobile URL transforms, and a Playwright real-Chrome fallback. The engine lives **inside this skill** at `engine/` and is invoked as a module.
+
+```bash
+# Core command — auto-detects WAF, runs the full fetch grid (run from the skill dir):
+python3 -m engine "https://example.com/blocked-page"
+#   add --selector "<CSS>" for positive-proof validation, --device auto|desktop|mobile,
+#   --trace to inspect every attempt, --json for machine-readable output.
+
+# YouTube subtitles / metadata (no browser):
+yt-dlp --write-sub --write-auto-sub --sub-lang "en,ko" --skip-download -o "/tmp/%(id)s" "<URL>"
+
+# Reddit / HN / Bluesky / arXiv etc. use official public endpoints — see the Phase 0 index in
+# references/insane-search/README.md (Twitter syndication, Reddit .json, HN Firebase, ...).
+```
+
+The full engine harness (rules R1-R7, the Phase 0 official-API index, the no-site-name rule, and the `references/insane-search/*.md` deep-dives for TLS, Playwright routing, Naver, media, etc.) is in [`references/insane-search/README.md`](references/insane-search/README.md). Read it before tuning the engine or adding a WAF profile.
+
+### Escalate to Tier 1.5 or Tier 2 when
+- The target is a Chinese / social platform with a native reader -> Tier 1.5.
+- insane-search returns empty/partial, or the page needs JS interaction, a screenshot, a persistent login, or media playback -> Tier 2.
+
+## Tier 1.5 — agent-reach (platform-native readers)
+
+**When**: the target is a platform with a first-class API/CLI that beats generic fetching — especially Chinese platforms that stealth browsers still cannot reach cleanly. Several channels are zero-config (Douyin, Weibo via Jina, V2EX, Reddit, Jina Reader, RSS, YouTube); others need a one-time auth you supply via environment variables if you have access.
+
+| Category | Platforms | Entry |
+|---|---|---|
+| social | xhs (Xiaohongshu), douyin, weibo, bilibili, V2EX, Reddit, Twitter/X | [references/agent-reach/social.md](references/agent-reach/social.md) |
+| web | Jina Reader, WeChat articles, RSS | [references/agent-reach/web.md](references/agent-reach/web.md) |
+| video | YouTube, Bilibili, podcast transcripts, Douyin video | [references/agent-reach/video.md](references/agent-reach/video.md) |
+| career | LinkedIn | [references/agent-reach/career.md](references/agent-reach/career.md) |
+| dev | GitHub (gh CLI) | [references/agent-reach/dev.md](references/agent-reach/dev.md) |
+| search | Exa AI | [references/agent-reach/search.md](references/agent-reach/search.md) |
+
+```bash
+mcporter call 'douyin.parse_douyin_video_info(url: "<URL>")'   # douyin, zero-config
+curl -s "https://r.jina.ai/https://weibo.com/<uid>/<pid>"      # weibo via Jina
+yt-dlp --dump-json "<bilibili-url>"                            # Bilibili (overseas: add --cookies-from-browser)
+curl -s "https://www.v2ex.com/api/topics/hot.json"            # V2EX public API
+```
+
+Routing table, per-platform auth (set `TWITTER_*` env vars, `gh auth login`, a transcription key — only if you have access), rate-limit notes, and known version quirks are in [references/agent-reach/README.md](references/agent-reach/README.md).
+
+## Tier 2 — Chrome stealth (real interaction)
+
+**When**: real interaction is needed (clicks, forms, screenshots, video, persistent login), or Tier 1/1.5 failed.
+
+CloakBrowser is a stealth Chromium with source-level fingerprint patches that passes Cloudflare Turnstile, FingerprintJS, BrowserScan, and 30+ detectors; agent-browser is the CDP automation CLI that drives it. Both are runtime-installed tools (not vendored here). Full setup, version pins, launch flow, cookie login, and cross-platform notes are in [references/chrome-stealth.md](references/chrome-stealth.md).
+
+```bash
+# 1. Launch CloakBrowser with CDP on :9242 (see chrome-stealth.md for install + venv).
+# 2. CloakBrowser launches tabless — open the first tab via CDP before any agent-browser command:
+curl -s -X PUT "http://127.0.0.1:9242/json/new?https://example.com"
+# 3. Drive it with agent-browser over CDP:
+agent-browser --cdp 9242 snapshot -i        # interactive elements (@eN refs)
+agent-browser --cdp 9242 click @e3
+agent-browser --cdp 9242 screenshot out.png
+agent-browser --cdp 9242 close
+```
+
+### Cookie login (cross-platform)
+
+`scripts/extract_cookies.py` reads cookies from a local Chromium-family or Firefox-family browser and optionally injects them into the running CDP session. It resolves browser profile paths and decrypts cookie values per-OS (macOS Keychain, Linux libsecret, Windows DPAPI):
+
+```bash
+# Extract cookies to a file:
+mkdir -p ~/.local/state/omo-cookies
+python3 scripts/extract_cookies.py --browser chrome --domain youtube.com --output ~/.local/state/omo-cookies/youtube.cookies.json
+# Extract and inject into the running CDP session:
+python3 scripts/extract_cookies.py --browser chrome --domain youtube.com --inject --cdp 9242
+```
+
+Cookie export files are written with owner-only `0600` permissions. Do not place live auth cookies in shared temp directories or commit them to a repo. Cookie injection sends values to CDP over stdin rather than argv. Cookies apply on next navigation — reload after injecting. Google services use fingerprint-bound tokens that may not transfer across browser profiles. Full detail in [references/chrome-stealth.md](references/chrome-stealth.md).
+
+## Reference docs
+
+| File | When to read |
+|------|-------------|
+| [references/insane-search/README.md](references/insane-search/README.md) | Tier-1 engine harness (R1-R7, Phase 0 API index, no-site-name rule) + its `*.md` deep-dives |
+| [references/agent-reach/README.md](references/agent-reach/README.md) | Tier-1.5 routing table, platform auth, per-category `*.md` |
+| [references/chrome-stealth.md](references/chrome-stealth.md) | Tier-2 CloakBrowser + agent-browser install, CDP flow, version pins, cookie login |
+
+## Environment variables
+
+```bash
+CLOAK_CDP_PORT=9242              # CloakBrowser CDP port (default 9242)
+AGENT_BROWSER_USER_AGENT="..."   # override UA to hide HeadlessChrome
+AGENT_BROWSER_HEADED=1           # show the browser window
+# agent-reach auth: set the channel-specific env vars from each tool's docs only if you have access
+# insane-search needs no env vars — it auto-installs deps on first run
+```
+
+## Anti-patterns
+
+- Do NOT launch Chrome stealth for plain text extraction — use Tier 1.
+- Do NOT pass an `--init-script` for the webdriver flag — CloakBrowser already patches it at source; the only required override is `--user-agent`.
+- Do NOT run agent-browser before creating the first tab via `curl -X PUT .../json/new` — CloakBrowser launches tabless.
+- Do NOT use vanilla Chrome when stealth is needed — always CloakBrowser.
+- Do NOT forget to `close` the session when done.
+- Do NOT inject cookies without reloading the page.
+- Do NOT hardcode site domains/selectors into `engine/**` or `waf_profiles.yaml` — runtime hints only (see the no-site-name rule in the insane-search reference).

package/packages/omo-codex/plugin/skills/ultimate-browsing/agents/openai.yaml

@@ -0,0 +1,2 @@
+interface:
+  display_name: "(OmO) ultimate-browsing"

package/packages/omo-codex/plugin/skills/ultimate-browsing/engine/__init__.py

@@ -0,0 +1,24 @@
+"""insane-search engine — generic WAF-profile-based fetch chain.
+
+No site-specific logic lives here. Site specifics belong to runtime hints or
+observations, never to code. See `../SKILL.md` for the No-Site-Name Rule.
+"""
+
+from .validators import Verdict, ValidationResult, validate, CHALLENGE_MARKERS
+from .waf_detector import detect
+from .url_transforms import TRANSFORMS, apply_transform
+from .fetch_chain import fetch
+from .result_schema import Attempt, FetchResult
+
+__all__ = [
+    "Verdict",
+    "ValidationResult",
+    "validate",
+    "CHALLENGE_MARKERS",
+    "detect",
+    "TRANSFORMS",
+    "apply_transform",
+    "fetch",
+    "FetchResult",
+    "Attempt",
+]

package/packages/omo-codex/plugin/skills/ultimate-browsing/engine/__main__.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""CLI entrypoint for the insane-search engine.
+
+Usage:
+    python3 -m engine URL [--selector CSS] [--device auto|desktop|mobile]
+                          [--timeout N] [--max-attempts N] [--json] [--trace]
+
+Examples:
+    python3 -m engine "https://example.com/" --selector "h1"
+    python3 -m engine "https://example.com/" --json
+    python3 -m engine "https://example.com/" --device mobile --trace
+
+Exit codes:
+    0   strong_ok or weak_ok
+    1   ok=False (all attempts failed)
+    2   CLI arg error
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import fetch
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="python3 -m engine",
+                                description="Generic WAF-profile fetch chain.")
+    p.add_argument("url", help="URL to fetch.")
+    p.add_argument("--selector", "-s", action="append", default=None,
+                   dest="selectors", metavar="CSS",
+                   help="Positive-proof CSS selector. Repeatable.")
+    p.add_argument("--device", choices=("auto", "desktop", "mobile"), default="auto",
+                   help="Device class pin.")
+    p.add_argument("--timeout", type=int, default=25,
+                   help="Per-attempt timeout seconds (default 25).")
+    p.add_argument("--max-attempts", type=int, default=12,
+                   help="Upper bound across all phases (default 12).")
+    p.add_argument("--no-playwright", action="store_true",
+                   help="Skip Playwright fallback (curl-only).")
+    p.add_argument("--json", action="store_true",
+                   help="Emit FetchResult as JSON to stdout (content omitted).")
+    p.add_argument("--trace", action="store_true",
+                   help="Print per-attempt trace to stderr.")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        result = fetch(
+            args.url,
+            success_selectors=args.selectors,
+            device_class=args.device,
+            timeout=args.timeout,
+            max_attempts=args.max_attempts,
+            enable_playwright=not args.no_playwright,
+        )
+    except Exception as e:
+        print(f"engine fatal: {type(e).__name__}: {e}", file=sys.stderr)
+        return 2
+
+    if args.trace:
+        print("=== trace ===", file=sys.stderr)
+        for att in result.trace:
+            d = att.to_dict()
+            imp = d.get("impersonate") or "-"
+            ref = d.get("referer") or "-"
+            print(
+                f"[{d['phase']:<8}] {d['executor']:<18} "
+                f"xform={d['url_transform']:<16} imp={imp:<14} ref={ref:<14} "
+                f"status={d['status']:>4} size={d['body_size']:>8} "
+                f"verdict={d['verdict']} {('err=' + d['error'][:60]) if d.get('error') else ''}",
+                file=sys.stderr,
+            )
+        print(f"=== summary: {result.summary} ===", file=sys.stderr)
+
+    # Surface R7 hint (API-first route) prominently when summary contains it,
+    # regardless of --trace flag — this is actionable guidance, not noise.
+    if "R7 API-first" in (result.summary or ""):
+        print(
+            "\n════════════════════════════════════════════════════════════════\n"
+            "⚠️  R7 triggered — consider API-first route instead of HTML grid.\n"
+            "   See summary below (or re-run with --trace for full attempt log).\n"
+            "════════════════════════════════════════════════════════════════",
+            file=sys.stderr,
+        )
+        # Also print the full summary (which includes the hint) so caller sees it.
+        print(result.summary, file=sys.stderr)
+
+    if args.json:
+        payload = result.to_dict()
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+    else:
+        # Default: HTML to stdout, status to stderr.
+        print(result.content, end="")
+        print(f"\n[engine] ok={result.ok} verdict={result.verdict} "
+              f"profile={result.profile_used} attempts={len(result.trace)}",
+              file=sys.stderr)
+
+    return 0 if result.ok else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())