feat: try_lock/unlock hil commands (#1209)

Co-authored-by: chrisgalanis <christos.galanis@toolsforhumanity.com>

Author: sky-mart

nix/machines/home-hil.nix

@@ -14,12 +14,31 @@ let
       user = "worldcoin";
     };
   };
+  mkHilOrchestratorCmd =
+    { name, source }:
+    pkgs.writeShellScriptBin name ''
+      export HIL_ORCHESTRATOR_URL='${osConfig.worldcoin.hilOrchestratorUrl}'
+      export HIL_ORB_ID='${osConfig.worldcoin.orbId}'
+      exec ${pkgs.python3.withPackages (ps: [ ps.requests ])}/bin/python3 ${source} "$@"
+    '';
+  hilOrchestratorCmds =
+    lib.optionals (osConfig.worldcoin.orbId != null && osConfig.worldcoin.hilOrchestratorUrl != null)
+      [
+        (mkHilOrchestratorCmd {
+          name = "try_lock";
+          source = ../scripts/hil_try_lock.py;
+        })
+        (mkHilOrchestratorCmd {
+          name = "unlock";
+          source = ../scripts/hil_unlock.py;
+        })
+      ];
 in
 {
   home = {
     username = "worldcoin";
     homeDirectory = "/home/worldcoin";
-    packages = import "${packages}/hil.nix" { inherit pkgs; };
+    packages = (import "${packages}/hil.nix" { inherit pkgs; }) ++ hilOrchestratorCmds;
     sessionVariables = {
       EDITOR = "nvim";
       VISUAL = "nvim";

nix/scripts/hil_try_lock.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""try_lock: lock this HIL on the orb-hil-orchestrator.
+
+Reads `HIL_ORCHESTRATOR_URL` and `HIL_ORB_ID` from the environment (set by the
+NixOS wrapper).  Optional positional args become a note shown on the dashboard
+so other engineers know why this runner is locked.
+
+The server enforces the only real safety constraint: it rejects the request
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import requests
+
+
+TIMEOUT = 10
+
+
+def _error_msg(resp: requests.Response) -> str:
+    try:
+        return resp.json().get("error") or resp.text
+    except ValueError:
+        return resp.text
+
+
+def main() -> int:
+    orchestrator = os.environ["HIL_ORCHESTRATOR_URL"]
+    orb_id = os.environ["HIL_ORB_ID"]
+    note = " ".join(sys.argv[1:]).strip() or None
+
+    resp = requests.post(f"{orchestrator}/runners/{orb_id}/lock", timeout=TIMEOUT)
+    if resp.status_code != 200:
+        print(
+            f"try_lock failed (HTTP {resp.status_code}): {_error_msg(resp)}",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"lock queued for {orb_id}")
+
+    if note:
+        resp = requests.put(
+            f"{orchestrator}/runners/{orb_id}/note",
+            json={"note": note},
+            timeout=TIMEOUT,
+        )
+        if resp.status_code == 204:
+            print(f"note set: {note}")
+        else:
+            print(
+                f"try_lock: lock queued but note PUT failed "
+                f"(HTTP {resp.status_code})",
+                file=sys.stderr,
+            )
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

nix/scripts/hil_unlock.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+"""unlock: queue an unlock on the orb-hil-orchestrator and clear the note.
+
+Reads `HIL_ORCHESTRATOR_URL` and `HIL_ORB_ID` from the environment (set by the
+NixOS wrapper).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+import requests
+
+
+TIMEOUT = 10
+
+
+def _error_msg(resp: requests.Response) -> str:
+    try:
+        return resp.json().get("error") or resp.text
+    except ValueError:
+        return resp.text
+
+
+def main() -> int:
+    orchestrator = os.environ["HIL_ORCHESTRATOR_URL"]
+    orb_id = os.environ["HIL_ORB_ID"]
+
+    resp = requests.post(f"{orchestrator}/runners/{orb_id}/unlock", timeout=TIMEOUT)
+    if resp.status_code != 200:
+        print(
+            f"unlock failed (HTTP {resp.status_code}): {_error_msg(resp)}",
+            file=sys.stderr,
+        )
+        return 1
+    print(f"unlock queued for {orb_id}")
+
+    requests.delete(f"{orchestrator}/runners/{orb_id}/note", timeout=TIMEOUT)
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())