Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Python agent-infrastructureai-agentai-searchautomationbilibiliclaude-codeclicursorfree-apillm-toolsmcppythonreddit-scrapertwitter-scraperweb-scraperxiaohongshuyoutube-transcript
feat: unified entry with JSON envelope; move default channels
Pnant8e23bf2da4ab
diff --git a/agent_reach/channels/base.py b/agent_reach/channels/base.pyindex 2afec0a7..22e6ead1 100644--- a/agent_reach/channels/base.py+++ b/agent_reach/channels/base.py@@ -23,7 +23,36 @@ Backend routing semantics:"""from abc import ABC, abstractmethod-from typing import List, Optional, Tuple+from dataclasses import dataclass+from typing import Dict, List, Optional, Tuple+++@dataclass(frozen=True)+class Param:+ """One argument of a unified action."""++ name: str+ help: str+ required: bool = True+ type: type = str+ default: object = None+++@dataclass(frozen=True)+class Action:+ """A unified action (`agent-reach <channel> <action>`).++ `backends` is ordered: (backend label, channel method name). The+ dispatcher tries them in order and falls back on retryable errors.+ `live_test` holds params for `agent-reach check`; a backend passes when+ the call succeeds and returns at least one item.+ """++ name: str+ help: str+ params: Tuple[Param, ...]+ backends: Tuple[Tuple[str, str], ...]+ live_test: Optional[Dict[str, object]] = Noneclass Channel(ABC):@@ -34,6 +63,13 @@ class Channel(ABC):backends: List[str] = [] # ordered candidates — backends[0] = preferredtier: int = 0 # 0=zero-config, 1=needs free key, 2=needs setup+ #: Unified-entry tier: "default" / "optional" / "experimental".+ #: Empty means the channel is not on the unified entry yet. `tier` above+ #: is the legacy doctor grouping and goes away at cutover.+ level: str = ""+ #: Unified actions this channel exposes.+ actions: Tuple[Action, ...] = ()+#: Backend currently serving this channel; set by check(), None = unavailable.active_backend: Optional[str] = Nonediff --git a/agent_reach/channels/github.py b/agent_reach/channels/github.pyindex 8441fa2c..2282b9c9 100644--- a/agent_reach/channels/github.py+++ b/agent_reach/channels/github.py@@ -3,18 +3,38 @@from __future__ import annotations+import jsonimport os+import re+import urllib.errorfrom pathlib import Path+from urllib.parse import urlencodeimport yamlfrom agent_reach.probe import probe_command+from agent_reach.runtime.result import (+ BAD_INPUT,+ NEED_LOGIN,+ NOT_FOUND,+ RATE_LIMITED,+ ReachError,+ make_item,+)+from agent_reach.runtime.run import CommandFailed, http_request, run_cmdfrom agent_reach.utils.paths import (PrivatePathError,read_small_text_no_follow,)-from .base import Channel+from .base import Action, Channel, Param++_API = "https://api.github.com"+_TARGET_RE = re.compile(+ r"^(?:https?://(?:www\.)?github\.com/)?([\w.-]+)/([\w.-]+?)(?:\.git)?"+ r"(?:/(?:issues|pull)/(\d+))?/?(?:[?#].*)?$"+)+_README_MAX_CHARS = 50_000_MAX_HOSTS_BYTES = 1024 * 1024_GH_READ_ONLY_ENV = {@@ -92,12 +112,90 @@ def _explicit_github_credentials(config) -> bool:raise GitHubConfigError("Agent Reach 的 GitHub 配置无法读取") from exc+def _parse_target(target: str):+ """owner/repo, a repo link, or an issue/PR link → (owner, repo, number|None)."""+ m = _TARGET_RE.match(str(target).strip())+ if not m:+ raise ReachError(BAD_INPUT, "target must be owner/repo or a github.com repo/issue/PR link")+ owner, repo, number = m.groups()+ return owner, repo, int(number) if number else None+++def _gh_get(path: str, timeout: float, accept: str = "application/vnd.github+json") -> bytes:+ try:+ out = run_cmd(+ ["gh", "api", "-H", f"Accept: {accept}", path],+ timeout=timeout,+ env=_GH_READ_ONLY_ENV,+ )+ except CommandFailed as exc:+ err = exc.stderr.lower()+ if "http 404" in err or "not found" in err:+ raise ReachError(NOT_FOUND, exc.message) from None+ if "gh auth login" in err or "authentication" in err:+ raise ReachError(NEED_LOGIN, "gh is not logged in") from None+ if "rate limit" in err:+ raise ReachError(RATE_LIMITED, exc.message) from None+ raise+ return out.encode("utf-8")+++def _api_get(path: str, timeout: float, accept: str = "application/vnd.github+json") -> bytes:+ headers = {"Accept": accept, "User-Agent": "agent-reach"}+ token = os.environ.get("GH_TOKEN") or os.environ.get("GITHUB_TOKEN")+ if token:+ headers["Authorization"] = f"Bearer {token}"+ try:+ return http_request(f"{_API}{path}", timeout=timeout, headers=headers)+ except urllib.error.HTTPError as exc:+ if exc.code == 403:+ raise ReachError(RATE_LIMITED, "GitHub API rate limit (60/hour without a token)") from None+ raise+++def _repo_item(repo: dict, readme: str | None = None) -> dict:+ return make_item(+ title=repo.get("full_name"),+ url=repo.get("html_url"),+ author=(repo.get("owner") or {}).get("login"),+ published_at=repo.get("created_at"),+ text=readme or repo.get("description"),+ raw={+ k: repo.get(k)+ for k in ("description", "stargazers_count", "forks_count", "language",+ "topics", "pushed_at", "open_issues_count", "archived")+ }+ | {"license": (repo.get("license") or {}).get("spdx_id")},+ )++class GitHubChannel(Channel):name = "github"description = "GitHub 仓库和代码"backends = ["gh CLI"]tier = 0+ level = "default"+ actions = (+ Action(+ "search",+ "Search repositories",+ (+ Param("query", "what to search for"),+ Param("limit", "max results", required=False, type=int, default=5),+ ),+ (("gh", "_gh_search"), ("github-api", "_api_search")),+ live_test={"query": "yt-dlp", "limit": 2},+ ),+ Action(+ "read",+ "Read a repository (with README) or an issue / PR (with comments)",+ (Param("target", "owner/repo, or a repo / issue / PR link"),),+ (("gh", "_gh_read"), ("github-api", "_api_read")),+ live_test={"target": "yt-dlp/yt-dlp"},+ ),+ )+def can_handle(self, url: str) -> bool:from agent_reach.utils.url import host_matches@@ -143,3 +241,57 @@ class GitHubChannel(Channel):"gh CLI 可执行,但未检测到显式认证配置。运行 `gh auth login` ""完成登录;Doctor 不会自动执行 `gh auth status`。")++ # ── unified entry backends ──++ @staticmethod+ def _search(get, query: str, limit: int, timeout: float) -> list:+ path = "/search/repositories?" + urlencode({"q": query, "per_page": limit})+ data = json.loads(get(path, timeout))+ return [_repo_item(r) for r in data.get("items", [])[:limit]]++ @staticmethod+ def _read(get, target: str, timeout: float) -> list:+ owner, repo, number = _parse_target(target)+ if number is None:+ info = json.loads(get(f"/repos/{owner}/{repo}", timeout / 2))+ try:+ readme = get(f"/repos/{owner}/{repo}/readme", timeout / 2, "application/vnd.github.raw")+ readme_text = readme.decode("utf-8", errors="replace")[:_README_MAX_CHARS]+ except ReachError as exc:+ if exc.code != NOT_FOUND:+ raise+ readme_text = None+ return [_repo_item(info, readme_text)]+ issue = json.loads(get(f"/repos/{owner}/{repo}/issues/{number}", timeout / 2))+ comments = json.loads(get(f"/repos/{owner}/{repo}/issues/{number}/comments?per_page=50", timeout / 2))+ parts = [issue.get("body") or ""]+ for c in comments:+ parts.append(f"\n@{(c.get('user') or {}).get('login', '')}: {c.get('body') or ''}")+ return [+ make_item(+ title=issue.get("title"),+ url=issue.get("html_url"),+ author=(issue.get("user") or {}).get("login"),+ published_at=issue.get("created_at"),+ text="\n".join(parts).strip(),+ raw={+ "state": issue.get("state"),+ "labels": [lb.get("name") for lb in issue.get("labels", [])],+ "comments": issue.get("comments"),+ "is_pull_request": "pull_request" in issue,+ },+ )+ ]++ def _gh_search(self, *, query: str, limit: int, timeout: float) -> list:+ return self._search(_gh_get, query, limit, timeout)++ def _api_search(self, *, query: str, limit: int, timeout: float) -> list:+ return self._search(_api_get, query, limit, timeout)++ def _gh_read(self, *, target: str, timeout: float) -> list:+ return self._read(_gh_get, target, timeout)++ def _api_read(self, *, target: str, timeout: float) -> list:+ return self._read(_api_get, target, timeout)diff --git a/agent_reach/channels/v2ex.py b/agent_reach/channels/v2ex.pyindex d11d2455..de01ce97 100644--- a/agent_reach/channels/v2ex.py+++ b/agent_reach/channels/v2ex.py@@ -2,6 +2,7 @@"""V2EX — public API channel for topics, nodes, users, and replies."""import json+import reimport shutilimport sslimport subprocess@@ -9,10 +10,11 @@ import urllib.requestfrom typing import Anyfrom urllib.parse import quote, urlencode, urlsplit+from agent_reach.runtime.result import BAD_INPUT, NOT_FOUND, ReachError, make_item, unix_to_isofrom agent_reach.utils.process import utf8_subprocess_envfrom agent_reach.utils.text import scrub_url_credentials-from .base import Channel+from .base import Action, Channel, Param_UA = "agent-reach/1.0"_TIMEOUT = 10@@ -137,12 +139,74 @@ def _get_json(url: str) -> Any:return _get_json_with_curl(url)+_TOPIC_URL_RE = re.compile(r"^(?:https?://)?(?:www\.)?v2ex\.com/t/(\d+)")+++def _parse_topic_id(target: str) -> int:+ """Accept a topic id or a https://www.v2ex.com/t/<id> link."""+ t = str(target).strip()+ if t.isdigit():+ return int(t)+ match = _TOPIC_URL_RE.match(t)+ if match:+ return int(match.group(1))+ raise ReachError(BAD_INPUT, "target must be a V2EX topic link (https://www.v2ex.com/t/<id>) or id")+++def _topic_item(topic: dict, text: Any = None, raw: Any = None) -> dict:+ member = topic.get("member") or {}+ return make_item(+ title=topic.get("title"),+ url=topic.get("url"),+ author=member.get("username"),+ published_at=unix_to_iso(topic.get("created")),+ text=topic.get("content") if text is None else text,+ raw=topic if raw is None else raw,+ )+++class V2EXChannel(Channel):name = "v2ex"description = "V2EX 节点、主题与回复"backends = ["V2EX API (public)"]tier = 0+ level = "default"+ actions = (+ Action(+ "hot",+ "Today's hot topics",+ (Param("limit", "max items", required=False, type=int, default=10),),+ (("v2ex-api", "_api_hot"),),+ live_test={"limit": 3},+ ),+ Action(+ "node",+ "Latest topics in a node",+ (+ Param("node_name", "node name, e.g. python, programmer, jobs"),+ Param("limit", "max items", required=False, type=int, default=10),+ ),+ (("v2ex-api", "_api_node"),),+ live_test={"node_name": "python", "limit": 3},+ ),+ Action(+ "read",+ "Read a topic and its replies",+ (Param("target", "topic link or id"),),+ (("v2ex-api", "_api_read"),),+ live_test={"target": "https://www.v2ex.com/t/1000"},+ ),+ Action(+ "user",+ "A member's profile",+ (Param("username", "V2EX username"),),+ (("v2ex-api", "_api_user"),),+ live_test={"username": "Livid"},+ ),+ )+# ------------------------------------------------------------------ ## URL routing# ------------------------------------------------------------------ #@@ -346,3 +410,46 @@ class V2EXChannel(Channel):)}]++ # ------------------------------------------------------------------ #+ # Unified entry backends+ # ------------------------------------------------------------------ #++ def _api_hot(self, *, limit: int, timeout: float) -> list:+ data = _get_json("https://www.v2ex.com/api/topics/hot.json")+ return [_topic_item(t) for t in data[:limit]]++ def _api_node(self, *, node_name: str, limit: int, timeout: float) -> list:+ data = _get_json(_v2ex_url("/api/topics/show.json", node_name=node_name, page=1))+ if not isinstance(data, list):+ raise ReachError(NOT_FOUND, f"V2EX node not found: {node_name}")+ return [_topic_item(t) for t in data[:limit]]++ def _api_read(self, *, target: str, timeout: float) -> list:+ topic_id = _parse_topic_id(target)+ data = _get_json(_v2ex_url("/api/topics/show.json", id=topic_id))+ topic = data[0] if isinstance(data, list) and data else data+ if not isinstance(topic, dict) or not topic.get("id"):+ raise ReachError(NOT_FOUND, f"V2EX topic not found: {topic_id}")+ replies = _get_json(_v2ex_url("/api/replies/show.json", topic_id=topic_id, page=1))+ replies = replies if isinstance(replies, list) else []+ lines = [topic.get("content") or ""]+ for r in replies:+ who = (r.get("member") or {}).get("username", "")+ lines.append(f"\n@{who}: {r.get('content', '')}")+ return [_topic_item(topic, text="\n".join(lines).strip(), raw={"topic": topic, "replies": replies})]++ def _api_user(self, *, username: str, timeout: float) -> list:+ data = _get_json(_v2ex_url("/api/members/show.json", username=username))+ if not isinstance(data, dict) or not data.get("id"):+ raise ReachError(NOT_FOUND, f"V2EX user not found: {username}")+ return [+ make_item(+ title=data.get("username"),+ url=data.get("url"),+ author=data.get("username"),+ published_at=unix_to_iso(data.get("created")),+ text=data.get("bio"),+ raw=data,+ )+ ]diff --git a/agent_reach/channels/web.py b/agent_reach/channels/web.pyindex dfbea213..3e2e17d7 100644--- a/agent_reach/channels/web.py+++ b/agent_reach/channels/web.py@@ -1,15 +1,31 @@# -*- coding: utf-8 -*--"""Web — any URL via Jina Reader. Always available."""+"""Web — search (Exa) and read any page (Jina Reader, Exa fallback).+This channel is a fallback: agents that already have working built-in web+search / fetch should use those first.+"""++import json+import reimport urllib.request+from agent_reach.runtime.result import (+ BAD_INPUT,+ RATE_LIMITED,+ UPSTREAM_BROKEN,+ ReachError,+ make_item,+)+from agent_reach.runtime.run import http_requestfrom agent_reach.utils.url import normalize_public_http_url-from .base import Channel+from .base import Action, Channel, Param_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"_MAX_RESPONSE_BYTES = 5 * 1024 * 1024_ANTIBOT_SCAN_BYTES = 4096+_EXA_MCP = "https://mcp.exa.ai/mcp"+_EXA_HEADER_RE = re.compile(r"^(Title|URL|Published|Author):\s*(.*)$")def _is_antibot_page(body: bytes) -> bool:@@ -31,12 +47,111 @@ def _is_antibot_page(body: bytes) -> bool:return (jina_captcha_warning and challenge_structure) or cloudflare_block+def _public_url(target: str) -> str:+ try:+ return normalize_public_http_url(target)+ except ValueError:+ raise ReachError(BAD_INPUT, "target must be a public http(s) URL") from None+++def _exa_call(tool: str, arguments: dict, timeout: float) -> str:+ """Call one tool on Exa's free hosted MCP (no key) and return its text."""+ body = json.dumps(+ {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": tool, "arguments": arguments}}+ ).encode("utf-8")+ raw = http_request(+ _EXA_MCP,+ timeout=timeout,+ data=body,+ headers={"Content-Type": "application/json", "Accept": "application/json, text/event-stream"},+ ).decode("utf-8", errors="replace")+ payloads = [ln[5:].strip() for ln in raw.splitlines() if ln.startswith("data:")] or [raw]+ msg = json.loads(payloads[-1])+ if "error" in msg:+ text = str(msg["error"].get("message", msg["error"]))+ code = RATE_LIMITED if "rate" in text.lower() or "limit" in text.lower() else UPSTREAM_BROKEN+ raise ReachError(code, f"Exa: {text}")+ result = msg.get("result") or {}+ text = "\n".join(c.get("text", "") for c in result.get("content", []) if c.get("type") == "text")+ if result.get("isError"):+ code = RATE_LIMITED if "rate" in text.lower() else UPSTREAM_BROKEN+ raise ReachError(code, f"Exa: {text[:300]}")+ return text+++def _parse_exa_text(text: str) -> list:+ """Split Exa's `Title: / URL: / Published: / Author:` blocks into items."""+ items = []+ for block in re.split(r"\n(?=Title: )", "\n" + text.strip()):+ block = block.strip()+ if not block.startswith("Title:"):+ continue+ fields, body = {}, []+ lines = block.splitlines()+ i = 0+ while i < len(lines):+ m = _EXA_HEADER_RE.match(lines[i])+ if not m:+ break+ fields[m.group(1).lower()] = m.group(2).strip()+ i += 1+ for line in lines[i:]:+ if line.strip() in ("Highlights:", "Text:"):+ continue+ body.append(line)+ na = lambda v: None if v in (None, "", "N/A") else v # noqa: E731+ items.append(+ make_item(+ title=na(fields.get("title")),+ url=na(fields.get("url")),+ author=na(fields.get("author")),+ published_at=na(fields.get("published")),+ text="\n".join(body).strip(),+ raw=fields,+ )+ )+ return items+++def _parse_jina(url: str, body: str) -> dict:+ title = re.search(r"^Title:\s*(.*)$", body, re.M)+ published = re.search(r"^Published Time:\s*(.*)$", body, re.M)+ content = body.split("Markdown Content:", 1)[1] if "Markdown Content:" in body else body+ return make_item(+ title=title.group(1).strip() if title else None,+ url=url,+ published_at=published.group(1).strip() if published else None,+ text=content.strip(),+ )++class WebChannel(Channel):name = "web"- description = "任意网页"+ description = "网页搜索与阅读(Agent 自带工具不可用时的保底)"backends = ["Jina Reader"]tier = 0+ level = "default"+ actions = (+ Action(+ "search",+ "Search the web (Exa semantic search)",+ (+ Param("query", "what to search for"),+ Param("limit", "max results", required=False, type=int, default=5),+ ),+ (("exa", "_exa_search"),),+ live_test={"query": "yt-dlp github repository", "limit": 2},+ ),+ Action(+ "read",+ "Read a web page as clean text",+ (Param("target", "page URL"),),+ (("jina", "_jina_read"), ("exa", "_exa_read")),+ live_test={"target": "https://example.com"},+ ),+ )+def can_handle(self, url: str) -> bool:return True # Fallback — handles any URL@@ -45,7 +160,7 @@ class WebChannel(Channel):self.active_backend = self.backends[0]return "ok", "通过 Jina Reader 读取任意网页(curl https://r.jina.ai/URL)"- def read(self, url: str) -> str:+ def read(self, url: str, timeout: float = 30) -> str:"""通过 Jina Reader 读取网页,返回 Markdown 全文。"""url = normalize_public_http_url(url)jina_url = f"https://r.jina.ai/{url}"@@ -53,7 +168,7 @@ class WebChannel(Channel):jina_url,headers={"User-Agent": _UA, "Accept": "text/plain"},)- with urllib.request.urlopen(req, timeout=30) as resp:+ with urllib.request.urlopen(req, timeout=timeout) as resp:body = resp.read(_MAX_RESPONSE_BYTES + 1)if len(body) > _MAX_RESPONSE_BYTES:raise ValueError(@@ -65,3 +180,28 @@ class WebChannel(Channel):"请改用站点专用工具或浏览器读取")return body.decode("utf-8")++ # ── unified entry backends ──++ def _exa_search(self, *, query: str, limit: int, timeout: float) -> list:+ text = _exa_call("web_search_exa", {"query": query, "objective": query, "numResults": limit}, timeout)+ return _parse_exa_text(text)[:limit]++ def _exa_read(self, *, target: str, timeout: float) -> list:+ url = _public_url(target)+ text = _exa_call("web_fetch_exa", {"urls": [url], "maxCharacters": 20000}, timeout)+ items = _parse_exa_text(text)+ if items:+ items[0]["url"] = items[0]["url"] or url+ return items[:1]+ if not text.strip():+ raise ReachError(UPSTREAM_BROKEN, "Exa returned no content")+ return [make_item(url=url, text=text.strip())]++ def _jina_read(self, *, target: str, timeout: float) -> list:+ url = _public_url(target)+ try:+ body = self.read(url, timeout=timeout)+ except RuntimeError as exc:+ raise ReachError(UPSTREAM_BROKEN, str(exc)) from None+ return [_parse_jina(url, body)]diff --git a/agent_reach/channels/youtube.py b/agent_reach/channels/youtube.pyindex 2d358c29..a546019b 100644--- a/agent_reach/channels/youtube.py+++ b/agent_reach/channels/youtube.py@@ -1,10 +1,24 @@# -*- coding: utf-8 -*-"""YouTube — check if yt-dlp is available with JS runtime."""+import html+import json+import osimport reimport shutil+import sys+import tempfilefrom agent_reach.probe import probe_command+from agent_reach.runtime.result import (+ BAD_INPUT,+ NEED_LOGIN,+ NOT_FOUND,+ RATE_LIMITED,+ ReachError,+ make_item,+)+from agent_reach.runtime.run import CommandFailed, run_cmdfrom agent_reach.utils.paths import (PrivatePathError,get_ytdlp_config_path,@@ -12,7 +26,75 @@ from agent_reach.utils.paths import (render_ytdlp_fix_command,)-from .base import Channel+from .base import Action, Channel, Param++_VIDEO_ID_RE = re.compile(r"^[A-Za-z0-9_-]{11}$")+_VTT_TIME_RE = re.compile(r"^\d{2}:\d{2}(:\d{2})?\.\d{3} --> ")+_TAG_RE = re.compile(r"<[^>]+>")+_RAW_KEYS = ("id", "duration", "view_count", "like_count", "channel_id", "tags", "categories")+++def _ytdlp_argv(*args: str) -> list:+ """Run the yt-dlp bundled with Agent Reach (pinned via our dependencies)."""+ runtime = []+ if shutil.which("deno") is None and shutil.which("node"):+ runtime = ["--js-runtimes", "node"]+ return [sys.executable, "-m", "yt_dlp", "--no-warnings", *runtime, *args]+++def _video_url(target: str) -> str:+ from agent_reach.utils.url import host_matches++ t = str(target).strip()+ if _VIDEO_ID_RE.match(t):+ return f"https://www.youtube.com/watch?v={t}"+ candidate = t if "://" in t else f"https://{t}"+ if host_matches(candidate, "youtube.com", "youtu.be"):+ return candidate+ raise ReachError(BAD_INPUT, "target must be a YouTube link or 11-character video id")+++def _run_ytdlp(args: list, timeout: float, cwd=None) -> str:+ try:+ return run_cmd(_ytdlp_argv(*args), timeout=timeout, cwd=cwd, label="yt-dlp")+ except CommandFailed as exc:+ err = exc.stderr.lower()+ if any(s in err for s in ("video unavailable", "private video", "has been removed", "does not exist")):+ raise ReachError(NOT_FOUND, exc.message) from None+ if "sign in to confirm" in err:+ raise ReachError(+ NEED_LOGIN,+ exc.message,+ hint="YouTube is asking for a bot check. Ask the user whether to configure YouTube cookies; never sign in for them.",+ ) from None+ if "429" in err or "too many requests" in err:+ raise ReachError(RATE_LIMITED, exc.message) from None+ raise+++def _iso_date(yyyymmdd) -> str:+ s = str(yyyymmdd or "")+ return f"{s[:4]}-{s[4:6]}-{s[6:8]}" if len(s) == 8 and s.isdigit() else ""+++def vtt_to_text(vtt: str) -> str:+ """Plain text from WebVTT: drop headers, timings, tags; collapse auto-caption repeats."""+ out = []+ for line in vtt.splitlines():+ s = line.strip()+ if (+ not s+ or s == "WEBVTT"+ or s.startswith(("Kind:", "Language:", "NOTE", "STYLE"))+ or _VTT_TIME_RE.match(s)+ or s.isdigit()+ ):+ continue+ s = html.unescape(_TAG_RE.sub("", s)).strip()+ if s and (not out or out[-1] != s):+ out.append(s)+ return "\n".join(out)+_JS_RUNTIMES_SUPPORTED_FROM = (2025, 11, 12)_YTDLP_UPGRADE_COMMAND = 'python -m pip install -U "yt-dlp[default]"'@@ -42,6 +124,37 @@ class YouTubeChannel(Channel):backends = ["yt-dlp"]tier = 0+ level = "default"+ actions = (+ Action(+ "read",+ "Video title, channel, date and description",+ (Param("target", "video link or id"),),+ (("yt-dlp", "_ytdlp_read"),),+ live_test={"target": "https://www.youtube.com/watch?v=jNQXAC9IVRw"},+ ),+ Action(+ "search",+ "Search videos",+ (+ Param("query", "what to search for"),+ Param("limit", "max results", required=False, type=int, default=5),+ ),+ (("yt-dlp", "_ytdlp_search"),),+ live_test={"query": "python tutorial", "limit": 2},+ ),+ Action(+ "subtitle",+ "Full subtitle text of a video (manual or auto captions)",+ (+ Param("target", "video link or id"),+ Param("lang", "preferred languages, comma separated", required=False, default="zh-Hans,zh,en,en-orig"),+ ),+ (("yt-dlp", "_ytdlp_subtitle"),),+ live_test={"target": "https://www.youtube.com/watch?v=jNQXAC9IVRw"},+ ),+ )+def can_handle(self, url: str) -> bool:from agent_reach.utils.url import host_matches@@ -139,3 +252,69 @@ class YouTubeChannel(Channel):config=config,allow_provider_fallback=allow_provider_fallback,)++ # ── unified entry backends ──++ def _ytdlp_read(self, *, target: str, timeout: float) -> list:+ out = _run_ytdlp(["--dump-json", "--skip-download", _video_url(target)], timeout)+ info = json.loads(out.splitlines()[-1])+ return [+ make_item(+ title=info.get("title"),+ url=info.get("webpage_url"),+ author=info.get("uploader") or info.get("channel"),+ published_at=_iso_date(info.get("upload_date")),+ text=info.get("description"),+ raw={k: info.get(k) for k in _RAW_KEYS},+ )+ ]++ def _ytdlp_search(self, *, query: str, limit: int, timeout: float) -> list:+ out = _run_ytdlp(["--flat-playlist", "--dump-json", f"ytsearch{limit}:{query}"], timeout)+ items = []+ for line in out.splitlines():+ if not line.strip():+ continue+ info = json.loads(line)+ vid = info.get("id")+ items.append(+ make_item(+ title=info.get("title"),+ url=info.get("url") or (f"https://www.youtube.com/watch?v={vid}" if vid else None),+ author=info.get("channel") or info.get("uploader"),+ text=info.get("description"),+ raw={k: info.get(k) for k in _RAW_KEYS},+ )+ )+ return items++ def _ytdlp_subtitle(self, *, target: str, lang: str, timeout: float) -> list:+ url = _video_url(target)+ wanted = [x.strip() for x in lang.split(",") if x.strip()]+ with tempfile.TemporaryDirectory(prefix="agent-reach-subs-") as tmp:+ out = _run_ytdlp(+ [+ "--skip-download", "--no-simulate",+ "--write-subs", "--write-auto-subs",+ "--sub-langs", ",".join(wanted), "--sub-format", "vtt",+ "--print", "%(title)s",+ "-o", "%(id)s.%(ext)s",+ url,+ ],+ timeout,+ cwd=tmp,+ )+ files = [f for f in os.listdir(tmp) if f.endswith(".vtt")]+ if not files:+ raise ReachError(NOT_FOUND, f"no subtitles in {', '.join(wanted)} for this video")++ def rank(name: str) -> int:+ code = name.rsplit(".", 2)[-2] if name.count(".") >= 2 else ""+ return wanted.index(code) if code in wanted else len(wanted)++ best = min(files, key=rank)+ with open(os.path.join(tmp, best), encoding="utf-8", errors="replace") as fh:+ text = vtt_to_text(fh.read())+ title = next((ln for ln in out.splitlines() if ln.strip()), None)+ code = best.rsplit(".", 2)[-2] if best.count(".") >= 2 else None+ return [make_item(title=title, url=url, text=text, raw={"lang": code})]diff --git a/agent_reach/cli.py b/agent_reach/cli.pyindex 358b2182..81f91d07 100644--- a/agent_reach/cli.py+++ b/agent_reach/cli.py@@ -68,6 +68,14 @@ def _configure_logging(verbose: bool = False):def main():_ensure_utf8_console()+ # Unified entry (`<channel> <action>`, `read`, `channels`, `check`) prints+ # JSON only and runs before the legacy argparse tree.+ from agent_reach.runtime import cli as unified++ if unified.handles(sys.argv[1:]):+ _configure_logging(False)+ sys.exit(unified.main(sys.argv[1:]))+parser = argparse.ArgumentParser(prog="agent-reach",description="Give your AI Agent eyes to see the entire internet",diff --git a/agent_reach/runtime/__init__.py b/agent_reach/runtime/__init__.pynew file mode 100644index 00000000..3747e3dc--- /dev/null+++ b/agent_reach/runtime/__init__.py@@ -0,0 +1 @@+"""Unified entry runtime: result envelope, upstream calls, backend dispatch."""diff --git a/agent_reach/runtime/cli.py b/agent_reach/runtime/cli.pynew file mode 100644index 00000000..13a7d72d--- /dev/null+++ b/agent_reach/runtime/cli.py@@ -0,0 +1,222 @@+"""Unified entry: `agent-reach <channel> <action>`, `read <url>`, `channels`, `check`.++Everything here prints JSON to stdout (one object per invocation) so agents+never parse prose. Logs and warnings go to stderr. Exit code 0 = ok, 1 = error.+"""++from __future__ import annotations++import argparse+import json+import sys+from typing import Dict, List, Optional, Sequence++from agent_reach.channels import get_all_channels+from agent_reach.channels.base import Action, Channel++from .dispatch import DEFAULT_TIMEOUT, find_action, run_action+from .result import BAD_INPUT, SCHEMA_VERSION, ReachError, envelope++_TOP_LEVEL = ("channels", "check", "read")+++def unified_channels() -> List[Channel]:+ """Channels already moved to the unified entry."""+ return [ch for ch in get_all_channels() if ch.level]+++def _channel(name: str) -> Optional[Channel]:+ return next((ch for ch in unified_channels() if ch.name == name), None)+++def handles(argv: Sequence[str]) -> bool:+ """Whether this argv belongs to the unified entry (vs. legacy commands)."""+ if not argv:+ return False+ head = argv[0]+ return head in _TOP_LEVEL or _channel(head) is not None+++class _ArgError(Exception):+ pass+++class _Parser(argparse.ArgumentParser):+ """argparse that raises instead of printing usage and exiting."""++ def error(self, message: str): # type: ignore[override]+ raise _ArgError(message)+++def _emit(payload: dict) -> int:+ sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")+ sys.stdout.flush()+ return 0 if payload.get("ok") else 1+++def _usage(channel: Channel, action: Action) -> str:+ parts = ["agent-reach", channel.name, action.name]+ for p in action.params:+ parts.append(f"<{p.name}>" if p.required else f"[--{p.name} {p.name.upper()}]")+ return " ".join(parts)+++def _bad_input(channel: Optional[str], action: Optional[str], message: str) -> int:+ return _emit(envelope(channel=channel, action=action, error=ReachError(BAD_INPUT, message)))+++def _parse_action_args(action: Action, args: Sequence[str]) -> Dict[str, object]:+ parser = _Parser(prog=action.name, add_help=False)+ for p in action.params:+ if p.required:+ # Join extra words so an unquoted multi-word query still works.+ parser.add_argument(p.name, nargs="+" if p.type is str else None)+ else:+ parser.add_argument(f"--{p.name}", dest=p.name, default=None)+ parser.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT)+ ns = vars(parser.parse_args(list(args)))+ for p in action.params:+ if p.required and p.type is str and isinstance(ns.get(p.name), list):+ ns[p.name] = " ".join(ns[p.name])+ return ns+++def _cmd_action(channel: Channel, args: Sequence[str]) -> int:+ if not args or args[0].startswith("-"):+ valid = ", ".join(a.name for a in channel.actions)+ return _bad_input(channel.name, None, f"missing action for {channel.name}; valid: {valid}")+ action = find_action(channel, args[0])+ if action is None:+ # Let run_action produce the standard unknown-action envelope.+ return _emit(run_action(channel, args[0], {}))+ try:+ ns = _parse_action_args(action, args[1:])+ except _ArgError as exc:+ return _bad_input(channel.name, action.name, f"{exc}; usage: {_usage(channel, action)}")+ timeout = ns.pop("timeout")+ return _emit(run_action(channel, action.name, ns, timeout=timeout))+++def _cmd_read(args: Sequence[str]) -> int:+ parser = _Parser(prog="read", add_help=False)+ parser.add_argument("url")+ parser.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT)+ try:+ ns = parser.parse_args(list(args))+ except _ArgError as exc:+ return _bad_input(None, "read", f"{exc}; usage: agent-reach read <url>")+ readers = [ch for ch in unified_channels() if find_action(ch, "read")]+ specific = [ch for ch in readers if ch.name != "web"]+ target = next((ch for ch in specific if ch.can_handle(ns.url)), None)+ target = target or next((ch for ch in readers if ch.name == "web"), None)+ if target is None:+ return _bad_input(None, "read", "no channel can read this URL")+ return _emit(run_action(target, "read", {"target": ns.url}, timeout=ns.timeout))+++def _cmd_channels(_args: Sequence[str]) -> int:+ channels = []+ for ch in unified_channels():+ channels.append(+ {+ "name": ch.name,+ "description": ch.description,+ "level": ch.level,+ "actions": [+ {+ "name": a.name,+ "help": a.help,+ "usage": _usage(ch, a),+ "params": [+ {+ "name": p.name,+ "help": p.help,+ "required": p.required,+ "type": p.type.__name__,+ "default": p.default,+ }+ for p in a.params+ ],+ "backends": [label for label, _ in a.backends],+ }+ for a in ch.actions+ ],+ }+ )+ return _emit(+ {+ "schema_version": SCHEMA_VERSION,+ "ok": True,+ "commands": {+ "read": "agent-reach read <url> (picks the channel from the URL)",+ "action": "agent-reach <channel> <action> [args] [--timeout SECONDS]",+ },+ "channels": channels,+ }+ )+++def _cmd_check(args: Sequence[str]) -> int:+ parser = _Parser(prog="check", add_help=False)+ parser.add_argument("channels", nargs="*")+ parser.add_argument("--text", action="store_true")+ parser.add_argument("--timeout", type=float, default=60.0)+ try:+ ns = parser.parse_args(list(args))+ except _ArgError as exc:+ return _bad_input(None, "check", str(exc))+ selected = unified_channels()+ if ns.channels:+ unknown = set(ns.channels) - {ch.name for ch in selected}+ if unknown:+ return _bad_input(None, "check", f"unknown channel(s): {', '.join(sorted(unknown))}")+ selected = [ch for ch in selected if ch.name in ns.channels]++ results = []+ for ch in selected:+ for action in ch.actions:+ if action.live_test is None:+ continue+ for label, _ in action.backends:+ out = run_action(ch, action.name, dict(action.live_test), timeout=ns.timeout, only_backend=label)+ passed = bool(out["ok"] and out["items"])+ err = out["error"] or ({"code": "EMPTY", "message": "succeeded but returned no items"} if not passed else None)+ results.append(+ {+ "channel": ch.name,+ "action": action.name,+ "backend": label,+ "passed": passed,+ "elapsed_ms": out["meta"]["elapsed_ms"],+ "error": err and {"code": err["code"], "message": err["message"]},+ }+ )++ # An action passes when at least one of its backends works.+ by_action: Dict[tuple, bool] = {}+ for r in results:+ key = (r["channel"], r["action"])+ by_action[key] = by_action.get(key, False) or r["passed"]+ ok = bool(results) and all(by_action.values())++ if ns.text:+ for r in results:+ mark = "PASS" if r["passed"] else "FAIL"+ why = "" if r["passed"] else f" {r['error']['code']}: {r['error']['message']}"+ sys.stdout.write(f"{mark} {r['channel']} {r['action']} [{r['backend']}] {r['elapsed_ms']}ms{why}\n")+ sys.stdout.write(f"\n{sum(by_action.values())}/{len(by_action)} actions working\n")+ return 0 if ok else 1+ return _emit({"schema_version": SCHEMA_VERSION, "ok": ok, "results": results})+++def main(argv: Sequence[str]) -> int:+ head, rest = argv[0], argv[1:]+ if head == "channels":+ return _cmd_channels(rest)+ if head == "check":+ return _cmd_check(rest)+ if head == "read":+ return _cmd_read(rest)+ channel = _channel(head)+ assert channel is not None # guaranteed by handles()+ return _cmd_action(channel, rest)diff --git a/agent_reach/runtime/dispatch.py b/agent_reach/runtime/dispatch.pynew file mode 100644index 00000000..1902d9d6--- /dev/null+++ b/agent_reach/runtime/dispatch.py@@ -0,0 +1,141 @@+"""Run a unified action: validate params, try backends in order, build the envelope."""++from __future__ import annotations++import threading+import time+from typing import Any, Dict, List, Optional++from agent_reach.channels.base import Action, Channel++from .result import (+ BAD_INPUT,+ FINAL_CODES,+ NEED_SETUP,+ TIMEOUT,+ ReachError,+ classify,+ envelope,+)++DEFAULT_TIMEOUT = 30.0+++def find_action(channel: Channel, name: str) -> Optional[Action]:+ return next((a for a in channel.actions if a.name == name), None)+++def _validate(action: Action, params: Dict[str, Any]) -> Dict[str, Any]:+ clean: Dict[str, Any] = {}+ for p in action.params:+ value = params.get(p.name)+ if value is None or value == "":+ if p.required:+ raise ReachError(BAD_INPUT, f"missing required argument: {p.name}")+ value = p.default+ elif p.type is not str:+ try:+ value = p.type(value)+ except (TypeError, ValueError):+ raise ReachError(BAD_INPUT, f"{p.name} must be {p.type.__name__}") from None+ clean[p.name] = value+ unknown = set(params) - {p.name for p in action.params}+ if unknown:+ raise ReachError(BAD_INPUT, f"unknown argument(s): {', '.join(sorted(unknown))}")+ return clean+++def _call_with_deadline(fn, params: Dict[str, Any], timeout: float) -> List[dict]:+ """Run fn(timeout=..., **params); give up after `timeout` seconds.++ In-process HTTP calls cannot be interrupted, so the call runs in a daemon+ thread. Subprocess backends also receive `timeout` and kill themselves.+ """+ box: Dict[str, Any] = {}++ def target() -> None:+ try:+ box["items"] = fn(timeout=timeout, **params)+ except BaseException as exc: # noqa: BLE001 - forwarded to classify()+ box["error"] = exc++ worker = threading.Thread(target=target, daemon=True)+ worker.start()+ worker.join(timeout + 1.0)+ if worker.is_alive():+ raise ReachError(TIMEOUT, f"backend did not answer within {timeout:.0f}s")+ if "error" in box:+ raise box["error"]+ return list(box.get("items") or [])+++def _pick_error(errors: List[ReachError]) -> ReachError:+ """Report the most useful failure: a real error beats 'not installed'."""+ for err in errors:+ if err.code != NEED_SETUP:+ return err+ return errors[0]+++def run_action(+ channel: Channel,+ action_name: str,+ params: Dict[str, Any],+ *,+ timeout: float = DEFAULT_TIMEOUT,+ only_backend: Optional[str] = None,+) -> dict:+ """Execute one unified action and return the envelope dict."""+ started = time.monotonic()++ def elapsed() -> int:+ return int((time.monotonic() - started) * 1000)++ action = find_action(channel, action_name)+ if action is None:+ valid = ", ".join(a.name for a in channel.actions) or "none"+ err = ReachError(BAD_INPUT, f"unknown action '{action_name}' for {channel.name}; valid: {valid}")+ return envelope(channel=channel.name, action=action_name, elapsed_ms=elapsed(), error=err)+ try:+ clean = _validate(action, params)+ except ReachError as err:+ return envelope(channel=channel.name, action=action_name, elapsed_ms=elapsed(), error=err)++ backends = [b for b in action.backends if only_backend in (None, b[0])]+ deadline = started + timeout+ attempts: List[dict] = []+ errors: List[ReachError] = []+ for label, method_name in backends:+ remaining = deadline - time.monotonic()+ if remaining <= 0:+ attempts.append({"backend": label, "result": TIMEOUT})+ errors.append(ReachError(TIMEOUT, "no time left for this backend"))+ continue+ try:+ items = _call_with_deadline(getattr(channel, method_name), clean, remaining)+ except BaseException as exc: # noqa: BLE001+ err = classify(exc)+ attempts.append({"backend": label, "result": err.code, "message": err.message})+ errors.append(err)+ if err.code in FINAL_CODES:+ break+ continue+ attempts.append({"backend": label, "result": "ok"})+ return envelope(+ channel=channel.name,+ action=action_name,+ backend=label,+ items=items,+ elapsed_ms=elapsed(),+ attempts=attempts,+ )++ final = errors and next((e for e in errors if e.code in FINAL_CODES), None)+ err = final or (_pick_error(errors) if errors else ReachError(BAD_INPUT, f"no backend named '{only_backend}'"))+ return envelope(+ channel=channel.name,+ action=action_name,+ elapsed_ms=elapsed(),+ attempts=attempts,+ error=err,+ )diff --git a/agent_reach/runtime/result.py b/agent_reach/runtime/result.pynew file mode 100644index 00000000..874f1571--- /dev/null+++ b/agent_reach/runtime/result.py@@ -0,0 +1,139 @@+"""Unified result envelope and error codes for the agent-facing entry point.++Every unified command prints exactly one JSON object with this shape:++ {schema_version, ok, channel, action, backend, items, meta, error}++`schema_version` only changes on incompatible shape changes. Agents branch+on `ok` and `error.code`; they should never need to parse upstream output.+"""++from __future__ import annotations++import datetime as _dt+import socket+import subprocess+import urllib.error+from typing import Any, Optional++from agent_reach.utils.text import scrub_url_credentials++SCHEMA_VERSION = 1++NEED_SETUP = "NEED_SETUP"+NEED_LOGIN = "NEED_LOGIN"+UPSTREAM_BROKEN = "UPSTREAM_BROKEN"+TIMEOUT = "TIMEOUT"+RATE_LIMITED = "RATE_LIMITED"+NOT_FOUND = "NOT_FOUND"+BAD_INPUT = "BAD_INPUT"++#: Codes where trying another backend cannot help.+FINAL_CODES = frozenset({NOT_FOUND, BAD_INPUT})++DEFAULT_HINTS = {+ NEED_SETUP: "This backend is not installed. Ask the user to run `agent-reach doctor` for setup steps.",+ NEED_LOGIN: "Login is required or expired. Guide the user to log in themselves; never log in on their behalf.",+ UPSTREAM_BROKEN: "The upstream tool failed. Tell the user this channel is unavailable right now; do not retry in a loop.",+ TIMEOUT: "No backend answered in time. Retry later, or pass a larger --timeout.",+ RATE_LIMITED: "Rate limited by the platform. Wait a while before retrying.",+ NOT_FOUND: "The requested content does not exist. Check the link or id.",+ BAD_INPUT: "Invalid arguments. Run `agent-reach channels` to see valid usage.",+}++_MAX_MESSAGE_CHARS = 500+++class ReachError(Exception):+ """An upstream failure already mapped to a unified error code."""++ def __init__(self, code: str, message: str, hint: Optional[str] = None):+ super().__init__(message)+ self.code = code+ self.message = message+ self.hint = hint+++def _clean(text: object) -> str:+ return scrub_url_credentials(str(text)).strip()[:_MAX_MESSAGE_CHARS]+++def classify(exc: BaseException) -> ReachError:+ """Map any exception raised by a backend to a ReachError."""+ if isinstance(exc, ReachError):+ return exc+ if isinstance(exc, urllib.error.HTTPError):+ if exc.code == 404:+ return ReachError(NOT_FOUND, f"HTTP 404: {_clean(exc.reason)}")+ if exc.code == 429:+ return ReachError(RATE_LIMITED, "HTTP 429")+ return ReachError(UPSTREAM_BROKEN, f"HTTP {exc.code}: {_clean(exc.reason)}")+ if isinstance(exc, (subprocess.TimeoutExpired, socket.timeout, TimeoutError)):+ return ReachError(TIMEOUT, "upstream did not answer in time")+ if isinstance(exc, urllib.error.URLError):+ if isinstance(exc.reason, (socket.timeout, TimeoutError)):+ return ReachError(TIMEOUT, "upstream did not answer in time")+ return ReachError(UPSTREAM_BROKEN, f"network error: {_clean(exc.reason)}")+ if isinstance(exc, FileNotFoundError):+ return ReachError(NEED_SETUP, f"missing executable: {_clean(exc.filename or exc)}")+ return ReachError(UPSTREAM_BROKEN, f"{type(exc).__name__}: {_clean(exc)}")+++def make_item(+ *,+ title: Optional[str] = None,+ url: Optional[str] = None,+ author: Optional[str] = None,+ published_at: Optional[str] = None,+ text: Optional[str] = None,+ raw: Any = None,+) -> dict:+ """One normalized item. Missing fields are null; `raw` keeps upstream data."""+ return {+ "title": title or None,+ "url": url or None,+ "author": author or None,+ "published_at": published_at or None,+ "text": text or None,+ "raw": raw,+ }+++def unix_to_iso(value: Any) -> Optional[str]:+ """Convert a unix timestamp to ISO 8601 UTC, or None."""+ try:+ seconds = int(value)+ except (TypeError, ValueError):+ return None+ if seconds <= 0:+ return None+ return _dt.datetime.fromtimestamp(seconds, _dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")+++def envelope(+ *,+ channel: Optional[str],+ action: Optional[str],+ backend: Optional[str] = None,+ items: Optional[list] = None,+ elapsed_ms: int = 0,+ attempts: Optional[list] = None,+ error: Optional[ReachError] = None,+) -> dict:+ """Build the unified output object."""+ return {+ "schema_version": SCHEMA_VERSION,+ "ok": error is None,+ "channel": channel,+ "action": action,+ "backend": backend if error is None else None,+ "items": list(items or []) if error is None else [],+ "meta": {"elapsed_ms": elapsed_ms, "attempts": list(attempts or [])},+ "error": None+ if error is None+ else {+ "code": error.code,+ "message": error.message,+ "hint": error.hint or DEFAULT_HINTS.get(error.code, ""),+ },+ }diff --git a/agent_reach/runtime/run.py b/agent_reach/runtime/run.pynew file mode 100644index 00000000..91e5457f--- /dev/null+++ b/agent_reach/runtime/run.py@@ -0,0 +1,100 @@+"""Bounded calls to upstream tools: subprocesses and HTTP."""++from __future__ import annotations++import os+import shutil+import signal+import subprocess+import urllib.request+from pathlib import Path+from typing import Mapping, Optional, Sequence++from agent_reach.utils.process import utf8_subprocess_env++from .result import NEED_SETUP, TIMEOUT, ReachError, _clean++_DEFAULT_MAX_BYTES = 8 * 1024 * 1024+++class CommandFailed(ReachError):+ """Upstream exited non-zero. Channels may re-map it using `stderr`."""++ def __init__(self, code: str, message: str, stderr: str = "", stdout: str = ""):+ super().__init__(code, message)+ self.stderr = stderr+ self.stdout = stdout+++def run_cmd(+ argv: Sequence[str],+ *,+ timeout: float,+ env: Optional[Mapping[str, str]] = None,+ cwd: Optional[str] = None,+ label: Optional[str] = None,+) -> str:+ """Run an upstream command and return stdout.++ Runs from the user's home by default so tools never pick up config from+ whatever project the agent happens to be in. On timeout the whole process+ group is killed.+ """+ name = label or Path(argv[0]).name+ exe = shutil.which(argv[0])+ if not exe:+ raise ReachError(NEED_SETUP, f"{name} is not installed")+ run_env = utf8_subprocess_env()+ if env:+ run_env.update(env)+ proc = subprocess.Popen(+ [exe, *argv[1:]],+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ stdin=subprocess.DEVNULL,+ env=run_env,+ cwd=cwd or os.path.expanduser("~"),+ start_new_session=(os.name != "nt"),+ )+ try:+ out, err = proc.communicate(timeout=max(timeout, 0.1))+ except subprocess.TimeoutExpired:+ if os.name != "nt":+ try:+ os.killpg(proc.pid, signal.SIGKILL)+ except ProcessLookupError:+ pass+ else:+ proc.kill()+ proc.communicate()+ raise ReachError(TIMEOUT, f"{name} did not finish within {timeout:.0f}s")+ stdout = out.decode("utf-8", errors="replace")+ stderr = err.decode("utf-8", errors="replace")+ if proc.returncode != 0:+ last = next((ln for ln in reversed(stderr.splitlines()) if ln.strip()), "")+ raise CommandFailed(+ "UPSTREAM_BROKEN",+ f"{name} exited {proc.returncode}: {_clean(last) or 'no error output'}",+ stderr=stderr,+ stdout=stdout,+ )+ return stdout+++def http_request(+ url: str,+ *,+ timeout: float,+ data: Optional[bytes] = None,+ headers: Optional[Mapping[str, str]] = None,+ max_bytes: int = _DEFAULT_MAX_BYTES,+) -> bytes:+ """GET (or POST when `data` is given) with a size cap. Errors propagate to classify()."""+ merged = {"User-Agent": "agent-reach"}+ merged.update(headers or {})+ req = urllib.request.Request(url, data=data, headers=merged)+ with urllib.request.urlopen(req, timeout=max(timeout, 0.1)) as resp:+ body = resp.read(max_bytes + 1)+ if len(body) > max_bytes:+ raise ReachError("UPSTREAM_BROKEN", f"response exceeds {max_bytes} bytes")+ return bodydiff --git a/tests/test_unified_entry.py b/tests/test_unified_entry.pynew file mode 100644index 00000000..ac462992--- /dev/null+++ b/tests/test_unified_entry.py@@ -0,0 +1,265 @@+# -*- coding: utf-8 -*-+"""Unified entry: backend fallback, error selection, JSON contract, routing, parsers."""++import json+import time+import urllib.error++import pytest++from agent_reach.channels.base import Action, Channel, Param+from agent_reach.channels.github import _parse_target+from agent_reach.channels.v2ex import _parse_topic_id+from agent_reach.channels.web import _parse_exa_text+from agent_reach.channels.youtube import vtt_to_text+from agent_reach.runtime import cli as unified+from agent_reach.runtime.dispatch import run_action+from agent_reach.runtime.result import ReachError, classify++ENVELOPE_KEYS = {"schema_version", "ok", "channel", "action", "backend", "items", "meta", "error"}+++class FakeChannel(Channel):+ name = "fake"+ description = "fake"+ level = "default"+ actions = (+ Action(+ "search",+ "search",+ (Param("query", "q"), Param("limit", "n", required=False, type=int, default=3)),+ (("first", "_first"), ("second", "_second")),+ live_test={"query": "x"},+ ),+ Action("read", "read", (Param("target", "t"),), (("first", "_first_read"),)),+ )++ def __init__(self, first=None, second=None):+ self.first = first or (lambda **kw: [{"title": "first"}])+ self.second = second or (lambda **kw: [{"title": "second"}])+ self.calls = []++ def can_handle(self, url):+ return "fake.test" in url++ def _first(self, **kw):+ self.calls.append(("first", kw))+ return self.first(**kw)++ def _second(self, **kw):+ self.calls.append(("second", kw))+ return self.second(**kw)++ def _first_read(self, **kw):+ return [{"title": kw["target"]}]+++def _raise(code):+ def fn(**kw):+ raise ReachError(code, code.lower())+ return fn+++# ── dispatcher ──+++def test_falls_back_to_next_backend_on_retryable_error():+ ch = FakeChannel(first=_raise("TIMEOUT"))+ out = run_action(ch, "search", {"query": "q"})+ assert out["ok"] is True+ assert out["backend"] == "second"+ assert [a["result"] for a in out["meta"]["attempts"]] == ["TIMEOUT", "ok"]+++def test_not_found_stops_without_trying_other_backends():+ ch = FakeChannel(first=_raise("NOT_FOUND"))+ out = run_action(ch, "search", {"query": "q"})+ assert out["ok"] is False+ assert out["error"]["code"] == "NOT_FOUND"+ assert [name for name, _ in ch.calls] == ["first"]+++def test_real_failure_is_reported_over_not_installed():+ ch = FakeChannel(first=_raise("NEED_SETUP"), second=_raise("UPSTREAM_BROKEN"))+ out = run_action(ch, "search", {"query": "q"})+ assert out["error"]["code"] == "UPSTREAM_BROKEN"+++def test_all_backends_missing_reports_need_setup():+ ch = FakeChannel(first=_raise("NEED_SETUP"), second=_raise("NEED_SETUP"))+ assert run_action(ch, "search", {"query": "q"})["error"]["code"] == "NEED_SETUP"+++def test_params_are_validated_and_defaulted_before_any_backend_runs():+ ch = FakeChannel()+ assert run_action(ch, "search", {})["error"]["code"] == "BAD_INPUT"+ assert run_action(ch, "search", {"query": "q", "limit": "many"})["error"]["code"] == "BAD_INPUT"+ assert ch.calls == []+ run_action(ch, "search", {"query": "q"})+ assert ch.calls[0][1]["limit"] == 3+++def test_unknown_action_lists_valid_actions():+ out = run_action(FakeChannel(), "nope", {})+ assert out["error"]["code"] == "BAD_INPUT"+ assert "search" in out["error"]["message"] and "read" in out["error"]["message"]+++def test_hung_backend_is_abandoned_at_the_deadline():+ ch = FakeChannel(first=lambda **kw: time.sleep(5) or [], second=lambda **kw: [{"title": "x"}])+ started = time.monotonic()+ out = run_action(ch, "search", {"query": "q"}, timeout=0.3)+ assert time.monotonic() - started < 3+ assert out["ok"] is False+ assert out["error"]["code"] == "TIMEOUT"+++def test_unexpected_exception_becomes_upstream_broken():+ ch = FakeChannel(first=lambda **kw: 1 / 0, second=_raise("NEED_SETUP"))+ out = run_action(ch, "search", {"query": "q"})+ assert out["error"]["code"] == "UPSTREAM_BROKEN"+ assert "ZeroDivisionError" in out["error"]["message"]+++ "exc, code",+ [+ (urllib.error.HTTPError("u", 404, "nf", {}, None), "NOT_FOUND"),+ (urllib.error.HTTPError("u", 429, "rl", {}, None), "RATE_LIMITED"),+ (urllib.error.HTTPError("u", 500, "x", {}, None), "UPSTREAM_BROKEN"),+ (urllib.error.URLError(TimeoutError()), "TIMEOUT"),+ (FileNotFoundError("gh"), "NEED_SETUP"),+ ],+)+def test_classify_maps_upstream_failures(exc, code):+ assert classify(exc).code == code+++def test_error_messages_do_not_leak_url_credentials():+ err = classify(RuntimeError("failed https://user:[email protected]/x?token=abc123"))+ assert "secret" not in err.message and "abc123" not in err.message+++# ── CLI contract ──+++def fake_cli(monkeypatch):+ ch = FakeChannel()+ monkeypatch.setattr(unified, "get_all_channels", lambda: [ch])+ return ch+++def _run(capsys, argv):+ code = unified.main(argv)+ lines = capsys.readouterr().out.strip().splitlines()+ assert len(lines) == 1, "unified commands print exactly one JSON line"+ return code, json.loads(lines[0])+++def test_action_prints_one_envelope_and_exits_zero(capsys, fake_cli):+ code, out = _run(capsys, ["fake", "search", "two", "words", "--limit", "2"])+ assert code == 0+ assert set(out) == ENVELOPE_KEYS+ assert out["schema_version"] == 1+ assert fake_cli.calls[0][1]["query"] == "two words"+ assert fake_cli.calls[0][1]["limit"] == 2+++def test_failures_still_print_an_envelope_and_exit_one(capsys, fake_cli):+ code, out = _run(capsys, ["fake", "search"])+ assert code == 1+ assert set(out) == ENVELOPE_KEYS+ assert out["error"]["code"] == "BAD_INPUT"+ assert "usage: agent-reach fake search <query>" in out["error"]["message"]+++def test_read_routes_by_url(capsys, fake_cli):+ code, out = _run(capsys, ["read", "https://fake.test/a"])+ assert code == 0+ assert out["channel"] == "fake"+ assert out["items"][0]["title"] == "https://fake.test/a"+++def test_handles_only_claims_unified_commands(fake_cli):+ assert unified.handles(["fake", "search"])+ assert unified.handles(["channels"])+ assert not unified.handles(["doctor"])+ assert not unified.handles(["check-update"])+ assert not unified.handles([])+++def test_channels_lists_usage_for_agents(capsys, fake_cli):+ code, out = _run(capsys, ["channels"])+ assert code == 0+ action = out["channels"][0]["actions"][0]+ assert action["usage"] == "agent-reach fake search <query> [--limit LIMIT]"+ assert action["backends"] == ["first", "second"]+++def test_check_passes_when_any_backend_works(capsys, fake_cli):+ fake_cli.first = _raise("TIMEOUT")+ code, out = _run(capsys, ["check"])+ assert code == 0+ assert [(r["backend"], r["passed"]) for r in out["results"]] == [("first", False), ("second", True)]+++def test_check_fails_when_backend_returns_nothing(capsys, fake_cli):+ fake_cli.first = lambda **kw: []+ fake_cli.second = lambda **kw: []+ code, out = _run(capsys, ["check"])+ assert code == 1+ assert out["results"][0]["error"]["code"] == "EMPTY"+++# ── parsers ──+++def test_parse_exa_text_splits_results():+ text = (+ "Title: A\nURL: https://a.test\nPublished: N/A\nAuthor: Ann\nHighlights:\nbody a\n\n"+ "Title: B\nURL: https://b.test\nPublished: 2026-01-02\nAuthor: N/A\nbody b"+ )+ items = _parse_exa_text(text)+ assert [(i["title"], i["url"], i["author"], i["published_at"]) for i in items] == [+ ("A", "https://a.test", "Ann", None),+ ("B", "https://b.test", None, "2026-01-02"),+ ]+ assert items[0]["text"] == "body a"+++def test_vtt_to_text_drops_timings_tags_and_rolling_repeats():+ vtt = (+ "WEBVTT\nKind: captions\nLanguage: en\n\n"+ "00:00:01.000 --> 00:00:02.000\n<c>hello</c> world\n\n"+ "00:00:02.000 --> 00:00:03.000\nhello world\n\n"+ "2\n00:00:03.000 --> 00:00:04.000\nnext & last\n"+ )+ assert vtt_to_text(vtt) == "hello world\nnext & last"+++ "target, expected",+ [+ ("yt-dlp/yt-dlp", ("yt-dlp", "yt-dlp", None)),+ ("https://github.com/cli/cli.git", ("cli", "cli", None)),+ ("https://github.com/cli/cli/issues/42", ("cli", "cli", 42)),+ ("https://github.com/cli/cli/pull/7?x=1", ("cli", "cli", 7)),+ ],+)+def test_github_target_forms(target, expected):+ assert _parse_target(target) == expected++[email protected]("bad", ["not a target", "https://gitlab.com/a/b/c/d", "a/b/c"])+def test_github_rejects_other_targets(bad):+ with pytest.raises(ReachError) as info:+ _parse_target(bad)+ assert info.value.code == "BAD_INPUT"+++def test_v2ex_topic_id_forms():+ assert _parse_topic_id("1000") == 1000+ assert _parse_topic_id("https://www.v2ex.com/t/1000#reply3") == 1000+ with pytest.raises(ReachError):+ _parse_topic_id("https://example.com/t/1000")