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: local management: add installs prerequisites and the browser extension, remove cleans logins, removable defaults, unpinned tools with floor/exclude, update notice

Pnantd9dbb683390a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 420f79d5..ae97907e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,20 @@ All notable changes to this project will be documented in this file.
## [1.6.0] - unreleased
+中文:
+
+- 加一个平台只要一句话,需要的软件(Node.js、Chrome、ffmpeg、浏览器扩展)都会自动装好,不需要管理员密码;你只需要登录或者填一个 Key。
+- 默认平台也能去掉,去掉后更新不会再加回来;去掉时会一起清掉它的登录和专用工具。
+- 更新会把各平台用到的工具升到最新版;有新版本时,AI 会用大白话告诉你改了什么,你同意了才更新。
+- 登录不再读你自己浏览器的 Cookie,而是在 Agent Reach 专用浏览器里由你本人登录。
+
+English:
+
+- Adding a platform takes one sentence. Whatever it needs (Node.js, Chrome, ffmpeg, the browser extension) is installed for you, with no admin password; you only log in or enter a key.
+- Default platforms can be removed, and updates won't add them back; removing one also clears its login and private tools.
+- Updating also moves each platform's tools to their latest versions. When a new version is out, your AI tells you in plain words what changed and updates only if you say yes.
+- Logins no longer read your own browser's cookies; you log in yourself in the dedicated Agent Reach browser.
+
1.6 is a rebuild. Agents call one command, `agent-reach`; everything Agent Reach installs or stores lives under `~/.agent-reach/`.
1.6 是重构版本:Agent 只调一个命令 `agent-reach`,Agent Reach 装的、存的东西全部在 `~/.agent-reach/` 下。
@@ -17,10 +31,15 @@ All notable changes to this project will be documented in this file.
- **Management / 管理命令**: `setup`, `add` / `remove <channel>`, `login` / `logout <channel>`, `doctor`, `check`, `skill`, `skill link <dir>`, `update`, `configure`, `uninstall`.
- **One-step setup / 一步装好**: `setup` adds every default channel through the same path as `add` (bili-cli goes into `~/.agent-reach/tools/`) and reports what works, which AIs can read the skill, optional channels and optional logins. / `setup` 用和 `add` 同一套逻辑开启全部默认渠道,并汇报哪些能用、哪些 AI 能读到 skill、可选渠道和可选登录。
- **Skill placement / skill 放置**: one real copy at `~/.agents/skills/agent-reach/SKILL.md` (read directly by Codex, OpenCode, Cline, Warp, Zed); a link to it in the skill folder of Claude Code, OpenClaw, Hermes, Cursor, Gemini CLI, GitHub Copilot and Windsurf when installed (a copy where links are not allowed, e.g. Windows). `agent-reach skill link <dir>` covers any other AI. / 只放一份真文件,其他 AI 的 skill 目录里放指向它的链接(链接:一个指向原文件的快捷方式)。
-- **Private, pinned upstream installs / 上游私有安装**: tools go into `~/.agent-reach/tools/` at versions we tested; the user's own copies are untouched. Single-instance tools (OpenCLI) reuse the user's copy and are upgraded only with `--allow-upgrade`.
-- **Login state under `~/.agent-reach/` / 登录状态统一管理**: CLI tool logins in `sessions/`, browser logins in a dedicated Agent Reach browser (`agent-reach browser setup` once). The browser opens by itself when a channel needs it and closes after 10 minutes without use. Agent Reach never logs in for the user and never reads the user's own browser cookies. / 专用浏览器按需自动打开,10 分钟不用自动关闭。
+- **Private upstream installs, latest allowed version / 上游私有安装,用最新可用版本**: tools go into `~/.agent-reach/tools/`; the user's own copies are untouched. Versions are not pinned: each tool installs its latest version, limited only by an optional `floor` (minimum) and `exclude` (known-bad versions shipped in a release). `state.json` records the version actually installed and `doctor` shows it. Single-instance tools (OpenCLI) reuse the user's copy; if it is older than the floor, it is upgraded only with `--allow-upgrade`. / 工具不锁版本,装最新可用版;已知有问题的版本在新版本里排除;doctor 显示实际版本。
+- **`add` gives a finished result / `add` 一步到位**: missing prerequisites are installed without an admin password: uv (official script), ffmpeg (`imageio-ffmpeg` in a private venv), Node.js (official release under `~/.agent-reach/tools/node/` when the system has none), Chrome (system Chrome, else Chrome for Testing under `~/.agent-reach/tools/chrome/`). git is no longer needed (Boss installs from a GitHub archive). The user only logs in or enters a key. / 缺的依赖自动装好,用户只需登录或填 Key。
+- **Login state under `~/.agent-reach/` / 登录状态统一管理**: CLI tool logins in `sessions/`, browser logins in a dedicated Agent Reach browser. The browser opens by itself when a channel needs it and closes after 10 minutes without use. On macOS and Linux the OpenCLI extension is loaded automatically on every launch (no click); on Windows the user clicks "Add to Chrome" once. Agent Reach never logs in for the user and never reads the user's own browser cookies. / 专用浏览器按需自动打开,10 分钟不用自动关闭;macOS/Linux 自动装好扩展。
+- **remove cleans up / 去掉渠道会清理干净**: deletes the channel's private tools nobody else uses, its CLI session, its login keys and its site cookies in the Agent Reach browser. When no browser-login channel is left, the Agent Reach browser folder is deleted and OpenCLI is uninstalled if Agent Reach installed it.
+- **Removable default channels / 默认渠道可去掉**: `state.json` records `removed_defaults`; `setup` and `update` never add them back; `add` brings one back.
- **doctor states / 体检**: not_added, needs_setup, needs_login, unverified, ready, broken; plus `regressed` per channel (passed in the previous check, fails in the latest).
-- **update** runs `uv tool install --force` on the latest release, syncs tools to pinned versions and refreshes the skill. uv is the only supported installer. Pre-2.0 installs are migrated on first `setup` / `update`; `config.yaml` keys are kept.
+- **update** runs `uv tool install --force` on the latest release, upgrades every added channel's tools to the latest allowed version (also when Agent Reach itself has no new release), prunes tools no added channel uses, drops channels no longer in the registry, and refreshes the skill. `result.user_actions` lists in plain sentences what the user must do afterwards. Rollback: `uv tool install --force <previous release zip>`, then `agent-reach update --sync-only`. uv is the only supported installer. 1.5 and earlier installs are migrated on first `setup` / `update`; `config.yaml` keys are kept.
+- **Update notice / 新版本提醒**: at most once per 24 h, any command except `update` starts a short background check of the latest GitHub release (never waits on the network; offline is silent). When a newer version exists, every JSON envelope carries `meta.update = {current, latest, notes}`; the skill tells the AI to explain the notes to the user and update only with their yes. / 有新版本时 AI 用大白话告诉用户,用户同意才更新。
+- **Release notes / 发布说明**: every CHANGELOG version section starts with a plain summary for users in Chinese and English; it becomes the GitHub release body the AI shows users.
- Xueqiu quotes and stock search via Tencent public quotes (no login); Xueqiu community data uses a session the user imports with `agent-reach login xueqiu --sync`.
- YouTube `transcribe`; LinkedIn uses its own MCP registration in `~/.agent-reach/mcporter.json`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 96bf2be0..11b70ed8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -25,8 +25,8 @@ A channel is a `Channel` subclass in `agent_reach/channels/`, registered in `age
- `name`, `description`, and `can_handle(url)` so `agent-reach read <url>` can route links to it.
- `level`: `"default"` (works with no setup), `"optional"` (turned on with `agent-reach add`), or `"experimental"` (works but may break any time).
- `actions`: a tuple of `Action`s. Each has a `name`, `help`, `params` (a tuple of `Param(name, help, required, type, default)`), and **ordered** `backends` as `(label, method name)` pairs. The dispatcher tries them in order and falls back on retryable errors. `live_test` holds the params `agent-reach check` uses; a backend passes when it returns at least one item. Slow actions can set `timeout`.
-- `tools` (optional): keys of `runtime.tools.TOOLS` that `agent-reach add` installs privately under `~/.agent-reach/tools/`, pinned to an exact version.
-- `prereqs` (optional): machine prerequisites that are only checked and explained (keys of `runtime.manage.PREREQS`: node, git, chrome, ffmpeg, uv).
+- `tools` (optional): keys of `runtime.tools.TOOLS` that `agent-reach add` installs privately under `~/.agent-reach/tools/`. Versions are not pinned: `add` and `update` install the latest allowed version. A tool may set `floor` (minimum version) and `exclude` (known-bad versions); add a version to `exclude` in a release when an upstream release breaks.
+- `prereqs` (optional): machine prerequisites (keys of `runtime.manage.PREREQS`: node, chrome, ffmpeg, uv) that `agent-reach add` installs by itself when missing, without an admin password.
- Login, if the platform needs it:
- `login_url`: page opened in the Agent Reach browser by `agent-reach login`; the user logs in there.
- `session` + `login_argv`: a CLI tool whose own login runs with its state in `~/.agent-reach/sessions/<session>/`. `legacy_state` lists old locations `login --import-existing` may copy from.
@@ -38,7 +38,7 @@ Rules:
- Never read the user's own browser cookies and never log in on their behalf.
- Everything a channel stores lives under `~/.agent-reach/`.
-- Don't install anything globally; add the tool to `runtime.tools.TOOLS` with a pinned version.
+- Don't install anything globally; add the tool to `runtime.tools.TOOLS`.
## Dependency locking
@@ -69,6 +69,10 @@ Paste the `check --text` output into the PR. Also add unit tests under `tests/`
- Update the README channel table if you add a channel or change what it needs.
- Never commit keys, cookies, account names or machine-specific paths.
+## Release notes
+
+Every version section in `CHANGELOG.md` starts with a short plain summary for users, in Chinese and in English: what changed for them and anything they must do, in 1 to 4 short points, with no jargon (no file names, commands or internal terms). This text becomes the GitHub release body, which the AI reads from `meta.update.notes` and shows the user when it offers an update. Technical entries follow below the summary.
+
## Reporting issues
Include your OS, `agent-reach doctor --text`, `agent-reach check <channel> --text`, steps to reproduce, and what you expected. Remove personal data first.
@@ -81,3 +85,4 @@ Include your OS, `agent-reach doctor --text`, `agent-reach check <channel> --tex
- 不读用户自己浏览器的 Cookie,不替用户登录,数据只放在 `~/.agent-reach/` 下。
- 新渠道合并前必须在本地跑通 `agent-reach check <channel>` 实测,并把输出贴在 PR 里。
- 提交前运行 `ruff check agent_reach tests` 和 `pytest`。Commit message 用英文。
+- 发布说明:`CHANGELOG.md` 每个版本开头先写给用户看的大白话摘要(中文和英文各一份,1 到 4 条,不用术语),这段会成为 GitHub release 正文,AI 提示更新时会讲给用户听。
diff --git a/README.md b/README.md
index e5feaa55..59a7d7f1 100644
--- a/README.md
+++ b/README.md
@@ -64,7 +64,7 @@ Claude Code、Codex、Hermes Agent、OpenClaw 这类 CLI Agent 自带搜索和
- **中文平台**:B站、小红书、V2EX、雪球、小宇宙,通用搜索覆盖很差。
- **干净的结构化数据**:雪球行情、V2EX 帖子和回复、GitHub 仓库和 issue,直接给字段,不用从 HTML 里猜。
-Agent Reach 把这些平台背后的开源工具替你装好、固定版本、定期体检,然后给 Agent 一个统一入口:
+Agent Reach 把这些平台背后的开源工具替你装好、保持最新、定期体检,然后给 Agent 一个统一入口:
```bash
agent-reach channels # 有哪些渠道、每个渠道能做什么
@@ -82,6 +82,8 @@ agent-reach read https://www.v2ex.com/t/123 # 按链接自动选渠道
- **要花钱吗?** 程序和后端工具都是开源免费的。只有两处可能要你自己的 Key:播客/视频转文字用 Groq(有免费额度)或 OpenAI 的 Whisper 接口。
- **会碰我的浏览器和账号吗?** 不会读你自己浏览器里的 Cookie,也从不替你登录。需要登录的渠道,由你本人在 Agent Reach 专用浏览器里登录。详见[安全性](#安全性)。
- **支持哪些系统?** 优先保证 macOS,Linux 可用,Windows 尽力支持。
+- **要我自己装别的软件吗?** 不用。某个渠道要用的东西(Node.js、Chrome、ffmpeg、浏览器扩展)都由 `agent-reach add` 自己装好,不需要管理员密码。你本人只需要登录,或者提供一个 Key。
+- **怎么知道有新版本?** Agent Reach 每天最多在后台查一次,有新版本时 Agent 会用大白话告诉你改了什么、问你要不要更新,你同意了才更新。
---
@@ -98,18 +100,18 @@ agent-reach read https://www.v2ex.com/t/123 # 按链接自动选渠道
| bilibili | 默认 | 搜索、视频信息、热门、字幕 | 无;字幕需要登录(扫码) |
| xiaohongshu | 可选 | 搜笔记、读笔记 | 浏览器 + 登录 |
| reddit | 可选 | 搜索、读帖子和评论、看版块 | 浏览器 + 登录 |
-| linkedin | 可选 | 搜职位 | 登录(需要 Node.js 和 uv) |
-| boss | 可选 | 搜职位和 JD | 浏览器 + 登录(需要 git) |
-| xiaoyuzhou | 可选 | 播客完整转文字 | Groq Key + ffmpeg |
+| linkedin | 可选 | 搜职位 | 登录 |
+| boss | 可选 | 搜职位和 JD | 浏览器 + 登录 |
+| xiaoyuzhou | 可选 | 播客完整转文字 | Groq Key |
| xueqiu | 可选 | 实时行情、搜股票、热帖、热股 | 行情免登录;热帖热股需要浏览器登录 |
| twitter | 实验 | 搜推文、用户资料、用户推文、读推文串 | 浏览器 + 登录 |
| facebook | 实验 | 搜索、主页资料 | 浏览器 + 登录 |
| instagram | 实验 | 搜用户、主页资料、用户帖子 | 浏览器 + 登录 |
-- **默认**:装好就能用。
-- **可选**:用 `agent-reach add <渠道>` 按需开启,Agent Reach 会把它要的工具装到自己的目录里。
+- **默认**:装好就能用;不想要也可以去掉(`agent-reach remove <渠道>`),以后更新不会再加回来。
+- **可选**:用 `agent-reach add <渠道>` 按需开启,它需要的一切 Agent Reach 都会装到自己的目录里。
- **实验**:能用,但平台反爬更严,可能随时失效。
-- **浏览器**:指 Agent Reach 专用浏览器,一个独立的 Chrome 窗口(需要已安装 Google Chrome 和 Node.js)。第一次用要在里面装一个 OpenCLI 扩展,`agent-reach browser setup` 会带你完成。之后需要时它会自己打开(第一次打开大约要 40 秒),10 分钟没用就自动关掉。
+- **浏览器**:指 Agent Reach 专用浏览器,一个独立的 Chrome 窗口。电脑上没有 Chrome 的话 Agent Reach 会自己下载一个;里面要用的 OpenCLI 扩展也会自己装好(Windows 上需要你在弹出的窗口里点一次"添加至 Chrome")。之后需要时它会自己打开(第一次打开大约要 40 秒),10 分钟没用就自动关掉。
---
@@ -125,7 +127,7 @@ agent-reach read https://www.v2ex.com/t/123 # 按链接自动选渠道
- **允许它执行命令**:如果 Agent 说自己不能运行命令,去它的设置里打开"允许执行命令"。
- **装 uv**:uv 是一个安装命令行程序的小工具,不需要管理员密码。电脑上没有的话 Agent 会先装它,会跟你说一声。
-- **要不要加可选渠道**:装完后 Agent 会告诉你哪些已经能用(网页、YouTube、GitHub、V2EX、B站),以及还能加哪些、各自需要什么。你选了再加,也可以以后随时说"帮我加上小红书"。
+- **要不要加可选渠道**:装完后 Agent 会告诉你哪些已经能用(网页、YouTube、GitHub、V2EX、B站),以及还能加哪些。你选了再加,也可以以后随时说"帮我加上小红书",一条命令就装好。
需要你本人做的只有登录,Agent 从不替你登录,也不会要你的密码:
@@ -156,9 +158,9 @@ flowchart LR
| 你说 | Agent 运行 | 作用 |
|---|---|---|
| "看看 Agent Reach 状态" | `agent-reach doctor --text` | 每个渠道的状态:未开启 / 待配置 / 待登录 / 未验证 / 可用 / 故障,并标出"上次还好、现在坏了"的渠道 |
-| "加上小红书" / "去掉小红书" | `agent-reach add` / `remove <渠道>` | 开启 / 关闭渠道,加完再 `agent-reach login <渠道>` |
+| "加上小红书" / "去掉小红书" | `agent-reach add` / `remove <渠道>` | 开启渠道并装好它需要的一切,你只需登录或提供 Key / 关闭渠道并清掉它的登录和专用工具(默认渠道也能去掉) |
| "B站登录过期了" / "退出登录" | `agent-reach login` / `logout <渠道>` | 登录(你本人操作)/ 清除登录 |
-| "升级 Agent Reach" | `agent-reach update` | 一次更新程序、后端工具和 skill,见 [update.md](docs/update.md) |
+| "升级 Agent Reach" | `agent-reach update` | 一次更新程序、各渠道的工具(升到最新)和 skill,并告诉你还需要做什么,见 [update.md](docs/update.md) |
| "卸载 Agent Reach" | `agent-reach uninstall` | 见下面"安全性"里的卸载说明 |
| "让另一个 AI 也能用" | `agent-reach skill link <它的 skill 目录>` | 给不在自动名单里的 AI 也放一个说明链接 |
@@ -176,9 +178,9 @@ flowchart LR
平台改版、工具失效是常态。换后端只是调整这个列表,Agent 的调用方式不变。
-### 📌 固定版本,私有安装
+### 📌 保持最新,私有安装
-Agent Reach 装的工具(OpenCLI、bili-cli、boss-agent-cli、mcporter)都固定在验证过的版本,装在 `~/.agent-reach/tools/` 里,不污染你的全局环境。`agent-reach update` 会把它们一起更新到新版本验证过的版本。
+Agent Reach 装的工具(OpenCLI、bili-cli、boss-agent-cli、mcporter 等)装在 `~/.agent-reach/tools/` 里,不污染你的全局环境。工具不锁版本:每次装的都是最新版,`agent-reach update` 会把它们升到最新,即使 Agent Reach 本身没有新版本。已知有问题的上游版本会在新的 Agent Reach 版本里排除掉;`agent-reach doctor` 会显示每个工具实际装的版本。
### 🩺 能用要靠实测
diff --git a/agent_reach/backends/opencli.py b/agent_reach/backends/opencli.py
index 89f9edd5..70a11225 100644
--- a/agent_reach/backends/opencli.py
+++ b/agent_reach/backends/opencli.py
@@ -45,17 +45,15 @@ def _opencli_error(text: str, login_hint: str):
def _dedicated_profile_env() -> dict:
"""OPENCLI_PROFILE for the Agent Reach browser, opening the browser if it is closed.
- Fails fast with NEED_SETUP when the browser was never set up, instead of letting OpenCLI hang.
+ Sets the browser up first when it never was (automatic on macOS/Linux; the
+ Windows Web Store flow raises NEED_SETUP if the user has not added the extension).
"""
from agent_reach.runtime import browser
- from agent_reach.runtime.result import NEED_SETUP, ReachError
ctx = browser.bound_context()
if not ctx:
- raise ReachError(
- NEED_SETUP, "the Agent Reach browser is not set up",
- hint="Ask the user to run `agent-reach browser setup` and install the OpenCLI extension in the window it opens.",
- )
+ browser.setup()
+ ctx = browser.bound_context()
browser.ensure_running(ctx)
return {"OPENCLI_PROFILE": ctx}
diff --git a/agent_reach/channels/_opencli_site.py b/agent_reach/channels/_opencli_site.py
index 09688282..cf4999f3 100644
--- a/agent_reach/channels/_opencli_site.py
+++ b/agent_reach/channels/_opencli_site.py
@@ -32,8 +32,8 @@ class OpenCLISiteChannel(Channel):
def _opencli(self, args, timeout: float, *, empty_is_error: bool = True) -> list:
"""Run one OpenCLI command for this site and return unified items."""
hint = (
- f"Ask the user to log in to {self.login_hint} in their own Chrome (the one "
- "with the OpenCLI extension). Never log in for them."
+ f"Run `agent-reach login {self.name}` and ask the user to log in to {self.login_hint} "
+ "in the Agent Reach browser window it opens. Never log in for them."
)
items = opencli_items(opencli_call(self.site, list(args), timeout=timeout, login_hint=hint))
if not items:
diff --git a/agent_reach/channels/base.py b/agent_reach/channels/base.py
index 9ab73e36..a56f257b 100644
--- a/agent_reach/channels/base.py
+++ b/agent_reach/channels/base.py
@@ -64,10 +64,15 @@ class Channel(ABC):
#: copied into the session only when the user asks (`login --import-existing`).
legacy_state: Tuple[str, ...] = ()
#: Page the user logs in on, opened in the Agent Reach browser by `agent-reach login`.
+ #: A login_url makes the channel need Chrome (installed by `add` when missing).
login_url: str = ""
+ #: Cookie domains `agent-reach remove` clears in the Agent Reach browser
+ #: (empty = the login_url host without "www.").
+ domains: Tuple[str, ...] = ()
#: Upstream tools (keys of runtime.tools.TOOLS) `agent-reach add` installs.
tools: Tuple[str, ...] = ()
- #: Machine prerequisites we only check (keys of runtime.manage.PREREQS).
+ #: Machine prerequisites (node, uv, ffmpeg, chrome; keys of runtime.tools.TOOLS)
+ #: that `agent-reach add` installs when the machine has none.
prereqs: Tuple[str, ...] = ()
#: Config keys `agent-reach logout` clears.
logout_keys: Tuple[str, ...] = ()
diff --git a/agent_reach/channels/boss.py b/agent_reach/channels/boss.py
index a798188a..7072c29f 100644
--- a/agent_reach/channels/boss.py
+++ b/agent_reach/channels/boss.py
@@ -15,7 +15,6 @@ import json
from agent_reach.runtime.result import (
NEED_LOGIN,
- NEED_SETUP,
UPSTREAM_BROKEN,
ReachError,
make_item,
@@ -38,7 +37,7 @@ class BossChannel(Channel):
login_argv = ("boss", "--cdp-url", "http://localhost:9222", "login", "--cdp")
legacy_state = (".boss-agent",)
tools = ("boss-agent-cli",)
- prereqs = ("git", "chrome")
+ prereqs = ("chrome",)
actions = (
Action(
"search",
@@ -63,9 +62,10 @@ class BossChannel(Channel):
from agent_reach.runtime import browser
if not (browser.is_running() or browser.profile_dir().is_dir()):
+ # boss needs no extension, only a zhipin.com login in the browser, which a never-opened one lacks.
raise ReachError(
- NEED_SETUP,
- "the Agent Reach browser has never been opened",
+ NEED_LOGIN,
+ "nobody has logged in to zhipin.com in the Agent Reach browser yet",
hint="Run `agent-reach login boss`, let the user log in to zhipin.com in that window, then run `agent-reach login boss --sync`.",
)
browser.ensure_running()
diff --git a/agent_reach/channels/linkedin.py b/agent_reach/channels/linkedin.py
index 5298c9f7..4924013f 100644
--- a/agent_reach/channels/linkedin.py
+++ b/agent_reach/channels/linkedin.py
@@ -50,10 +50,12 @@ class LinkedInChannel(Channel):
def on_add(self) -> None:
from agent_reach.runtime.sessions import session_dir
+ from agent_reach.runtime.tools import resolve
servers = _own_servers()
servers["linkedin"] = {
- "command": "uvx",
+ # absolute path: uvx may be our private copy, which mcporter's PATH does not have
+ "command": resolve("uvx") or "uvx",
"args": [
f"mcp-server-linkedin@{_LINKEDIN_MCP_VERSION}",
"--user-data-dir", f"{session_dir(self.session)}/profile", "--claim-profile-root",
diff --git a/agent_reach/channels/xiaoyuzhou.py b/agent_reach/channels/xiaoyuzhou.py
index 3b2124dc..add183a6 100644
--- a/agent_reach/channels/xiaoyuzhou.py
+++ b/agent_reach/channels/xiaoyuzhou.py
@@ -2,7 +2,6 @@
"""Xiaoyuzhou Podcast (小宇宙播客) — transcribe podcasts via Groq Whisper API."""
import os
-import shutil
import tempfile
from agent_reach.config import Config
@@ -55,11 +54,17 @@ class XiaoyuzhouChannel(Channel):
NEED_SETUP, "no Groq API key configured",
hint="Ask the user for a free key from https://console.groq.com, then run `agent-reach configure groq-key`.",
)
- if not shutil.which("ffmpeg"):
- raise ReachError(NEED_SETUP, "ffmpeg is not installed", hint="Ask the user to install ffmpeg (macOS: brew install ffmpeg).")
+ from agent_reach.runtime.tools import ffmpeg_path
+
+ ffmpeg = ffmpeg_path()
+ if not ffmpeg:
+ raise ReachError(NEED_SETUP, "ffmpeg is not installed", hint="Run `agent-reach add xiaoyuzhou`.")
+ # our private ffmpeg goes first on the script's PATH
+ path = os.pathsep.join([os.path.dirname(ffmpeg), os.environ.get("PATH", "")])
with tempfile.TemporaryDirectory(prefix="agent-reach-xyz-") as tmp:
out = os.path.join(tmp, "transcript.txt")
- run_cmd(["bash", _SCRIPT, str(target).strip(), out], timeout=timeout, env={"GROQ_API_KEY": str(key)}, label="transcribe")
+ run_cmd(["bash", _SCRIPT, str(target).strip(), out], timeout=timeout,
+ env={"GROQ_API_KEY": str(key), "PATH": path}, label="transcribe")
with open(out, encoding="utf-8", errors="replace") as fh:
text = fh.read().strip()
return [make_item(url=str(target).strip(), text=text)]
diff --git a/agent_reach/channels/youtube.py b/agent_reach/channels/youtube.py
index 5061b01d..1c964e0e 100644
--- a/agent_reach/channels/youtube.py
+++ b/agent_reach/channels/youtube.py
@@ -28,7 +28,7 @@ _RAW_KEYS = ("id", "duration", "view_count", "like_count", "channel_id", "tags",
def _ytdlp_argv(*args: str) -> list:
- """Run the yt-dlp bundled with Agent Reach (pinned via our dependencies)."""
+ """Run the yt-dlp installed with Agent Reach (one of its dependencies)."""
runtime = []
if shutil.which("deno") is None and shutil.which("node"):
runtime = ["--js-runtimes", "node"]
@@ -94,6 +94,8 @@ class YouTubeChannel(Channel):
description = "YouTube 视频和字幕"
level = "default"
+ #: transcribe re-encodes and chunks audio
+ prereqs = ("ffmpeg",)
actions = (
Action(
"read",
diff --git a/agent_reach/runtime/browser.py b/agent_reach/runtime/browser.py
index 8dee242e..c692d723 100644
--- a/agent_reach/runtime/browser.py
+++ b/agent_reach/runtime/browser.py
@@ -1,16 +1,26 @@
"""The Agent Reach dedicated browser.
A separate Chrome whose profile lives in ~/.agent-reach/browser/profile/, so
-every browser login Agent Reach relies on stays under ~/.agent-reach/. The user
-installs the OpenCLI extension in it once; `agent-reach browser setup` then
-records which OpenCLI profile it is (~/.agent-reach/browser/state.json).
-The user's own ~/.opencli settings are never modified.
+every browser login Agent Reach relies on stays under ~/.agent-reach/. The
+user's own Chrome profiles and ~/.opencli settings are never touched.
+
+Chrome: the system Google Chrome if there is one, else Chrome for Testing
+(stable) under ~/.agent-reach/tools/chrome/ (`ensure_chrome`).
+
+OpenCLI extension: the `opencli-extension-*.zip` of the latest OpenCLI GitHub
+release, unpacked at ~/.agent-reach/browser/extension/ (a stable path, so the
+extension id stays the same). Branded Chrome ignores `--load-extension`, so on
+macOS/Linux the idle watcher (runtime.browser_watcher) launches Chrome with
+`--remote-debugging-pipe --enable-unsafe-extension-debugging` and loads the
+extension over that pipe with CDP `Extensions.loadUnpacked` on every launch
+(it does not persist). Chrome exits when the pipe closes, so the watcher owns
+the browser for its whole life. `setup()` then records which OpenCLI profile
+is the dedicated browser (~/.agent-reach/browser/state.json); no user click.
+Windows has no fd passing: the user adds the extension from the Web Store once.
Browser channels open it on demand (`ensure_running`). Every Agent Reach use
-touches ~/.agent-reach/browser/last_used; when Agent Reach launches the
-browser it also starts one detached watcher (runtime.browser_watcher) that
-closes the browser after IDLE_LIMIT seconds without use and exits when the
-browser is gone.
+touches ~/.agent-reach/browser/last_used; the watcher closes the browser after
+IDLE_LIMIT seconds without use.
Debugging is bound to 127.0.0.1:9222 only. Any local process that can reach
that port can control this browser; that is why it closes when idle.
@@ -24,12 +34,15 @@ import os
import platform
import re
import shutil
+import signal
import socket
import subprocess
import sys
+import tempfile
import time
import urllib.parse
import urllib.request
+import zipfile
from pathlib import Path
from typing import Callable, Iterator, List, Optional
@@ -52,6 +65,13 @@ START_WAIT = 90.0
#: Extra wait for a browser that has been up longer than START_WAIT.
_RUNNING_GRACE = 5.0
_LOCK_WAIT = START_WAIT + 30.0
+#: How long Windows setup waits for the user to add the extension from the Web Store.
+_STORE_WAIT = 180.0
+
+OPENCLI_RELEASE_API = "https://api.github.com/repos/jackwener/OpenCLI/releases/latest"
+_EXTENSION_ASSET_RE = re.compile(r"^opencli-extension-.*\.zip$")
+CFT_VERSIONS_URL = "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json"
+_USER_AGENT = "agent-reach"
def browser_root() -> Path:
@@ -62,6 +82,14 @@ def profile_dir() -> Path:
return browser_root() / "profile"
+def extension_dir() -> Path:
+ return browser_root() / "extension"
+
+
+def watcher_log_path() -> Path:
+ return browser_root() / "watcher.log"
+
+
def _state_path() -> Path:
return browser_root() / "state.json"
@@ -94,6 +122,17 @@ def _save_state(state: dict) -> None:
atomic_write_private_text(_state_path(), json.dumps(state, indent=2))
+def update_state(**changes) -> None:
+ """Merge `changes` into the browser state (None deletes a key); re-reads first, other processes write too."""
+ state = _load_state()
+ for key, value in changes.items():
+ if value is None:
+ state.pop(key, None)
+ else:
+ state[key] = value
+ _save_state(state)
+
+
# ── last use ──
@@ -168,10 +207,57 @@ def watcher_running() -> bool:
os.close(fd)
-# ── process ──
+def wait_for(check: Callable[[], bool], seconds: float, interval: float = 1.0) -> bool:
+ deadline = time.monotonic() + seconds
+ while True:
+ if check():
+ return True
+ if time.monotonic() >= deadline:
+ return False
+ time.sleep(interval)
-def chrome_binary() -> Optional[str]:
+# ── downloads ──
+
+
+def _fetch(url: str, timeout: float = 30.0) -> bytes:
+ """GET `url` (honours the OS / env proxy settings)."""
+ req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ return resp.read()
+
+
+def _download(url: str, dest: Path, timeout: float = 60.0) -> None:
+ req = urllib.request.Request(url, headers={"User-Agent": _USER_AGENT})
+ with urllib.request.urlopen(req, timeout=timeout) as resp, open(dest, "wb") as out:
+ shutil.copyfileobj(resp, out, 1 << 20)
+
+
+def _unzip(archive: Path, dest: Path) -> None:
+ """Extract keeping symlinks and exec bits (a Chrome .app is full of both)."""
+ if platform.system() == "Darwin" and shutil.which("ditto"):
+ subprocess.run(["ditto", "-x", "-k", str(archive), str(dest)], check=True, capture_output=True, timeout=600)
+ return
+ root = dest.resolve()
+ with zipfile.ZipFile(archive) as zf:
+ for info in zf.infolist():
+ target = (dest / info.filename).resolve()
+ if target != root and root not in target.parents:
+ raise ValueError(f"unsafe path in archive: {info.filename}")
+ mode = info.external_attr >> 16
+ if (mode & 0o170000) == 0o120000: # symlink
+ target.parent.mkdir(parents=True, exist_ok=True)
+ os.symlink(zf.read(info).decode("utf-8"), target)
+ continue
+ zf.extract(info, dest)
+ if mode & 0o111 and not info.is_dir():
+ os.chmod(target, (mode & 0o777) | 0o600)
+
+
+# ── Chrome ──
+
+
+def _system_chrome() -> Optional[str]:
system = platform.system()
candidates = []
if system == "Darwin":
@@ -186,77 +272,231 @@ def chrome_binary() -> Optional[str]:
return next((c for c in candidates if c and os.path.exists(c)), None)
+def _cft_dir() -> Path:
+ from . import tools
+
+ return tools.tool_dir("chrome")
+
+
+def _cft_platform() -> Optional[str]:
+ system, machine = platform.system(), platform.machine().lower()
+ arm = machine in ("arm64", "aarch64")
+ if system == "Darwin":
+ return "mac-arm64" if arm else "mac-x64"
+ if system == "Windows":
+ return "win64" if sys.maxsize > 2**32 else "win32"
+ if system == "Linux":
+ return "linux-arm64" if arm else "linux64"
+ return None
+
+
+def _cft_binary(plat: Optional[str] = None) -> Path:
+ plat = plat or _cft_platform() or ""
+ base = _cft_dir() / f"chrome-{plat}"
+ if plat.startswith("mac"):
+ return base / "Google Chrome for Testing.app" / "Contents" / "MacOS" / "Google Chrome for Testing"
+ if plat.startswith("win"):
+ return base / "chrome.exe"
+ return base / "chrome"
+
+
+def chrome_binary() -> Optional[str]:
+ """System Google Chrome, else our Chrome for Testing if installed, else None (never downloads)."""
+ system = _system_chrome()
+ if system:
+ return system
+ cft = _cft_binary()
+ return str(cft) if _cft_platform() and cft.exists() else None
+
+
+def ensure_chrome() -> str:
+ """Path to a Chrome binary, installing Chrome for Testing (stable) when the system has no Chrome."""
+ from .result import NEED_SETUP, UPSTREAM_BROKEN, ReachError
+
+ found = chrome_binary()
+ if found:
+ return found
+ plat = _cft_platform()
+ if not plat:
+ raise ReachError(NEED_SETUP, f"no Chrome build for {platform.system()} {platform.machine()}",
+ hint="Ask the user to install Google Chrome.")
+ try:
+ stable = json.loads(_fetch(CFT_VERSIONS_URL))["channels"]["Stable"]
+ version = stable["version"]
+ url = next(d["url"] for d in stable["downloads"]["chrome"] if d["platform"] == plat)
+ except Exception as exc: # noqa: BLE001
+ raise ReachError(UPSTREAM_BROKEN, f"could not look up Chrome for Testing: {exc}") from None
+ dest = _cft_dir()
+ dest.parent.mkdir(parents=True, exist_ok=True)
+ work = Path(tempfile.mkdtemp(prefix=".chrome-", dir=dest.parent))
+ try:
+ archive = work / "chrome.zip"
+ _download(url, archive, timeout=120)
+ unpacked = work / "unpacked"
+ unpacked.mkdir()
+ _unzip(archive, unpacked)
+ archive.unlink()
+ shutil.rmtree(dest, ignore_errors=True)
+ os.replace(unpacked, dest)
+ except Exception as exc: # noqa: BLE001
+ raise ReachError(UPSTREAM_BROKEN, f"could not install Chrome for Testing: {exc}") from None
+ finally:
+ shutil.rmtree(work, ignore_errors=True)
+ exe = _cft_binary(plat)
+ if not exe.exists():
+ raise ReachError(UPSTREAM_BROKEN, "Chrome for Testing download did not contain a browser")
+ from . import tools
+
+ record = getattr(tools, "record", None)
+ if record:
+ record("chrome", version)
+ return str(exe)
+
+
+def can_load_extension() -> bool:
+ """macOS/Linux: the watcher loads the extension over the launch pipe. Windows: Web Store only."""
+ return os.name != "nt"
+
+
+def chrome_argv(exe: str, url: str, *, pipe: bool) -> List[str]:
+ argv = [
+ exe,
+ "--remote-debugging-address=127.0.0.1",
+ f"--remote-debugging-port={CDP_PORT}",
+ f"--user-data-dir={profile_dir()}",
+ "--no-first-run",
+ "--no-default-browser-check",
+ ]
+ if pipe:
+ argv += ["--remote-debugging-pipe", "--enable-unsafe-extension-debugging"]
+ if os.environ.get("AGENT_REACH_TEST_MOCK_KEYCHAIN") == "1":
+ # Tests only (temp HOME has no login keychain). Never for real users: it changes the cookie key.
+ argv += ["--use-mock-keychain", "--password-store=basic"]
+ return argv + [url]
+
+
+# ── OpenCLI extension ──
+
+
+def extension_version() -> Optional[str]:
+ try:
+ return json.loads((extension_dir() / "manifest.json").read_text("utf-8")).get("version")
+ except (OSError, ValueError):
+ return None
+
+
+def refresh_extension() -> dict:
+ """Install or update the OpenCLI extension from the latest OpenCLI release.
+
+ Keeps the current copy when GitHub is unreachable; raises only if there is none.
+ Returns {"version", "updated"}. A running browser is closed before files change.
+ """
+ from .result import UPSTREAM_BROKEN, ReachError
+
+ current = extension_version()
+ try:
+ release = json.loads(_fetch(OPENCLI_RELEASE_API))
+ asset = next(a for a in release.get("assets", []) if _EXTENSION_ASSET_RE.match(a.get("name", "")))
+ except Exception as exc: # noqa: BLE001
+ if current:
+ return {"version": current, "updated": False}
+ raise ReachError(UPSTREAM_BROKEN, f"could not find the OpenCLI extension release: {exc}") from None
+ state = _load_state()
+ if current and state.get("extension_asset") == asset["name"]:
+ return {"version": current, "updated": False}
+ make_private_dir(browser_root())
+ work = Path(tempfile.mkdtemp(prefix=".extension-", dir=browser_root()))
+ try:
+ archive = work / "extension.zip"
+ _download(asset["browser_download_url"], archive)
+ unpacked = work / "unpacked"
+ unpacked.mkdir()
+ _unzip(archive, unpacked)
+ manifest = next(unpacked.rglob("manifest.json"), None)
+ if manifest is None:
+ raise ValueError("no manifest.json in the extension zip")
+ version = json.loads(manifest.read_text("utf-8")).get("version")
+ if current and version == current:
+ update_state(extension_asset=asset["name"], extension_version=version)
+ return {"version": version, "updated": False}
+ if is_running():
+ stop() # never swap files under a running extension; the next launch loads the new one
+ shutil.rmtree(extension_dir(), ignore_errors=True)
+ os.replace(manifest.parent, extension_dir())
+ except ReachError:
+ raise
+ except Exception as exc: # noqa: BLE001
+ if current and extension_version():
+ return {"version": current, "updated": False}
+ raise ReachError(UPSTREAM_BROKEN, f"could not install the OpenCLI extension: {exc}") from None
+ finally:
+ shutil.rmtree(work, ignore_errors=True)
+ update_state(extension_asset=asset["name"], extension_version=version)
+ return {"version": version, "updated": True}
+
+
+# ── process ──
+
+
def is_running() -> bool:
with socket.socket() as s:
s.settimeout(1)
return s.connect_ex(("127.0.0.1", CDP_PORT)) == 0
+def _detach_kwargs() -> dict:
+ if os.name == "nt":
+ return {"creationflags": subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+ | subprocess.CREATE_NO_WINDOW}
+ return {"start_new_session": True}
+
+
def _launch(url: str) -> None:
- """Start Chrome on the dedicated profile, then the idle watcher. Caller holds start_lock()."""
- exe = chrome_binary()
- if not exe:
- from .result import NEED_SETUP, ReachError
+ """Start the dedicated browser. Caller holds start_lock().
- raise ReachError(NEED_SETUP, "Google Chrome is not installed", hint="Ask the user to install Google Chrome.")
- make_private_dir(profile_dir())
- subprocess.Popen(
- [
- exe,
- "--remote-debugging-address=127.0.0.1",
- f"--remote-debugging-port={CDP_PORT}",
- f"--user-data-dir={profile_dir()}",
- "--no-first-run",
- "--no-default-browser-check",
- url,
- ],
- stdin=subprocess.DEVNULL,
- stdout=subprocess.DEVNULL,
- stderr=subprocess.DEVNULL,
- start_new_session=(os.name != "nt"),
- )
- state = _load_state()
- state["started_at"] = time.time()
- _save_state(state)
- if not wait_for(is_running, START_WAIT):
- from .result import UPSTREAM_BROKEN, ReachError
+ macOS/Linux: the watcher launches Chrome (it must own the pipe). Windows:
+ Chrome is started here and the watcher only watches.
+ """
+ from .result import UPSTREAM_BROKEN, ReachError
- raise ReachError(UPSTREAM_BROKEN, f"the Agent Reach browser did not open within {START_WAIT:.0f}s")
- _spawn_watcher()
+ exe = ensure_chrome()
+ make_private_dir(profile_dir())
+ update_state(started_at=time.time())
+ if not can_load_extension():
+ subprocess.Popen(chrome_argv(exe, url, pipe=False), stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL, **_detach_kwargs())
+ if not wait_for(is_running, START_WAIT):
+ raise ReachError(UPSTREAM_BROKEN, f"the Agent Reach browser did not open within {START_WAIT:.0f}s")
+ _spawn_watcher()
+ return
+ if not extension_version():
+ with contextlib.suppress(ReachError):
+ refresh_extension() # offline: open without it; the OpenCLI wait reports the problem
+ # A watcher still exiting from the last browser holds its lock for a moment; the new one waits for it.
+ with open(watcher_log_path(), "wb") as log:
+ proc = subprocess.Popen(
+ [sys.executable, "-m", "agent_reach.runtime.browser_watcher", "--launch", url, "--chrome", exe],
+ stdin=subprocess.DEVNULL, stdout=log, stderr=log, **_detach_kwargs(),
+ )
+ if not wait_for(lambda: is_running() or proc.poll() is not None, START_WAIT, interval=0.2) or not is_running():
+ tail = ""
+ with contextlib.suppress(OSError):
+ tail = watcher_log_path().read_text("utf-8", "replace").strip().splitlines()[-1][:300]
+ raise ReachError(UPSTREAM_BROKEN, "the Agent Reach browser did not open" + (f": {tail}" if tail else ""))
def _spawn_watcher() -> None:
- """Start the detached idle watcher unless one is already running."""
+ """Windows: start the detached idle watcher for an already-open browser unless one runs."""
if watcher_running():
return
- kwargs: dict = {}
- if os.name == "nt":
- kwargs["creationflags"] = (
- subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW
- )
- else:
- kwargs["start_new_session"] = True
subprocess.Popen(
[sys.executable, "-m", "agent_reach.runtime.browser_watcher"],
- stdin=subprocess.DEVNULL,
- stdout=subprocess.DEVNULL,
- stderr=subprocess.DEVNULL,
- **kwargs,
+ stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, **_detach_kwargs(),
)
# Hold start_lock until the watcher owns its lock, so a racing launch sees it.
wait_for(watcher_running, 5.0, interval=0.1)
-def wait_for(check: Callable[[], bool], seconds: float, interval: float = 1.0) -> bool:
- deadline = time.monotonic() + seconds
- while True:
- if check():
- return True
- if time.monotonic() >= deadline:
- return False
- time.sleep(interval)
-
-
def _remaining_start_wait() -> float:
"""How long a browser that is open but not ready yet still gets."""
started = _load_state().get("started_at") or 0.0
@@ -264,7 +504,7 @@ def _remaining_start_wait() -> float:
def start(url: str = "about:blank") -> None:
- """Show `url` in the dedicated browser, launching it if needed (login, setup)."""
+ """Show `url` in the dedicated browser, launching it if needed (login)."""
touch()
if is_running():
open_url(url)
@@ -279,7 +519,8 @@ def start(url: str = "about:blank") -> None:
def ensure_running(context: Optional[str] = None) -> None:
"""Make the dedicated browser ready for an action, launching it if needed.
- With `context`, also wait until that OpenCLI profile is connected.
+ With `context`, also wait until that OpenCLI profile is connected. A browser
+ left open without its watcher (so without the extension) is relaunched.
The wait does not count against the action's --timeout.
Raises ReachError when it is not ready within START_WAIT.
"""
@@ -294,11 +535,18 @@ def ensure_running(context: Optional[str] = None) -> None:
if ready():
return
with off_the_clock(), start_lock():
+ if context and can_load_extension() and is_running() and not watcher_running():
+ stop() # an orphan from an older Agent Reach: reopen it with the extension
if not is_running():
_launch("about:blank")
if not wait_for(ready, _remaining_start_wait()):
if not is_running():
raise ReachError(UPSTREAM_BROKEN, "the Agent Reach browser closed while starting")
+ if can_load_extension():
+ raise ReachError(
+ UPSTREAM_BROKEN, "the Agent Reach browser is running but OpenCLI is not connected to it",
+ hint="Run `agent-reach browser setup` once; if it fails the same way, OpenCLI itself is broken.",
+ )
raise ReachError(
NEED_SETUP, "the Agent Reach browser is running but OpenCLI is not connected to it",
hint="Ask the user to check the OpenCLI extension is enabled in the Agent Reach browser window.",
@@ -318,8 +566,6 @@ def stop(timeout: float = 10.0) -> bool:
if wait_for(lambda: not is_running(), timeout, interval=0.2):
return True
if pid:
- import signal
-
with contextlib.suppress(OSError):
os.kill(int(pid), signal.SIGTERM)
return wait_for(lambda: not is_running(), 5.0, interval=0.2)
@@ -328,10 +574,69 @@ def stop(timeout: float = 10.0) -> bool:
def open_url(url: str) -> None:
"""Open a new tab in the running dedicated browser."""
req = urllib.request.Request(f"{CDP_URL}/json/new?{urllib.parse.quote(url, safe='')}", method="PUT")
- with urllib.request.urlopen(req, timeout=5):
+ opener = urllib.request.build_opener(urllib.request.ProxyHandler({})) # loopback: never proxy
+ with opener.open(req, timeout=5):
pass
+def _profile_pids() -> List[int]:
+ """Processes started with our --user-data-dir (Chrome and its helpers)."""
+ if os.name == "nt":
+ return []
+ try:
+ out = subprocess.run(["ps", "-axww", "-o", "pid=,command="], capture_output=True, text=True, timeout=10).stdout
+ except (OSError, subprocess.TimeoutExpired):
+ return []
+ flag = f"--user-data-dir={profile_dir()}"
+ pids = []
+ for line in out.splitlines():
+ pid, _, cmd = line.strip().partition(" ")
+ if pid.isdigit() and int(pid) != os.getpid() and (flag + " " in cmd + " "):
+ pids.append(int(pid))
+ return pids
+
+
+def clear_site(domains: List[str]) -> int:
+ """Delete the dedicated browser's cookies for `domains` (and subdomains); returns how many.
+
+ Opens the browser if it is closed; does nothing when it was never used.
+ """
+ if not domains or not (is_running() or profile_dir().is_dir()):
+ return 0
+ from . import cdp
+
+ ensure_running()
+ doomed = [c for c in (cdp.call("Storage.getCookies") or {}).get("cookies", [])
+ if any(cdp.domain_matches(c.get("domain", ""), d) for d in domains)]
+ if not doomed:
+ return 0
+ keys = ("name", "domain", "path", "secure", "httpOnly", "sameSite", "partitionKey", "sourceScheme", "sourcePort")
+ expired = [{**{k: c[k] for k in keys if k in c}, "value": "", "expires": 1} for c in doomed]
+ cdp.call("Storage.setCookies", {"cookies": expired})
+ left = {(c.get("name"), c.get("domain"), c.get("path")) for c in (cdp.call("Storage.getCookies") or {}).get("cookies", [])}
+ return sum((c.get("name"), c.get("domain"), c.get("path")) not in left for c in doomed)
+
+
+def delete_profile() -> bool:
+ """Close the dedicated browser and remove ~/.agent-reach/browser/. True if something was removed."""
+ root = browser_root()
+ if not root.exists():
+ return False
+ with contextlib.suppress(Exception), start_lock(wait=15.0):
+ stop()
+ pids = _profile_pids()
+ for pid in pids:
+ with contextlib.suppress(OSError):
+ os.kill(pid, signal.SIGTERM)
+ if not wait_for(lambda: not _profile_pids(), 5.0, interval=0.2):
+ for pid in _profile_pids():
+ with contextlib.suppress(OSError):
+ os.kill(pid, signal.SIGKILL)
+ wait_for(lambda: not watcher_running(), 20.0, interval=0.2)
+ shutil.rmtree(root, ignore_errors=True)
+ return not root.exists()
+
+
# ── OpenCLI binding ──
@@ -349,7 +654,7 @@ def bound_context() -> Optional[str]:
def bind() -> dict:
- """Record which OpenCLI profile is the dedicated browser.
+ """Record which OpenCLI profile is the dedicated browser (Windows Web Store flow).
The first call snapshots profiles already connected (the user's own
Chrome). After the user installs the extension in the dedicated window,
@@ -372,6 +677,78 @@ def bind() -> dict:
return {"status": "waiting_for_extension"}
+def _ambiguous(candidates: List[str]):
+ from .result import NEED_SETUP, ReachError
+
+ return ReachError(
+ NEED_SETUP, f"more than one new OpenCLI profile connected: {', '.join(candidates)}",
+ hint="Ask the user to close other Chrome windows that have the OpenCLI extension, then run setup again.",
+ )
+
+
+def setup() -> dict:
+ """Make the dedicated browser ready with the OpenCLI extension loaded and bound; returns status().
+
+ macOS/Linux: fully automatic. Windows: opens the Web Store page and waits for the user's click.
+ Needs `opencli` installed (binding reads `opencli profile list`).
+ """
+ from .clock import off_the_clock
+
+ with off_the_clock():
+ ensure_chrome()
+ if not can_load_extension():
+ return _setup_from_store()
+ refresh_extension()
+ touch()
+ with start_lock():
+ ctx = bound_context()
+ if ctx and is_running() and watcher_running() and ctx in connected_contexts():
+ return status()
+ stop() # (re)launch so this browser connects fresh and we can tell it apart
+ if ctx: # let OpenCLI notice the old connection is gone before taking the snapshot
+ wait_for(lambda: ctx not in connected_contexts(), 10.0)
+ baseline = connected_contexts()
+ _launch("about:blank")
+ found: List[str] = []
+
+ def new_context() -> bool:
+ found[:] = [c for c in connected_contexts() if c not in baseline]
+ return len(found) == 1
+
+ if not wait_for(new_context, _remaining_start_wait(), interval=0.5):
+ from .result import UPSTREAM_BROKEN, ReachError
+
+ if found:
+ raise _ambiguous(found)
+ raise ReachError(
+ UPSTREAM_BROKEN, "the OpenCLI extension did not connect to OpenCLI in the Agent Reach browser",
+ hint=f"Details: {watcher_log_path()}. Check `opencli profile list` works.",
+ )
+ update_state(opencli_context=found[0], baseline=None)
+ touch()
+ return status()
+
+
+def _setup_from_store() -> dict:
+ from agent_reach.backends.opencli import OPENCLI_EXTENSION_URL
+
+ from .result import NEED_SETUP, ReachError
+
+ touch()
+ result = bind()
+ if result["status"] == "waiting_for_extension":
+ start(OPENCLI_EXTENSION_URL)
+ found = wait_for(lambda: result.update(bind()) or result["status"] != "waiting_for_extension", _STORE_WAIT)
+ if not found:
+ raise ReachError(
+ NEED_SETUP, "waiting for the OpenCLI extension in the Agent Reach browser",
+ hint="Ask the user to click 'Add to Chrome' in the window that just opened, then run `agent-reach browser setup` again.",
+ )
+ if result["status"] == "ambiguous":
+ raise _ambiguous(result["candidates"])
+ return status()
+
+
def status() -> dict:
ctx = bound_context()
running = is_running()
@@ -383,6 +760,8 @@ def status() -> dict:
connected = False
return {
"profile_dir": str(profile_dir()),
+ "chrome": chrome_binary(),
+ "extension_version": extension_version(),
"running": running,
"opencli_context": ctx,
"opencli_connected": connected,
@@ -391,7 +770,10 @@ def status() -> dict:
def setup_problems() -> List[str]:
- """What blocks browser-login channels right now (offline checks only)."""
- if not bound_context():
+ """What blocks browser-login channels right now (offline checks only).
+
+ macOS/Linux set the browser up by themselves on first use, so nothing blocks there.
+ """
+ if not can_load_extension() and not bound_context():
return ["Agent Reach browser not set up: run `agent-reach browser setup`"]
return []
diff --git a/agent_reach/runtime/browser_watcher.py b/agent_reach/runtime/browser_watcher.py
index 70330ce9..9da126fe 100644
--- a/agent_reach/runtime/browser_watcher.py
+++ b/agent_reach/runtime/browser_watcher.py
@@ -1,8 +1,15 @@
-"""Idle watcher for the Agent Reach browser (`python -m agent_reach.runtime.browser_watcher`).
+"""Owner and idle watcher of the Agent Reach browser (`python -m agent_reach.runtime.browser_watcher`).
-Started detached by runtime.browser when Agent Reach launches the browser.
-Holds ~/.agent-reach/browser/watcher.lock so only one runs; exits when the
-browser is gone, and closes it after `idle` seconds without Agent Reach use.
+Started detached by runtime.browser. Holds ~/.agent-reach/browser/watcher.lock
+so only one runs.
+
+With `--launch URL` (macOS/Linux) it starts Chrome itself with
+`--remote-debugging-pipe`, loads the OpenCLI extension over that pipe
+(`Extensions.loadUnpacked`, needed on every launch) and keeps the pipe open:
+Chrome exits when the pipe closes, so the browser lives exactly as long as
+this process. Without `--launch` (Windows) it only watches a browser started
+elsewhere. Either way it closes the browser after `idle` seconds without
+Agent Reach use and exits when the browser is gone.
"""
from __future__ import annotations
@@ -10,23 +17,84 @@ from __future__ import annotations
import argparse
import contextlib
import os
+import subprocess
+import sys
import time
from typing import Optional
from . import browser
-def watch(idle: Optional[float] = None, poll: float = 15.0) -> str:
+def _launch_with_pipe(chrome: str, url: str):
+ """Start Chrome with the CDP pipe on its fds 3 (commands in) and 4 (replies out)."""
+ import fcntl
+
+ from .cdp import PipeConnection
+
+ to_chrome_r, to_chrome_w = os.pipe()
+ from_chrome_r, from_chrome_w = os.pipe()
+ # Child ends above 4 so placing them on 3/4 never overwrites one with the other.
+ child_in = fcntl.fcntl(to_chrome_r, fcntl.F_DUPFD_CLOEXEC, 10)
+ child_out = fcntl.fcntl(from_chrome_w, fcntl.F_DUPFD_CLOEXEC, 10)
+ for fd in (to_chrome_r, from_chrome_w):
+ os.close(fd)
+
+ def place_pipe() -> None: # in the child, after fork: dup2 leaves 3/4 inheritable
+ os.dup2(child_in, 3)
+ os.dup2(child_out, 4)
+
+ try:
+ proc = subprocess.Popen(
+ browser.chrome_argv(chrome, url, pipe=True),
+ stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+ close_fds=False, # Python fds are non-inheritable by default; only 3/4 get through
+ preexec_fn=place_pipe, # noqa: PLW1509 - single-threaded here
+ start_new_session=True,
+ )
+ finally:
+ os.close(child_in)
+ os.close(child_out)
+ return proc, PipeConnection(to_chrome_w, from_chrome_r)
+
+
+def _load_extension(conn) -> None:
+ ext = browser.extension_dir()
+ if not (ext / "manifest.json").is_file():
+ print("OpenCLI extension missing; browser opened without it", file=sys.stderr, flush=True)
+ return
+ reply = conn.call("Extensions.loadUnpacked", {"path": str(ext)}, timeout=60)
+ if "result" in reply:
+ browser.update_state(extension_id=reply["result"].get("id"))
+ print(f"extension loaded: {reply['result'].get('id')}", file=sys.stderr, flush=True)
+ else:
+ print(f"Extensions.loadUnpacked failed: {reply.get('error')}", file=sys.stderr, flush=True)
+
+
+def watch(idle: Optional[float] = None, poll: float = 15.0, *, launch: Optional[str] = None,
+ chrome: Optional[str] = None) -> str:
"""Run until the browser is gone. Returns why it stopped."""
idle = browser.IDLE_LIMIT if idle is None else idle
fd = browser._open_lock(browser.watcher_lock_path())
+ proc = conn = None
try:
# A probe (watcher_running) holds the lock for an instant; a live watcher holds it for good.
- if not browser.wait_for(lambda: browser.try_lock(fd), 2.0, interval=0.1):
+ # A watcher of a browser that just closed may still be on its way out: give it a moment.
+ if not browser.wait_for(lambda: browser.try_lock(fd), 10.0 if launch else 2.0, interval=0.1):
return "another watcher is running"
+ if launch is not None:
+ if browser.is_running():
+ return "a browser is already using the debugging port"
+ proc, conn = _launch_with_pipe(chrome or browser.ensure_chrome(), launch)
+ _load_extension(conn)
began = time.time()
+
+ def gone() -> bool:
+ if conn is not None:
+ return conn.closed.is_set() or proc.poll() is not None
+ return not browser.is_running()
+
while True:
- if not browser.is_running():
+ if gone():
return "browser closed"
used = max(began, browser.last_used() or 0.0)
left = used + idle - time.time()
@@ -36,16 +104,32 @@ def watch(idle: Optional[float] = None, poll: float = 15.0) -> str:
if used + idle <= time.time() and browser.stop():
return "closed after idle"
left = poll # used again meanwhile, or close failed: check later
- time.sleep(min(poll, left + 0.5))
+ pause = min(poll, left + 0.5)
+ if conn is not None:
+ conn.closed.wait(pause) # wake the moment Chrome exits
+ else:
+ time.sleep(pause)
finally:
+ if conn is not None:
+ conn.close() # Chrome exits when its pipe closes
+ if proc is not None:
+ try:
+ proc.wait(15)
+ except subprocess.TimeoutExpired:
+ proc.kill()
+ proc.wait(5)
os.close(fd)
def main() -> None:
parser = argparse.ArgumentParser(prog="agent_reach.runtime.browser_watcher")
parser.add_argument("--idle", type=float, default=None, help="seconds without use before closing")
+ parser.add_argument("--launch", default=None, help="start Chrome with this URL and own it (macOS/Linux)")
+ parser.add_argument("--chrome", default=None, help="Chrome binary for --launch")
ns = parser.parse_args()
- watch(ns.idle)
+ reason = watch(ns.idle, launch=ns.launch, chrome=ns.chrome)
+ print(reason, file=sys.stderr, flush=True)
+ sys.exit(0 if reason in ("browser closed", "closed after idle") else 1)
if __name__ == "__main__":
diff --git a/agent_reach/runtime/cdp.py b/agent_reach/runtime/cdp.py
index 00f89d2f..23cdcd07 100644
--- a/agent_reach/runtime/cdp.py
+++ b/agent_reach/runtime/cdp.py
@@ -1,6 +1,8 @@
"""Minimal Chrome DevTools Protocol client for the Agent Reach browser (127.0.0.1 only).
Only used against the dedicated browser, never the user's own Chrome.
+Two transports: the 127.0.0.1 debugging port (`call`, any process) and the
+launch pipe (`PipeConnection`, only the idle watcher, which owns the browser).
"""
from __future__ import annotations
@@ -11,8 +13,9 @@ import json
import os
import socket
import struct
+import threading
import urllib.request
-from typing import List, Optional
+from typing import Dict, List, Optional
from urllib.parse import urlparse
from .browser import CDP_URL
@@ -109,8 +112,92 @@ def call(method: str, params: Optional[dict] = None) -> Optional[dict]:
return None
+def domain_matches(cookie_domain: str, domain: str) -> bool:
+ """`cookie_domain` is `domain` or one of its subdomains (".a.reddit.com" yes, "notreddit.com" no)."""
+ c, d = cookie_domain.lstrip(".").lower(), domain.lstrip(".").lower()
+ return c == d or c.endswith("." + d)
+
+
def cookies(domain: str) -> List[dict]:
"""Cookies the dedicated browser holds for `domain` (and its subdomains)."""
result = call("Storage.getCookies") or {}
- d = domain.lstrip(".")
- return [c for c in result.get("cookies", []) if c.get("domain", "").lstrip(".").endswith(d)]
+ return [c for c in result.get("cookies", []) if domain_matches(c.get("domain", ""), domain)]
+
+
+class PipeConnection:
+ """CDP over `--remote-debugging-pipe`: NUL-delimited JSON, we write `wfd`, read `rfd`.
+
+ A reader thread drains the pipe for as long as the browser lives (an
+ undrained pipe would stall Chrome); `closed` is set when Chrome exits.
+ Closing our write end makes Chrome exit.
+ """
+
+ def __init__(self, wfd: int, rfd: int) -> None:
+ self._wfd, self._rfd = wfd, rfd
+ self._lock = threading.Lock()
+ self._next_id = 0
+ self._waiting: Dict[int, list] = {}
+ self.closed = threading.Event()
+ threading.Thread(target=self._read_loop, name="cdp-pipe", daemon=True).start()
+
+ def _read_loop(self) -> None:
+ buf = b""
+ try:
+ while True:
+ chunk = os.read(self._rfd, 65536)
+ if not chunk:
+ break
+ buf += chunk
+ while b"\0" in buf:
+ raw, buf = buf.split(b"\0", 1)
+ try:
+ msg = json.loads(raw.decode("utf-8"))
+ except ValueError:
+ continue
+ with self._lock:
+ slot = self._waiting.get(msg.get("id")) if isinstance(msg, dict) else None
+ if slot is not None:
+ slot.append(msg)
+ slot[0].set()
+ except OSError:
+ pass
+ finally:
+ self.closed.set()
+ with self._lock:
+ for slot in self._waiting.values():
+ slot[0].set()
+
+ def call(self, method: str, params: Optional[dict] = None, timeout: float = 30.0) -> dict:
+ """Send one command; returns the whole reply ({"result": ...} or {"error": ...})."""
+ with self._lock:
+ self._next_id += 1
+ msg_id = self._next_id
+ slot: list = [threading.Event()]
+ self._waiting[msg_id] = slot
+ try:
+ if self.closed.is_set():
+ return {"error": {"message": "browser closed"}}
+ data = json.dumps({"id": msg_id, "method": method, "params": params or {}}).encode("utf-8") + b"\0"
+ try:
+ while data:
+ data = data[os.write(self._wfd, data):]
+ except OSError as exc:
+ return {"error": {"message": f"pipe write failed: {exc}"}}
+ if not slot[0].wait(timeout) or len(slot) < 2:
+ return {"error": {"message": "browser closed" if self.closed.is_set() else f"no reply in {timeout:.0f}s"}}
+ return slot[1]
+ finally:
+ with self._lock:
+ self._waiting.pop(msg_id, None)
+
+ def close(self) -> None:
+ """Close our write end (Chrome exits); the reader thread closes the read end when it stops."""
+ try:
+ os.close(self._wfd)
+ except OSError:
+ pass
+ if self.closed.wait(15):
+ try:
+ os.close(self._rfd)
+ except OSError:
+ pass
diff --git a/agent_reach/runtime/cli.py b/agent_reach/runtime/cli.py
index c140a75d..939b5005 100644
--- a/agent_reach/runtime/cli.py
+++ b/agent_reach/runtime/cli.py
@@ -8,6 +8,9 @@ Everything prints one JSON object to stdout so agents never parse prose; logs
go to stderr. Exit code 0 = ok, 1 = error. Exceptions for humans: `help`, and
`--text` on doctor / check. `login` shows the upstream's interactive
output (QR codes, prompts) on stderr so stdout still carries only the JSON.
+
+When a newer release is known (cached by a background check at most once a
+day, never waited on), every JSON object carries meta.update = {current, latest, notes}.
"""
from __future__ import annotations
@@ -48,13 +51,14 @@ For agents:
For the user:
agent-reach setup first run: install the default channels and the agent skill
- agent-reach add|remove <channel> install / remove an optional channel
+ agent-reach add <channel> add a channel; installs everything it needs, opens its login
+ agent-reach remove <channel> remove a channel (defaults too) and what only it used
agent-reach login|logout <channel> log in (the user does it) / forget the login
agent-reach browser setup|status the Agent Reach browser for browser-login channels
agent-reach skill [link <skills-dir>] where the agent skill is; link it for another AI
- agent-reach doctor [--text] status of every channel (no network)
+ agent-reach doctor [--text] status of every channel and installed tool versions (no network)
agent-reach check [channel] [--text] live-test channels
- agent-reach update [--check] upgrade Agent Reach, its tools and the skill
+ agent-reach update [--check] upgrade Agent Reach, every added channel's tools and the skill
agent-reach configure <key> [value] groq-key | openai-key | proxy | github-token
agent-reach uninstall [--dry-run] remove everything Agent Reach installed
"""
@@ -91,7 +95,18 @@ class _Parser(argparse.ArgumentParser):
raise _ArgError(message)
+#: Attach meta.update to JSON output (off for `update`, which reports versions itself).
+_SHOW_NOTICE = True
+
+
def _emit(payload: dict) -> int:
+ if _SHOW_NOTICE:
+ from .update_notice import notice
+
+ info = notice()
+ if info:
+ meta = payload.get("meta")
+ payload["meta"] = {**(meta if isinstance(meta, dict) else {}), "update": info}
sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
sys.stdout.flush()
return 0 if payload.get("ok") else 1
@@ -245,6 +260,10 @@ def _cmd_doctor(args: Sequence[str]) -> int:
if c["regressed"]:
extra = f"REGRESSED (worked at the previous check) {extra}"
sys.stdout.write(f"{c['status']:<12} {c['channel']:<12} {c['level']:<13} {extra}\n")
+ if result["tools"]:
+ sys.stdout.write("\nTools\n")
+ for t in result["tools"]:
+ sys.stdout.write(f"{t['tool']:<16} {str(t.get('version') or '?'):<12} {t.get('owner', '')}\n")
return 0
@@ -360,11 +379,9 @@ def _cmd_login(args: Sequence[str]) -> int:
browser.start(ch.login_url)
except ReachError as err:
return _emit(envelope(channel=ch.name, action="login", error=err))
- needs_sync = bool(ch.session) or type(ch).sync_login is not Channel.sync_login
- nxt = (
- f"After the user logs in, run `agent-reach login {ch.name} --sync`."
- if needs_sync else "The user logs in in that window; then retry the action."
- )
+ from . import manage
+
+ nxt = manage.browser_login_next(ch)
return _emit(envelope(channel=ch.name, action="login", backend="agent-reach-browser",
items=[{"opened": ch.login_url, "next": nxt}]))
try:
@@ -413,8 +430,6 @@ def _cmd_logout(args: Sequence[str]) -> int:
def _cmd_browser(args: Sequence[str]) -> int:
- from agent_reach.backends.opencli import OPENCLI_EXTENSION_URL
-
parser = _Parser(prog="browser", add_help=False)
parser.add_argument("op", choices=("setup", "status"))
try:
@@ -423,30 +438,25 @@ def _cmd_browser(args: Sequence[str]) -> int:
return _bad_input(None, "browser", f"{exc}; usage: agent-reach browser setup|status")
action = f"browser {ns.op}"
try:
- if ns.op == "setup":
- browser.touch()
- result = browser.bind()
- if result["status"] == "waiting_for_extension":
- browser.start(OPENCLI_EXTENSION_URL)
- raise ReachError(
- NEED_SETUP, "waiting for the OpenCLI extension in the Agent Reach browser",
- hint="Ask the user to click 'Add to Chrome' in the window that just opened, then run `agent-reach browser setup` again.",
- )
- if result["status"] == "ambiguous":
- raise ReachError(
- NEED_SETUP, f"more than one new OpenCLI profile connected: {', '.join(result['candidates'])}",
- hint="Ask the user to close other Chrome windows that have the OpenCLI extension, then run setup again.",
- )
+ item = browser.setup() if ns.op == "setup" else browser.status()
except ReachError as err:
return _emit(envelope(channel=None, action=action, error=err))
- return _emit(envelope(channel=None, action=action, backend="agent-reach-browser", items=[browser.status()]))
+ return _emit(envelope(channel=None, action=action, backend="agent-reach-browser", items=[item]))
def main(argv: Sequence[str]) -> int:
+ global _SHOW_NOTICE
+
if not argv or argv[0] in ("help", "-h", "--help"):
sys.stdout.write(HELP)
return 0
+ from . import tools, update_notice
+
+ tools.extend_path()
+ _SHOW_NOTICE = argv[0] != "update"
+ if argv[0] not in ("update", "uninstall"):
+ update_notice.maybe_refresh()
_apply_saved_proxy()
head, rest = argv[0], argv[1:]
if head == "channels":
diff --git a/agent_reach/runtime/manage.py b/agent_reach/runtime/manage.py
index 5d3322eb..4722557d 100644
--- a/agent_reach/runtime/manage.py
+++ b/agent_reach/runtime/manage.py
@@ -11,37 +11,22 @@ import os
import shutil
import subprocess
import sys
-import urllib.request
from pathlib import Path
from typing import Dict, List, Optional
+from urllib.parse import urlparse
from agent_reach import __version__
from agent_reach.utils.paths import home_dir
-from . import state, tools
+from . import state, tools, update_notice
from .result import BAD_INPUT, NEED_SETUP, UPSTREAM_BROKEN, ReachError
-REPO = "Panniantong/Agent-Reach"
+REPO = update_notice.REPO
CHECK_FRESH_SECONDS = 24 * 3600
-
-def _chrome_present() -> bool:
- from .browser import chrome_binary
-
- return chrome_binary() is not None
-
-
-# ── prerequisites we only check and explain ──
-
-PREREQS: Dict[str, dict] = {
- "node": {"check": lambda: bool(shutil.which("node") and shutil.which("npm")),
- "hint": "Install Node.js: https://nodejs.org (macOS: brew install node)"},
- "git": {"check": lambda: bool(shutil.which("git")), "hint": "Install git (macOS: xcode-select --install)"},
- "chrome": {"check": lambda: _chrome_present(), "hint": "Install Google Chrome: https://www.google.com/chrome"},
- "ffmpeg": {"check": lambda: bool(shutil.which("ffmpeg")), "hint": "Install ffmpeg (macOS: brew install ffmpeg)"},
- "uv": {"check": lambda: bool(shutil.which("uvx")),
- "hint": "Install uv: https://docs.astral.sh/uv/getting-started/installation/"},
-}
+#: Machine prerequisites a channel may list in `prereqs` (keys of tools.TOOLS).
+#: `add` installs them when the machine has none, without an admin password.
+PREREQS = ("node", "uv", "ffmpeg", "chrome")
def _channels():
@@ -59,17 +44,46 @@ def _channel(name: str):
def is_added(ch, data: Optional[dict] = None) -> bool:
- return ch.level == "default" or ch.name in (data or state.load())["channels"]
+ data = data or state.load()
+ if ch.name in data["channels"]:
+ return True
+ return ch.level == "default" and ch.name not in data["removed_defaults"]
+
+
+def _uses_browser(ch) -> bool:
+ return bool(ch.login_url)
-def missing_prereqs(ch) -> List[str]:
- return [p for p in ch.prereqs if not PREREQS[p]["check"]()]
+def channel_tools(ch) -> List[str]:
+ """Everything `add` installs for the channel, prerequisites first."""
+ names = list(ch.prereqs) + (["chrome"] if _uses_browser(ch) else []) + list(ch.tools)
+ return list(dict.fromkeys(names))
+
+
+def site_domains(ch) -> List[str]:
+ """Cookie domains of the channel's site in the Agent Reach browser."""
+ if getattr(ch, "domains", ()):
+ return list(ch.domains)
+ host = (urlparse(ch.login_url).hostname or "").lower()
+ if host.startswith("www."):
+ host = host[4:]
+ return [host] if host else []
def _has_login(ch) -> bool:
return bool(ch.login_url or ch.login_argv or ch.logout_keys)
+def browser_login_next(ch) -> str:
+ """The single sentence for the user after the login page opened in the Agent Reach browser."""
+ from agent_reach.channels.base import Channel
+
+ needs_sync = bool(ch.session) or type(ch).sync_login is not Channel.sync_login
+ if needs_sync:
+ return (f"The user logs in to {ch.name} in the Agent Reach browser window that just opened; "
+ f"then run `agent-reach login {ch.name} --sync`.")
+ return f"The user logs in to {ch.name} in the Agent Reach browser window that just opened; then retry the action."
+
# ── checks ──
def run_checks(names: Optional[List[str]] = None, timeout: float = 60.0) -> dict:
@@ -128,9 +142,7 @@ def regressed(check: Optional[dict]) -> bool:
def channel_status(ch, data: dict) -> dict:
if not is_added(ch, data):
return {"status": "not_added", "problems": [], "hint": f"agent-reach add {ch.name}"}
- problems = [f"missing {p}: {PREREQS[p]['hint']}" for p in missing_prereqs(ch)]
- problems += [f"{t} not installed: run `agent-reach add {ch.name}`" for t in ch.tools
- if not tools.resolve(tools.TOOLS[t].commands[0])]
+ problems = [f"{t} not installed: run `agent-reach add {ch.name}`" for t in channel_tools(ch) if not tools.present(t)]
problems += ch.setup_problems()
if problems:
return {"status": "needs_setup", "problems": problems}
@@ -154,37 +166,76 @@ def doctor() -> dict:
for ch in _channels():
channels.append({"channel": ch.name, "level": ch.level, **channel_status(ch, data),
"regressed": regressed(data["checks"].get(ch.name))})
- return {"version": __version__, "channels": channels}
+ return {"version": __version__, "channels": channels, "tools": tools.recorded()}
# ── add / remove ──
+def _install_channel(ch, *, allow_upgrade: bool = False) -> List[dict]:
+ installed = [tools.ensure(t, allow_upgrade=allow_upgrade) for t in channel_tools(ch)]
+ ch.on_add()
+ return installed
+
+
+def _sentence(text: str) -> str:
+ text = text.strip()
+ return text if text.endswith((".", "。")) else text + "."
+
+
+def _next_step(ch) -> Optional[str]:
+ """What the user still does after `add`, as one plain sentence (None = nothing).
+
+ Browser-login channels: the Agent Reach browser is made ready (extension
+ loaded and bound) and the login page opened; the user only logs in there.
+ """
+ if _uses_browser(ch):
+ from . import browser
+
+ try:
+ if "opencli" in channel_tools(ch):
+ browser.setup()
+ browser.start(ch.login_url)
+ except ReachError as err:
+ return _sentence(err.hint or err.message)
+ return browser_login_next(ch)
+ parts = [_sentence(p) for p in ch.setup_problems()]
+ if ch.login_argv:
+ parts.append(f"The user logs in to {ch.name}: run `agent-reach login {ch.name}`.")
+ return " ".join(parts) or None
+
+
def add(name: str, *, allow_upgrade: bool = False) -> dict:
+ """Install whatever the channel needs (prerequisites included), add it, open its login."""
ch = _channel(name)
- missing = missing_prereqs(ch)
- if missing:
- raise ReachError(NEED_SETUP, f"missing prerequisites: {', '.join(missing)}",
- hint="; ".join(PREREQS[p]["hint"] for p in missing))
- installed = [tools.ensure(t, allow_upgrade=allow_upgrade) for t in ch.tools]
- ch.on_add()
+ installed = _install_channel(ch, allow_upgrade=allow_upgrade)
data = state.load()
data["channels"][name] = {"added_at": state.now()}
+ data["removed_defaults"] = [n for n in data["removed_defaults"] if n != name]
state.save(data)
- nxt = list(ch.setup_problems())
- if _has_login(ch):
- nxt.append(f"log in: `agent-reach login {name}`")
- return {"channel": name, "added": True, "tools": installed, "next": nxt}
+ return {"channel": name, "added": True, "tools": installed, "next": _next_step(ch)}
+
+
+def _needed_tools(data: dict) -> set:
+ return tools.closure(t for c in _channels() if is_added(c, data) for t in channel_tools(c))
+
+
+def _prune(data: dict) -> List[str]:
+ """Remove our tools no added channel uses."""
+ return tools.prune(_needed_tools(data))
def remove(name: str) -> dict:
- ch = _channel(name)
- if ch.level == "default":
- raise ReachError(BAD_INPUT, f"{name} is a default channel and cannot be removed")
+ """Remove a channel (defaults too) and everything only it used."""
+ from . import browser
from .sessions import clear_session
+ ch = _channel(name)
data = state.load()
- was_added = data["channels"].pop(name, None) is not None
+ was_added = is_added(ch, data)
+ data["channels"].pop(name, None)
data["checks"].pop(name, None)
+ if ch.level == "default" and name not in data["removed_defaults"]:
+ data["removed_defaults"].append(name)
state.save(data)
ch.on_remove()
if ch.session:
@@ -196,9 +247,19 @@ def remove(name: str) -> dict:
for key in ch.logout_keys:
if cfg.get(key):
cfg.delete(key)
- still_needed = {t for c in _channels() if c.name != name and is_added(c, data) for t in c.tools}
- removed_tools = [t for t in ch.tools if t not in still_needed and tools.remove_private(t)]
- return {"channel": name, "removed": was_added, "removed_tools": removed_tools}
+ cookies, browser_deleted, warnings = 0, False, []
+ if _uses_browser(ch):
+ others = [c for c in _channels() if c.name != name and _uses_browser(c) and is_added(c, data)]
+ try:
+ if others:
+ if browser.profile_dir().is_dir():
+ cookies = browser.clear_site(site_domains(ch))
+ else:
+ browser_deleted = browser.delete_profile()
+ except ReachError as err:
+ warnings.append(err.message)
+ return {"channel": name, "removed": was_added, "removed_tools": _prune(data),
+ "cleared_cookies": cookies, "browser_deleted": browser_deleted, "warnings": warnings}
# ── skill (the agent-facing instructions) ──
@@ -468,35 +529,31 @@ def migrate() -> dict:
}
+def _optional_entry(c) -> dict:
+ """What the user must do for an optional channel; installs happen by themselves."""
+ needs = (["login"] if (c.login_url or c.login_argv) else []) + ([c.needs_key] if c.needs_key else [])
+ return {"channel": c.name, "level": c.level, "add": f"agent-reach add {c.name}", "needs": needs}
+
+
def setup() -> dict:
+ """Add the default channels (except ones the user removed) and place the skill."""
migration = migrate() if not state.exists() and (state.root() / "config.yaml").exists() else None
if not state.exists():
state.save(state.load())
skill = place_skill()
- defaults = [c for c in _channels() if c.level == "default"]
+ data = state.load()
+ defaults = [c for c in _channels() if c.level == "default" and is_added(c, data)]
added = []
for ch in defaults:
try:
- out = add(ch.name)
- added.append({"channel": ch.name, "ok": True, "tools": out["tools"]})
+ added.append({"channel": ch.name, "ok": True, "tools": _install_channel(ch)})
except ReachError as err:
added.append({"channel": ch.name, "ok": False, "tools": [],
"error": {"code": err.code, "message": err.message, "hint": err.hint}})
- needed = list(dict.fromkeys(p for ch in defaults for p in ch.prereqs))
- prereqs = {}
- for p in needed:
- ok = PREREQS[p]["check"]()
- prereqs[p] = {"ok": ok, **({} if ok else {"hint": PREREQS[p]["hint"]})}
- optional = [
- {"channel": c.name, "level": c.level, "add": f"agent-reach add {c.name}",
- "needs": list(c.prereqs) + (["login"] if (c.login_url or c.login_argv) else [])
- + ([c.needs_key] if c.needs_key else [])}
- for c in _channels() if c.level != "default"
- ]
+ optional = [_optional_entry(c) for c in _channels() if not is_added(c, data)]
return {
"version": __version__,
"default_channels": added,
- "prerequisites": prereqs,
"skill": skill,
"optional_channels": optional,
"logins": [{"channel": c.name, "command": f"agent-reach login {c.name}"} for c in defaults if _has_login(c)],
@@ -506,27 +563,21 @@ def setup() -> dict:
# ── update ──
-def _version_tuple(v: str) -> tuple:
- try:
- return tuple(int(x) for x in v.strip().lstrip("v").split("."))
- except ValueError:
- return ()
-
-
def update_check() -> dict:
+ """Live check of the latest release; also refreshes the background notice cache."""
try:
- req = urllib.request.Request(f"https://api.github.com/repos/{REPO}/releases/latest",
- headers={"User-Agent": "agent-reach", "Accept": "application/vnd.github+json"})
- with urllib.request.urlopen(req, timeout=15) as resp:
- rel = json.loads(resp.read())
+ rel = update_notice.fetch_latest(timeout=15)
except Exception as exc: # noqa: BLE001
raise ReachError(UPSTREAM_BROKEN, f"could not reach GitHub: {exc}") from None
- latest = str(rel.get("tag_name", "")).lstrip("v")
+ try:
+ update_notice.write_cache(rel)
+ except OSError:
+ pass
return {
"current": __version__,
- "latest": latest,
- "update_available": _version_tuple(latest) > _version_tuple(__version__),
- "notes": (rel.get("body") or "")[:2000],
+ "latest": rel["latest"],
+ "update_available": update_notice.version_tuple(rel["latest"]) > update_notice.version_tuple(__version__),
+ "notes": rel["notes"],
}
@@ -556,25 +607,66 @@ def upgrade_command(version: str) -> List[str]:
UNINSTALL_PROGRAM = "uv tool uninstall agent-reach"
+def _ordered_tools(names) -> List[str]:
+ """Tools plus what they need, dependencies first, each once."""
+ out: List[str] = []
+
+ def visit(n: str) -> None:
+ if n in out or n not in tools.TOOLS:
+ return
+ for d in tools.TOOLS[n].needs:
+ visit(d)
+ out.append(n)
+
+ for n in names:
+ visit(n)
+ return out
+
+
def sync() -> dict:
- """After the program itself changed: bring tools to this version's pins, refresh the skill."""
+ """Bring every added channel's tools to their latest allowed version, prune unused
+ tools, drop channels this version no longer has, refresh the skill.
+
+ `user_actions` are plain sentences for what the user must do now.
+ """
migration = migrate() if not state.exists() else None
data = state.load()
- synced, problems = [], []
- for ch in _channels():
- if not is_added(ch, data):
+ known = {c.name for c in _channels()}
+ dropped = sorted(set(data["channels"]) - known)
+ for n in dropped:
+ data["channels"].pop(n, None)
+ data["checks"].pop(n, None)
+ data["removed_defaults"] = [n for n in data["removed_defaults"] if n in known]
+ state.save(data)
+ actions = [f"The {n} channel is no longer part of Agent Reach and was removed." for n in dropped]
+ added = [c for c in _channels() if is_added(c, data)]
+ synced, problems, failed = [], [], set()
+ for t in _ordered_tools(t for c in added for t in channel_tools(c)):
+ try:
+ synced.append(tools.ensure(t, upgrade=True))
+ except ReachError as err:
+ failed.add(t)
+ problems.append({"tool": t, "code": err.code, "message": err.message, "hint": err.hint})
+ for c in added:
+ bad = [t for t in channel_tools(c) if t in failed]
+ if bad:
+ hint = next((p["hint"] for p in problems if p["tool"] in bad and p.get("hint")), None)
+ actions.append(_sentence(f"{c.name} could not update {', '.join(bad)}" + (f": {hint}" if hint else "")))
continue
- for t in ch.tools:
- try:
- synced.append(tools.ensure(t))
- except ReachError as err:
- problems.append({"tool": t, "code": err.code, "message": err.message, "hint": err.hint})
- ch.on_add()
- return {"version": __version__, "tools": synced, "problems": problems,
- "skill": place_skill(), "migration": migration}
+ try:
+ c.on_add()
+ except ReachError as err:
+ actions.append(_sentence(f"{c.name}: {err.hint or err.message}"))
+ actions += [_sentence(f"{c.name}: {p}") for p in c.setup_problems()]
+ check = data["checks"].get(c.name) or {}
+ if "NEED_LOGIN" in (check.get("codes") or {}).values():
+ actions.append(f"The user needs to log in to {c.name} again: run `agent-reach login {c.name}`.")
+ return {"version": __version__, "tools": synced, "problems": problems, "removed_tools": _prune(state.load()),
+ "dropped_channels": dropped, "user_actions": actions, "skill": place_skill(), "migration": migration}
def update(check_only: bool = False) -> dict:
+ """Upgrade Agent Reach when a release is newer, then upgrade every added channel's tools."""
info = update_check()
if check_only:
return info
@@ -587,26 +679,31 @@ def update(check_only: bool = False) -> dict:
hint=f"Reinstall once with uv: `{' '.join(cmd)}`, then remove the old copy "
"(e.g. `pipx uninstall agent-reach` or `pip uninstall agent-reach`).",
)
+ run = [tools.resolve("uv") or cmd[0], *cmd[1:]]
try:
- proc = subprocess.run(cmd, capture_output=True, text=True, timeout=900)
+ proc = subprocess.run(run, capture_output=True, text=True, timeout=900)
except FileNotFoundError:
- raise ReachError(NEED_SETUP, "uv is not on PATH", hint=PREREQS["uv"]["hint"]) from None
+ raise ReachError(NEED_SETUP, "uv is not on PATH",
+ hint="Install uv: https://docs.astral.sh/uv/getting-started/installation/") from None
if proc.returncode != 0:
raise ReachError(UPSTREAM_BROKEN, f"upgrade failed: {proc.stderr.strip()[-300:]}",
hint=f"Run manually: {' '.join(cmd)}")
exe = shutil.which("agent-reach") or sys.argv[0]
out = subprocess.run([exe, "update", "--sync-only"], capture_output=True, text=True, timeout=1800)
try:
- synced = json.loads(out.stdout.strip().splitlines()[-1]).get("result")
+ synced = json.loads(out.stdout.strip().splitlines()[-1]).get("result") or {}
except (ValueError, IndexError):
synced = {"raw": out.stdout[-500:]}
- return {**info, "upgraded": True, "method": method, "sync": synced}
- return {**info, "upgraded": False, "method": method, "sync": sync()}
+ return {**info, "upgraded": True, "method": method, "sync": synced,
+ "user_actions": synced.get("user_actions", [])}
+ synced = sync()
+ return {**info, "upgraded": False, "method": method, "sync": synced, "user_actions": synced["user_actions"]}
# ── uninstall ──
-_OWNED = ("config.yaml", "state.json", "mcporter.json", "sessions", "browser")
+_OWNED = ("config.yaml", "state.json", "mcporter.json", "sessions", "browser",
+ "update-check.json", "update-check.started")
def uninstall(dry_run: bool = False) -> dict:
@@ -615,7 +712,7 @@ def uninstall(dry_run: bool = False) -> dict:
root = state.root()
targets = _skill_uninstall_targets() # before state.json goes: it records the links
targets += [root / n for n in _OWNED]
- targets += [tools.tool_dir(n) for n in tools.TOOLS] + [root / "tools" / "xiaoyuzhou"]
+ targets += [tools.tool_dir(n) for n in tools.TOOLS] + [tools.npm_global_dir(), root / "tools" / "xiaoyuzhou"]
targets = [t for t in targets if t.exists() or t.is_symlink()]
globals_ = tools.uninstall_global_owned(dry_run=True)
if not dry_run:
diff --git a/agent_reach/runtime/state.py b/agent_reach/runtime/state.py
index cfac72e7..8bec517e 100644
--- a/agent_reach/runtime/state.py
+++ b/agent_reach/runtime/state.py
@@ -3,12 +3,15 @@
{
"version": 1,
"channels": {"bilibili": {"added_at": "..."}},
- "tools": {"bili-cli": {"spec": "...", "owner": "agent-reach" | "user", "scope": "private" | "global"}},
+ "removed_defaults": ["youtube"],
+ "tools": {"bili-cli": {"owner": "agent-reach" | "user", "scope": "private" | "global", "version": "0.6.2"}},
"checks": {"bilibili": {"at": "...", "actions": {"search": true}, "previous": {"search": true}}},
"skill": {"links": [{"agent": "claude-code", "path": "...", "kind": "link" | "copy"}]}
}
-`owner` decides what uninstall may delete: only "agent-reach" entries.
+`owner` decides what remove/sync/uninstall may delete: only "agent-reach" entries.
+`version` is the version actually installed (tools are not pinned).
+`removed_defaults` are default channels the user removed; setup and update leave them out.
`skill.links` are the skill links/copies we made; update refreshes them, uninstall removes them.
"""
@@ -51,6 +54,8 @@ def load() -> dict:
for key in ("channels", "tools", "checks", "skill"):
data.setdefault(key, {})
data["skill"].setdefault("links", [])
+ if not isinstance(data.get("removed_defaults"), list):
+ data["removed_defaults"] = []
return data
diff --git a/agent_reach/runtime/tools.py b/agent_reach/runtime/tools.py
index 8ff2c96f..d1e9555b 100644
--- a/agent_reach/runtime/tools.py
+++ b/agent_reach/runtime/tools.py
@@ -1,57 +1,78 @@
-"""Upstream tools Agent Reach installs, at pinned versions.
+"""Upstream tools and machine prerequisites Agent Reach installs, at their latest allowed version.
-Two kinds:
-- private: installed into ~/.agent-reach/tools/<name>/ (its own venv or npm
+Versions are not pinned. Each tool may set `floor` (oldest version we accept)
+and `exclude` (known-bad versions, added in a release when an upstream breaks);
+the install asks the package manager for the newest version inside those limits.
+state.json records the version actually installed.
+
+Kinds:
+- pip / npm: private, under ~/.agent-reach/tools/<name>/ (own venv or npm
prefix). Never on the user's PATH; the user's own copy, if any, is untouched.
-- singleton: tools that can only exist once per machine (OpenCLI owns a fixed
- daemon port and a Chrome extension). If the user already has one that is new
- enough we use theirs; if it is too old we upgrade only with explicit consent;
- if it is missing we install it globally and record it as ours.
+- singleton (npm): can only exist once per machine (OpenCLI owns a fixed daemon
+ port and a Chrome extension). A user copy inside the limits is used as is; an
+ out-of-limits user copy is upgraded only with explicit consent; when missing
+ it is installed into ~/.agent-reach/tools/npm-global/ and recorded as ours.
+- prerequisites (node, uv, ffmpeg, chrome): the system copy is used when there
+ is one; otherwise a private copy is installed without an admin password.
"""
from __future__ import annotations
+import json
import os
+import platform
import re
import shutil
import subprocess
import sys
+import tempfile
+import urllib.request
from dataclasses import dataclass
from pathlib import Path
-from typing import Optional, Tuple
+from typing import Dict, Iterable, List, Optional, Set, Tuple
from . import state
from .result import NEED_SETUP, UPSTREAM_BROKEN, ReachError
+OURS = "agent-reach"
+
@dataclass(frozen=True)
class Tool:
name: str
- kind: str # "pip" | "npm"
- spec: str # pinned install spec
- commands: Tuple[str, ...] # executables it provides
+ kind: str # "pip" | "npm" | "ffmpeg" | "node" | "uv" | "chrome"
+ package: str # pip requirement / npm package name ("" for prerequisites)
+ commands: Tuple[str, ...] # executables it provides
singleton: bool = False
- min_version: str = "" # singleton only: oldest user copy we accept
+ floor: str = "" # oldest acceptable version
+ exclude: Tuple[str, ...] = () # known-bad versions
+ needs: Tuple[str, ...] = () # tools that must be installed first
-TOOLS = {
+TOOLS: Dict[str, Tool] = {
t.name: t
for t in (
- Tool("bili-cli", "pip", "bilibili-cli==0.6.2", ("bili",)),
+ Tool("bili-cli", "pip", "bilibili-cli", ("bili",)),
Tool(
"boss-agent-cli", "pip",
- "boss-agent-cli @ git+https://github.com/can4hou6joeng4/boss-agent-cli.git"
- "@4c991b77086a203173bf08a4cb64a23af6514fe6",
+ "boss-agent-cli @ https://github.com/can4hou6joeng4/boss-agent-cli/archive/HEAD.zip",
("boss",),
),
- Tool("mcporter", "npm", "[email protected]", ("mcporter",)),
- Tool("opencli", "npm", "@jackwener/[email protected]", ("opencli",), singleton=True, min_version="1.8.6"),
+ Tool("mcporter", "npm", "mcporter", ("mcporter",), needs=("node",)),
+ Tool("opencli", "npm", "@jackwener/opencli", ("opencli",), singleton=True, floor="1.8.6", needs=("node",)),
+ Tool("ffmpeg", "ffmpeg", "imageio-ffmpeg", ("ffmpeg",)),
+ Tool("node", "node", "", ("node", "npm", "npx")),
+ Tool("uv", "uv", "", ("uv", "uvx")),
+ Tool("chrome", "chrome", "", ()),
)
}
#: Command name → tool, for resolving executables.
_BY_COMMAND = {c: t for t in TOOLS.values() for c in t.commands}
+_SAFE_NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+_WIN = os.name == "nt"
+
def tools_root() -> Path:
return state.root() / "tools"
@@ -61,12 +82,50 @@ def tool_dir(name: str) -> Path:
return tools_root() / name
+def npm_global_dir() -> Path:
+ """Prefix for singletons we install (`npm -g --prefix`): no admin rights needed."""
+ return tools_root() / "npm-global"
+
+
+def _exe(name: str) -> str:
+ return name + (".exe" if _WIN else "")
+
+
+def _node_bin_dir() -> Path:
+ base = tool_dir("node") / "current"
+ return base if _WIN else base / "bin"
+
+
+def _npm_global_bin() -> Path:
+ return npm_global_dir() if _WIN else npm_global_dir() / "bin"
+
+
def _private_bin(tool: Tool, command: str) -> Path:
base = tool_dir(tool.name)
if tool.kind == "pip":
- sub = "Scripts" if os.name == "nt" else "bin"
- return base / "venv" / sub / (command + (".exe" if os.name == "nt" else ""))
- return base / "node_modules" / ".bin" / (command + (".cmd" if os.name == "nt" else ""))
+ return base / "venv" / ("Scripts" if _WIN else "bin") / _exe(command)
+ if tool.kind == "npm":
+ return base / "node_modules" / ".bin" / (command + (".cmd" if _WIN else ""))
+ if tool.kind == "node":
+ return _node_bin_dir() / (command + (".cmd" if _WIN and command != "node" else ".exe" if _WIN else ""))
+ if tool.kind in ("uv", "ffmpeg"):
+ return base / "bin" / _exe(command)
+ return base / command
+
+
+def bin_dirs() -> List[Path]:
+ """Private bin folders that exist (node, our npm -g prefix, uv, ffmpeg)."""
+ dirs = [_node_bin_dir(), _npm_global_bin(), tool_dir("uv") / "bin", tool_dir("ffmpeg") / "bin"]
+ return [d for d in dirs if d.is_dir()]
+
+
+def extend_path() -> None:
+ """Append our private bin folders to PATH (system copies still win), so that
+ upstream scripts find node/uvx/ffmpeg and children we start inherit them."""
+ parts = os.environ.get("PATH", "").split(os.pathsep)
+ extra = [str(d) for d in bin_dirs() if str(d) not in parts]
+ if extra:
+ os.environ["PATH"] = os.pathsep.join([p for p in parts if p] + extra)
def resolve(command: str) -> Optional[str]:
@@ -76,16 +135,88 @@ def resolve(command: str) -> Optional[str]:
private = _private_bin(tool, command)
if private.exists():
return str(private)
- return shutil.which(command)
+ found = shutil.which(command)
+ if found or not tool or not tool.singleton:
+ return found
+ ours = _npm_global_bin() / (command + (".cmd" if _WIN else ""))
+ return str(ours) if ours.exists() else None
+def ffmpeg_path() -> Optional[str]:
+ return resolve("ffmpeg")
+
+
+def present(name: str) -> bool:
+ """Is the tool usable right now (ours or the system's)? Offline."""
+ tool = TOOLS[name]
+ if tool.kind == "chrome":
+ from .browser import chrome_binary
+
+ return chrome_binary() is not None
+ return all(resolve(c) for c in tool.commands)
+
+
+# ── versions ──
+
def _version_tuple(text: str) -> tuple:
m = re.search(r"(\d+)\.(\d+)\.(\d+)", text or "")
return tuple(int(x) for x in m.groups()) if m else ()
-def installed_version(tool: Tool) -> Optional[str]:
- exe = resolve(tool.commands[0])
+def allowed(tool: Tool, version: Optional[str]) -> bool:
+ v = _version_tuple(version or "")
+ if not v:
+ return False
+ if tool.floor and v < _version_tuple(tool.floor):
+ return False
+ return not any(v == _version_tuple(x) for x in tool.exclude)
+
+
+def install_spec(tool: Tool) -> str:
+ """What the package manager is asked for: the newest version inside floor/exclude."""
+ if tool.kind in ("pip", "ffmpeg"):
+ cons = ([f">={tool.floor}"] if tool.floor else []) + [f"!={x}" for x in tool.exclude]
+ if " @ " in tool.package or not cons:
+ return tool.package
+ return tool.package + ",".join(cons)
+ # npm: a range made of the gaps between excluded versions
+ bad = sorted(set(tool.exclude), key=_version_tuple)
+ lower, parts = f">={tool.floor}" if tool.floor else ">=0.0.0", []
+ for x in bad:
+ parts.append(f"{lower} <{x}")
+ lower = f">{x}"
+ parts.append(lower)
+ rng = " || ".join(parts)
+ return tool.package if rng == ">=0.0.0" else f"{tool.package}@{rng}"
+
+
+def _dist_name(tool: Tool) -> str:
+ return re.split(r"[\s@<>=!~\[;]", tool.package, 1)[0]
+
+
+def _pip_version(tool: Tool) -> Optional[str]:
+ want = re.sub(r"[-_.]+", "_", _dist_name(tool)).lower()
+ venv = tool_dir(tool.name) / "venv"
+ sites = [venv / "Lib" / "site-packages"] if _WIN else sorted((venv / "lib").glob("python*/site-packages"))
+ for site in sites:
+ for d in site.glob("*.dist-info"):
+ name, _, ver = d.name[: -len(".dist-info")].partition("-")
+ if re.sub(r"[-_.]+", "_", name).lower() == want:
+ return ver
+ return None
+
+
+def _npm_version(prefix: Path, package: str) -> Optional[str]:
+ """Version from package.json under a local prefix (node_modules) or an -g prefix (lib/node_modules)."""
+ for base in (prefix / "node_modules", prefix / "lib" / "node_modules"):
+ try:
+ return json.loads((base / package / "package.json").read_text("utf-8")).get("version")
+ except (OSError, ValueError):
+ continue
+ return None
+
+
+def _command_version(exe: Optional[str]) -> Optional[str]:
if not exe:
return None
try:
@@ -96,12 +227,26 @@ def installed_version(tool: Tool) -> Optional[str]:
return m.group(0) if m else None
+def installed_version(tool: Tool) -> Optional[str]:
+ """Version of the copy `resolve` would use (singletons: whichever is on PATH)."""
+ return _command_version(resolve(tool.commands[0]))
+
+
+def _private_version(tool: Tool) -> Optional[str]:
+ if tool.kind in ("pip", "ffmpeg"):
+ return _pip_version(tool)
+ if tool.kind == "npm":
+ return _npm_version(tool_dir(tool.name), tool.package)
+ return _command_version(str(_private_bin(tool, tool.commands[0])))
+
+
+# ── installing ──
+
def _install_env() -> dict:
"""pip and npm only read proxy env vars; hand them the OS proxy (e.g. the macOS system proxy) when none is set."""
+ extend_path()
env = dict(os.environ)
if not (env.get("HTTPS_PROXY") or env.get("https_proxy")):
- import urllib.request
-
found = urllib.request.getproxies()
proxy = found.get("https") or found.get("http")
if proxy:
@@ -109,91 +254,320 @@ def _install_env() -> dict:
return env
-def _run(argv, timeout: float = 600) -> None:
+def _run(argv, timeout: float = 600, env: Optional[dict] = None) -> str:
+ run_env = _install_env()
+ run_env.update(env or {})
try:
- proc = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, env=_install_env())
+ proc = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, env=run_env)
except FileNotFoundError:
raise ReachError(NEED_SETUP, f"{Path(argv[0]).name} is not installed") from None
except subprocess.TimeoutExpired:
- raise ReachError(UPSTREAM_BROKEN, f"installing timed out: {' '.join(argv[:3])}") from None
+ raise ReachError(UPSTREAM_BROKEN, f"installing timed out: {' '.join(map(str, argv[:3]))}") from None
if proc.returncode != 0:
last = next((ln for ln in reversed(proc.stderr.splitlines()) if ln.strip()), "")
raise ReachError(UPSTREAM_BROKEN, f"install failed: {last[:300]}")
+ return proc.stdout
-def _install(tool: Tool, *, global_: bool = False) -> None:
- if tool.kind == "pip":
- venv = tool_dir(tool.name) / "venv"
- shutil.rmtree(venv, ignore_errors=True)
- venv.parent.mkdir(parents=True, exist_ok=True)
- _run([sys.executable, "-m", "venv", str(venv)])
- py = venv / ("Scripts/python.exe" if os.name == "nt" else "bin/python")
- _run([str(py), "-m", "pip", "install", "--quiet", "--disable-pip-version-check", tool.spec])
- return
- npm = shutil.which("npm")
+def _download(url: str, dest: Path, timeout: float = 600) -> None:
+ proxy = _install_env().get("HTTPS_PROXY")
+ handlers = [urllib.request.ProxyHandler({"https": proxy, "http": proxy})] if proxy else []
+ opener = urllib.request.build_opener(*handlers)
+ req = urllib.request.Request(url, headers={"User-Agent": "agent-reach"})
+ try:
+ with opener.open(req, timeout=60) as resp, open(dest, "wb") as fh:
+ shutil.copyfileobj(resp, fh, 1024 * 1024)
+ except OSError as exc:
+ raise ReachError(UPSTREAM_BROKEN, f"download failed: {url}: {exc}") from None
+
+
+def _install_pip(tool: Tool) -> None:
+ venv = tool_dir(tool.name) / "venv"
+ shutil.rmtree(venv, ignore_errors=True)
+ venv.parent.mkdir(parents=True, exist_ok=True)
+ _run([sys.executable, "-m", "venv", str(venv)])
+ py = venv / ("Scripts/python.exe" if _WIN else "bin/python")
+ _run([str(py), "-m", "pip", "install", "--quiet", "--disable-pip-version-check", install_spec(tool)])
+ if tool.kind == "ffmpeg":
+ exe = _run([str(py), "-c", "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())"]).strip()
+ link = _private_bin(tool, "ffmpeg")
+ link.parent.mkdir(parents=True, exist_ok=True)
+ if link.exists() or link.is_symlink():
+ link.unlink()
+ try:
+ link.symlink_to(exe)
+ except (OSError, NotImplementedError):
+ shutil.copy2(exe, link)
+
+
+def _npm_cmd() -> str:
+ npm = resolve("npm")
if not npm:
- raise ReachError(NEED_SETUP, "npm is not installed", hint="Ask the user to install Node.js (https://nodejs.org).")
- if global_:
- _run([npm, "install", "-g", tool.spec])
+ raise ReachError(NEED_SETUP, "npm is not installed", hint="Run `agent-reach add <channel>` again.")
+ return npm
+
+
+def _install_npm(tool: Tool, *, global_prefix: Optional[Path] = None, system_global: bool = False) -> None:
+ npm = _npm_cmd()
+ spec = install_spec(tool)
+ if system_global:
+ _run([npm, "install", "-g", spec])
+ elif global_prefix is not None:
+ global_prefix.mkdir(parents=True, exist_ok=True)
+ _run([npm, "install", "-g", "--prefix", str(global_prefix), "--no-fund", "--no-audit", spec])
else:
prefix = tool_dir(tool.name)
prefix.mkdir(parents=True, exist_ok=True)
- _run([npm, "install", "--prefix", str(prefix), "--no-fund", "--no-audit", tool.spec])
+ _run([npm, "install", "--prefix", str(prefix), "--no-fund", "--no-audit", spec])
+
+
+def _node_platform() -> Tuple[str, str, str]:
+ """(os, arch, archive extension) in nodejs.org naming."""
+ system = platform.system()
+ os_name = {"Darwin": "darwin", "Linux": "linux", "Windows": "win"}.get(system)
+ machine = platform.machine().lower()
+ arch = {"x86_64": "x64", "amd64": "x64", "arm64": "arm64", "aarch64": "arm64"}.get(machine)
+ if not os_name or not arch:
+ raise ReachError(NEED_SETUP, f"no official Node.js build for {system} {machine}",
+ hint="Ask the user to install Node.js from https://nodejs.org.")
+ return os_name, arch, "zip" if os_name == "win" else "tar.gz"
+
+
+def _install_node(tool: Tool) -> None:
+ import hashlib
+ import tarfile
+ import zipfile
+
+ os_name, arch, ext = _node_platform()
+ with tempfile.TemporaryDirectory(prefix="agent-reach-node-") as tmp:
+ index = Path(tmp) / "index.json"
+ _download("https://nodejs.org/dist/index.json", index)
+ key = {"darwin": f"osx-{arch}-tar", "linux": f"linux-{arch}", "win": f"win-{arch}-zip"}[os_name]
+ try:
+ release = next(r for r in json.loads(index.read_text("utf-8")) if r.get("lts") and key in r.get("files", []))
+ except (StopIteration, ValueError):
+ raise ReachError(UPSTREAM_BROKEN, "could not find a Node.js LTS release for this machine") from None
+ version = release["version"]
+ if _command_version(str(_private_bin(tool, "node"))) == version.lstrip("v"):
+ return # already the latest LTS
+ stem = f"node-{version}-{os_name}-{arch}"
+ archive = Path(tmp) / f"{stem}.{ext}"
+ base = f"https://nodejs.org/dist/{version}"
+ _download(f"{base}/{archive.name}", archive)
+ sums = Path(tmp) / "SHASUMS256.txt"
+ _download(f"{base}/SHASUMS256.txt", sums)
+ digest = hashlib.sha256(archive.read_bytes()).hexdigest()
+ if f"{digest} {archive.name}" not in sums.read_text("utf-8"):
+ raise ReachError(UPSTREAM_BROKEN, f"checksum mismatch for {archive.name}")
+ out = Path(tmp) / "x"
+ if ext == "zip":
+ with zipfile.ZipFile(archive) as zf:
+ zf.extractall(out)
+ else:
+ with tarfile.open(archive) as tf:
+ if hasattr(tarfile, "data_filter"):
+ tf.extractall(out, filter="data")
+ else: # pragma: no cover - Python < 3.12 without the filter backport
+ tf.extractall(out)
+ dest = tool_dir("node")
+ shutil.rmtree(dest, ignore_errors=True)
+ dest.mkdir(parents=True)
+ shutil.move(str(out / stem), str(dest / "current"))
+
+
+def _install_uv(tool: Tool) -> None:
+ dest = tool_dir("uv") / "bin"
+ env = {"UV_INSTALL_DIR": str(dest), "UV_NO_MODIFY_PATH": "1", "INSTALLER_NO_MODIFY_PATH": "1"}
+ if _WIN:
+ _run(["powershell", "-ExecutionPolicy", "ByPass", "-c", "irm https://astral.sh/uv/install.ps1 | iex"], env=env)
+ else:
+ with tempfile.TemporaryDirectory(prefix="agent-reach-uv-") as tmp:
+ script = Path(tmp) / "install.sh"
+ _download("https://astral.sh/uv/install.sh", script)
+ _run(["sh", str(script)], env=env)
+ nested = dest / "bin" # older installers add a bin/ below UV_INSTALL_DIR
+ if nested.is_dir():
+ for f in nested.iterdir():
+ shutil.move(str(f), str(dest / f.name))
+ nested.rmdir()
+ if not _private_bin(tool, "uvx").exists():
+ raise ReachError(UPSTREAM_BROKEN, "the uv installer finished but uvx is missing")
-def ensure(name: str, *, allow_upgrade: bool = False) -> dict:
- """Make sure the tool is installed at an acceptable version; record it in state."""
- tool = TOOLS[name]
+def _install(tool: Tool, *, global_: bool = False) -> None:
+ """Install (or upgrade) one tool. Singletons: global_=True (our npm -g prefix)."""
+ if tool.kind in ("pip", "ffmpeg"):
+ _install_pip(tool)
+ elif tool.kind == "npm":
+ _install_npm(tool, global_prefix=npm_global_dir() if global_ else None)
+ elif tool.kind == "node":
+ _install_node(tool)
+ elif tool.kind == "uv":
+ _install_uv(tool)
+ else:
+ raise ReachError(UPSTREAM_BROKEN, f"no installer for {tool.name}")
+ extend_path()
+
+
+def _upgrade_user_singleton(tool: Tool) -> None:
+ """Upgrade the user's own global copy in place (only with consent)."""
+ _install_npm(tool, system_global=True)
+
+
+def record(name: str, version: Optional[str], *, owner: str = OURS, scope: str = "private", **extra) -> dict:
+ """Record a tool in state.json (also used by browser.ensure_chrome for Chrome for Testing)."""
data = state.load()
- entry = data["tools"].get(name)
+ entry = {"owner": owner, "scope": scope, "version": version, **extra}
+ data["tools"][name] = entry
+ state.save(data)
+ return {"tool": name, **entry}
+
+
+def ensure(name: str, *, allow_upgrade: bool = False, upgrade: bool = False) -> dict:
+ """Make sure the tool is installed inside its limits; record it in state.
+
+ `upgrade`: reinstall our private copy at the latest allowed version (update/sync).
+ Returns {"tool", "owner", "scope", "version"}; owner "system" = not ours, not recorded.
+ """
+ tool = TOOLS[name]
+ for dep in tool.needs:
+ ensure(dep) # callers that upgrade list the dependency themselves (manage.sync)
+ entry = state.load()["tools"].get(name) or {}
+ ours = entry.get("owner") == OURS
+
+ if tool.kind == "chrome":
+ from . import browser
+
+ browser.ensure_chrome()
+ entry = state.load()["tools"].get(name)
+ if entry:
+ return {"tool": name, **entry}
+ return {"tool": name, "owner": "system", "scope": "system", "version": None}
if tool.singleton:
current = installed_version(tool)
if current is None:
_install(tool, global_=True)
- entry = {"spec": tool.spec, "owner": "agent-reach", "scope": "global"}
- elif _version_tuple(current) < _version_tuple(tool.min_version):
- if not allow_upgrade:
- raise ReachError(
- NEED_SETUP,
- f"{name} {current} is older than the required {tool.min_version}",
- hint=f"Ask the user whether to upgrade their {name}; if yes, rerun with --allow-upgrade.",
- )
- _install(tool, global_=True)
- entry = {"spec": tool.spec, "owner": (entry or {}).get("owner", "user"), "scope": "global"}
- elif entry is None:
- entry = {"spec": f"user:{current}", "owner": "user", "scope": "global"}
- elif not entry or entry.get("spec") != tool.spec or not _private_bin(tool, tool.commands[0]).exists():
+ return record(name, installed_version(tool), scope="global", prefix=str(npm_global_dir()))
+ if allowed(tool, current) and not (upgrade and ours):
+ if not entry:
+ return record(name, current, owner="user", scope="global")
+ if entry.get("version") != current:
+ return record(name, current, **{k: v for k, v in entry.items() if k != "version"})
+ return {"tool": name, **entry}
+ if ours:
+ if entry.get("prefix"):
+ _install(tool, global_=True)
+ else:
+ _upgrade_user_singleton(tool)
+ return record(name, installed_version(tool), **{k: v for k, v in entry.items() if k != "version"})
+ if not allow_upgrade:
+ raise ReachError(
+ NEED_SETUP,
+ f"{name} {current} is outside the supported versions (needs >= {tool.floor or 'any'}"
+ + (f", not {', '.join(tool.exclude)}" if tool.exclude else "") + ")",
+ hint=f"Ask the user whether to upgrade their {name}; if yes, rerun with --allow-upgrade.",
+ )
+ _upgrade_user_singleton(tool)
+ return record(name, installed_version(tool), owner=entry.get("owner", "user"), scope="global")
+
+ private_ok = all(_private_bin(tool, c).exists() for c in tool.commands)
+ if tool.kind in ("node", "uv", "ffmpeg") and not private_ok and all(shutil.which(c) for c in tool.commands):
+ return {"tool": name, "owner": "system", "scope": "system", "version": None}
+ if not private_ok or not ours or upgrade:
_install(tool)
- entry = {"spec": tool.spec, "owner": "agent-reach", "scope": "private"}
+ elif entry.get("version"):
+ return {"tool": name, **entry}
+ # fresh install, or a record from an older Agent Reach without a version
+ return record(name, _private_version(tool))
- data["tools"][name] = entry
- state.save(data)
- return {"tool": name, **entry}
+
+# ── removing ──
+
+def _uninstall_global(name: str, entry: dict, dry_run: bool) -> Optional[str]:
+ """Uninstall a singleton we installed. Returns a description, or None if not ours."""
+ tool = TOOLS.get(name)
+ if not tool or not tool.singleton or entry.get("owner") != OURS:
+ return None
+ prefix = entry.get("prefix")
+ desc = f"npm -g {tool.package}" + (f" (in {prefix})" if prefix else "")
+ npm = resolve("npm")
+ if not dry_run and npm:
+ argv = [npm, "uninstall", "-g"] + (["--prefix", prefix] if prefix else []) + [tool.package]
+ try:
+ subprocess.run(argv, capture_output=True, timeout=300, env=_install_env())
+ except (OSError, subprocess.TimeoutExpired):
+ pass
+ return desc
def remove_private(name: str) -> bool:
- """Delete a private install. Singletons are never removed here."""
- tool = TOOLS[name]
- if tool.singleton:
- return False
+ """Delete one of our installs and its record. User/system copies are never touched."""
data = state.load()
+ entry = data["tools"].get(name)
+ tool = TOOLS.get(name)
+ if tool and tool.singleton:
+ if entry is None:
+ return False
+ if entry.get("owner") == OURS:
+ _uninstall_global(name, entry, dry_run=False)
+ data["tools"].pop(name, None)
+ state.save(data)
+ return entry.get("owner") == OURS
+ if entry is not None and entry.get("owner") not in (None, OURS):
+ return False
removed = data["tools"].pop(name, None) is not None
- if tool_dir(name).exists():
+ if _SAFE_NAME.match(name) and tool_dir(name).exists():
shutil.rmtree(tool_dir(name))
removed = True
state.save(data)
return removed
+def closure(names: Iterable[str]) -> Set[str]:
+ """The tools plus everything they need."""
+ out: Set[str] = set()
+ todo = [n for n in names if n in TOOLS]
+ while todo:
+ n = todo.pop()
+ if n not in out:
+ out.add(n)
+ todo.extend(TOOLS[n].needs)
+ return out
+
+
+def prune(keep: Set[str]) -> List[str]:
+ """Remove our tools not in `keep` (and drop records of user copies no channel uses)."""
+ removed = []
+ for name, entry in list(state.load()["tools"].items()):
+ if name in keep:
+ continue
+ if entry.get("owner") != OURS:
+ data = state.load()
+ data["tools"].pop(name, None)
+ state.save(data)
+ continue
+ if name not in TOOLS and not _SAFE_NAME.match(name):
+ continue
+ if name == "chrome":
+ from . import browser
+
+ browser.stop()
+ if remove_private(name):
+ removed.append(name)
+ return removed
+
+
def uninstall_global_owned(dry_run: bool) -> list:
"""Global singletons we installed (owner agent-reach); uninstall them."""
out = []
for name, entry in state.load()["tools"].items():
- tool = TOOLS.get(name)
- if tool and tool.singleton and entry.get("owner") == "agent-reach" and entry.get("scope") == "global":
- out.append(f"npm -g {tool.spec.rsplit('@', 1)[0]}")
- if not dry_run and shutil.which("npm"):
- subprocess.run([shutil.which("npm"), "uninstall", "-g", tool.spec.rsplit("@", 1)[0]],
- capture_output=True, timeout=300)
+ desc = _uninstall_global(name, entry, dry_run)
+ if desc:
+ out.append(desc)
return out
+
+
+def recorded() -> List[dict]:
+ """Every tool in state.json with its installed version (for doctor)."""
+ return [{"tool": n, **e} for n, e in sorted(state.load()["tools"].items())]
diff --git a/agent_reach/runtime/update_notice.py b/agent_reach/runtime/update_notice.py
new file mode 100644
index 00000000..d1f2e1b3
--- /dev/null
+++ b/agent_reach/runtime/update_notice.py
@@ -0,0 +1,125 @@
+"""Background "new version" notice.
+
+Commands never wait on the network. At most once per 24 h a command starts a
+short detached process (`python -m agent_reach.runtime.update_notice`) that
+reads the latest GitHub release (10 s timeout) and writes
+~/.agent-reach/update-check.json {checked_at, latest, notes}. No network = no
+file change, silently. `notice()` reads that cache only: it returns
+{current, latest, notes} when the cached latest is newer than this version.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import time
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+from agent_reach import __version__
+from agent_reach.utils.paths import (
+ PrivatePathError,
+ atomic_write_private_text,
+ make_private_dir,
+ read_small_text_no_follow,
+)
+
+from . import state
+
+REPO = "Panniantong/Agent-Reach"
+INTERVAL = 24 * 3600
+FETCH_TIMEOUT = 10.0
+NOTES_MAX = 2000
+#: Set to any value to never start the background check (tests, CI).
+DISABLE_ENV = "AGENT_REACH_NO_UPDATE_CHECK"
+
+
+def cache_path() -> Path:
+ return state.root() / "update-check.json"
+
+
+def started_path() -> Path:
+ """Touched when a background check starts: limits starts to one per INTERVAL, online or not."""
+ return state.root() / "update-check.started"
+
+
+def version_tuple(v: str) -> tuple:
+ try:
+ return tuple(int(x) for x in str(v).strip().lstrip("v").split("."))
+ except ValueError:
+ return ()
+
+
+def fetch_latest(timeout: float = FETCH_TIMEOUT) -> dict:
+ """{latest, notes} of the latest GitHub release. Raises on network errors."""
+ req = urllib.request.Request(f"https://api.github.com/repos/{REPO}/releases/latest",
+ headers={"User-Agent": "agent-reach", "Accept": "application/vnd.github+json"})
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ rel = json.loads(resp.read())
+ return {"latest": str(rel.get("tag_name", "")).lstrip("v"), "notes": (rel.get("body") or "")[:NOTES_MAX]}
+
+
+def write_cache(info: dict) -> None:
+ make_private_dir(state.root())
+ atomic_write_private_text(cache_path(), json.dumps(
+ {"checked_at": state.now(), "latest": info["latest"], "notes": info["notes"]}, ensure_ascii=False))
+
+
+def read_cache() -> Optional[dict]:
+ try:
+ data = json.loads(read_small_text_no_follow(cache_path(), max_bytes=64 * 1024) or "null")
+ except (OSError, ValueError, PrivatePathError):
+ return None
+ return data if isinstance(data, dict) else None
+
+
+def notice() -> Optional[dict]:
+ """{current, latest, notes} when the cached latest release is newer than this version."""
+ data = read_cache()
+ if not data:
+ return None
+ latest = str(data.get("latest") or "")
+ current = version_tuple(__version__)
+ if not current or version_tuple(latest) <= current:
+ return None
+ return {"current": __version__, "latest": latest, "notes": str(data.get("notes") or "")}
+
+
+def _due() -> bool:
+ try:
+ return time.time() - started_path().stat().st_mtime >= INTERVAL
+ except OSError:
+ return True
+
+
+def maybe_refresh() -> None:
+ """Start the detached background check if the last one began over 24 h ago. Never blocks or raises."""
+ if os.environ.get(DISABLE_ENV) or not _due():
+ return
+ try:
+ make_private_dir(state.root())
+ started_path().touch()
+ kwargs: dict = {"stdin": subprocess.DEVNULL, "stdout": subprocess.DEVNULL, "stderr": subprocess.DEVNULL,
+ "close_fds": True, "cwd": str(state.root())}
+ if os.name == "nt":
+ kwargs["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+ else:
+ kwargs["start_new_session"] = True
+ subprocess.Popen([sys.executable, "-m", "agent_reach.runtime.update_notice"], **kwargs)
+ except (OSError, PrivatePathError):
+ pass
+
+
+def _main() -> int:
+ try:
+ write_cache(fetch_latest())
+ except Exception: # noqa: BLE001 - offline or GitHub down: stay silent
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(_main())
diff --git a/agent_reach/scripts/transcribe_xiaoyuzhou.sh b/agent_reach/scripts/transcribe_xiaoyuzhou.sh
index d5ab6396..cede2104 100755
--- a/agent_reach/scripts/transcribe_xiaoyuzhou.sh
+++ b/agent_reach/scripts/transcribe_xiaoyuzhou.sh
@@ -137,10 +137,11 @@ curl --fail --show-error --location --silent \
FILE_SIZE=$(ls -lh "$WORK_DIR/original.$EXT" | awk '{print $5}')
echo "📦 文件大小: $FILE_SIZE"
-# Step 3: 获取时长
-if ! DURATION_RAW=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 \
- "$WORK_DIR/original.$EXT" 2>/dev/null); then
- echo "❌ ffprobe 无法读取音频时长" >&2
+# Step 3: 获取时长(用 ffmpeg 自己读:Agent Reach 自带的 ffmpeg 没有 ffprobe)
+DURATION_RAW=$(ffmpeg -hide_banner -i "$WORK_DIR/original.$EXT" 2>&1 \
+ | awk '/Duration: [0-9]+:[0-9]+:[0-9.]+/ { split($2, t, ":"); sub(",", "", t[3]); printf "%.3f", t[1] * 3600 + t[2] * 60 + t[3]; exit }')
+if [ -z "$DURATION_RAW" ]; then
+ echo "❌ ffmpeg 无法读取音频时长" >&2
exit 1
fi
if DURATION=$(DURATION_RAW="$DURATION_RAW" MAX_DURATION_SECONDS="$MAX_DURATION_SECONDS" \
@@ -166,7 +167,7 @@ else
if [ "$duration_status" -eq 3 ]; then
echo "❌ 音频时长超过 3 小时限制" >&2
else
- echo "❌ ffprobe 返回无效音频时长: ${DURATION_RAW:-<empty>}" >&2
+ echo "❌ ffmpeg 返回无效音频时长: ${DURATION_RAW:-<empty>}" >&2
fi
exit 1
fi
diff --git a/agent_reach/skill/SKILL.md b/agent_reach/skill/SKILL.md
index 6e5d624e..f18c77c2 100644
--- a/agent_reach/skill/SKILL.md
+++ b/agent_reach/skill/SKILL.md
@@ -47,7 +47,7 @@ agent-reach read <链接> # 给链接,自动认出渠道
{{CHANNEL_TABLE}}
-`default` 装好就能用;其余要用户先 `agent-reach add <渠道>`。
+`default` 装好就能用;其余要用户先 `agent-reach add <渠道>`。默认渠道也可以去掉,去掉后更新不会再加回来。
## 浏览器
@@ -58,11 +58,21 @@ agent-reach read <链接> # 给链接,自动认出渠道
| 用户说 | 你运行 |
|---|---|
| 看看状态 / 哪些能用 | `agent-reach doctor --text`(要实测再跑 `agent-reach check --text`) |
-| 加上某个平台(如"加上小红书") | `agent-reach add <渠道>`,照 `result.next` 做,再 `agent-reach login <渠道>` 让用户本人登录 |
+| 加上某个平台(如"加上小红书") | `agent-reach add <渠道>`,一条命令就装好它需要的一切。只告诉用户他本人要做的事:在弹出的窗口里登录(`agent-reach login <渠道>`),或者提供一个 Key |
| 登录过期了 | `agent-reach login <渠道>`(用户本人登录) |
-| 去掉某个平台 / 退出登录 | `agent-reach remove <渠道>` / `agent-reach logout <渠道>` |
-| 升级 / 更新 | `agent-reach update` |
+| 去掉某个平台 / 退出登录 | `agent-reach remove <渠道>`(默认渠道也能去掉)/ `agent-reach logout <渠道>` |
+| 升级 / 更新 | `agent-reach update`(同时把各渠道的工具升到最新),然后按下面"有新版本时"把结果告诉用户 |
| 卸载 | 先 `agent-reach uninstall --dry-run` 给用户看,确认后 `agent-reach uninstall` |
| 让另一个 AI 也能用 | `agent-reach skill link <那个 AI 的 skill 目录>`;`agent-reach skill` 查看现在放在哪 |
首次安装:`agent-reach setup`。
+
+## 有新版本时
+
+任何结果里出现 `meta.update`,就说明有新版本。每次对话只提一次,用用户的语言、大白话:
+
+1. 告诉用户 Agent Reach 有新版本(`meta.update.latest`)。
+2. 从 `meta.update.notes` 里挑 1 到 3 个简短要点,说清楚这次改了什么。
+3. 问用户要不要更新。
+
+用户说要,才运行 `agent-reach update`;没得到同意绝不更新。更新完再用大白话说一遍改了什么,并把 `result.user_actions` 里每一条(比如某个渠道要重新登录)告诉用户。
diff --git a/agent_reach/skill/SKILL_en.md b/agent_reach/skill/SKILL_en.md
index fcb2b7ae..624e3e5c 100644
--- a/agent_reach/skill/SKILL_en.md
+++ b/agent_reach/skill/SKILL_en.md
@@ -48,7 +48,7 @@ Results:
{{CHANNEL_TABLE}}
-`default` channels work right away; others need `agent-reach add <channel>` first.
+`default` channels work right away; others need `agent-reach add <channel>` first. Default channels can be removed too; updates never add a removed one back.
## Browser
@@ -59,11 +59,21 @@ Xiaohongshu, Reddit, Twitter, Boss Zhipin, Xueqiu hot posts and similar channels
| User asks | You run |
|---|---|
| Status / what works | `agent-reach doctor --text` (for a live test, `agent-reach check --text`) |
-| Add a platform ("add Xiaohongshu") | `agent-reach add <channel>`, follow `result.next`, then `agent-reach login <channel>` so the user logs in |
+| Add a platform ("add Xiaohongshu") | `agent-reach add <channel>`; one command installs everything it needs. Tell the user only what they must do: log in in the window that opens (`agent-reach login <channel>`), or provide a key |
| Login expired | `agent-reach login <channel>` (the user logs in) |
-| Remove a platform / log out | `agent-reach remove <channel>` / `agent-reach logout <channel>` |
-| Upgrade / update | `agent-reach update` |
+| Remove a platform / log out | `agent-reach remove <channel>` (default channels too) / `agent-reach logout <channel>` |
+| Upgrade / update | `agent-reach update` (also upgrades every channel's tools to their latest versions), then report as in "When there is a new version" below |
| Uninstall | show `agent-reach uninstall --dry-run` first, then `agent-reach uninstall` once they confirm |
| Another AI should use it | `agent-reach skill link <that AI's skills folder>`; `agent-reach skill` shows where it is placed now |
First install: `agent-reach setup`.
+
+## When there is a new version
+
+Any result with `meta.update` means a newer version exists. Mention it once per conversation, in the user's language and plain words:
+
+1. Agent Reach has a new version (`meta.update.latest`).
+2. What changed: 1 to 3 short points taken from `meta.update.notes`.
+3. Ask whether to update.
+
+Run `agent-reach update` only after the user says yes; never update without it. Afterwards, tell them plainly again what changed, plus every sentence in `result.user_actions` (e.g. a channel now needs a login).
diff --git a/agent_reach/transcribe.py b/agent_reach/transcribe.py
index 34e9fa19..2b17c236 100644
--- a/agent_reach/transcribe.py
+++ b/agent_reach/transcribe.py
@@ -22,7 +22,7 @@ from __future__ import annotations
import ipaddress
import math
-import shutil
+import re
import socket
import subprocess
import tempfile
@@ -41,7 +41,7 @@ MAX_SOURCE_BYTES = 512 * 1024 * 1024
MAX_CHUNKS = 24 # 4 hours at the standard 10-minute segment size
MAX_TOTAL_CHUNK_BYTES = 96 * 1024 * 1024
MAX_AUDIO_SECONDS = MAX_CHUNKS * CHUNK_SECONDS
-FFPROBE_TIMEOUT_SECONDS = 30
+PROBE_TIMEOUT_SECONDS = 30
PROVIDERS = {
"groq": {
@@ -75,9 +75,18 @@ _BLOCKED_HOSTS = {
}
+def _bin(binary: str) -> str:
+ """Our private copy (e.g. the ffmpeg `agent-reach add` installs) first, then PATH."""
+ from agent_reach.runtime.tools import resolve
+
+ return resolve(binary) or binary
+
+
def _require(binary: str) -> None:
- if not shutil.which(binary):
- raise MissingDependency(f"{binary} not found in PATH")
+ from agent_reach.runtime.tools import resolve
+
+ if not resolve(binary):
+ raise MissingDependency(f"{binary} not found (run `agent-reach add youtube`)")
def _require_size_at_most(path: Path, limit: int, label: str) -> int:
@@ -89,54 +98,43 @@ def _require_size_at_most(path: Path, limit: int, label: str) -> int:
return size
+_DURATION_RE = re.compile(r"Duration:\s*(\d+):(\d{2}):(\d{2}(?:\.\d+)?)")
+
+
def _probe_audio_duration(path: Path) -> float:
- """Return duration in seconds or fail closed before media generation."""
- _require("ffprobe")
- cmd = [
- "ffprobe",
- "-v",
- "error",
- "-show_entries",
- "format=duration",
- "-of",
- "default=noprint_wrappers=1:nokey=1",
- "-i",
- str(path),
- ]
+ """Return duration in seconds or fail closed before media generation.
+
+ Read from `ffmpeg -i` (no ffprobe: the private ffmpeg Agent Reach installs
+ ships only ffmpeg). Without an output file ffmpeg exits 1 after printing
+ the input's details, so the exit code is not checked.
+ """
+ _require("ffmpeg")
+ cmd = [_bin("ffmpeg"), "-hide_banner", "-i", str(path)]
try:
proc = subprocess.run(
cmd,
capture_output=True,
encoding="utf-8",
errors="replace",
- timeout=FFPROBE_TIMEOUT_SECONDS,
+ timeout=PROBE_TIMEOUT_SECONDS,
)
except subprocess.TimeoutExpired:
raise TranscribeError(
- "ffprobe timed out while reading audio duration "
- f"after {FFPROBE_TIMEOUT_SECONDS}s"
+ "ffmpeg timed out while reading audio duration "
+ f"after {PROBE_TIMEOUT_SECONDS}s"
) from None
except OSError as exc:
raise TranscribeError(
- f"ffprobe could not read audio duration: {exc}"
+ f"ffmpeg could not read audio duration: {exc}"
) from exc
- if proc.returncode != 0:
- detail = proc.stderr.strip()[:300] or "unknown ffprobe error"
- raise TranscribeError(
- f"ffprobe failed while reading audio duration: {detail}"
- )
-
- raw_duration = proc.stdout.strip()
- try:
- duration = float(raw_duration)
- except (TypeError, ValueError):
- raise TranscribeError(
- "ffprobe could not parse a valid audio duration"
- ) from None
+ m = _DURATION_RE.search(proc.stderr or "")
+ if not m:
+ raise TranscribeError("ffmpeg could not parse a valid audio duration")
+ duration = int(m.group(1)) * 3600 + int(m.group(2)) * 60 + float(m.group(3))
if not math.isfinite(duration) or duration <= 0:
raise TranscribeError(
- "ffprobe could not parse a valid positive audio duration"
+ "ffmpeg could not parse a valid positive audio duration"
)
return duration
@@ -262,6 +260,8 @@ def download_audio(url: str, out_dir: Path) -> Path:
"--audio-quality",
"0",
"--no-playlist",
+ "--ffmpeg-location",
+ _bin("ffmpeg"),
"--max-filesize",
str(MAX_SOURCE_BYTES),
"-o",
@@ -288,7 +288,7 @@ def compress_audio(src: Path, out_dir: Path) -> Path:
dst = out_dir / "compressed.m4a"
_run(
[
- "ffmpeg",
+ _bin("ffmpeg"),
"-loglevel",
"error",
"-y",
@@ -326,7 +326,7 @@ def chunk_audio(src: Path, out_dir: Path, segment_seconds: int = CHUNK_SECONDS)
pattern = out_dir / "chunk_%03d.m4a"
_run(
[
- "ffmpeg",
+ _bin("ffmpeg"),
"-loglevel",
"error",
"-y",
diff --git a/docs/README_en.md b/docs/README_en.md
index 2b7889e0..509e746e 100644
--- a/docs/README_en.md
+++ b/docs/README_en.md
@@ -66,7 +66,7 @@ CLI agents such as Claude Code, Codex, Hermes Agent and OpenClaw come with web s
- **Chinese platforms**: Bilibili, XiaoHongShu, V2EX, Xueqiu, Xiaoyuzhou, which general search covers poorly.
- **Clean structured data**: Xueqiu quotes, V2EX topics and replies, GitHub repos and issues, as fields instead of HTML to guess from.
-Agent Reach installs the open-source tools behind these platforms, pins their versions, health-checks them, and gives the agent one entry point:
+Agent Reach installs the open-source tools behind these platforms, keeps them up to date, health-checks them, and gives the agent one entry point:
```bash
agent-reach channels # which channels exist and what each can do
@@ -84,6 +84,8 @@ Every command prints the same JSON shape, so the agent doesn't have to learn eac
- **Does it cost money?** The program and its backends are open source and free. The only keys you may need are for speech-to-text: Groq (has a free tier) or OpenAI Whisper.
- **Does it touch my browser or accounts?** It never reads your own browser's cookies and never logs in for you. For login channels, you log in yourself in the dedicated Agent Reach browser. See [Security](#security).
- **Which OS?** macOS first, Linux works, Windows best effort.
+- **Do I have to install anything else?** No. Whatever a channel needs (Node.js, Chrome, ffmpeg, the browser extension) is installed by `agent-reach add` itself, with no admin password. All you do is log in or provide a key.
+- **How do I hear about new versions?** Agent Reach checks at most once a day in the background. When there is a new version, your agent tells you in plain words what changed and asks whether to update; it updates only if you say yes.
---
@@ -100,18 +102,18 @@ Every command prints the same JSON shape, so the agent doesn't have to learn eac
| bilibili | default | search, video info, trending, subtitles | nothing; subtitles need a login (QR scan) |
| xiaohongshu | optional | search notes, read a note | browser + login |
| reddit | optional | search, read posts with comments, browse a subreddit | browser + login |
-| linkedin | optional | job search | login (needs Node.js and uv) |
-| boss | optional | job and JD search | browser + login (needs git) |
-| xiaoyuzhou | optional | full podcast transcripts | Groq key + ffmpeg |
+| linkedin | optional | job search | login |
+| boss | optional | job and JD search | browser + login |
+| xiaoyuzhou | optional | full podcast transcripts | Groq key |
| xueqiu | optional | real-time quotes, stock search, hot posts, hot stocks | quotes need nothing; hot posts/stocks need a browser login |
| twitter | experimental | search tweets, profiles, user tweets, threads | browser + login |
| facebook | experimental | search, profiles | browser + login |
| instagram | experimental | user search, profiles, user posts | browser + login |
-- **default**: works right after install.
-- **optional**: turn on with `agent-reach add <channel>`; Agent Reach installs the tools it needs into its own folder.
+- **default**: works right after install; you can remove one (`agent-reach remove <channel>`) and updates won't add it back.
+- **optional**: turn on with `agent-reach add <channel>`; Agent Reach installs everything it needs into its own folder.
- **experimental**: works, but the platform fights automation harder and it can break at any time.
-- **browser**: the Agent Reach browser, a separate Chrome window (needs Google Chrome and Node.js). The first time, you add the OpenCLI extension to it; `agent-reach browser setup` walks you through it. After that it opens by itself when needed (the first open takes about 40 seconds) and closes after 10 minutes without use.
+- **browser**: the Agent Reach browser, a separate Chrome window. If the machine has no Chrome, Agent Reach downloads its own copy; it also installs the OpenCLI extension in it by itself (on Windows you click "Add to Chrome" once in the window that opens). After that it opens by itself when needed (the first open takes about 40 seconds) and closes after 10 minutes without use.
---
@@ -127,7 +129,7 @@ The agent does the rest by following [install.md](install.md). Along the way you
- **Let it run commands**: if the agent says it can't run commands, turn on command execution in its settings.
- **Allow installing uv**: uv is a small tool that installs command-line programs; no admin password needed. The agent installs it first if it's missing and tells you.
-- **Pick optional channels**: afterwards the agent tells you what works now (web, YouTube, GitHub, V2EX, Bilibili) and what else you can add and what each needs. Pick now, or later just say "add Xiaohongshu".
+- **Pick optional channels**: afterwards the agent tells you what works now (web, YouTube, GitHub, V2EX, Bilibili) and what else you can add. Pick now, or later just say "add Xiaohongshu"; one command sets it up.
The only thing you do yourself is log in; the agent never logs in for you and never asks for your password:
@@ -158,9 +160,9 @@ Just tell your agent in plain words; it runs the command for you:
| You say | Agent runs | What it does |
|---|---|---|
| "How is Agent Reach doing?" | `agent-reach doctor --text` | status of every channel: not_added / needs_setup / needs_login / unverified / ready / broken, and which ones broke since the last check |
-| "Add Xiaohongshu" / "Remove Xiaohongshu" | `agent-reach add` / `remove <channel>` | turn a channel on / off; after adding, `agent-reach login <channel>` |
+| "Add Xiaohongshu" / "Remove Xiaohongshu" | `agent-reach add` / `remove <channel>` | turn a channel on and install everything it needs; you only log in or provide a key / turn it off and clear its login and private tools (default channels too) |
| "My Bilibili login expired" / "Log out" | `agent-reach login` / `logout <channel>` | log in (you do it) / forget the login |
-| "Upgrade Agent Reach" | `agent-reach update` | update the program, its tools and the skill in one go, see [update.md](update.md) |
+| "Upgrade Agent Reach" | `agent-reach update` | update the program, every channel's tools (to their latest versions) and the skill in one go, and tell you anything left to do, see [update.md](update.md) |
| "Uninstall Agent Reach" | `agent-reach uninstall` | see Uninstall under Security below |
| "Let my other AI use it too" | `agent-reach skill link <its skills folder>` | link the instructions for an AI not covered automatically |
@@ -178,9 +180,9 @@ Each action of each channel has an ordered list of backends. `bilibili read` tri
Platforms change and tools break all the time. Switching backends only reorders that list; the way the agent calls Agent Reach stays the same.
-### 📌 Pinned versions, private installs
+### 📌 Kept current, private installs
-The tools Agent Reach installs (OpenCLI, bili-cli, boss-agent-cli, mcporter) are pinned to tested versions and live in `~/.agent-reach/tools/`, away from your global environment. `agent-reach update` moves them to the versions tested with the new release.
+The tools Agent Reach installs (OpenCLI, bili-cli, boss-agent-cli, mcporter and others) live in `~/.agent-reach/tools/`, away from your global environment. Versions are not pinned: each install takes the latest version, and `agent-reach update` upgrades them to the latest even when Agent Reach itself has no new release. Known-bad upstream versions are excluded in a new Agent Reach release; `agent-reach doctor` shows the version actually installed for each tool.
### 🩺 Working means live-tested
diff --git a/docs/install.md b/docs/install.md
index c9136989..9b7a6993 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -23,7 +23,7 @@ agent-reach check --text
`agent-reach` not found after install? Run `uv tool update-shell` and open a new shell.
-`setup` takes about 20 s, `check` about 1 minute; allow a timeout of at least 3 minutes. `setup` turns on the default channels (web, YouTube, GitHub, V2EX, Bilibili) and gives the AIs found on this machine the Agent Reach instructions (a "skill"). If `result.prerequisites` lists something missing, tell the user its `hint`; only the channels that need it are affected.
+`setup` takes about 20 s, `check` about 1 minute; allow a timeout of at least 3 minutes. `setup` turns on the default channels (web, YouTube, GitHub, V2EX, Bilibili) and gives the AIs found on this machine the Agent Reach instructions (a "skill").
`check --text` tests the channels that are on and exits 1 if any action fails. A `NEED_LOGIN` failure (e.g. Bilibili subtitles) is normal: that feature needs an optional login. Any other failure: tell the user which feature does not work yet.
@@ -33,9 +33,9 @@ Keep it short and plain:
1. **Works now**: the channels in `result.default_channels` with `ok: true`. Mention features that failed `check` only as "needs login" or "not working yet".
2. **Which AIs can use it**: `result.skill.agents` (the AIs found on this machine).
-3. **Optional, add any time**: each entry of `result.optional_channels` with what it `needs`. In `needs`, `login` means the user logs in, `groq-key` means a free key from https://console.groq.com, anything else (node, chrome, git, ffmpeg, uv) is software the machine needs. Mention that `experimental` ones can break at any time. Optional logins for channels already on: `result.logins` (e.g. Bilibili login unlocks subtitles).
-4. **How to add one later**: "Just tell me, e.g. 'add Xiaohongshu'."
+3. **Optional, add any time**: each entry of `result.optional_channels`. Say only what the user will have to do: log in, or get a key (`groq-key`: a free key from https://console.groq.com). Anything else a channel needs (Node.js, Chrome, ffmpeg, the browser extension) is installed by Agent Reach itself, with no admin password. Mention that `experimental` ones can break at any time. Optional logins for channels already on: `result.logins` (e.g. Bilibili login unlocks subtitles).
+4. **How to add or remove one later**: "Just tell me, e.g. 'add Xiaohongshu' or 'remove V2EX'." Default channels can be removed too.
-When the user asks for a channel, run `agent-reach add <channel>`, follow its `result.next`, then `agent-reach login <channel>`. The user logs in themselves: never log in for them, never ask for their password, never read their browser's cookies. Suggest a secondary account. Keys (e.g. a free Groq key from https://console.groq.com for podcast transcripts) are entered by the user in their own terminal with `agent-reach configure groq-key` (hidden input); if you must run it yourself, pipe the value: `agent-reach configure groq-key --stdin`.
+When the user asks for a channel, run `agent-reach add <channel>`; it installs everything the channel needs. Then tell the user only what is left for them: logging in (`agent-reach login <channel>` opens a window; they log in there) or entering a key. Browser channels set up the Agent Reach browser and its extension by themselves; on Windows the user clicks "Add to Chrome" once in the window that opens. Never log in for the user, never ask for their password, never read their browser's cookies. Suggest a secondary account. Keys are entered by the user in their own terminal with `agent-reach configure groq-key` (hidden input); if you must run it yourself, pipe the value: `agent-reach configure groq-key --stdin`.
Problems: [troubleshooting.md](troubleshooting.md).
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 1303968d..571c9744 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -13,9 +13,9 @@ Every failed command returns `ok: false` and an `error` with `code`, `message` a
| Code | Meaning | What to do |
|---|---|---|
-| `NEED_SETUP` | a tool, key, prerequisite or the Agent Reach browser is missing | run `agent-reach doctor --text` and follow the problem listed for the channel: `agent-reach add <channel>`, install the missing prerequisite, `agent-reach browser setup`, or `agent-reach configure groq-key` |
+| `NEED_SETUP` | a tool, key or the Agent Reach browser is missing | run `agent-reach doctor --text` and follow the problem listed for the channel: usually `agent-reach add <channel>` again (it installs whatever is missing), `agent-reach browser setup`, or `agent-reach configure groq-key` |
| `NEED_LOGIN` | login is missing or expired | the user runs `agent-reach login <channel>` and logs in themselves; if it still fails, `agent-reach logout <channel>` then log in again |
-| `UPSTREAM_BROKEN` | the upstream tool or platform failed | don't retry in a loop; try again later, run `agent-reach update` (newer pinned tools often fix this), then `agent-reach check <channel>`; still broken → open an issue with the `message` |
+| `UPSTREAM_BROKEN` | the upstream tool or platform failed | don't retry in a loop; try again later, run `agent-reach update` (it upgrades the channel's tools to their latest versions, which often fixes this), then `agent-reach check <channel>`; still broken → open an issue with the `message` |
| `TIMEOUT` | no backend answered in time | retry later, or pass a larger `--timeout SECONDS`; on a restricted network set a proxy (below) |
| `RATE_LIMITED` | the platform is throttling | wait before retrying; avoid many requests in a row |
| `NOT_FOUND` | the content does not exist | check the link, id or username |
@@ -26,7 +26,7 @@ Every failed command returns `ok: false` and an `error` with `code`, `message` a
| Status | Meaning | What to do |
|---|---|---|
| `not_added` | optional channel not turned on | `agent-reach add <channel>` |
-| `needs_setup` | something is missing; `problems` says what | follow each problem: install prerequisite, `agent-reach add <channel>` again, `agent-reach browser setup`, or `agent-reach configure <key>` |
+| `needs_setup` | something is missing; `problems` says what | follow each problem: `agent-reach add <channel>` again, `agent-reach browser setup`, or `agent-reach configure <key>` |
| `needs_login` | the last live check failed only on login | `agent-reach login <channel>` (the user logs in) |
| `unverified` | set up, but no live check in the last 24 hours | `agent-reach check <channel>` |
| `ready` | passed a live check in the last 24 hours | nothing |
@@ -34,13 +34,17 @@ Every failed command returns `ok: false` and an `error` with `code`, `message` a
Run `agent-reach check` first if you want fresh live results. In the `doctor` output, `regressed: true` on a channel means an action passed in the previous check and fails in the latest one.
+## Tool versions
+
+Agent Reach installs the latest version of each channel's tools; it does not pin them. `agent-reach doctor` shows the version actually installed for each tool. If an upstream release turns out to be broken, a new Agent Reach release excludes that version (and may set a minimum); `agent-reach update` then moves you to a good one. Until that release exists, roll back as below or wait.
+
## Agent Reach browser
Used by xiaohongshu, reddit, twitter, facebook, instagram, boss and xueqiu. It is a separate Chrome window with its own profile in `~/.agent-reach/browser/`. It opens by itself when one of these channels needs it (the first open can take about 40 seconds) and closes after 10 minutes without Agent Reach use.
-- **`agent-reach browser setup` keeps saying it is waiting for the extension**: in the Agent Reach window, click "Add to Chrome" on the OpenCLI extension page, then run `agent-reach browser setup` again.
+- **The extension did not connect**: run `agent-reach browser setup`; on macOS and Linux it loads the OpenCLI extension by itself. On Windows, click "Add to Chrome" once on the OpenCLI extension page in the window that opens, then run `agent-reach browser setup` again.
- **"more than one new OpenCLI profile connected"**: close other Chrome windows that have the OpenCLI extension, then run setup again.
-- **Chrome not installed**: install Google Chrome, then retry.
+- **No Chrome on the machine**: nothing to do; Agent Reach downloads its own copy (Chrome for Testing) into `~/.agent-reach/tools/chrome/`.
- **Window closed by hand**: nothing to do; the next command that needs it opens it again. `agent-reach browser status` shows its state.
- While it is open, any local process can control it through its debugging port; it closes itself after 10 idle minutes.
@@ -48,10 +52,19 @@ Used by xiaohongshu, reddit, twitter, facebook, instagram, boss and xueqiu. It i
`agent-reach skill` shows the one real copy of the instructions (`~/.agents/skills/agent-reach/SKILL.md`) and the links made for other AIs. An AI not covered automatically: `agent-reach skill link <its skills folder>`. On Windows, where links may not be allowed, a copy is made instead and refreshed by `agent-reach update`.
-## Install and update
+## Install, update and roll back
Agent Reach is installed with uv only. If `agent-reach update` says the program was installed another way, reinstall once as in [install.md](install.md); your channels, keys and logins under `~/.agent-reach/` are kept.
+A new version broke something? Go back to the previous release, then line the tools and skill up with it:
+
+```bash
+uv tool install --force https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v<previous>.zip
+agent-reach update --sync-only
+```
+
+Removed default channels stay removed across updates; `agent-reach add <channel>` brings one back.
+
## Proxy
Some platforms block certain networks or regions. Save a proxy once (the address is asked for with hidden input, since it may contain a password):
@@ -67,5 +80,5 @@ It is used for every Agent Reach command. An `HTTPS_PROXY` set in your shell tak
## Still stuck
- `agent-reach update` and try again.
-- Remove and re-add a channel: `agent-reach remove <channel>` then `agent-reach add <channel>` (this also clears its login).
+- Remove and re-add a channel: `agent-reach remove <channel>` then `agent-reach add <channel>` (remove also clears its login, its site cookies in the Agent Reach browser, and its private tools nobody else uses).
- Open an issue at https://github.com/Panniantong/Agent-Reach/issues with the output of `agent-reach doctor --text` (it starts with the version) and `agent-reach check <channel> --text`. Remove any personal data first.
diff --git a/docs/update.md b/docs/update.md
index 404b8170..b11addbe 100644
--- a/docs/update.md
+++ b/docs/update.md
@@ -9,15 +9,30 @@ agent-reach update
One command does everything:
- upgrades the program to the latest GitHub release (`uv tool install --force <release zip>`)
-- moves the tools of your added channels to the versions pinned by that release
+- upgrades the tools of every added channel to their latest versions, even when Agent Reach itself has no new release (known-bad versions are skipped); tools no channel uses any more are removed
- refreshes the Agent Reach skill (the one real copy, and the links that let your other AIs read it)
-Only want to know if there is a new version? `agent-reach update --check`.
+Default channels you removed stay removed; `agent-reach add <channel>` brings one back.
+
+`result.user_actions` lists, in plain sentences, anything the user must do afterwards (e.g. a channel now needs a login). Tell the user each one.
+
+Only want to know if there is a new version? `agent-reach update --check`. Agent Reach also checks by itself at most once a day in the background; when a newer version exists, every command's JSON carries `meta.update` with the version and its release notes.
Afterwards, `agent-reach check --text` confirms your channels still work.
If the upgrade step fails, the error `hint` holds the exact command to run by hand. Installed some other way than uv? The hint says to reinstall once with uv, as below.
+## Roll back
+
+A new version misbehaves? Go back to the previous one (replace `<previous>` with its number, e.g. `1.6.0`):
+
+```bash
+uv tool install --force https://github.com/Panniantong/Agent-Reach/archive/refs/tags/v<previous>.zip
+agent-reach update --sync-only
+```
+
+`--sync-only` brings the channel tools and the skill in line with the installed version without upgrading the program again. Channels, keys and logins under `~/.agent-reach/` are kept.
+
## Coming from 1.5 or earlier
Older versions installed differently, so reinstall once with the same command as [install.md](install.md) (no `uv` yet? see step 0 there):
@@ -38,4 +53,4 @@ agent-reach setup
agent-reach login <channel> --import-existing
```
-Browser-login channels (xiaohongshu, reddit, twitter, ...) no longer use your own browser's cookies. Run `agent-reach browser setup` and log in again in the Agent Reach browser with `agent-reach login <channel>`.
+Browser-login channels (xiaohongshu, reddit, twitter, ...) no longer use your own browser's cookies. Add them again with `agent-reach add <channel>` (it sets up the Agent Reach browser by itself), then log in there with `agent-reach login <channel>`.
diff --git a/llms.txt b/llms.txt
index ec997cd7..ea4b0be7 100644
--- a/llms.txt
+++ b/llms.txt
@@ -15,6 +15,8 @@
- `agent-reach read <url>`: read a link with the matching channel
- Output: `{schema_version, ok, channel, action, backend, items, meta, error}`; error codes NEED_SETUP, NEED_LOGIN, UPSTREAM_BROKEN, TIMEOUT, RATE_LIMITED, NOT_FOUND, BAD_INPUT
- Management: `setup`, `add|remove <channel>`, `login|logout <channel>` (the user logs in), `browser setup|status`, `doctor`, `check`, `skill`, `skill link <dir>`, `update`, `configure`, `uninstall`
+- `add` installs everything a channel needs (Node.js, Chrome, ffmpeg, browser extension; no admin password); the user only logs in or enters a key. `remove` also clears its login and private tools; default channels can be removed and stay removed across updates.
+- `update` upgrades the program and every added channel's tools to their latest versions (not pinned; known-bad versions excluded) and returns `result.user_actions`. When a newer release exists, any JSON output carries `meta.update = {current, latest, notes}`; tell the user and update only after they agree.
- Browser channels open the dedicated Agent Reach browser by themselves; it closes after 10 minutes without use.
## Channels
diff --git a/tests/conftest.py b/tests/conftest.py
index 6d203e96..0aa41623 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -81,6 +81,8 @@ def isolated_home(tmp_path, monkeypatch):
monkeypatch.setenv("APPDATA", str(home / "AppData" / "Roaming"))
monkeypatch.setenv("LOCALAPPDATA", str(home / "AppData" / "Local"))
monkeypatch.delenv("OPENCLAW_HOME", raising=False)
+ # never start the background release check from tests
+ monkeypatch.setenv("AGENT_REACH_NO_UPDATE_CHECK", "1")
config_dir = home / ".agent-reach"
monkeypatch.setattr(Config, "CONFIG_DIR", config_dir)
diff --git a/tests/test_browser.py b/tests/test_browser.py
new file mode 100644
index 00000000..4e5643e8
--- /dev/null
+++ b/tests/test_browser.py
@@ -0,0 +1,159 @@
+"""Agent Reach dedicated browser: extension, Chrome for Testing, cookies, CDP pipe (no real Chrome)."""
+
+import json
+import os
+import shutil
+import threading
+import zipfile
+
+import pytest
+
+from agent_reach.runtime import browser, cdp, tools
+
+
+def home(monkeypatch, tmp_path):
+ monkeypatch.setenv("HOME", str(tmp_path))
+ monkeypatch.setattr(browser, "is_running", lambda: False)
+ return tmp_path
+
+
+def _zip(path, files):
+ with zipfile.ZipFile(path, "w") as zf:
+ for name, (data, mode) in files.items():
+ info = zipfile.ZipInfo(name)
+ info.external_attr = (0o100000 | mode) << 16
+ zf.writestr(info, data)
+ return path
+
+
+def _fake_downloads(monkeypatch, index: dict, archives: dict):
+ monkeypatch.setattr(browser, "_fetch", lambda url, timeout=30.0: json.dumps(index[url]).encode())
+ monkeypatch.setattr(browser, "_download", lambda url, dest, timeout=60.0: shutil.copy(archives[url], dest))
+
+
+def test_domain_match_is_exact_or_subdomain():
+ assert cdp.domain_matches(".reddit.com", "reddit.com")
+ assert cdp.domain_matches("www.reddit.com", "reddit.com")
+ assert not cdp.domain_matches("notreddit.com", "reddit.com")
+
+
+def test_extension_installs_at_a_stable_path_and_refreshes_only_on_new_release(home, monkeypatch, tmp_path):
+ manifest = lambda v: (json.dumps({"manifest_version": 3, "version": v}), 0o644) # noqa: E731
+ v1 = _zip(tmp_path / "v1.zip", {"manifest.json": manifest("1.0.1"), "dist/background.js": ("//", 0o644)})
+ v2 = _zip(tmp_path / "v2.zip", {"manifest.json": manifest("1.0.2")})
+ release = {"assets": [{"name": "opencli-extension-v1.0.1.zip", "browser_download_url": "u1"}]}
+ _fake_downloads(monkeypatch, {browser.OPENCLI_RELEASE_API: release}, {"u1": v1, "u2": v2})
+
+ assert browser.refresh_extension() == {"version": "1.0.1", "updated": True}
+ assert (browser.extension_dir() / "dist" / "background.js").is_file()
+ assert browser.refresh_extension() == {"version": "1.0.1", "updated": False}
+
+ release["assets"] = [{"name": "opencli-extension-v1.0.2.zip", "browser_download_url": "u2"}]
+ assert browser.refresh_extension() == {"version": "1.0.2", "updated": True}
+ assert browser.extension_version() == "1.0.2"
+ assert browser._load_state()["extension_version"] == "1.0.2"
+
+
+def test_extension_refresh_offline_keeps_the_current_copy(home, monkeypatch):
+ browser.extension_dir().mkdir(parents=True)
+ (browser.extension_dir() / "manifest.json").write_text(json.dumps({"version": "1.0.0"}))
+
+ def offline(url, timeout=30.0):
+ raise OSError("offline")
+
+ monkeypatch.setattr(browser, "_fetch", offline)
+ assert browser.refresh_extension() == {"version": "1.0.0", "updated": False}
+
+
+def test_ensure_chrome_installs_chrome_for_testing_when_system_has_none(home, monkeypatch, tmp_path):
+ archive = _zip(tmp_path / "cft.zip", {"chrome-linux64/chrome": ("#!/bin/sh\n", 0o755)})
+ index = {"channels": {"Stable": {"version": "155.0.1", "downloads": {"chrome": [
+ {"platform": "linux64", "url": "cft-url"}]}}}}
+ _fake_downloads(monkeypatch, {browser.CFT_VERSIONS_URL: index}, {"cft-url": archive})
+ monkeypatch.setattr(browser, "_system_chrome", lambda: None)
+ monkeypatch.setattr(browser, "_cft_platform", lambda: "linux64")
+ recorded = []
+ monkeypatch.setattr(tools, "record", lambda name, version: recorded.append((name, version)), raising=False)
+
+ assert browser.chrome_binary() is None # never downloads by itself
+ exe = browser.ensure_chrome()
+ assert exe == str(tools.tool_dir("chrome") / "chrome-linux64" / "chrome")
+ assert os.access(exe, os.X_OK)
+ assert browser.chrome_binary() == exe
+ assert recorded == [("chrome", "155.0.1")]
+ assert browser.ensure_chrome() == exe and len(recorded) == 1 # second call: no download
+
+
+def test_ensure_chrome_prefers_system_chrome(home, monkeypatch):
+ monkeypatch.setattr(browser, "_system_chrome", lambda: "/sys/chrome")
+ monkeypatch.setattr(browser, "_fetch", lambda *a, **k: pytest.fail("must not download"))
+ assert browser.ensure_chrome() == "/sys/chrome"
+
+
+def test_clear_site_expires_only_that_sites_cookies(home, monkeypatch):
+ jar = [
+ {"name": "a", "value": "1", "domain": ".reddit.com", "path": "/"},
+ {"name": "b", "value": "2", "domain": "www.reddit.com", "path": "/"},
+ {"name": "c", "value": "3", "domain": "notreddit.com", "path": "/"},
+ ]
+
+ def fake_call(method, params=None):
+ if method == "Storage.getCookies":
+ return {"cookies": list(jar)}
+ if method == "Storage.setCookies":
+ for c in params["cookies"]:
+ assert c["expires"] == 1
+ jar[:] = [j for j in jar if (j["name"], j["domain"]) != (c["name"], c["domain"])]
+ return {}
+ raise AssertionError(method)
+
+ browser.profile_dir().mkdir(parents=True)
+ monkeypatch.setattr(browser, "ensure_running", lambda context=None: None)
+ monkeypatch.setattr(cdp, "call", fake_call)
+ assert browser.clear_site(["reddit.com"]) == 2
+ assert [c["name"] for c in jar] == ["c"]
+
+
+def test_clear_site_never_opens_a_browser_that_was_never_used(home, monkeypatch):
+ monkeypatch.setattr(browser, "ensure_running", lambda context=None: pytest.fail("opened the browser"))
+ assert browser.clear_site(["reddit.com"]) == 0
+
+
+def test_delete_profile_removes_the_browser_folder(home, monkeypatch):
+ monkeypatch.setattr(browser, "stop", lambda timeout=10.0: True)
+ browser.profile_dir().mkdir(parents=True)
+ browser.touch()
+ assert browser.delete_profile() is True
+ assert not browser.browser_root().exists()
+ assert browser.delete_profile() is False
+
+
+def test_pipe_connection_matches_replies_and_notices_close():
+ to_chrome_r, to_chrome_w = os.pipe()
+ from_chrome_r, from_chrome_w = os.pipe()
+
+ def fake_chrome(): # echoes each NUL-delimited command back as a reply, with an event first
+ buf = b""
+ while True:
+ chunk = os.read(to_chrome_r, 4096)
+ if not chunk:
+ break
+ buf += chunk
+ while b"\0" in buf:
+ raw, buf = buf.split(b"\0", 1)
+ msg = json.loads(raw)
+ os.write(from_chrome_w, json.dumps({"method": "Some.event"}).encode() + b"\0")
+ os.write(from_chrome_w, json.dumps({"id": msg["id"], "result": {"id": msg["params"]["path"]}}).encode() + b"\0")
+ os.close(from_chrome_w) # Chrome exits when its input pipe closes
+ os.close(to_chrome_r)
+
+ t = threading.Thread(target=fake_chrome)
+ t.start()
+ conn = cdp.PipeConnection(to_chrome_w, from_chrome_r)
+ assert conn.call("Extensions.loadUnpacked", {"path": "/ext"}) == {"id": 1, "result": {"id": "/ext"}}
+ assert conn.call("Extensions.loadUnpacked", {"path": "/two"})["result"] == {"id": "/two"}
+ conn.close()
+ t.join(5)
+ assert conn.closed.is_set()
+ assert "error" in conn.call("Browser.close", timeout=1)
diff --git a/tests/test_manage.py b/tests/test_manage.py
index 2a4e916c..f7f86461 100644
--- a/tests/test_manage.py
+++ b/tests/test_manage.py
@@ -1,13 +1,22 @@
# -*- coding: utf-8 -*-
-"""Management commands: private installs, add/remove, setup, doctor, uninstall, update, skill."""
+"""Management commands: installs, add/remove, setup, sync, doctor, uninstall, update notice, skill.
+Package managers and downloads are faked (fake executables that print a
+version); everything else (state.json, tool folders, pruning, the CLI JSON)
+runs for real in the per-test temp HOME.
+"""
+
+import dataclasses
import json
import os
+import re
+import shutil
+import time
import pytest
from agent_reach.channels.base import Action, Channel, Param
-from agent_reach.runtime import browser, manage, state, tools
+from agent_reach.runtime import browser, manage, state, tools, update_notice
from agent_reach.runtime.result import ReachError
from agent_reach.utils.paths import home_dir
@@ -33,6 +42,10 @@ class Web(_Base):
name, level, actions = "web", "default", _actions()
+class Vid(_Base):
+ name, level, actions, tools = "vid", "default", _actions(), ("bili-cli",)
+
+
class Bili(_Base):
name, level, actions, tools = "bili", "optional", _actions(), ("bili-cli",)
@@ -42,78 +55,201 @@ class Bili2(_Base):
class Needy(_Base):
- name, level, actions, prereqs = "needy", "optional", _actions(), ("x",)
+ name, level, actions, prereqs = "needy", "optional", _actions(), ("ffmpeg",)
+
+
+class Site(_Base):
+ name, level, actions, tools, prereqs = "site", "optional", _actions(), ("opencli",), ("node",)
+ login_url = "https://www.site.example/login"
+
+
+class Site2(Site):
+ name, login_url = "site2", "https://other.example/"
+
+
+class Linky(_Base):
+ name, level, actions, tools = "linky", "optional", _actions(), ("mcporter",)
+ login_argv = ("mcporter", "login")
+
+
+def _fake_exe(path, version):
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(f"#!/bin/sh\necho {version}\n")
+ path.chmod(0o755)
@pytest.fixture
def env(monkeypatch):
- chans = [Web(), Bili(), Bili2(), Needy()]
+ monkeypatch.setenv("PATH", os.environ.get("PATH", "")) # cli.main extends PATH; restore it
+ chans = [Web(), Vid(), Bili(), Bili2(), Needy(), Site(), Site2(), Linky()]
monkeypatch.setattr(manage, "_channels", lambda: chans)
- monkeypatch.setitem(manage.PREREQS, "x", {"check": lambda: False, "hint": "install x"})
- installs = []
+ system = {} # command -> path the "user's PATH" has
+ monkeypatch.setattr(tools.shutil, "which", lambda c, *a, **k: system.get(c))
+ installs, versions = [], {}
def fake_install(tool, *, global_=False):
- installs.append((tool.name, global_))
- if not global_:
- b = tools._private_bin(tool, tool.commands[0])
- b.parent.mkdir(parents=True, exist_ok=True)
- b.write_text("")
+ installs.append(tool.name)
+ version = versions.get(tool.name, "1.2.3")
+ if tool.kind in ("pip", "ffmpeg"):
+ shutil.rmtree(tools.tool_dir(tool.name) / "venv", ignore_errors=True) # as the real installer
+ paths = ([tools._npm_global_bin() / c for c in tool.commands] if global_
+ else [tools._private_bin(tool, c) for c in tool.commands])
+ for p in paths:
+ _fake_exe(p, version)
+ if tool.kind in ("pip", "ffmpeg"):
+ site = tools.tool_dir(tool.name) / "venv" / "lib" / "python3.12" / "site-packages"
+ dist = re.sub(r"[-_.]+", "_", tools._dist_name(tool))
+ (site / f"{dist}-{version}.dist-info").mkdir(parents=True, exist_ok=True)
+ if tool.kind == "npm" and not global_:
+ pkg = tools.tool_dir(tool.name) / "node_modules" / tool.package
+ pkg.mkdir(parents=True, exist_ok=True)
+ (pkg / "package.json").write_text(json.dumps({"version": version}))
+
+ def fake_user_upgrade(tool):
+ installs.append(("user-upgrade", tool.name))
+ _fake_exe(home_dir() / "usr-bin" / tool.commands[0], versions.get(tool.name, "1.9.0"))
monkeypatch.setattr(tools, "_install", fake_install)
- stopped = []
+ monkeypatch.setattr(tools, "_upgrade_user_singleton", fake_user_upgrade)
+ calls, stopped = [], []
+ monkeypatch.setattr(browser, "ensure_chrome", lambda: calls.append("ensure_chrome") or "/x/chrome", raising=False)
+ monkeypatch.setattr(browser, "chrome_binary", lambda: "/x/chrome")
+ monkeypatch.setattr(browser, "setup", lambda: calls.append("setup") or {}, raising=False)
+ monkeypatch.setattr(browser, "start", lambda url="about:blank": calls.append(("start", url)))
+ monkeypatch.setattr(browser, "clear_site", lambda d: calls.append(("clear_site", tuple(d))) or 3, raising=False)
+ monkeypatch.setattr(browser, "delete_profile", lambda: calls.append("delete_profile") or True, raising=False)
monkeypatch.setattr(browser, "is_running", lambda: False)
- monkeypatch.setattr(browser, "stop", lambda: stopped.append(True), raising=False)
- return {"chans": chans, "installs": installs, "stopped": stopped}
+ monkeypatch.setattr(browser, "stop", lambda *a, **k: stopped.append(True) or True, raising=False)
+ return {"chans": chans, "installs": installs, "versions": versions, "system": system,
+ "calls": calls, "stopped": stopped}
+
+
+def _user_copy(env, command, version):
+ path = home_dir() / "usr-bin" / command
+ _fake_exe(path, version)
+ env["system"][command] = str(path)
-# ── private installs ──
+# ── installs and versions ──
-def test_private_copy_wins_over_path(env, monkeypatch):
- monkeypatch.setattr(tools.shutil, "which", lambda c: "/usr/bin/" + c)
+def test_private_copy_wins_over_path(env):
+ env["system"]["bili"] = "/usr/bin/bili"
assert tools.resolve("bili") == "/usr/bin/bili"
tools.ensure("bili-cli")
assert tools.resolve("bili") == str(tools._private_bin(tools.TOOLS["bili-cli"], "bili"))
-def test_private_install_is_recorded_as_ours_and_not_repeated(env):
- assert tools.ensure("bili-cli")["owner"] == "agent-reach"
+def test_install_records_the_installed_version_and_upgrade_reinstalls(env):
+ assert tools.ensure("bili-cli") == {"tool": "bili-cli", "owner": "agent-reach", "scope": "private",
+ "version": "1.2.3"}
tools.ensure("bili-cli")
- assert env["installs"] == [("bili-cli", False)]
+ assert env["installs"] == ["bili-cli"], "an installed tool is not reinstalled by add"
+ env["versions"]["bili-cli"] = "2.0.0"
+ tools.ensure("bili-cli", upgrade=True)
+ assert env["installs"] == ["bili-cli", "bili-cli"]
+ assert state.load()["tools"]["bili-cli"]["version"] == "2.0.0"
+
+
+def test_old_record_without_version_gets_one_without_reinstall(env):
+ tools.ensure("bili-cli")
+ data = state.load()
+ data["tools"]["bili-cli"] = {"spec": "bilibili-cli==0.6.2", "owner": "agent-reach", "scope": "private"}
+ state.save(data)
+ assert tools.ensure("bili-cli")["version"] == "1.2.3"
+ assert env["installs"] == ["bili-cli"]
+
+
+def test_install_spec_is_unpinned_and_honours_floor_and_exclude():
+ assert tools.install_spec(tools.TOOLS["bili-cli"]) == "bilibili-cli"
+ assert "git+" not in tools.install_spec(tools.TOOLS["boss-agent-cli"])
+ assert tools.install_spec(tools.Tool("y", "pip", "pkg", ("y",), floor="1.0", exclude=("1.5",))) == "pkg>=1.0,!=1.5"
+ npm = tools.Tool("x", "npm", "pkg", ("x",), floor="1.0.0", exclude=("1.2.0", "1.1.0"))
+ assert tools.install_spec(npm) == "pkg@>=1.0.0 <1.1.0 || >1.1.0 <1.2.0 || >1.2.0"
+ assert tools.install_spec(tools.Tool("z", "npm", "pkg", ("z",))) == "pkg"
@pytest.mark.parametrize(
- "user_version, allow, expect_install, expect_owner",
- [("1.9.0", False, False, "user"), ("1.8.0", True, True, "user"), (None, False, True, "agent-reach")],
+ "user_version, allow, expect_install, expect_owner, expect_version",
+ [("1.9.0", False, [], "user", "1.9.0"),
+ ("1.8.0", True, [("user-upgrade", "opencli")], "user", "1.9.0"),
+ (None, False, ["opencli"], "agent-reach", "1.2.3")],
)
def test_singleton_reuses_user_copy_and_upgrades_only_with_consent(
- env, monkeypatch, user_version, allow, expect_install, expect_owner
+ env, user_version, allow, expect_install, expect_owner, expect_version
):
- monkeypatch.setattr(tools, "installed_version", lambda t: user_version)
+ env["system"].update(node="/usr/bin/node", npm="/usr/bin/npm", npx="/usr/bin/npx")
+ if user_version:
+ _user_copy(env, "opencli", user_version)
entry = tools.ensure("opencli", allow_upgrade=allow)
assert entry["owner"] == expect_owner and entry["scope"] == "global"
- assert (env["installs"] == [("opencli", True)]) is expect_install
+ assert entry["version"] == expect_version
+ assert env["installs"] == expect_install
-def test_singleton_too_old_without_consent_changes_nothing(env, monkeypatch):
- monkeypatch.setattr(tools, "installed_version", lambda t: "1.0.0")
+def test_singleton_outside_limits_without_consent_changes_nothing(env, monkeypatch):
+ env["system"].update(node="/usr/bin/node", npm="/usr/bin/npm", npx="/usr/bin/npx")
+ monkeypatch.setitem(tools.TOOLS, "opencli", dataclasses.replace(tools.TOOLS["opencli"], exclude=("1.9.0",)))
+ _user_copy(env, "opencli", "1.9.0")
with pytest.raises(ReachError) as info:
tools.ensure("opencli")
assert info.value.code == "NEED_SETUP" and "--allow-upgrade" in info.value.hint
- assert env["installs"] == []
+ assert env["installs"] == [] and "opencli" not in state.load()["tools"]
-# ── add / remove ──
+def test_our_singleton_is_upgraded_by_update(env):
+ tools.ensure("opencli")
+ env["versions"]["opencli"] = "2.0.0"
+ assert tools.ensure("opencli", upgrade=True)["version"] == "2.0.0"
+ assert env["installs"] == ["node", "opencli", "opencli"]
-def test_add_with_missing_prerequisite_installs_nothing(env):
- with pytest.raises(ReachError) as info:
- manage.add("needy")
- assert info.value.code == "NEED_SETUP" and "install x" in info.value.hint
- assert "needy" not in state.load()["channels"]
+# ── add: missing prerequisites are installed ──
+
+
+def test_add_installs_missing_prerequisite_privately(env):
+ out = manage.add("needy")
+ assert out["added"] is True and env["installs"] == ["ffmpeg"]
+ assert tools.ffmpeg_path() == str(tools._private_bin(tools.TOOLS["ffmpeg"], "ffmpeg"))
+ assert state.load()["tools"]["ffmpeg"] == {"owner": "agent-reach", "scope": "private", "version": "1.2.3"}
+ assert "needy" in state.load()["channels"]
+
+
+def test_system_prerequisite_is_used_not_installed(env):
+ env["system"]["ffmpeg"] = "/usr/bin/ffmpeg"
+ manage.add("needy")
+ assert env["installs"] == [] and "ffmpeg" not in state.load()["tools"]
+
+
+def test_npm_tool_gets_private_node_first(env):
+ out = manage.add("linky")
+ assert env["installs"] == ["node", "mcporter"]
+ assert {t: e["version"] for t, e in state.load()["tools"].items()} == {"node": "1.2.3", "mcporter": "1.2.3"}
+ assert "agent-reach login linky" in out["next"]
+
+
+def test_browser_channel_add_opens_login_and_remove_cleans_up(env):
+ out = manage.add("site")
+ assert "ensure_chrome" in env["calls"]
+ assert env["calls"][-2:] == ["setup", ("start", "https://www.site.example/login")]
+ assert isinstance(out["next"], str) and "logs in" in out["next"]
+ manage.add("site2")
+ browser.profile_dir().mkdir(parents=True)
+ first = manage.remove("site")
+ assert ("clear_site", ("site.example",)) in env["calls"] and first["cleared_cookies"] == 3
+ assert first["removed_tools"] == [] and "delete_profile" not in env["calls"]
+ last = manage.remove("site2")
+ assert "delete_profile" in env["calls"] and last["browser_deleted"] is True
+ assert set(last["removed_tools"]) == {"opencli", "node"}
+ assert state.load()["tools"] == {}
+ assert not tools.tool_dir("node").exists()
+
+
+# ── remove ──
def test_remove_keeps_tool_still_used_by_another_channel(env):
+ manage.remove("vid")
manage.add("bili")
manage.add("bili2")
assert manage.remove("bili")["removed_tools"] == []
@@ -122,9 +258,122 @@ def test_remove_keeps_tool_still_used_by_another_channel(env):
assert not tools.tool_dir("bili-cli").exists()
-def test_default_channels_cannot_be_removed(env):
- with pytest.raises(ReachError):
- manage.remove("web")
+def test_default_channel_can_be_removed_and_stays_removed(env):
+ manage.setup()
+ assert tools.tool_dir("bili-cli").exists()
+ out = manage.remove("vid")
+ assert out["removed"] is True and out["removed_tools"] == ["bili-cli"]
+ assert state.load()["removed_defaults"] == ["vid"]
+ manage.setup()
+ manage.sync()
+ assert not tools.tool_dir("bili-cli").exists() and _status("vid") == "not_added"
+ manage.add("vid")
+ assert state.load()["removed_defaults"] == [] and _status("vid") == "unverified"
+
+
+# ── sync / update ──
+
+
+def test_sync_upgrades_prunes_drops_and_reports(env):
+ manage.add("bili")
+ data = state.load()
+ data["tools"]["old-tool"] = {"owner": "agent-reach", "scope": "private", "version": "0.1.0"}
+ data["tools"]["user-thing"] = {"owner": "user", "scope": "global", "version": "1.0.0"}
+ data["channels"]["gone"] = {"added_at": "2026-01-01T00:00:00Z"}
+ data["checks"]["bili"] = {"at": state.now(), "actions": {"search": False}, "codes": {"search": "NEED_LOGIN"}}
+ state.save(data)
+ (tools.tool_dir("old-tool") / "bin").mkdir(parents=True)
+ env["versions"]["bili-cli"] = "2.0.0"
+ out = manage.sync()
+ assert out["removed_tools"] == ["old-tool"] and not tools.tool_dir("old-tool").exists()
+ assert set(state.load()["tools"]) == {"bili-cli"}, "records of unused user copies are dropped, the copies kept"
+ assert state.load()["tools"]["bili-cli"]["version"] == "2.0.0"
+ assert env["installs"].count("bili-cli") == 2, "shared tools upgrade once per sync"
+ assert out["dropped_channels"] == ["gone"] and "gone" not in state.load()["channels"]
+ assert any("gone" in a for a in out["user_actions"])
+ assert any("log in to bili" in a for a in out["user_actions"])
+
+
[email protected]("latest, available", [("v2.0.1", True), ("v2.0.0", False), ("v1.9.9", False)])
+def test_update_check_compares_versions_and_refreshes_the_cache(monkeypatch, latest, available):
+ monkeypatch.setattr(manage, "__version__", "2.0.0")
+ monkeypatch.setattr(update_notice, "__version__", "2.0.0")
+ monkeypatch.setattr(update_notice, "fetch_latest", lambda timeout=10: {"latest": latest.lstrip("v"), "notes": "n"})
+ assert manage.update_check()["update_available"] is available
+ assert update_notice.read_cache()["latest"] == latest.lstrip("v")
+ assert (update_notice.notice() is not None) is available
+
+
+def test_upgrade_reinstalls_the_release_with_uv():
+ cmd = manage.upgrade_command("2.0.1")
+ assert cmd[:4] == ["uv", "tool", "install", "--force"] and cmd[-1].endswith("/v2.0.1.zip")
+
+
+def test_update_from_a_non_uv_install_asks_for_one_uv_reinstall(monkeypatch):
+ monkeypatch.setattr(manage, "update_check", lambda: {"current": "2.0.0", "latest": "2.0.1",
+ "update_available": True})
+ monkeypatch.setattr(manage, "install_method", lambda: "other")
+ monkeypatch.setattr(manage.subprocess, "run", lambda *a, **k: pytest.fail("must not run an installer"))
+ with pytest.raises(ReachError) as info:
+ manage.update()
+ assert "uv tool install --force" in info.value.hint
+
+
+def test_update_without_new_release_still_upgrades_tools(env, monkeypatch):
+ monkeypatch.setattr(manage, "update_check", lambda: {"current": "2.0.0", "latest": "2.0.0",
+ "update_available": False})
+ manage.add("bili")
+ env["versions"]["bili-cli"] = "3.0.0"
+ out = manage.update()
+ assert out["upgraded"] is False and isinstance(out["user_actions"], list)
+ assert state.load()["tools"]["bili-cli"]["version"] == "3.0.0"
+
+
+# ── update notice ──
+
+
+def _cli_json(capsys, argv):
+ from agent_reach.runtime import cli
+
+ cli.main(argv)
+ return json.loads(capsys.readouterr().out.strip().splitlines()[-1])
+
+
+def test_every_json_output_carries_meta_update_only_when_newer(env, capsys, monkeypatch):
+ monkeypatch.setattr(update_notice, "__version__", "1.6.0")
+ assert "meta" not in _cli_json(capsys, ["doctor"]), "no cache, no notice"
+ update_notice.write_cache({"latest": "1.7.0", "notes": "faster"})
+ expected = {"current": "1.6.0", "latest": "1.7.0", "notes": "faster"}
+ assert _cli_json(capsys, ["doctor"])["meta"]["update"] == expected
+ channels = _cli_json(capsys, ["channels"])
+ assert channels["meta"]["update"] == expected
+ action = _cli_json(capsys, ["web", "search", "x"])
+ assert action["meta"]["update"] == expected and "elapsed_ms" in action["meta"]
+ update_notice.write_cache({"latest": "1.6.0", "notes": ""})
+ assert "meta" not in _cli_json(capsys, ["doctor"])
+
+
+def test_background_check_starts_at_most_once_a_day(monkeypatch):
+ monkeypatch.delenv(update_notice.DISABLE_ENV)
+ started = []
+ monkeypatch.setattr(update_notice.subprocess, "Popen", lambda argv, **k: started.append(argv))
+ update_notice.maybe_refresh()
+ update_notice.maybe_refresh()
+ assert len(started) == 1 and started[0][-1] == "agent_reach.runtime.update_notice"
+ old = time.time() - update_notice.INTERVAL - 5
+ os.utime(update_notice.started_path(), (old, old))
+ update_notice.maybe_refresh()
+ assert len(started) == 2
+
+
+def test_background_check_writes_cache_or_stays_silent(monkeypatch):
+ def offline(timeout=10):
+ raise OSError("offline")
+
+ monkeypatch.setattr(update_notice, "fetch_latest", offline)
+ assert update_notice._main() == 1 and not update_notice.cache_path().exists()
+ monkeypatch.setattr(update_notice, "fetch_latest", lambda timeout=10: {"latest": "9.9.9", "notes": "n"})
+ assert update_notice._main() == 0 and update_notice.read_cache()["latest"] == "9.9.9"
# ── doctor ──
@@ -152,9 +401,9 @@ def test_doctor_states(env):
assert _status("bili") == "unverified"
-def test_doctor_reports_missing_tool_as_needs_setup(env, monkeypatch):
- monkeypatch.setattr(tools.shutil, "which", lambda c: None)
+def test_doctor_reports_missing_tool_and_shows_versions(env):
manage.add("bili")
+ assert {"tool": "bili-cli", "owner": "agent-reach", "scope": "private", "version": "1.2.3"} in manage.doctor()["tools"]
tools.remove_private("bili-cli")
assert _status("bili") == "needs_setup"
@@ -162,7 +411,7 @@ def test_doctor_reports_missing_tool_as_needs_setup(env, monkeypatch):
def test_check_without_names_tests_only_default_and_added_channels(env):
manage.add("bili")
tested = {r["channel"] for r in manage.run_checks()["results"]}
- assert tested == {"web", "bili"}
+ assert tested == {"web", "vid", "bili"}
def test_doctor_marks_regressed_only_when_the_previous_check_passed(env):
@@ -200,13 +449,16 @@ def test_setup_adds_default_channels_and_survives_a_failing_install(env, monkeyp
monkeypatch.setattr(tools, "_install", failing_install)
result = manage.setup()
by_name = {c["channel"]: c for c in result["default_channels"]}
- assert set(by_name) == {"web", "broken"}
+ assert set(by_name) == {"web", "vid", "broken"}
assert by_name["web"]["ok"] is True
assert by_name["broken"]["ok"] is False and by_name["broken"]["error"]["code"] == "UPSTREAM_BROKEN"
- assert result["prerequisites"] == {}, "only prerequisites of default channels are reported"
+ assert "prerequisites" not in result, "prerequisites are installed, not reported"
assert result["logins"] == [{"channel": "broken", "command": "agent-reach login broken"}]
- assert {c["channel"] for c in result["optional_channels"]} == {"bili", "bili2", "needy"}
+ optional = {c["channel"]: c["needs"] for c in result["optional_channels"]}
+ assert set(optional) == {"bili", "bili2", "needy", "site", "site2", "linky"}
+ assert optional["needy"] == [] and optional["site"] == ["login"]
assert result["skill"]["installed"] is True
+ assert env["calls"] == [], "setup opens no login window"
# ── uninstall ──
@@ -218,12 +470,14 @@ def test_uninstall_removes_only_what_we_own(env):
(root / "config.yaml").write_text("x: 1")
(root / "my-notes").mkdir()
(root / "tools" / "someone-elses-tool").mkdir(parents=True)
+ update_notice.write_cache({"latest": "1.0.0", "notes": ""})
dry = manage.uninstall(dry_run=True)
assert (root / "state.json").exists(), "dry run changes nothing"
assert str(tools.tool_dir("bili-cli")) in dry["removed"]
assert env["stopped"] == []
manage.uninstall()
assert not (root / "state.json").exists() and not (root / "config.yaml").exists()
+ assert not update_notice.cache_path().exists()
assert not tools.tool_dir("bili-cli").exists()
assert (root / "my-notes").exists() and (root / "tools" / "someone-elses-tool").exists()
@@ -232,42 +486,6 @@ def test_uninstall_closes_the_browser_instead_of_refusing(env):
manage.uninstall()
assert env["stopped"] == [True]
-
-# ── update ──
-
-
[email protected]("latest, available", [("v2.0.1", True), ("v2.0.0", False), ("v1.9.9", False)])
-def test_update_check_compares_versions(monkeypatch, latest, available):
- class Resp:
- def __enter__(self):
- return self
-
- def __exit__(self, *a):
- return False
-
- def read(self):
- return json.dumps({"tag_name": latest}).encode()
-
- monkeypatch.setattr(manage, "__version__", "2.0.0")
- monkeypatch.setattr(manage.urllib.request, "urlopen", lambda *a, **k: Resp())
- assert manage.update_check()["update_available"] is available
-
-
-def test_upgrade_reinstalls_the_release_with_uv():
- cmd = manage.upgrade_command("2.0.1")
- assert cmd[:4] == ["uv", "tool", "install", "--force"] and cmd[-1].endswith("/v2.0.1.zip")
-
-
-def test_update_from_a_non_uv_install_asks_for_one_uv_reinstall(monkeypatch):
- monkeypatch.setattr(manage, "update_check", lambda: {"current": "2.0.0", "latest": "2.0.1",
- "update_available": True})
- monkeypatch.setattr(manage, "install_method", lambda: "other")
- monkeypatch.setattr(manage.subprocess, "run", lambda *a, **k: pytest.fail("must not run an installer"))
- with pytest.raises(ReachError) as info:
- manage.update()
- assert "uv tool install --force" in info.value.hint
-
-
# ── skill ──
diff --git a/tests/test_transcribe.py b/tests/test_transcribe.py
index 29680bed..741a0cdd 100644
--- a/tests/test_transcribe.py
+++ b/tests/test_transcribe.py
@@ -1,6 +1,7 @@
# -*- coding: utf-8 -*-
"""Tests for agent_reach.transcribe — provider routing, fallback, and errors."""
+import os
import subprocess
from pathlib import Path
from typing import List
@@ -281,12 +282,13 @@ class TestOrchestrator:
events = []
def fake_run(cmd, **_kwargs):
- events.append(cmd[0])
+ events.append(os.path.basename(cmd[0]))
+ seconds = tr.MAX_AUDIO_SECONDS + 1
return subprocess.CompletedProcess(
cmd,
- 0,
- stdout=str(tr.MAX_AUDIO_SECONDS + 1),
- stderr="",
+ 1,
+ stdout="",
+ stderr=f" Duration: {seconds // 3600:02d}:{seconds % 3600 // 60:02d}:{seconds % 60:02d}.00, start: 0\n",
)
monkeypatch.setattr(tr, "_require", lambda _binary: None)
@@ -302,7 +304,7 @@ class TestOrchestrator:
with pytest.raises(tr.TranscribeError, match="duration.*limit"):
tr.transcribe(str(chunk_file), config=fake_config)
- assert events == ["ffprobe"]
+ assert events == ["ffmpeg"]
def test_duration_probe_timeout_fails_before_compression(
self, monkeypatch, fake_config, chunk_file
@@ -314,7 +316,7 @@ class TestOrchestrator:
observed["timeout"] = _kwargs.get("timeout")
raise subprocess.TimeoutExpired(
cmd,
- timeout=tr.FFPROBE_TIMEOUT_SECONDS,
+ timeout=tr.PROBE_TIMEOUT_SECONDS,
)
monkeypatch.setattr(tr, "_require", lambda _binary: None)
@@ -329,11 +331,11 @@ class TestOrchestrator:
with pytest.raises(
tr.TranscribeError,
- match=r"ffprobe timed out.*30s",
+ match=r"ffmpeg timed out.*30s",
):
tr.transcribe(str(chunk_file), config=fake_config)
- assert observed["timeout"] == tr.FFPROBE_TIMEOUT_SECONDS
+ assert observed["timeout"] == tr.PROBE_TIMEOUT_SECONDS
def test_unparseable_duration_fails_before_compression(
self, monkeypatch, fake_config, chunk_file
@@ -345,9 +347,9 @@ class TestOrchestrator:
"run",
lambda cmd, **_kwargs: subprocess.CompletedProcess(
cmd,
- 0,
- stdout="N/A\n",
- stderr="",
+ 1,
+ stdout="",
+ stderr=" Duration: N/A, bitrate: N/A\n",
),
)
monkeypatch.setattr(
@@ -360,7 +362,7 @@ class TestOrchestrator:
with pytest.raises(
tr.TranscribeError,
- match=r"ffprobe could not parse.*duration",
+ match=r"ffmpeg could not parse.*duration",
):
tr.transcribe(str(chunk_file), config=fake_config)
diff --git a/tests/test_unified_entry.py b/tests/test_unified_entry.py
index 3bc2589c..cba74534 100644
--- a/tests/test_unified_entry.py
+++ b/tests/test_unified_entry.py
@@ -356,18 +356,32 @@ def fake_browser(monkeypatch, tmp_path):
from agent_reach.runtime import browser
monkeypatch.setenv("HOME", str(tmp_path))
- state = {"contexts": ["daily"], "running": True, "opened": [], "launches": 0, "launch_delay": 0.0}
+ state = {"contexts": ["daily"], "running": True, "opened": [], "launches": 0, "launch_delay": 0.0,
+ "watched": False}
def fake_launch(url):
state["launches"] += 1
time.sleep(state["launch_delay"])
state["running"] = True
+ state["watched"] = True # a real launch starts the owning watcher
state["contexts"].append("dedicated")
+ def fake_stop(timeout=10.0):
+ state["running"] = False
+ state["watched"] = False
+ if "dedicated" in state["contexts"]:
+ state["contexts"].remove("dedicated")
+ return True
+
+ real_watcher_running = browser.watcher_running
monkeypatch.setattr(browser, "connected_contexts", lambda: list(state["contexts"]))
monkeypatch.setattr(browser, "is_running", lambda: state["running"])
+ monkeypatch.setattr(browser, "watcher_running", lambda: state["watched"] or real_watcher_running())
monkeypatch.setattr(browser, "start", lambda url="about:blank": state["opened"].append(url))
monkeypatch.setattr(browser, "_launch", fake_launch)
+ monkeypatch.setattr(browser, "stop", fake_stop)
+ monkeypatch.setattr(browser, "ensure_chrome", lambda: "/fake/chrome")
+ monkeypatch.setattr(browser, "refresh_extension", lambda: {"version": "1.0.0", "updated": False})
monkeypatch.setattr(browser, "_RUNNING_GRACE", 0.0)
return state
@@ -380,26 +394,21 @@ def _bind_dedicated(fake_browser):
browser.bind()
-def test_browser_action_opens_closed_browser_only_when_set_up(fake_browser):
+def test_browser_action_sets_up_unbound_browser_by_itself(fake_browser):
from agent_reach.backends.opencli import _dedicated_profile_env
from agent_reach.runtime import browser
fake_browser["running"] = False
- with pytest.raises(ReachError) as info:
- _dedicated_profile_env()
- assert info.value.code == "NEED_SETUP"
- assert "browser setup" in info.value.hint
- assert fake_browser["launches"] == 0
+ assert _dedicated_profile_env() == {"OPENCLI_PROFILE": "dedicated"} # no NEED_SETUP, no user click
+ assert browser.bound_context() == "dedicated" # the user's own "daily" profile is never picked
+ assert fake_browser["launches"] == 1
- fake_browser["running"] = True
- _bind_dedicated(fake_browser)
assert _dedicated_profile_env() == {"OPENCLI_PROFILE": "dedicated"}
- assert fake_browser["launches"] == 0 # already open: no second browser
+ assert fake_browser["launches"] == 1 # already open: no second browser
- fake_browser["running"] = False
- fake_browser["contexts"].remove("dedicated")
+ browser.stop()
assert _dedicated_profile_env() == {"OPENCLI_PROFILE": "dedicated"}
- assert fake_browser["launches"] == 1
+ assert fake_browser["launches"] == 2 # closed: reopened, not set up again
assert browser.last_used() is not None
@@ -501,26 +510,48 @@ def test_bind_refuses_to_guess_between_two_new_profiles(fake_browser):
assert browser.bound_context() is None
-def test_opencli_calls_fail_fast_without_dedicated_browser(fake_browser):
- from agent_reach.backends.opencli import opencli_call
+def test_windows_without_extension_still_needs_the_users_click(fake_browser, monkeypatch):
+ from agent_reach.backends.opencli import OPENCLI_EXTENSION_URL, opencli_call
+ from agent_reach.runtime import browser
+ monkeypatch.setattr(browser, "can_load_extension", lambda: False)
+ monkeypatch.setattr(browser, "_STORE_WAIT", 0.0)
with pytest.raises(ReachError) as info:
opencli_call("reddit", ["search", "x"], timeout=5)
assert info.value.code == "NEED_SETUP"
+ assert fake_browser["opened"] == [OPENCLI_EXTENSION_URL]
+ assert browser.setup_problems()
+
+def test_mac_and_linux_report_no_setup_problem_before_first_use(fake_browser):
+ from agent_reach.runtime import browser
+
+ assert browser.setup_problems() == []
-def test_opencli_calls_fail_fast_when_dedicated_browser_disconnected(fake_browser):
+
+def test_opencli_calls_fail_fast_when_dedicated_browser_disconnected(fake_browser, monkeypatch):
from agent_reach.backends.opencli import opencli_call
from agent_reach.runtime import browser
- browser.bind()
- fake_browser["contexts"].append("dedicated")
- browser.bind()
+ browser.setup()
+ monkeypatch.setattr(browser, "watcher_running", lambda: True) # our own browser, extension just gone
fake_browser["contexts"].remove("dedicated")
with pytest.raises(ReachError) as info:
opencli_call("reddit", ["search", "x"], timeout=5)
- assert info.value.code == "NEED_SETUP"
+ assert info.value.code == "UPSTREAM_BROKEN"
assert "not connected" in info.value.message
+ assert fake_browser["launches"] == 1
+
+
+def test_browser_left_open_without_watcher_is_reopened_with_extension(fake_browser, monkeypatch):
+ from agent_reach.backends.opencli import _dedicated_profile_env
+ from agent_reach.runtime import browser
+
+ browser.setup()
+ fake_browser["contexts"].remove("dedicated") # e.g. opened by an older Agent Reach, no extension
+ monkeypatch.setattr(browser, "watcher_running", lambda: False)
+ assert _dedicated_profile_env() == {"OPENCLI_PROFILE": "dedicated"}
+ assert fake_browser["launches"] == 2
def test_login_opens_site_in_dedicated_browser(capsys, monkeypatch, fake_browser):