Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

13.4 KB
Raw Blame
#!/usr/bin/env python3
"""The Hermes / OpenClaw agent-runtime lane: which changes reach it, what it runs.

One table for three consumers, so they cannot drift apart:

* ``classify_changes.py`` turns the ``agent_runtimes`` lane on for
  :data:`PREFIXES` / :data:`FILES`;
* ``select_tests.py`` adds :data:`SUITE` to an impact selection that touches
  the lane, so a change to the runtimes also runs the chat and society code
  that drives them (not only the tests that import the changed module);
* the ``agent-runtimes-unit`` / ``agent-runtimes-headless`` CI jobs run
  ``python scripts/ci/agent_runtime_suite.py`` — the same command on every OS.

The real-binary check (``scripts/spikes/agent_runtimes_gateway_e2e.py
--replay``) is a separate job: it needs Hermes or OpenClaw installed.

    python scripts/ci/agent_runtime_suite.py            # run the suite
    python scripts/ci/agent_runtime_suite.py --list     # print the test paths
    python scripts/ci/agent_runtime_suite.py --headless # the slim-container subset
    python scripts/ci/agent_runtime_suite.py --pin hermes   # install pin -> $GITHUB_OUTPUT
    python scripts/ci/agent_runtime_suite.py --bump openclaw --version 2026.9.8

The pin comes from ``dodaios/agent_runtimes/runtime-versions.json``:
``{"hermes": {"tested": "0.21.5", "commit": "<sha>"}, "openclaw": {"tested":
"2026.9.8"}}``. Hermes is pinned by ``commit`` (its installers take
``--commit`` / ``-Commit``; a version string alone cannot select a release),
OpenClaw by ``tested`` (an npm version). A missing file or key means latest:
the lane still runs, it just proves the newest upstream instead of the pin.
"""

from __future__ import annotations

import argparse
import json
import os
import re
import shutil
import subprocess
import sys
from pathlib import Path

REPO_ROOT = Path(__file__).resolve().parents[2]
MANIFEST = REPO_ROOT / "dodaios" / "agent_runtimes" / "runtime-versions.json"
RUNTIMES: tuple[str, ...] = ("hermes", "openclaw")
_VERSION = re.compile(r"[0-9A-Za-z][0-9A-Za-z.+-]{0,63}")
_COMMIT = re.compile(r"[0-9a-f]{40}")

#: Code whose change can break an agent on Hermes or OpenClaw.
PREFIXES: tuple[str, ...] = (
    "dodaios/agent_runtimes/",
    "tests/unit/agent_runtimes/",
    "scripts/spikes/agent_runtimes_",
)
FILES: frozenset[str] = frozenset(
    {
        "dodaios/agent_chat/runner_acp.py",
        "dodaios/agent_chat/runner_cli.py",
        "dodaios/agent_chat/service.py",
        "dodaios/agent_chat/send_queue.py",
        "dodaios/agent_chat/control.py",
        "dodaios/agent_chat/task_recovery.py",
        "dodaios/agent_chat/catalog.py",
        "dodaios/society/chat_binding.py",
        "dodaios/society/roster.py",
        "dodaios/society/routine_runner.py",
        "dodaios/society/seat_brain.py",
        "dodaios/ui/web/agent_runtime_routes.py",
        "dodaios/ui/web/runtime_gateway_routes.py",
        "dodaios/ui/web/society_routes.py",
        "tests/fakes/fake_acp_agent.py",
        "tests/fakes/fake_runtime_brain.py",
        "scripts/ci/agent_runtime_suite.py",
        "scripts/ci/agent_runtime_e2e.py",
    }
)

#: Unit and integration tests of the runtimes and of the chat / society code
#: that drives them. Fakes only: no runtime binary, no network, no key.
SUITE: tuple[str, ...] = (
    "tests/unit/agent_runtimes",
    "tests/unit/agent_chat/test_agent_chat_service.py",
    "tests/unit/agent_chat/test_controls.py",
    "tests/unit/agent_chat/test_send_queue.py",
    "tests/unit/agent_chat/test_task_recovery.py",
    "tests/unit/agent_chat/test_turn_host.py",
    "tests/unit/society/test_agent_runtime_field.py",
    "tests/unit/society/test_chat_binding.py",
    "tests/unit/society/test_roster.py",
    "tests/unit/society/test_routines.py",
    "tests/unit/society/test_seat_brain_runtime.py",
    "tests/unit/society/test_runtime_grant_revocation.py",
    "tests/unit/ui/web/test_society_routes.py",
    "tests/contract/test_routine_chats.py",
)

#: What must pass on a bare ``python:3.11-slim`` (no GPU, audio, desktop).
HEADLESS: tuple[str, ...] = ("tests/unit/agent_runtimes",)


def touches(path: str) -> bool:
    """Whether a changed repo-relative path reaches the runtime lane."""
    path = path.strip().replace("\\", "/")
    return path.startswith(PREFIXES) or path in FILES


def _existing(paths: tuple[str, ...]) -> list[str]:
    missing = [path for path in paths if not (REPO_ROOT / path).exists()]
    if missing:
        # A renamed test must be renamed here too; a silent skip would shrink
        # the lane's evidence without anyone noticing.
        raise SystemExit(f"agent runtime suite names missing tests: {', '.join(missing)}")
    return list(paths)


def _manifest(path: Path) -> dict:
    try:
        data = json.loads(path.read_text(encoding="utf-8"))
    except FileNotFoundError:
        return {}
    return data if isinstance(data, dict) else {}


def pin(runtime: str, path: Path = MANIFEST) -> dict[str, str]:
    """How CI installs ``runtime``: ``version`` (shown), ``npm_spec`` (OpenClaw)
    and ``hermes_commit`` ("" = the installer's default branch, latest)."""
    entry = _manifest(path).get(runtime)
    if isinstance(entry, str):
        entry = {"tested": entry}
    elif not isinstance(entry, dict):
        entry = {}
    version = str(entry.get("tested") or "")
    commit = str(entry.get("commit") or "")
    # Values reach a shell command line: accept only plain versions and SHAs.
    version = version if _VERSION.fullmatch(version) else ""
    commit = commit if _COMMIT.fullmatch(commit) else ""
    return {
        "version": version or "latest",
        "npm_spec": f"openclaw@{version or 'latest'}",
        "hermes_commit": commit,
    }


def bump(runtime: str, version: str, commit: str = "", path: Path = MANIFEST) -> bool:
    """Record ``version`` (and Hermes' ``commit``) as tested; True when it changed."""
    if not _VERSION.fullmatch(version) or (commit and not _COMMIT.fullmatch(commit)):
        raise SystemExit(f"refusing to record an unexpected version {version!r} / {commit!r}")
    data = _manifest(path)
    entry = data.get(runtime) if isinstance(data.get(runtime), dict) else {}
    updated = {**entry, "tested": version, **({"commit": commit} if commit else {})}
    if updated == entry:
        return False
    data[runtime] = updated
    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
    return True


def bump_from(folder: Path, path: Path = MANIFEST, *, expected_reports: int = 3) -> bool:
    """Raise each runtime's pin to what the canary proved on EVERY OS.

    ``folder`` holds one ``report`` JSON per green canary job. A runtime is
    raised only when all ``expected_reports`` OS jobs reported the same
    version and commit; one missing or disagreeing OS keeps the old pin.
    """
    seen: dict[str, list[tuple[str, str]]] = {}
    for file in sorted(folder.rglob("*.json")):
        data = json.loads(file.read_text(encoding="utf-8"))
        if isinstance(data, dict) and data.get("runtime") in RUNTIMES:
            seen.setdefault(data["runtime"], []).append(
                (str(data.get("version") or ""), str(data.get("commit") or ""))
            )
    changed = False
    for runtime, reports in seen.items():
        if len(reports) != expected_reports or len(set(reports)) != 1:
            print(f"{runtime}: {len(reports)} report(s) {sorted(set(reports))}; pin kept")
            continue
        version, commit = reports[0]
        changed = bump(runtime, version, commit, path) or changed
    return changed


def _git(*args: str) -> str:
    return subprocess.run(  # noqa: S603 — fixed git query
        ["git", *args],
        capture_output=True,
        text=True,
        check=False,
        creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
    ).stdout.strip()


def _hermes_commit(upstream: str = "") -> str:
    """The full UPSTREAM commit of the installed Hermes.

    ``upstream`` is the short sha from ``hermes --version`` ("upstream
    ed2dd0b3"); a checkout's HEAD may carry local commits no other machine
    can install, so it is used only on a clean checkout without that line.
    """
    home = Path(os.environ.get("HERMES_HOME") or Path.home() / ".hermes")
    local = os.environ.get("LOCALAPPDATA")
    candidates = [home / "hermes-agent"]
    if local:
        candidates.insert(0, Path(local) / "hermes" / "hermes-agent")
    for checkout in candidates:
        if not (checkout / ".git").exists():
            continue
        found = _git("-C", str(checkout), "rev-parse", f"{upstream or 'HEAD'}^{{commit}}")
        if _COMMIT.fullmatch(found):
            return found
    return ""


def report(runtime: str) -> dict[str, str]:
    """What the canary just proved: the installed version (and Hermes' commit)."""
    sys.path.insert(0, str(REPO_ROOT))
    from dodaios.agent_runtimes import driver

    target = driver(runtime)
    status = target.detect(refresh=True)
    if not status.ready or not _VERSION.fullmatch(status.version or ""):
        raise SystemExit(f"{runtime} is not ready to report ({status.problem or 'no version'})")
    commit = ""
    if runtime == "hermes":
        revision = getattr(target, "revision", None)
        upstream = revision(status) if callable(revision) else ""
        commit = _hermes_commit(upstream if re.fullmatch(r"[0-9a-f]{7,40}", upstream) else "")
        if not commit:
            # Without an upstream commit the pin cannot select this release.
            raise SystemExit("the installed Hermes' upstream commit could not be read")
    return {"runtime": runtime, "version": status.version, "commit": commit}


def point_at_latest(runtime: str, path: Path = MANIFEST) -> dict[str, str]:
    """Aim the app's own setup at upstream latest (the canary's checkout only).

    OpenClaw: ``tested`` = the newest npm release. Hermes: ``commit`` = the
    head of its default branch; ``tested`` stays, so the install reports as
    untested until the canary's pull request raises it.
    """
    data = _manifest(path)
    entry = data.get(runtime) if isinstance(data.get(runtime), dict) else {}
    if runtime == "openclaw":
        npm = shutil.which("npm") or shutil.which("npm.cmd")
        latest = subprocess.run(  # noqa: S603 — fixed registry query
            [npm or "npm", "view", "openclaw", "version"],
            capture_output=True, text=True, check=False,
            creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
        ).stdout.strip()
        if not _VERSION.fullmatch(latest):
            raise SystemExit(f"npm named no OpenClaw release ({latest!r})")
        entry = {**entry, "tested": latest}
    else:
        head = _git("ls-remote", "https://github.com/NousResearch/hermes-agent", "HEAD").split()
        if not head or not _COMMIT.fullmatch(head[0]):
            raise SystemExit("the Hermes repository named no head commit")
        entry = {**entry, "commit": head[0]}
    data[runtime] = entry
    path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
    return {key: str(value) for key, value in entry.items()}


def _emit(values: dict[str, str]) -> None:
    lines = [f"{key}={value}" for key, value in values.items()]
    output = os.environ.get("GITHUB_OUTPUT")
    if output:
        with open(output, "a", encoding="utf-8") as handle:
            handle.write("\n".join(lines) + "\n")
    print("\n".join(lines))


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    parser.add_argument("--list", action="store_true", help="Print the test paths and exit.")
    parser.add_argument("--headless", action="store_true", help="Only the slim-container subset.")
    parser.add_argument("--pin", choices=RUNTIMES, help="Print how CI installs this runtime.")
    parser.add_argument("--bump", choices=RUNTIMES, help="Record --version as tested.")
    parser.add_argument("--version", default="", help="With --bump: the version that passed.")
    parser.add_argument("--commit", default="", help="With --bump hermes: its commit.")
    parser.add_argument("--report", choices=RUNTIMES, help="Write the installed version as JSON.")
    parser.add_argument(
        "--point-at-latest", choices=RUNTIMES, help="Canary: set the pin to upstream latest."
    )
    parser.add_argument("--out", type=Path, help="With --report: the JSON file to write.")
    parser.add_argument(
        "--bump-from", type=Path, help="Record every report JSON in this folder that agrees."
    )
    args, extra = parser.parse_known_args(argv)
    if args.point_at_latest:
        _emit(point_at_latest(args.point_at_latest))
        return 0
    if args.report:
        found = report(args.report)
        if args.out:
            args.out.write_text(json.dumps(found), encoding="utf-8")
        _emit(found)
        return 0
    if args.bump_from:
        _emit({"changed": "true" if bump_from(args.bump_from) else "false"})
        return 0
    if args.pin:
        _emit(pin(args.pin))
        return 0
    if args.bump:
        _emit({"changed": "true" if bump(args.bump, args.version, args.commit) else "false"})
        return 0
    tests = _existing(HEADLESS if args.headless else SUITE)
    if args.list:
        print("\n".join(tests))
        return 0
    command = [sys.executable, "-m", "pytest", *tests, "-q", "-p", "no:cacheprovider", *extra]
    # No CREATE_NO_WINDOW: this runs in a CI console, and on Windows that flag
    # detaches pytest from it, so its report would vanish.
    return subprocess.call(command, cwd=REPO_ROOT)  # noqa: S603 — this interpreter


if __name__ == "__main__":
    sys.exit(main())