Skip to content

Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.

feat: unified entry with JSON envelope; move default channels

Pnant8e23bf2da4ab
diff --git a/agent_reach/channels/base.py b/agent_reach/channels/base.py
index 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]] = None
class Channel(ABC):
@@ -34,6 +63,13 @@ class Channel(ABC):
backends: List[str] = [] # ordered candidates — backends[0] = preferred
tier: 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] = None
diff --git a/agent_reach/channels/github.py b/agent_reach/channels/github.py
index 8441fa2c..2282b9c9 100644
--- a/agent_reach/channels/github.py
+++ b/agent_reach/channels/github.py
@@ -3,18 +3,38 @@
from __future__ import annotations
+import json
import os
+import re
+import urllib.error
from pathlib import Path
+from urllib.parse import urlencode
import yaml
from 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_cmd
from 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.py
index 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 re
import shutil
import ssl
import subprocess
@@ -9,10 +10,11 @@ import urllib.request
from typing import Any
from urllib.parse import quote, urlencode, urlsplit
+from agent_reach.runtime.result import BAD_INPUT, NOT_FOUND, ReachError, make_item, unix_to_iso
from agent_reach.utils.process import utf8_subprocess_env
from 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.py
index 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 re
import urllib.request
+from agent_reach.runtime.result import (
+ BAD_INPUT,
+ RATE_LIMITED,
+ UPSTREAM_BROKEN,
+ ReachError,
+ make_item,
+)
+from agent_reach.runtime.run import http_request
from 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.py
index 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 os
import re
import shutil
+import sys
+import tempfile
from 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_cmd
from 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.py
index 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 body
diff --git a/tests/test_unified_entry.py b/tests/test_unified_entry.py
new file mode 100644
index 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 &amp; 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")