How Agent Reach Manages Upstream Tool Versioning: A Complete Technical Guide

Agent Reach manages upstream tool versioning through a single source-of-truth version string in agent_reach/__init__.py, explicit dependency pins in pyproject.toml, isolated binary storage under ~/.agent-reach/tools, and a built-in check-update CLI command that queries GitHub Releases.

Maintaining reproducible behavior across distributed environments demands strict control over both package and dependency versions. In the Panniantong/Agent-Reach repository, upstream tool versioning is handled through a tightly coupled system of source-of-truth constants, explicit manifest constraints, and CLI-driven update checks. This design ensures that the installed copy of Agent Reach always aligns with verified upstream releases.

Single Source of Truth for the Package Version

Agent Reach defines its library version once in agent_reach/__init__.py at line 4 as the __version__ string. Both the CLI entry point in agent_reach/cli.py and the [project] table in pyproject.toml consume this value, preventing drift between the runtime report and the package metadata.

The argparse setup in cli.py lines 11–18 imports this constant to power the --version flag. Because the same string also appears in the [project] version field, the package version and declared dependency versions stay in sync across all interfaces.

Explicit Dependency Constraints in pyproject.toml

All runtime requirements carry explicit version constraints inside pyproject.toml lines 3–38. The manifest specifies pins such as requests>=2.28 and yt-dlp>=2024.0, ensuring that compatible upstream tool versions are resolved at install time.

# Dependency excerpt from pyproject.toml

dependencies = [
    "requests>=2.28",
    "yt-dlp>=2024.0",
]

Optional dependency groups defined at lines 40–44 provide additional pins for specialized capabilities. Installing the browser, cookies, or all extras pulls exact versions of underlying tools like Playwright, guaranteeing platform compatibility without polluting the base environment.

Built-In CLI Version Reporting

The agent-reach version command prints the current package version by reading __version__ directly from agent_reach/__init__.py. This avoids hard-coded strings in the CLI parser.

$ agent-reach version
Agent Reach v1.4.0

Because cli.py wires the --version action into argparse at lines 11–18, the displayed string is guaranteed to match the source-of-truth constant.

Automatic Update Checks Against GitHub Releases

Agent Reach can detect when a newer upstream release is available without external package managers. The check-update subcommand, implemented in cli.py at lines 31–35 and 128–131, queries the GitHub Releases API, compares the latest tag against the local __version__, and notifies the user.

$ agent-reach check-update
当前版本: v1.4.0
✅ 已是最新

If the remote tag is newer, the CLI outputs a message such as 新版本可用: v1.5.0, allowing users to upgrade proactively.

Isolated Binary Installation Under ~/.agent-reach/tools

For platforms that rely on external binaries rather than Python packages, the agent-reach install … command creates a user-specific directory at ~/.agent-reach/tools. As implemented in cli.py lines 69–73, the installer clones the upstream repository or downloads a tagged release into this location, storing the exact version independently of the system Python environment.

$ agent-reach install --channels youtube

# installer creates ~/.agent-reach/tools/yt-dlp-2024.0

This isolation makes upgrades deterministic: the tool version pinned in pyproject.toml (yt-dlp>=2024.0) is the same version fetched into the local tools directory.

Optional Dependency Groups for Reproducible Environments

The pyproject.toml optional groups let users install upstream tools through pip when binaries are not required. Running pip install -e .[browser] resolves Playwright and related tools at the exact versions declared in the manifest, ensuring the library and its upstream utilities remain compatible.

$ pip install -e .[browser]

# pulls Playwright >=1.40 as declared in pyproject.toml

Health-check utilities in agent_reach/doctor.py also reference the current __version__ when reporting system status, extending version visibility beyond the CLI.

Summary

• Agent Reach keeps its package version in agent_reach/__init__.py and shares it with cli.py and pyproject.toml to prevent mismatches.
• Runtime dependencies and optional extras are pinned with explicit constraints in pyproject.toml lines 3–44.
• The agent-reach version and check-update commands surface the local version and check GitHub Releases for newer tags via cli.py.
• External binaries are installed into an isolated ~/.agent-reach/tools directory, keeping upstream tool versions separate from the system environment.
• Optional groups like browser and all provide reproducible dependency resolution through pip.

Frequently Asked Questions

How does Agent Reach store external tool binaries?

The installer command in agent_reach/cli.py (lines 69–73) creates a local ~/.agent-reach/tools folder for each supported platform. It either clones the upstream repository or downloads a tagged release into that folder, isolating the exact binary version from the system Python packages.

Where is the single source of truth for the Agent Reach version?

The library defines __version__ in agent_reach/__init__.py at line 4. This constant is imported by the CLI parser, displayed by the --version flag in cli.py lines 11–18, and synchronized with the [project] version field in pyproject.toml.

How does the check-update command know when a new release is available?

The check-update subcommand in agent_reach/cli.py (lines 31–35 and 128–131) queries the GitHub Releases API for the latest tag. It compares that tag against the local __version__ string and prints a notification when a newer upstream version exists.

What optional dependency groups does Agent Reach provide?

pyproject.toml defines optional groups such as browser, cookies, and all at lines 40–44. Installing a group (for example, pip install -e .[browser]) resolves exact versions of upstream tools like Playwright, ensuring compatibility with the library’s scraping and automation features.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}