hold-sdk 0.2.0__tar.gz

hold_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: hold-sdk
+Version: 0.2.0
+Summary: Fail-closed approval client for Hold My Agent
+License: MIT
+Project-URL: Homepage, https://holdmyagent.com
+Project-URL: Repository, https://github.com/holdmyagent/arbiter
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# `hold-sdk`
+
+Python client for Hold My Agent's Arbiter server — gate an agent action
+behind a human approval with one call:
+
+```python
+from hold_sdk import request_approval
+
+if request_approval("Deploy to prod?", severity="high") != "approved":
+    raise SystemExit("blocked: not approved")
+```
+
+Fail-closed: any timeout, network error, or unconfigured client returns
+`"denied"`, never raises.
+
+- Homepage: https://holdmyagent.com
+- Source / issues: https://github.com/holdmyagent/arbiter

hold_sdk-0.2.0/README.md

@@ -0,0 +1,17 @@
+# `hold-sdk`
+
+Python client for Hold My Agent's Arbiter server — gate an agent action
+behind a human approval with one call:
+
+```python
+from hold_sdk import request_approval
+
+if request_approval("Deploy to prod?", severity="high") != "approved":
+    raise SystemExit("blocked: not approved")
+```
+
+Fail-closed: any timeout, network error, or unconfigured client returns
+`"denied"`, never raises.
+
+- Homepage: https://holdmyagent.com
+- Source / issues: https://github.com/holdmyagent/arbiter

hold_sdk-0.2.0/hold_sdk/__init__.py

@@ -0,0 +1,32 @@
+import os
+import time
+import httpx
+
+def request_approval(title, *, description="", severity="medium", target=None,
+                     ttl_seconds=300, payload=None, action_type="generic",
+                     server_url=None, token=None, poll_interval=2, timeout=None,
+                     _transport=None) -> str:
+    server_url = server_url or os.environ.get("HMA_SERVER_URL")
+    token = token or os.environ.get("HMA_AGENT_TOKEN")
+    if not server_url or not token:
+        return "denied"  # fail-closed: unconfigured is a no
+    hdr = {"Authorization": f"Bearer {token}"}
+    try:
+        with httpx.Client(base_url=server_url.rstrip("/"), timeout=10, transport=_transport) as c:
+            r = c.post("/v1/requests", headers=hdr, json={
+                "title": title, "description": description, "action_type": action_type,
+                "payload": payload or {}, "severity": severity,
+                "ttl_seconds": ttl_seconds, "target": target})
+            r.raise_for_status()
+            rid = r.json()["id"]
+            deadline = time.time() + (timeout if timeout is not None else ttl_seconds + 5)
+            while time.time() < deadline:
+                g = c.get(f"/v1/requests/{rid}", headers=hdr)
+                g.raise_for_status()
+                status = g.json()["status"]
+                if status in ("approved", "denied", "expired"):
+                    return status
+                time.sleep(poll_interval)
+    except Exception:
+        return "denied"  # fail-closed
+    return "denied"      # local timeout

hold_sdk-0.2.0/hold_sdk/client.py

@@ -0,0 +1,34 @@
+import time
+import httpx
+
+class ArbiterClient:
+    def __init__(self, base_url, agent_token, app_token=None, verify=True):
+        self.base_url = base_url.rstrip("/")
+        self.agent_token = agent_token
+        self._http = httpx.Client(base_url=self.base_url, verify=verify, timeout=10)
+
+    def request_approval(self, title, description="", action_type="generic",
+                         payload=None, severity="medium", ttl=300, target=None,
+                         poll_interval=2, timeout=None) -> str:
+        try:
+            r = self._http.post("/v1/requests",
+                headers={"Authorization": f"Bearer {self.agent_token}"},
+                json={"title": title, "description": description, "action_type": action_type,
+                      "payload": payload or {}, "severity": severity, "ttl_seconds": ttl, "target": target})
+            r.raise_for_status()
+            rid = r.json()["id"]
+        except Exception:
+            return "denied"  # fail-closed
+        deadline = time.time() + (timeout if timeout is not None else ttl + 5)
+        while time.time() < deadline:
+            try:
+                g = self._http.get(f"/v1/requests/{rid}",
+                    headers={"Authorization": f"Bearer {self.agent_token}"})
+                g.raise_for_status()
+                status = g.json()["status"]
+            except Exception:
+                return "denied"  # fail-closed
+            if status in ("approved", "denied", "expired"):
+                return status
+            time.sleep(poll_interval)
+        return "denied"  # fail-closed on local timeout

hold_sdk-0.2.0/hold_sdk.egg-info/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: hold-sdk
+Version: 0.2.0
+Summary: Fail-closed approval client for Hold My Agent
+License: MIT
+Project-URL: Homepage, https://holdmyagent.com
+Project-URL: Repository, https://github.com/holdmyagent/arbiter
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# `hold-sdk`
+
+Python client for Hold My Agent's Arbiter server — gate an agent action
+behind a human approval with one call:
+
+```python
+from hold_sdk import request_approval
+
+if request_approval("Deploy to prod?", severity="high") != "approved":
+    raise SystemExit("blocked: not approved")
+```
+
+Fail-closed: any timeout, network error, or unconfigured client returns
+`"denied"`, never raises.
+
+- Homepage: https://holdmyagent.com
+- Source / issues: https://github.com/holdmyagent/arbiter

hold_sdk-0.2.0/hold_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+hold_sdk/__init__.py
+hold_sdk/client.py
+hold_sdk.egg-info/PKG-INFO
+hold_sdk.egg-info/SOURCES.txt
+hold_sdk.egg-info/dependency_links.txt
+hold_sdk.egg-info/requires.txt
+hold_sdk.egg-info/top_level.txt
+tests/test_client.py
+tests/test_request_approval.py

hold_sdk-0.2.0/hold_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

hold_sdk-0.2.0/hold_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+httpx>=0.27
+
+[dev]
+pytest>=8.3
+pytest-asyncio>=0.24
+ruff>=0.6

hold_sdk-0.2.0/hold_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+hold_sdk

hold_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "hold-sdk"
+version = "0.2.0"
+description = "Fail-closed approval client for Hold My Agent"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+dependencies = [
+  "httpx>=0.27",
+]
+
+# SDK tests exercise the client against the real server — install with: pip install -r requirements-dev.txt
+[project.optional-dependencies]
+dev = ["pytest>=8.3", "pytest-asyncio>=0.24", "ruff>=0.6"]
+
+[project.urls]
+Homepage = "https://holdmyagent.com"
+Repository = "https://github.com/holdmyagent/arbiter"
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py311"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["hold_sdk*"]

hold_sdk-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hold_sdk-0.2.0/tests/test_client.py

@@ -0,0 +1,74 @@
+import tempfile
+import threading
+import time
+from pathlib import Path
+from fastapi import FastAPI
+from fastapi.responses import PlainTextResponse, Response
+from fastapi.testclient import TestClient
+from arbiter.app import create_app
+from arbiter.config import Config
+from arbiter.db import Database
+from hold_sdk.client import ArbiterClient
+
+def _server():
+    absent = Path(tempfile.mkdtemp()) / "absent.toml"  # never written -> Config.load uses defaults
+    cfg = Config.load(str(absent))
+    cfg.auth.agent_token = "A"
+    cfg.auth.app_token = "P"
+    cfg.auth.admin_password = "pw"
+    cfg.auth.session_secret = "secret"
+    db = Database(":memory:")
+    class S:
+        async def send(self,t,p): return "skipped"
+    return create_app(cfg, db, S()), db
+
+def test_approved():
+    app, db = _server()
+    # TestClient is an httpx.Client subclass that properly bridges sync→async ASGI
+    tc = TestClient(app, base_url="http://test", raise_server_exceptions=False)
+    client = ArbiterClient("http://test","A",app_token="P")
+    client._http = tc
+    # create via SDK in a thread, approve out-of-band
+    result = {}
+    def run(): result["r"] = client.request_approval("t", severity="low", ttl=300, poll_interval=0.05)
+    th = threading.Thread(target=run)
+    th.start()
+    time.sleep(0.2)
+    rid = db.list_requests("pending")[0]["id"]
+    db.set_decision(rid, "approve", "iPhone")
+    th.join(timeout=5)
+    assert result["r"] == "approved"
+
+def test_failclosed_bad_url():
+    client = ArbiterClient("http://127.0.0.1:1","A")
+    assert client.request_approval("t", ttl=1, poll_interval=0.1, timeout=0.5)=="denied"
+
+def test_failclosed_server_500_on_create():
+    """Server returns HTTP 500 on POST /v1/requests → fail-closed (denied)."""
+    fapp = FastAPI()
+
+    @fapp.post("/v1/requests")
+    def _create_error():
+        return Response(status_code=500)
+
+    tc = TestClient(fapp, base_url="http://test", raise_server_exceptions=False)
+    client = ArbiterClient("http://test", "A")
+    client._http = tc
+    assert client.request_approval("t", ttl=5, poll_interval=0.05, timeout=1) == "denied"
+
+def test_failclosed_garbage_poll_body():
+    """Poll response is not valid JSON → fail-closed (denied)."""
+    fapp = FastAPI()
+
+    @fapp.post("/v1/requests")
+    def _create_ok():
+        return {"id": "stub-x"}
+
+    @fapp.get("/v1/requests/{rid}")
+    def _get_garbage(rid: str):
+        return PlainTextResponse("not-json!!!")
+
+    tc = TestClient(fapp, base_url="http://test", raise_server_exceptions=False)
+    client = ArbiterClient("http://test", "A")
+    client._http = tc
+    assert client.request_approval("t", ttl=5, poll_interval=0.05, timeout=1) == "denied"

hold_sdk-0.2.0/tests/test_request_approval.py

@@ -0,0 +1,33 @@
+import httpx
+from hold_sdk import request_approval
+
+def _transport(status_after=1, decision="approved", capture=None):
+    state = {"polls": 0}
+    def handler(request):
+        if capture is not None and request.method == "POST":
+            import json
+            capture.update(json.loads(request.read()))
+        if request.method == "POST":
+            return httpx.Response(200, json={"id": "r1", "status": "pending"})
+        state["polls"] += 1
+        st = decision if state["polls"] >= status_after else "pending"
+        return httpx.Response(200, json={"id": "r1", "status": st})
+    return httpx.MockTransport(handler)
+
+def test_approved_and_fields_sent(monkeypatch):
+    monkeypatch.setenv("HMA_SERVER_URL", "http://test")
+    monkeypatch.setenv("HMA_AGENT_TOKEN", "t")
+    sent = {}
+    out = request_approval("Deploy?", severity="high", target="prod", poll_interval=0,
+                           _transport=_transport(capture=sent))
+    assert out == "approved" and sent["target"] == "prod" and sent["severity"] == "high"
+
+def test_missing_config_is_denied(monkeypatch):
+    monkeypatch.delenv("HMA_SERVER_URL", raising=False)
+    monkeypatch.delenv("HMA_AGENT_TOKEN", raising=False)
+    assert request_approval("x") == "denied"
+
+def test_server_down_is_denied(monkeypatch):
+    monkeypatch.setenv("HMA_SERVER_URL", "http://127.0.0.1:1")
+    monkeypatch.setenv("HMA_AGENT_TOKEN", "t")
+    assert request_approval("x", timeout=1, poll_interval=0) == "denied"