third_party

third_party

Path resolution and commit-pin verification for foreign frameworks.

The _third_party.toml file declares the canonical filesystem path and expected git commit for each foreign framework (Hermes Agent, OpenClaw). Env vars (HERMES_AGENT_PATH, OPENCLAW_PATH) override the default path. JARVIS_ALLOW_COMMIT_DRIFT=1 disables strict commit-pin enforcement.

Classes

ThirdPartyError

Bases: Exception

Base exception for third-party framework problems.

ThirdPartyNotFoundError

Bases: ThirdPartyError

Raised when the third-party path cannot be resolved or doesn't exist.

CommitDriftError

Bases: ThirdPartyError

Raised when the third-party repo's HEAD does not match the pinned commit.

ThirdPartyEntry dataclass

ThirdPartyEntry(name: str, path: Path, pinned_commit: str, runner_script: str, python_executable: str = '', node_executable: str = '')

One foreign framework's configuration.

ThirdPartyConfig dataclass

ThirdPartyConfig(entries: Dict[str, ThirdPartyEntry] = dict())

Top-level config: a map from framework name -> entry.

Functions

load_third_party_config

load_third_party_config(toml_path: Optional[Path] = None) -> ThirdPartyConfig

Load the third-party config, applying env-var path overrides.

Raises: ThirdPartyNotFoundError: if the TOML doesn't exist.

Source code in src/openjarvis/evals/comparison/third_party.py

def load_third_party_config(toml_path: Optional[Path] = None) -> ThirdPartyConfig:
    """Load the third-party config, applying env-var path overrides.

    Raises:
        ThirdPartyNotFoundError: if the TOML doesn't exist.
    """
    if toml_path is None:
        toml_path = _default_toml_path()
    if not toml_path.exists():
        raise ThirdPartyNotFoundError(
            f"_third_party.toml not found at {toml_path}. "
            "Either create it or pass an explicit toml_path."
        )

    with open(toml_path, "rb") as fh:
        raw = tomllib.load(fh)

    entries: Dict[str, ThirdPartyEntry] = {}
    for name, body in raw.items():
        path_env = _PATH_ENV_VAR.get(name)
        path_str = os.environ.get(path_env, body["path"]) if path_env else body["path"]
        runtime_env = _RUNTIME_ENV_VAR.get(name)
        runtime_override = os.environ.get(runtime_env, "") if runtime_env else ""
        # The runtime-env override takes precedence over the TOML default for
        # whichever runtime field is relevant to this framework.
        python_exe = body.get("python_executable", "")
        node_exe = body.get("node_executable", "")
        if runtime_override:
            if name == "hermes":
                python_exe = runtime_override
            elif name == "openclaw":
                node_exe = runtime_override
        entries[name] = ThirdPartyEntry(
            name=name,
            path=Path(path_str),
            pinned_commit=body.get("pinned_commit", ""),
            runner_script=body.get("runner_script", ""),
            python_executable=python_exe,
            node_executable=node_exe,
        )
    return ThirdPartyConfig(entries=entries)

verify_commit_pin

verify_commit_pin(entry: ThirdPartyEntry) -> None

Verify the entry's path is at the pinned commit.

Raises: ThirdPartyNotFoundError: if the path doesn't exist or isn't a git repo. CommitDriftError: if HEAD doesn't match pinned_commit, unless JARVIS_ALLOW_COMMIT_DRIFT=1 is set (then logs a warning).

Source code in src/openjarvis/evals/comparison/third_party.py

def verify_commit_pin(entry: ThirdPartyEntry) -> None:
    """Verify the entry's path is at the pinned commit.

    Raises:
        ThirdPartyNotFoundError: if the path doesn't exist or isn't a git repo.
        CommitDriftError: if HEAD doesn't match pinned_commit, unless
            ``JARVIS_ALLOW_COMMIT_DRIFT=1`` is set (then logs a warning).
    """
    env_var = _PATH_ENV_VAR.get(entry.name, "<env var>")
    if str(entry.path) == "" or str(entry.path) == ".":
        raise ThirdPartyNotFoundError(
            f"{entry.name} path is not configured. "
            f"Set the {env_var} environment variable to point at your "
            f"local {entry.name} checkout, or set `path = ...` in "
            f"_third_party.toml."
        )
    if not entry.path.exists():
        raise ThirdPartyNotFoundError(
            f"{entry.name} path does not exist: {entry.path}. "
            f"Set {env_var} to override, or update _third_party.toml."
        )

    try:
        result = subprocess.run(
            ["git", "-C", str(entry.path), "rev-parse", "HEAD"],
            capture_output=True,
            text=True,
            check=True,
        )
    except subprocess.CalledProcessError as e:
        raise ThirdPartyNotFoundError(
            f"{entry.name} path is not a git repo: {entry.path} ({e.stderr.strip()})"
        ) from e

    actual = result.stdout.strip()
    pinned = entry.pinned_commit.strip()
    # Allow short-hash matches (e.g. pinned "abc123" matches actual "abc123def...")
    if not actual.startswith(pinned) and not pinned.startswith(actual):
        msg = (
            f"{entry.name} commit drift: pinned={pinned}, actual={actual}. "
            f"Either reset the repo to the pinned commit or update _third_party.toml. "
            f"To bypass for this run, set JARVIS_ALLOW_COMMIT_DRIFT=1."
        )
        if os.environ.get("JARVIS_ALLOW_COMMIT_DRIFT") == "1":
            LOGGER.warning(msg)
            return
        raise CommitDriftError(msg)