Skip to content

HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.

environments: an apt version's epoch is part of a package spec (#552)

Rudy Mizrahi Celekli3cfdeb97e0ed
diff --git a/gateway/app.py b/gateway/app.py
index 7a9935a7..f3d7ba65 100644
--- a/gateway/app.py
+++ b/gateway/app.py
@@ -18701,7 +18701,10 @@ class EnvironmentBody(BaseModel):
runtime: dict | None = None # {"python": "3.12"}: the interpreter a build makes the venv with
-_ENV_SPEC_RE = re.compile(r"^@?[A-Za-z0-9][A-Za-z0-9._/+-]{0,99}(?:(?:==|>=|<=|~=|!=|@|=)[A-Za-z0-9._*+^~<>-]{0,60})?$")
+# One declared package: the runner's own pattern (runner/environments.py _SPEC_RE), so a spec the runner
+# builds is never refused here first; an apt version may carry its epoch ("7:4.4.2-0ubuntu0.22.04.1").
+# gateway/tests/test_env_spec_parity.py holds the two equal.
+_ENV_SPEC_RE = re.compile(r"^@?[A-Za-z0-9][A-Za-z0-9._/+-]{0,99}(?:(?:==|>=|<=|~=|!=|@|=)(?:[0-9]{1,4}:)?[A-Za-z0-9._*+^~<>-]{0,60})?$")
_ENV_MANAGERS = ("pip", "npm", "apt")
diff --git a/gateway/tests/test_env_spec_parity.py b/gateway/tests/test_env_spec_parity.py
new file mode 100644
index 00000000..23d3e467
--- /dev/null
+++ b/gateway/tests/test_env_spec_parity.py
@@ -0,0 +1,29 @@
+"""A package spec is read by one rule on both sides. The gateway checks a declared package before the
+runner ever sees it (GET /v1/environments/packages/check, and an environment's create and update); a
+copy of the runner's pattern that drifted refused, at the gateway, the apt spec with an epoch the
+runner accepts ("ffmpeg=7:4.4.2-0ubuntu0.22.04.1"), so the console was told no for a package it can
+build.
+"""
+import os
+import pathlib
+import re
+import sys
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1]))
+os.environ.setdefault("HR_BACKING", "local")
+import app as gw # noqa: E402
+
+RUNNER = pathlib.Path(__file__).resolve().parents[2] / "runner" / "environments.py"
+
+
+def test_the_gateway_reads_a_spec_by_the_runners_own_pattern():
+ src = RUNNER.read_text()
+ runner_pattern = re.search(r'^_SPEC_RE = re\.compile\(r"(.*)"\)', src, re.M).group(1)
+ assert gw._ENV_SPEC_RE.pattern == runner_pattern
+
+
+def test_an_apt_version_with_its_epoch_is_a_spec_at_the_gateway():
+ for spec in ("ffmpeg=7:4.4.2-0ubuntu0.22.04.1", "libssl3=3.0.2-0ubuntu1.18", "numpy==2.3.1", "[email protected]", "jq"):
+ assert gw._ENV_SPEC_RE.match(spec), spec
+ for bad in ("rm -rf /", "a;b", "x=12345:1.0", "x=1:2:3"):
+ assert not gw._ENV_SPEC_RE.match(bad), bad
diff --git a/runner/environments.py b/runner/environments.py
index a2270611..f1186f64 100644
--- a/runner/environments.py
+++ b/runner/environments.py
@@ -66,7 +66,12 @@ TREE_MAX = 20_000 # entri
# thing SPI-001 says not to trust).
NOT_COPIED = {".venv", "venv", "node_modules", "__pycache__", ".pnpm-store", ".cache", ".hr-build.json"}
_ID_SAFE = set("abcdefghijklmnopqrstuvwxyz0123456789_-")
-_SPEC_RE = re.compile(r"^@?[A-Za-z0-9][A-Za-z0-9._/+-]{0,99}(?:(?:==|>=|<=|~=|!=|@|=)[A-Za-z0-9._*+^~<>-]{0,60})?$") # one declared package
+# One declared package. A version may carry apt's epoch — digits and a colon before the upstream
+# version, as in `ffmpeg=7:4.4.2-0ubuntu0.22.04.1`: the form apt itself prints as the candidate and
+# the one check_package tells an owner to declare. The colon is admitted only in that position
+# (`[0-9]{1,4}:`), so nothing else a colon introduces — npm's `pkg@npm:other`, a `pkg@https:` direct
+# reference — becomes a spec for pip or npm, which share this pattern and have no epoch.
+_SPEC_RE = re.compile(r"^@?[A-Za-z0-9][A-Za-z0-9._/+-]{0,99}(?:(?:==|>=|<=|~=|!=|@|=)(?:[0-9]{1,4}:)?[A-Za-z0-9._*+^~<>-]{0,60})?$")
_ARCH_DIRS = {"amd64": "x86_64-linux-gnu", "arm64": "aarch64-linux-gnu"}
# ── who may read an environment ─────────────────────────────────────────────────────────────────
diff --git a/runner/tests/test_environments.py b/runner/tests/test_environments.py
index d83e15e2..981428a0 100644
--- a/runner/tests/test_environments.py
+++ b/runner/tests/test_environments.py
@@ -794,3 +794,52 @@ def test_an_npm_dist_tag_resolves_to_its_version(monkeypatch):
assert exact["version"] == "" and "9.9.9 is not published" in exact["error"]
pinned = E.check_package("npm", "[email protected]")
assert pinned["version"] == "4.17.20" and not pinned["error"]
+
+
+def test_an_apt_epoch_is_a_spec_the_check_recommends_and_both_the_check_and_the_build_accept(monkeypatch, tmp_path):
+ """An apt version may carry an epoch (`7:4.4.2-0ubuntu0.22.04.1`), and `_SPEC_RE` left `:` out of
+ its version class, so the spec `check_package` itself tells an owner to declare came back from
+ `check_package` as HTTP 400 "that is not a package spec" and was dropped from a build's
+ declaration by `clean_specs` with no error at all. The rest of the file already reads epochs:
+ the `Candidate:` line is split once on `:`, and `_apt_packages` decodes `%3a` back to one."""
+ candidate = "7:4.4.2-0ubuntu0.22.04.1"
+
+ def fake_run(cmd, **kw):
+ class R:
+ stdout, stderr, returncode = "", "", 0
+ out = R()
+ if cmd[:2] == ["apt-cache", "policy"]:
+ assert cmd[2] == "ffmpeg", cmd
+ out.stdout = f"ffmpeg:\n Installed: (none)\n Candidate: {candidate}\n"
+ if cmd[:2] == ["apt-cache", "madison"]:
+ out.stdout = f" ffmpeg | {candidate} | http://archive.ubuntu.com jammy/main amd64 Packages\n"
+ return out
+ monkeypatch.setattr(E.subprocess, "run", fake_run)
+ monkeypatch.setattr(E, "_apt_lists", lambda: None)
+
+ # the round trip: the advice a range gets names a spec, and that spec is accepted
+ advice = E.check_package("apt", "ffmpeg>=7")["error"]
+ recommended = advice.split(", or ", 1)[1].split(" to pin", 1)[0]
+ assert recommended == f"ffmpeg={candidate}", advice
+ pinned = E.check_package("apt", recommended)
+ assert pinned["error"] == "" and pinned["exists"] is True and pinned["version"] == candidate
+ assert E.spec_parts(recommended, "apt") == ("ffmpeg", candidate)
+
+ # and the build keeps it instead of silently dropping it: it reaches apt-get as declared
+ assert E.clean_specs([recommended]) == [recommended]
+ argv = _apt_install_argv(monkeypatch, tmp_path, [recommended])
+ assert argv[-1] == f"ffmpeg={candidate}", argv
+
+ # the gate is still a gate: the colon is admitted only as apt's epoch, so nothing else a colon
+ # introduces becomes a spec, and a malformed version is refused as before
+ for bad in ("foo@npm:other", "pkg@https://example.invalid/x", "ffmpeg=1:2:3", ":1.0",
+ "ffmpeg=99999:1.0", "jq==1.0;rm -rf /", "jq=1.0 2.0"):
+ assert E.clean_specs([bad]) == [], bad
+ with pytest.raises(HTTPException) as e:
+ E.check_package("apt", bad)
+ assert e.value.status_code == 400 and e.value.detail == "that is not a package spec", bad
+
+ # `_SPEC_RE` is shared with pip and npm, which have no epoch: their own spellings are unchanged
+ for ok in ("requests==2.31.0", "numpy==1.4.*", "numpy>=1.4", "lodash@^4.17.0", "[email protected]",
+ "@types/[email protected]", "lodash@latest", "jq"):
+ assert E.clean_specs([ok]) == [ok], ok