oh-my-opencode 4.19.4 → 5.0.0-beta.2

package/packages/shared-skills/skills/ultimate-browsing/engine/tests/test_surrogate.py

@@ -0,0 +1,252 @@
+"""Surrogate registry/fetch/ordering tests; registry entries and responses are faked, never live network."""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import unittest
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from engine.result_schema import Attempt  # noqa: E402
+from engine.validators import Verdict  # noqa: E402
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+TARGET = "https://en.wikipedia.org/wiki/Web_archiving"  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+
+
+def _fixture(name: str) -> str:
+    return (FIXTURES / name).read_text(encoding="utf-8", errors="replace")
+
+
+class _Resp:
+    def __init__(self, text: str = "", status: int = 200, url: str = "", payload: dict | None = None):
+        self.text = text
+        self.status_code = status
+        self.url = url
+        self.cookies = {}
+        self.headers = {}
+        self._payload = payload
+
+    def json(self):
+        if self._payload is None:
+            raise ValueError("no json payload")
+        return self._payload
+
+
+def _fail_attempt(phase: str) -> Attempt:
+    return Attempt(
+        phase=phase,
+        executor="curl_cffi",
+        url=TARGET,
+        url_transform="original",
+        impersonate="safari",
+        referer="self_root",
+        verdict=Verdict.CHALLENGE.value,
+    )
+
+
+class SurrogateRegistry(unittest.TestCase):
+    def test_default_registry_contains_wayback(self) -> None:
+        from engine import surrogate
+
+        reg = surrogate.load_surrogates()
+        self.assertIn("wayback", reg)
+        self.assertEqual(reg["wayback"]["kind"], "archive")
+        self.assertEqual(reg["wayback"]["trust"], "archive")
+
+    def test_stale_entries_detected(self) -> None:
+        from engine import surrogate
+
+        self.assertTrue(surrogate.is_stale({"last_verified": "2025-01-01"}, max_age_days=90))
+        self.assertFalse(surrogate.is_stale({"last_verified": "2999-01-01"}, max_age_days=90))
+
+
+class SurrogateFetch(unittest.TestCase):
+    def test_wayback_success_sets_snapshot_provenance(self) -> None:
+        from engine import surrogate
+
+        discovery = json.loads(_fixture("wayback_available.json"))
+
+        def fake_http(u: str, **kw):
+            if "wayback/available" in u:
+                return _Resp(json.dumps(discovery), 200, u, payload=discovery)
+            return _Resp(_fixture("wayback_snapshot.html"), 200, u)
+
+        with patch.object(surrogate, "_http_get", side_effect=fake_http):
+            atts, meta, content = surrogate.run_surrogate(TARGET, registry=surrogate.load_surrogates(), timeout=5)
+
+        att = atts[-1]
+        self.assertEqual(att.phase, "surrogate")
+        self.assertEqual(att.executor, "surrogate_wayback")
+        self.assertEqual(att.verdict, Verdict.WEAK_OK.value)
+        self.assertEqual(meta["provenance"], "snapshot")
+        self.assertTrue(meta["snapshot_timestamp"])
+        self.assertEqual(meta["trust"], "archive")
+        self.assertGreater(len(content), 3000)
+
+    def test_stub_snapshot_is_not_accepted(self) -> None:
+        from engine import surrogate
+
+        disc = {"archived_snapshots": {"closest": {"available": True, "url": "https://web.archive.org/web/2024/x", "timestamp": "20240101000000"}}}  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+
+        def fake_http(u: str, **kw):
+            if "wayback/available" in u:
+                return _Resp(json.dumps(disc), 200, u, payload=disc)
+            return _Resp(_fixture("amp_redirect_stub.html"), 200, u)
+
+        with patch.object(surrogate, "_http_get", side_effect=fake_http):
+            atts, _, _ = surrogate.run_surrogate(TARGET, registry={"wayback": surrogate.DEFAULT_SURROGATES["wayback"]}, timeout=5)
+        att = atts[-1]
+        self.assertNotIn(att.verdict, (Verdict.STRONG_OK.value, Verdict.WEAK_OK.value))
+
+    def test_proxy_skips_without_allow_flag(self) -> None:
+        from engine import surrogate
+
+        reg = {"anon_relay": {"kind": "proxy", "trust": "untrusted", "enabled": False,
+                              "last_verified": "2999-01-01", "fetch": "https://relay.invalid/{target}"}}  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+        called: list[str] = []
+
+        with patch.object(surrogate, "_http_get", side_effect=lambda u, **kw: (called.append(u), _Resp("<html>" + "y" * 4000 + "</html>", 200, u))[1]):
+            atts, _, _ = surrogate.run_surrogate(TARGET, registry=reg, allow_proxy=False, timeout=5)
+        self.assertEqual(len(called), 0)
+
+        with patch.object(surrogate, "_http_get", side_effect=lambda u, **kw: (called.append(u), _Resp("<html>" + "y" * 4000 + "</html>", 200, u))[1]):
+            atts, meta, _ = surrogate.run_surrogate(TARGET, registry=reg, allow_proxy=True, timeout=5)
+        self.assertEqual(len(called), 1)
+        att = atts[-1]
+        self.assertEqual(att.executor, "surrogate_anon_relay")
+        self.assertEqual(meta["trust"], "untrusted")
+
+    def test_proxy_never_carries_credentials(self) -> None:
+        from engine import surrogate
+
+        seen: list[dict] = []
+
+        def fake_http(u: str, **kw):
+            seen.append(kw.get("headers", {}))
+            return _Resp("<html>" + "z" * 4000 + "</html>", 200, u)
+
+        reg = {"anon_relay": {"kind": "proxy", "trust": "untrusted", "enabled": False,
+                              "last_verified": "2999-01-01", "fetch": "https://relay.invalid/{target}"}}  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+        os.environ["OMOB_TEST_TOKEN"] = "secret"
+        try:
+            with patch.object(surrogate, "_http_get", side_effect=fake_http):
+                surrogate.run_surrogate(TARGET, registry=reg, allow_proxy=True, timeout=5)
+        finally:
+            os.environ.pop("OMOB_TEST_TOKEN", None)
+
+        self.assertEqual(len(seen), 1)
+        joined = json.dumps(seen[0]).lower()
+        self.assertNotIn("secret", joined)
+        self.assertNotIn("authorization", joined)
+        self.assertNotIn("cookie", joined)
+
+
+class ChainOrdering(unittest.TestCase):
+    def _profile(self) -> dict:
+        return {
+            "tls_impersonate_candidates": [[]],
+            "referer_strategies": [],
+            "url_transform_order": ["original"],
+            "fallback_when_challenge": ["surrogate_wayback", "playwright_real_chrome"],
+        }
+
+    def test_surrogate_success_short_circuits_playwright(self) -> None:
+        from engine.fetch_chain import fetch
+        from engine import surrogate
+        from engine import executor as ex
+
+        def fake_surrogate(*a, **kw):
+            att = Attempt(
+                phase="surrogate",
+                executor="surrogate_wayback",
+                url=TARGET,
+                url_transform="original",
+                impersonate=None,
+                referer="",
+                verdict=Verdict.WEAK_OK.value,
+                body_size=5000,
+            )
+            return [att], {"provenance": "snapshot", "snapshot_timestamp": "20240101000000", "trust": "archive"}, "<html>content</html>"
+
+        def fail_playwright(*a, **kw):
+            raise AssertionError("playwright must not run after surrogate success")
+
+        with patch("engine.fetch_chain._load_profiles", return_value={}), \
+                patch("engine.fetch_chain.last_load_error", return_value=None), \
+                patch("engine.fetch_chain.run_attempt", side_effect=lambda *a, **kw: (_fail_attempt(str(kw.get("phase", "grid"))), None)), \
+                patch("engine.fetch_chain.detect", return_value=[]), \
+                patch("engine.fetch_chain.load_profile", side_effect=lambda *a, **kw: self._profile()), \
+                patch.object(surrogate, "run_surrogate", side_effect=fake_surrogate), \
+                patch.object(ex, "run_playwright_fallback", side_effect=fail_playwright):
+            result = fetch(TARGET, enable_playwright=True, max_attempts=1)
+
+        self.assertTrue(result.ok)
+        self.assertEqual(result.provenance, "snapshot")
+        self.assertEqual(result.snapshot_timestamp, "20240101000000")
+
+    def test_surrogate_still_runs_when_playwright_disabled(self) -> None:
+        from engine.fetch_chain import fetch
+        from engine import surrogate
+
+        calls: list[str] = []
+
+        def fake_surrogate(*a, **kw):
+            calls.append("surrogate")
+            att = Attempt(phase="surrogate", executor="surrogate_wayback", url=TARGET,
+                          url_transform="original", impersonate=None, referer="",
+                          verdict=Verdict.WEAK_OK.value, body_size=5000)
+            return [att], {"provenance": "snapshot", "snapshot_timestamp": "20240101000000", "trust": "archive"}, "<html>snap</html>"
+
+        with patch("engine.fetch_chain._load_profiles", return_value={}), \
+                patch("engine.fetch_chain.last_load_error", return_value=None), \
+                patch("engine.fetch_chain.run_attempt", side_effect=lambda *a, **kw: (_fail_attempt(str(kw.get("phase", "grid"))), None)), \
+                patch("engine.fetch_chain.detect", return_value=[]), \
+                patch("engine.fetch_chain.load_profile", side_effect=lambda *a, **kw: self._profile()), \
+                patch.object(surrogate, "run_surrogate", side_effect=fake_surrogate):
+            result = fetch(TARGET, enable_playwright=False, max_attempts=1)
+
+        self.assertEqual(calls, ["surrogate"])
+        self.assertTrue(result.ok)
+        self.assertEqual(result.provenance, "snapshot")
+
+    def test_playwright_runs_when_surrogate_fails(self) -> None:
+        from engine.fetch_chain import fetch
+        from engine import surrogate
+        from engine import executor as ex
+
+        calls: list[str] = []
+
+        def fake_surrogate(*a, **kw):
+            calls.append("surrogate")
+            att = Attempt(phase="surrogate", executor="surrogate_wayback", url=TARGET,
+                          url_transform="original", impersonate=None, referer="",
+                          verdict=Verdict.UNKNOWN.value)
+            return [att], {"provenance": "live", "snapshot_timestamp": None, "trust": "origin"}, ""
+
+        def fake_playwright(*a, **kw):
+            calls.append("playwright")
+            att = Attempt(phase="fallback", executor="playwright_real_chrome", url=TARGET,
+                          url_transform="original", impersonate=None, referer="",
+                          verdict=Verdict.WEAK_OK.value, body_size=5000)
+            return att, "<html>chrome content</html>"
+
+        with patch("engine.fetch_chain._load_profiles", return_value={}), \
+                patch("engine.fetch_chain.last_load_error", return_value=None), \
+                patch("engine.fetch_chain.run_attempt", side_effect=lambda *a, **kw: (_fail_attempt(str(kw.get("phase", "grid"))), None)), \
+                patch("engine.fetch_chain.detect", return_value=[]), \
+                patch("engine.fetch_chain.load_profile", side_effect=lambda *a, **kw: self._profile()), \
+                patch.object(surrogate, "run_surrogate", side_effect=fake_surrogate), \
+                patch.object(ex, "run_playwright_fallback", side_effect=fake_playwright):
+            result = fetch(TARGET, enable_playwright=True, max_attempts=1)
+
+        self.assertTrue(result.ok)
+        self.assertEqual(result.provenance, "live")
+        self.assertEqual(calls, ["surrogate", "playwright"])
+
+
+if __name__ == "__main__":
+    unittest.main()

package/packages/shared-skills/skills/ultimate-browsing/engine/tests/test_surrogate_validators.py

@@ -0,0 +1,78 @@
+"""Surrogate-tier validation tests; fixtures only, never live network, so the suite cannot flake."""
+from __future__ import annotations
+
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from engine.result_schema import FetchResult  # noqa: E402
+from engine.validators import Verdict, validate  # noqa: E402
+
+FIXTURES = Path(__file__).resolve().parent / "fixtures"
+
+
+def _fixture(name: str) -> str:
+    return (FIXTURES / name).read_text(encoding="utf-8", errors="replace")
+
+
+class _Resp:
+    def __init__(self, text: str = "", status: int = 200, url: str = ""):
+        self.text = text
+        self.status_code = status
+        self.url = url
+        self.cookies = {}
+        self.headers = {}
+
+
+class RedirectStubRejection(unittest.TestCase):
+    def test_amp_redirect_stub_is_not_ok(self) -> None:
+        body = _fixture("amp_redirect_stub.html")
+        self.assertLess(len(body), 1000)
+        resp = _Resp(body, 200, "https://en-wikipedia-org.cdn.ampproject.org/c/s/x")  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+        vr = validate(resp, target_url="https://en.wikipedia.org/wiki/Web_archiving")  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+        self.assertIn(vr.verdict, (Verdict.CHALLENGE, Verdict.UNKNOWN))
+        self.assertFalse(vr.ok)
+
+    def test_real_snapshot_still_passes(self) -> None:
+        resp = _Resp(_fixture("wayback_snapshot.html"), 200, "https://web.archive.org/web/2024/x")  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+        vr = validate(resp, target_url="https://en.wikipedia.org/wiki/Web_archiving")  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+        self.assertTrue(vr.ok)
+
+    def test_plain_page_still_weak_ok(self) -> None:
+        resp = _Resp("<html><body>" + ("x" * 4000) + "</body></html>", 200, "https://example.com/")
+        vr = validate(resp, target_url="https://example.com/")
+        self.assertTrue(vr.ok)
+
+
+class InterstitialRejection(unittest.TestCase):
+    def test_search_engine_interstitial_is_not_ok(self) -> None:
+        body = _fixture("search_interstitial.html")
+        resp = _Resp(body, 200, "https://webcache.googleusercontent.com/search?q=cache:x")  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+        vr = validate(resp, target_url="https://en.wikipedia.org/wiki/Web_archiving")  # NOTE-BIAS-OK — fixture URL from a third-party surrogate service, not a target site
+        self.assertIn(vr.verdict, (Verdict.CHALLENGE, Verdict.UNKNOWN))
+        self.assertFalse(vr.ok)
+
+
+class ResultSchemaProvenance(unittest.TestCase):
+    def test_defaults_are_live_origin(self) -> None:
+        r = FetchResult(ok=True)
+        self.assertEqual(r.provenance, "live")
+        self.assertEqual(r.trust, "origin")
+        self.assertIsNone(r.snapshot_timestamp)
+        d = r.to_dict()
+        self.assertEqual(d["provenance"], "live")
+        self.assertEqual(d["trust"], "origin")
+        self.assertIn("snapshot_timestamp", d)
+
+    def test_snapshot_fields_roundtrip(self) -> None:
+        r = FetchResult(ok=True, provenance="snapshot", snapshot_timestamp="20241227132135", trust="archive")
+        d = r.to_dict()
+        self.assertEqual(d["provenance"], "snapshot")
+        self.assertEqual(d["snapshot_timestamp"], "20241227132135")
+        self.assertEqual(d["trust"], "archive")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/packages/shared-skills/skills/ultimate-browsing/engine/validators.py

@@ -43,6 +43,41 @@ CHALLENGE_MARKERS: list[str] = [
 # that know their response type should pass success_selectors instead.
 SMALL_BODY_THRESHOLD = 3000
 
+# Surrogate-route interstitial: a search-engine front page returned in place
+# of the cached page (dead cache services fall back to their home page).
+INTERSTITIAL_TITLE_MARKERS: list[str] = [
+    "<title>google search</title>",
+]
+
+
+def is_interstitial_title(body_lower: str) -> bool:
+    return any(m in body_lower for m in INTERSTITIAL_TITLE_MARKERS)
+
+
+def is_redirect_stub(text: str, *, target_url: Optional[str] = None) -> bool:
+    """True when the body only exists to send the reader back to `target_url`.
+
+    AMP-cache style stubs answer HTTP 200 with a few hundred bytes whose sole
+    content is a meta-refresh / JS redirect pointing at the origin we failed
+    to fetch — accepting one loops the caller straight back into the block.
+    """
+    if not text or len(text) >= SMALL_BODY_THRESHOLD:
+        return False
+    lowered = text.lower()
+    has_redirect = (
+        "http-equiv=\"refresh\"" in lowered
+        or "location.replace" in lowered
+        or "window.location" in lowered
+    )
+    if not has_redirect:
+        return False
+    if target_url is None:
+        return True
+    host_match = "".join(c for c in target_url.split("//")[-1].split("/")[0])
+    if not host_match:
+        return True
+    return host_match.lower() in lowered
+
 
 class Verdict(Enum):
     """Three-level classification (Codex suggestion — avoid binary)."""
@@ -115,6 +150,7 @@ def validate(
     success_selectors: Optional[list[str]] = None,
     known_bad_sizes: Optional[list[int]] = None,
     size_tolerance: int = 20,
+    target_url: Optional[str] = None,
 ) -> ValidationResult:
     """Validate a `curl_cffi` / `requests` response.
 
@@ -153,6 +189,16 @@ def validate(
         r.reasons.extend(f"marker:{m}" for m in markers[:3])
         return r
 
+    # --- Layer 1.5: surrogate-route dead ends (interstitial / redirect stub) --
+    if is_interstitial_title(lowered):
+        r.verdict = Verdict.CHALLENGE
+        r.reasons.append("interstitial_title")
+        return r
+    if is_redirect_stub(text, target_url=target_url):
+        r.verdict = Verdict.CHALLENGE
+        r.reasons.append("redirect_stub")
+        return r
+
     # --- Layer 2: size fingerprints (caller hint, tolerant match) ---
     # Fingerprint match is a strong negative signal — override even selectors.
     if known_bad_sizes:

package/packages/shared-skills/skills/ultimate-browsing/engine/waf_detector.py

@@ -39,7 +39,7 @@ _DEFAULT_PROFILES: dict = {
         ],
         "referer_strategies": ["self_root", "google_search", "none"],
         "url_transform_order": ["original", "mobile_subdomain"],
-        "fallback_when_challenge": ["playwright_mcp", "playwright_real_chrome"],
+        "fallback_when_challenge": ["surrogate_wayback", "playwright_mcp", "playwright_real_chrome"],
         "notes": "in-code default — waf_profiles.yaml unavailable",
     },
 }

package/packages/shared-skills/skills/ultimate-browsing/engine/waf_profiles.yaml

@@ -34,21 +34,21 @@ akamai_bot_manager:
     # at least a challenge page (i.e. IP still alive) rather than an outright
     # TLS reject. Grouped by family; planner tries top groups first.
     # Refresh quarterly — vendor WAFs shift which TLS fingerprints they trust.
-    - [safari, safari15_3, safari15_5, safari17_0, safari260]
+    - [safari, safari15_3, safari15_5, safari17_0, safari260, safari2601]
     - [safari_ios, safari17_2_ios, safari260_ios]
-    - [chrome99, chrome100, chrome101, chrome104, chrome110, chrome116, chrome119, chrome124, chrome131, chrome133a, chrome136, chrome145, chrome146]
+    - [chrome99, chrome100, chrome101, chrome104, chrome110, chrome116, chrome119, chrome124, chrome131, chrome133a, chrome136, chrome142, chrome145, chrome146]
     - [chrome_android, chrome131_android]
     - [edge99, edge101]
   tls_impersonate_avoid:
     # Empirically observed to 403 immediately (TLS fingerprint blacklisted).
     # DO NOT hard-block — planner deprioritizes only. Refresh quarterly.
+    # NOTE: requires curl_cffi >= 0.15.0 for chrome142/145/146 + safari260/2601 +
+    # firefox144/147 targets (added 0.14.0-0.15.0; default aliases resolve to
+    # chrome146/safari2601/firefox147 in 0.16.0+). Older installs raise ImpersonateError.
     - safari18_0
     - chrome107
     - chrome120
     - chrome123
-    - chrome145     # curl_cffi 0.11+ needed — mark avoid for older installs
-    - chrome146
-    - firefox
     - firefox133
     - firefox135
   referer_strategies:
@@ -57,6 +57,7 @@ akamai_bot_manager:
     - original
     - mobile_subdomain   # www.* → m.* — strong observational win in SSR sites
   fallback_when_challenge:
+    - surrogate_wayback   # Phase 2.5: archive/reader copy before a browser spin-up
     - curl_grid_exhaust   # try more impersonate × referer × url combos
     - playwright_real_chrome
   notes: |
@@ -77,6 +78,7 @@ cloudflare_turnstile:
     - google_search
     - self_root
   fallback_when_challenge:
+    - surrogate_wayback   # Phase 2.5: archive/reader copy before a browser spin-up
     - playwright_mcp       # MCP sufficient; Chromium TLS passes CF baseline
     - playwright_real_chrome
 
@@ -112,6 +114,7 @@ datadome_probable:
   tls_impersonate_candidates:
     - [safari, chrome]
   fallback_when_challenge:
+    - surrogate_wayback   # Phase 2.5: archive/reader copy before a browser spin-up
     - playwright_real_chrome
   notes: |
     "_probable" suffix reminds us this is a growing attack surface — mark
@@ -127,6 +130,7 @@ perimeterx_human:
   tls_impersonate_candidates:
     - [safari, chrome]
   fallback_when_challenge:
+    - surrogate_wayback   # Phase 2.5: archive/reader copy before a browser spin-up
     - playwright_real_chrome
   notes: |
     PerimeterX (now HUMAN Bot Defender). Distinct cookie family from
@@ -154,6 +158,7 @@ unknown_challenge:
     - original
     - mobile_subdomain
   fallback_when_challenge:
+    - surrogate_wayback   # Phase 2.5: archive/reader copy before a browser spin-up
     - playwright_mcp
     - playwright_real_chrome
   notes: |

package/packages/shared-skills/skills/ultimate-browsing/references/agent-reach/social.md

@@ -40,7 +40,7 @@ xhs favorites              # 可能返回 API error
 >
 > **频率控制**: 高频请求（批量搜索、深翻评论）会触发验证码，这是平台限制无法绕过。建议每次操作间隔 2-3 秒。
 >
-> **POST 操作风险**: 发帖(post)、评论(comment)、点赞(like) 等写操作在 v0.6.x 可能因签名问题返回 406。如需使用，建议降级到 v0.3.5 (`pipx install xiaohongshu-cli==0.3.5`)。
+> **POST 操作**: 发帖(post)、评论(comment)、点赞(like) 等写操作在 v0.6.4 已修复签名问题 (PR [#19](https://github.com/jackwener/xiaohongshu-cli/pull/19))，可正常使用。
 
 ## 抖音 / Douyin
 

package/packages/shared-skills/skills/ultimate-browsing/references/chrome-stealth.md

@@ -2,8 +2,8 @@
 
 Real interaction (clicks, forms, screenshots, video, persistent login) for pages that defeat Tier 1/1.5. Two runtime tools, both installed on demand — neither is vendored in this skill:
 
-- **CloakBrowser** (`pip`) — stealth Chromium with source-level C++ fingerprint patches. The Python wrapper source is MIT; the downloaded Chromium binary is covered by CloakBrowser's separate binary license and is not redistributed by this package. Passes Cloudflare Turnstile, FingerprintJS, BrowserScan, and 30+ detectors. Pin **0.4.10**.
-- **agent-browser** (`npm`, Apache-2.0) — native CDP automation CLI that drives CloakBrowser. AX-tree snapshots, `@eN` refs, click/fill/type/scroll, screenshots, video, cookie/state/session management. Pin **0.31.1**.
+- **CloakBrowser** (`pip`) — stealth Chromium with source-level C++ fingerprint patches. The Python wrapper source is MIT; the downloaded Chromium binary is covered by CloakBrowser's separate binary license and is not redistributed by this package. Passes Cloudflare Turnstile, FingerprintJS, BrowserScan, and 30+ detectors. Pin **0.5.5**.
+- **agent-browser** (`npm`, Apache-2.0) — native CDP automation CLI that drives CloakBrowser. AX-tree snapshots, `@eN` refs, click/fill/type/scroll, screenshots, video, cookie/state/session management. Pin **0.33.2**.
 
 ```
 CloakBrowser (stealth Chromium) <- CDP port 9242 -> agent-browser CLI
@@ -18,22 +18,22 @@ CloakBrowser (stealth Chromium) <- CDP port 9242 -> agent-browser CLI
 CloakBrowser runs in a dedicated Python venv. Cross-platform: macOS, Linux, and Windows all supported by both tools (use the venv path convention for your OS).
 
 ```bash
-# CloakBrowser (MIT wrapper source; separate binary license, pin 0.4.10):
+# CloakBrowser (MIT wrapper source; separate binary license, pin 0.5.5):
 uv venv .cloak-venv --python 3.13
 # macOS/Linux: source .cloak-venv/bin/activate    Windows: .cloak-venv\Scripts\activate
-uv pip install "cloakbrowser==0.4.10"
+uv pip install "cloakbrowser==0.5.5"
 python -c "import cloakbrowser; cloakbrowser.ensure_binary()"   # downloads stealth Chromium on first import
 
-# agent-browser (Apache-2.0, pin 0.31.1):
-npm i -g agent-browser@0.31.1 && agent-browser install
-agent-browser --version   # 0.31.1
+# agent-browser (Apache-2.0, pin 0.33.2):
+npm i -g agent-browser@0.33.2 && agent-browser install
+agent-browser --version   # 0.33.2
 ```
 
 Verify CloakBrowser:
 
 ```bash
 python -c "import cloakbrowser; print(cloakbrowser.__version__, cloakbrowser.CHROMIUM_VERSION, cloakbrowser.binary_info()['installed'])"
-# -> 0.4.10  <chromium-version>  True
+# -> 0.5.5  <chromium-version>  True
 ```
 
 ## Launch + drive
@@ -76,7 +76,9 @@ agent-browser skills list                # everything available on the installed
 agent-browser --cdp 9242 eval 'navigator.webdriver'   # must print false
 ```
 
-Verified 2026-07 with CloakBrowser 0.4.10 + agent-browser 0.31.1: `navigator.webdriver` reads the boolean false with no init-script, bot.sannysoft.com all-green, browserscan.net "Normal" (15/15), nowsecure.nl Turnstile bypassed.
+Verified 2026-07 with CloakBrowser 0.5.5 + agent-browser 0.33.2: `navigator.webdriver` reads the boolean false with no init-script, bot.sannysoft.com all-green, browserscan.net "Normal" (15/15), nowsecure.nl Turnstile bypassed.
+
+> **agent-browser 0.33.x behavior note:** the daemon now defaults to a 1-hour idle timeout (saves restore state, closes the browser, exits after 1 h of no commands). Set `AGENT_BROWSER_IDLE_TIMEOUT_MS=0` to restore the old always-persist behavior. External WebSocket stream consumers see latest-wins frame delivery; `record` (CDP) and the dashboard are unaffected.
 
 ## Cookie login (cross-platform)
 
@@ -115,6 +117,6 @@ lsof -ti:9242 | xargs kill -9
 # agent-browser can't connect:
 curl -s http://127.0.0.1:9242/json/version | head -5   # empty -> CloakBrowser not running
 # Update either tool:
-uv pip install --upgrade "cloakbrowser==0.4.10" && python -c "import cloakbrowser; cloakbrowser.ensure_binary()"
-npm i -g agent-browser@0.31.1
+uv pip install --upgrade "cloakbrowser==0.5.5" && python -c "import cloakbrowser; cloakbrowser.ensure_binary()"
+npm i -g agent-browser@0.33.2
 ```

package/packages/shared-skills/skills/ultimate-browsing/references/insane-search/README.md

@@ -71,9 +71,9 @@
 |------------|------|
 | URL 제공 (`https://...`) | → Phase 0 검사 후 없으면 Phase 1 (generic fetch chain) |
 | 핸들 제공 (`@username`) | → Phase 0 syndication/API |
-| 키워드만 ("X에서 AI 검색") | → WebSearch(`site:{domain} {keyword}`) 먼저 → URL 확보 후 재진입 |
+| 키워드만 ("X에서 AI 검색") | → 웹 검색 도구(`site:{domain} {keyword}`) 먼저 → URL 확보 후 재진입 |
 
-> **한국어 신규 콘텐츠 한계**: 네이버/다음/한국 커뮤니티의 키워드 검색은 WebSearch 경유가 유일하며, 신규 콘텐츠 인덱싱이 지연될 수 있다.
+> **한국어 신규 콘텐츠 한계**: 네이버/다음/한국 커뮤니티의 키워드 검색은 웹 검색 도구 경유가 유일하며, 신규 콘텐츠 인덱싱이 지연될 수 있다.
 
 ## Phase 0 — 플랫폼 공식 API 인덱스
 
@@ -83,7 +83,7 @@
 
 | 플랫폼 | 방법 | 상세 |
 |--------|------|------|
-| X/Twitter | syndication (타임라인) + oEmbed (개별 트윗) + 키워드 검색: WebSearch → oEmbed | [twitter.md](twitter.md) |
+| X/Twitter | syndication (타임라인) + oEmbed (개별 트윗) + 키워드 검색: 웹 검색 도구 → oEmbed | [twitter.md](twitter.md) |
 | Reddit | URL + `.json` + Mobile UA | [json-api.md](json-api.md) |
 | Bluesky | AT Protocol (`public.api.bsky.app/xrpc/...`) | [public-api.md](public-api.md) |
 | Mastodon | 인스턴스별 공개 API | [public-api.md](public-api.md) |
@@ -301,7 +301,7 @@ yt-dlp --write-sub --write-auto-sub --sub-lang "en,ko" --skip-download -o "/tmp/
 |------|-------------|-----------------|
 | [`json-api.md`](json-api.md) | Reddit/Wikipedia/HN/npm/PyPI 등 **URL 변형만으로** JSON을 주는 사이트 | Reddit `/json` suffix + Mobile UA, HN Firebase, Algolia Search, Wikipedia REST, npm/PyPI Registry API |
 | [`public-api.md`](public-api.md) | Bluesky/Mastodon/arXiv/Stack Overflow/CrossRef/GitHub/OpenLibrary/Wayback 공식 API 사용 시 | 인증 없이 쓰는 공식 공개 REST/AT/Atom API 엔드포인트, 요청 형식, 공통 파라미터 |
-| [`twitter.md`](twitter.md) | X/Twitter 접근 — 프로필 타임라인, 특정 트윗, 키워드 검색 | `syndication.twitter.com` 타임라인, oEmbed 개별 트윗, 검색은 WebSearch로 URL 확보 후 oEmbed |
+| [`twitter.md`](twitter.md) | X/Twitter 접근 — 프로필 타임라인, 특정 트윗, 키워드 검색 | `syndication.twitter.com` 타임라인, oEmbed 개별 트윗, 검색은 웹 검색 도구로 URL 확보 후 oEmbed |
 | [`naver.md`](naver.md) | 네이버 블로그·뉴스·증권·검색 접근 | 서비스별 우회(블로그는 `m.blog.naver.com` 변환, 증권은 비공식 JSON, 검색은 `search.naver.com`), 한글 검색 쿼리 패턴 |
 | [`media.md`](media.md) | YouTube/Vimeo/Twitch/TikTok/SoundCloud 등 미디어 메타·자막·오디오 필요 시 | `yt-dlp --dump-json` 기반 1,858개 사이트 커버, 자막 다운로드(`--write-sub`), 포맷 선택, 라이브/팟캐스트 |