managed_tools

Disable network downloads of managed binaries (e.g. ripgrep).

Parsed by is_env_truthy: accepts 1, true, yes, on as enabled. When truthy, managed_tools.ensure_ripgrep will not attempt to download a binary and falls back to the existing missing-tool notification + slow Python regex path.

Select how ripgrep is provisioned: managed (default) or system.

managed downloads the pinned, SHA-256-verified upstream binary into the dcode installation (no sudo). system skips that download so power users can rely on their distro package / existing toolchain instead; the install script's system mode keeps the brew/apt/cargo path. A system rg already on PATH is reused under either setting. Unrecognized values fall back to managed. See managed_tools.ripgrep_installer.

Process-wide path snapshot captured before any dotenv loader can run.

Pinned release. Bump alongside both SHA-256 tables.

(sys.platform, normalized arch) -> (asset filename, sha256 hex).

SHA-256 of the extracted rg binary in each pinned release asset.

Preferred directory for managed binaries, shared by every profile.

Prepended to PATH on startup. Tied to the installation rather than the profile so relocating DEEPAGENTS_HOME reuses one verified download.

Profile-scoped bin directory used when BIN_DIR is not writable.

A system or root-owned install prefix (pip install --break-system-packages, a packaged interpreter) leaves BIN_DIR unwritable for a normal user, which would otherwise mean no managed ripgrep at all.

Stable reason token for logging and telemetry.

The two recognized ripgrep installer modes.

Default installer mode: fetch the pinned, checksummed upstream binary.

Installer mode that defers ripgrep to the system package manager / PATH.

Return whether env var name is set to a recognizably truthy value.

Unlike bool(os.environ.get(name)), this does not treat "0" or "false" as enabled. Use this for on/off flags where the user would reasonably expect VAR=0 to mean "disabled".

Classify a path as existing, missing, or unreadable.

Return the first candidate directory that accepts a file.

Shared by the managed-bin and update-lock resolvers, which both walk a preferred-then-fallback pair. Callers keep their own "fell back" warning, because the consequence of falling back differs between them.

Return both managed bin locations in preference order.

Read from the module globals on each call rather than frozen into a constant, so a test (or a future runtime override) that patches BIN_DIR is honored by lookup, PATH assembly, and install alike.

Return the managed ripgrep filename for this platform.

Return the managed ripgrep binary path (.exe on Windows).

Return whether managed-tool downloads are disabled via env var.

Return the configured ripgrep installer mode.

Reads RIPGREP_INSTALLER and normalizes it to INSTALLER_MANAGED or INSTALLER_SYSTEM, falling back to INSTALLER_MANAGED for unset or unrecognized values. The strip().lower() normalization must stay in sync with the case block in scripts/install.sh so both layers agree on the parsed mode.

Return whether the user opted into the system ripgrep installer.

In system mode ripgrep is provisioned by the OS package manager or an existing PATH entry rather than the managed download.

Idempotently expose managed ripgrep through os.environ["PATH"].

Safe to call on every startup. The installation-scoped directory is prepended directly. A verified profile fallback is exposed through a process-private shim containing only rg, because the profile may be repository-controlled. Both managed directories are removed from the rest of PATH so neither a stale copy nor a fallback sibling can shadow it.

Prepending only one directory matters for the profile fallback. TB14 permits a DEEPAGENTS_HOME inside a checkout, so <profile>/bin can be a repository-controlled directory. Verifying rg does not make siblings such as git trustworthy, so that directory never enters PATH.

Ensure a usable rg binary is available, installing if necessary.

Resolution order:

1. If the system installer is selected, return a non-managed rg found on PATH, or None when only the managed binary is present.
2. If a managed rg exists and matches RIPGREP_VERSION, return it.
3. Otherwise, if a system rg is on PATH and no managed binary exists, return its resolved path. This is gated on the absence of a managed binary: once a managed rg exists, the pinned version always wins, so a stale managed binary is re-fetched rather than deferring to a system rg and the resolved version stays deterministic.
4. If offline, return None so callers fall back to the existing notification + slow path.
5. If no managed asset matches the platform/arch, return a non-managed rg on PATH when one exists; otherwise raise ManagedToolUnavailableError so callers can explain that retrying will not help.
6. Otherwise download → SHA-256 verify → extract → install → prepend the active managed bin dir to PATH → return the installed path. On a checksum mismatch, raises ChecksumMismatchError so callers can surface a loud notice. On a 404, or when neither managed bin directory is writable, raises ManagedToolUnavailableError; other failures log and return None.

A stale managed binary is never proactively deleted. The atomic replace in _install_ripgrep_sync overwrites it on success, and on failure the user is strictly better off keeping the older copy than being left with no rg at all.

Whether a probed path exists, is absent, or could not be read.

A StrEnum so the value serializes directly to JSON without a custom encoder.

Raised when a downloaded archive fails SHA-256 verification.

Distinct from generic install failure so callers can surface a loud, user-visible notice — a checksum mismatch is a supply-chain anomaly (CDN poisoning, MITM, tampered mirror) and must not be silently treated like "you're offline".

Raised when no managed helper binary is available for this system.

Distinct from transient network/download failures so callers can tell users whether retrying can help or whether they need a different install path.