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.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
feat(gateway): upload a local harness to a hosted workspace
richard-epsillad04569dc82f2
diff --git a/gateway/app.py b/gateway/app.pyindex 7a5018cd..32fb96b3 100644--- a/gateway/app.py+++ b/gateway/app.py@@ -11606,6 +11606,238 @@ async def list_harnesses_public(request: Request) -> dict:return {"harnesses": items}+# ── Cloud upload: a local harness, pushed to a hosted workspace ────────────────+# One-way door. The self-hosted instance is the source of truth and the hosted copy is a+# deployment target: an upload REPLACES it, nothing is pulled back, and the hosted copy is not+# protected from the next upload. Upsert on the harness id, so the hosted id is the local id and+# stays stable forever (API callers and links on the hosted side keep working across re-uploads).+# The hosted workspace is whatever the API key was minted in; the operator pastes one key and+# Test shows the destination name. Stored encrypted beside the provider keys, never handed to the+# browser; this process does the upload. Not a UHP surface: a product feature, like plugins.+_CLOUD_UPLOAD_KEY = "harness-cloud-upload" # vault: {base_url, api_key}+_CLOUD_UPLOAD_DEFAULT_BASE = os.environ.get("HR_CLOUD_API_BASE", "https://api.harnessrouter.ai").rstrip("/")+_CLOUD_UPLOAD_RECORDS_KEY = "harness-cloud-upload-records" # vault: {hid: {fingerprint, uploaded_at, target}}+_HID_RE = re.compile(r"^chrn_[0-9a-f]{32}$")+++class CloudTargetBody(BaseModel):+ api_key: str | None = None # omitted or "" on PUT keeps the stored key+ base_url: str | None = None+++async def _cloud_target() -> dict:+ v = await _vault_get(GLOBAL_TENANT, _CLOUD_UPLOAD_KEY)+ try:+ doc = json.loads(v) if v else {}+ except Exception: # noqa: BLE001+ doc = {}+ return doc if isinstance(doc, dict) else {}+++def _cloud_target_public(t: dict) -> dict:+ key = str(t.get("api_key") or "")+ return {"configured": bool(key), "base_url": t.get("base_url") or _CLOUD_UPLOAD_DEFAULT_BASE,+ "key_hint": (key[:6] + "…" + key[-4:]) if len(key) >= 10 else ("…" if key else ""),+ "org": t.get("org") or "", "org_name": t.get("org_name") or "",+ "workspace": t.get("workspace") or "", "workspace_name": t.get("workspace_name") or ""}+++async def _cloud_records() -> dict:+ v = await _vault_get(GLOBAL_TENANT, _CLOUD_UPLOAD_RECORDS_KEY)+ try:+ doc = json.loads(v) if v else {}+ except Exception: # noqa: BLE001+ doc = {}+ return doc if isinstance(doc, dict) else {}+++async def _cloud_me(base_url: str, api_key: str) -> dict:+ """Resolve a key to where an upload lands. Raises HTTPException with the hosted side's words."""+ try:+ async with httpx.AsyncClient(timeout=httpx.Timeout(20.0, connect=8.0)) as c:+ r = await c.get(f"{base_url}/v1/me", headers={"authorization": f"Bearer {api_key}"})+ except Exception as e: # noqa: BLE001+ raise HTTPException(502, f"could not reach {base_url}: {str(e)[:120]}")+ if r.status_code == 401:+ raise HTTPException(401, "the cloud workspace rejected this key")+ if r.status_code != 200:+ raise HTTPException(502, f"cloud answered {r.status_code}")+ me = r.json() if r.headers.get("content-type", "").startswith("application/json") else {}+ if not isinstance(me, dict) or not me.get("org"):+ raise HTTPException(502, "cloud answered without an org")+ if not me.get("workspace"):+ raise HTTPException(400, "this key is not bound to a workspace; mint one inside the workspace")+ return me+++async def _cloud_harness_body(org: str, hid: str, v: dict) -> dict:+ """What travels: the harness config, with every skill's files inlined (a bundle the local+ instance offloaded to a blob is a local detail; the hosted side gets the files). Never:+ provider keys (not part of a harness), sessions, produced files, the local workspace."""+ out = _harness_out(await _mcp_migrate(org, hid, v))+ skills = []+ for sk in out.get("skills") or []:+ if not isinstance(sk, dict):+ continue+ sk = dict(sk)+ if sk.get("blob") and not sk.get("files"):+ raw = await _blob_get(f"skills/{sk['blob']}.json", kb=BLOB_KB)+ if raw:+ try:+ sk["files"] = json.loads(raw)+ except Exception: # noqa: BLE001+ pass+ sk.pop("blob", None)+ skills.append(sk)+ return {"name": out["name"], "base": out["base"], "base_label": out.get("baseLabel") or out["base"],+ "default_model": out.get("defaultModel") or None, "system_prompt": out.get("systemPrompt") or None,+ "mcp_servers": out.get("mcpServers") or [], "skills": skills,+ "disabled_tools": out.get("disabledTools") or [], "max_step": out.get("maxStep"),+ "timeout_seconds": out.get("timeoutSeconds"), "additional_headers": out.get("additionalHeaders") or [],+ "kit": out.get("kit") or None,+ "source": "selfhost", "source_instance": socket.gethostname()}+++def _cloud_fingerprint(body: dict) -> str:+ stable = {k: v for k, v in body.items() if k not in ("source", "source_instance")}+ return hashlib.sha256(json.dumps(stable, sort_keys=True, separators=(",", ":")).encode()).hexdigest()[:16]+++async def _cloud_upload_one(org: str, hid: str, target: dict, records: dict) -> dict:+ """Upload one harness. Returns the per-row result the dialog renders; never raises for a+ single harness, so a batch finishes every row."""+ if not _HID_RE.match(hid):+ return {"id": hid, "ok": False, "action": "skip", "error": "built-in"}+ v = await _vertex_get(hid)+ if not v or str(v.get("org") or "") != org or str(v.get("deleted") or "") in ("1", "true"):+ return {"id": hid, "ok": False, "action": "skip", "error": "not found"}+ body = await _cloud_harness_body(org, hid, v)+ fp = _cloud_fingerprint(body)+ action = "replace" if hid in records else "create"+ try:+ async with httpx.AsyncClient(timeout=httpx.Timeout(60.0, connect=8.0)) as c:+ r = await c.put(f"{target['base_url']}/v1/harnesses/{hid}", json=body,+ headers={"authorization": f"Bearer {target['api_key']}"})+ except Exception as e: # noqa: BLE001+ return {"id": hid, "ok": False, "action": action, "error": f"could not reach cloud: {str(e)[:120]}"}+ if r.status_code not in (200, 201):+ detail = ""+ try:+ j = r.json()+ detail = str((j.get("error") or {}).get("message") or j.get("detail") or "")+ except Exception: # noqa: BLE001+ detail = r.text[:160]+ return {"id": hid, "ok": False, "action": action, "error": f"cloud answered {r.status_code}: {detail}"[:300]}+ records[hid] = {"fingerprint": fp, "uploaded_at": int(time.time() * 1000),+ "target": f"{target.get('org_name') or target.get('org')} / {target.get('workspace_name') or target.get('workspace')}"}+ return {"id": hid, "ok": True, "action": action, "name": body["name"]}+++def _cloud_status(hid: str, records: dict, fp: str | None) -> dict:+ rec = records.get(hid)+ if not rec:+ return {"uploaded": False}+ return {"uploaded": True, "uploaded_at": rec.get("uploaded_at"), "target": rec.get("target"),+ "changed": bool(fp) and rec.get("fingerprint") != fp}++[email protected]("/v1/cloud-upload/target")+async def cloud_target_get(request: Request) -> dict:+ await _principal(request)+ return _cloud_target_public(await _cloud_target())++[email protected]("/v1/cloud-upload/target")+async def cloud_target_put(body: CloudTargetBody, request: Request) -> dict:+ await _principal(request)+ cur = await _cloud_target()+ key = (body.api_key or "").strip() or str(cur.get("api_key") or "")+ base = (body.base_url or "").strip().rstrip("/") or str(cur.get("base_url") or "") or _CLOUD_UPLOAD_DEFAULT_BASE+ if not key:+ raise HTTPException(400, "an API key is required")+ me = await _cloud_me(base, key)+ doc = {"base_url": base, "api_key": key, "org": me.get("org") or "", "org_name": me.get("org_name") or "",+ "workspace": me.get("workspace") or "", "workspace_name": me.get("workspace_name") or ""}+ await BACKING.secrets.put(GLOBAL_TENANT, _CLOUD_UPLOAD_KEY, json.dumps(doc), require_encryption=True)+ return _cloud_target_public(doc)++[email protected]("/v1/cloud-upload/target/test")+async def cloud_target_test(body: CloudTargetBody, request: Request) -> dict:+ """Where would an upload land. Tests the key in the body, or the stored one when omitted."""+ await _principal(request)+ cur = await _cloud_target()+ key = (body.api_key or "").strip() or str(cur.get("api_key") or "")+ base = (body.base_url or "").strip().rstrip("/") or str(cur.get("base_url") or "") or _CLOUD_UPLOAD_DEFAULT_BASE+ if not key:+ raise HTTPException(400, "an API key is required")+ me = await _cloud_me(base, key)+ return {"ok": True, "org": me.get("org") or "", "org_name": me.get("org_name") or "",+ "workspace": me.get("workspace") or "", "workspace_name": me.get("workspace_name") or ""}++[email protected]("/v1/cloud-upload/target")+async def cloud_target_delete(request: Request) -> dict:+ await _principal(request)+ await BACKING.secrets.put(GLOBAL_TENANT, _CLOUD_UPLOAD_KEY, "", require_encryption=True)+ return {"configured": False}+++class CloudUploadBody(BaseModel):+ ids: list[str]++[email protected]("/v1/harnesses/upload")+async def cloud_upload_batch(body: CloudUploadBody, request: Request) -> dict:+ p = await _principal(request)+ target = await _cloud_target()+ if not target.get("api_key"):+ raise HTTPException(400, "no cloud workspace connected")+ records = await _cloud_records()+ results = [await _cloud_upload_one(p.get("org", ""), str(h), target, records) for h in body.ids[:200]]+ await BACKING.secrets.put(GLOBAL_TENANT, _CLOUD_UPLOAD_RECORDS_KEY, json.dumps(records))+ return {"results": results, "target": _cloud_target_public(target)}++[email protected]("/v1/harnesses/{hid}/upload")+async def cloud_upload_one(hid: str, request: Request) -> dict:+ p = await _principal(request)+ target = await _cloud_target()+ if not target.get("api_key"):+ raise HTTPException(400, "no cloud workspace connected")+ records = await _cloud_records()+ res = await _cloud_upload_one(p.get("org", ""), hid, target, records)+ await BACKING.secrets.put(GLOBAL_TENANT, _CLOUD_UPLOAD_RECORDS_KEY, json.dumps(records))+ if not res.get("ok"):+ raise HTTPException(400 if res.get("action") == "skip" else 502, res.get("error") or "upload failed")+ return {**res, "status": _cloud_status(hid, records, None) | {"changed": False}}++[email protected]("/v1/harnesses/{hid}/upload")+async def cloud_upload_status(hid: str, request: Request) -> dict:+ """The chip on the harness page: never uploaded, uploaded, or changed since."""+ p = await _principal(request)+ records = await _cloud_records()+ if hid not in records:+ return {"uploaded": False}+ v = await _vertex_get(hid)+ fp = _cloud_fingerprint(await _cloud_harness_body(p.get("org", ""), hid, v)) if v else None+ return _cloud_status(hid, records, fp)++[email protected]("/v1/cloud-upload/status")+async def cloud_upload_status_all(request: Request) -> dict:+ """For the list: which harnesses have been uploaded, and whether each changed since."""+ p = await _principal(request)+ records = await _cloud_records()+ out = {}+ for hid in records:+ v = await _vertex_get(hid)+ fp = _cloud_fingerprint(await _cloud_harness_body(p.get("org", ""), hid, v)) if v else None+ out[hid] = _cloud_status(hid, records, fp)+ return {"harnesses": out}++@app.get("/v1/harnesses/{hid}")async def get_harness_public(hid: str, request: Request) -> dict:org, _ = await _pub_org_member(request)diff --git a/gateway/tests/conftest.py b/gateway/tests/conftest.pynew file mode 100644index 00000000..c1f41b92--- /dev/null+++ b/gateway/tests/conftest.py@@ -0,0 +1,25 @@+"""The gateway's test environment, set once, before any test module imports `app`.++`app` reads its configuration at import and never again, so whichever test module imports it+first decides the environment for the whole run. Three files (database, media, media_attack) each+set a full environment at the top and relied on being that first module; any new file sorting+before `test_database_mcp.py` that imported `app` bare silently won the race with no environment,+and 100+ tests in those files failed on collection order alone. pytest loads conftest before any+test module, so this is the one place the environment lives. The per-file `os.environ.update`+blocks still run, later and harmlessly: same keys, and each keeps its own data directory."""+import os+import tempfile++_DATA = tempfile.mkdtemp(prefix="hr-gwtest-")+os.environ.update({+ "HR_BACKING": "local",+ "HR_DATA_DIR": _DATA,+ "HARNESS_WORKSPACE": os.path.join(_DATA, "workspaces"),+ "HR_SECRET_KEY": "test-passphrase-not-a-real-one",+ "HARNESS_INTERNAL_KEY": "test-internal-key",+ "HARNESS_GLOBAL_TENANT": "global",+ "HARNESS_PUBLIC_BASE_URL": "https://gateway.example",+ "HR_POOL_AUTH": "none",+ "HR_IDENTITY_MODE": "off",+ "HR_MEDIA_SWEEP_S": "3600",+})diff --git a/gateway/tests/test_cloud_upload.py b/gateway/tests/test_cloud_upload.pynew file mode 100644index 00000000..03d9043d--- /dev/null+++ b/gateway/tests/test_cloud_upload.py@@ -0,0 +1,165 @@+"""Cloud upload: a local harness pushed to a hosted workspace, one way, upsert on its own id.+The hosted side is a mock at the HTTP boundary, which pins the contract this feature depends on:+GET /v1/me resolves a key to org + workspace, PUT /v1/harnesses/{id} creates or replaces."""+import asyncio+import json+import sys+from pathlib import Path++import httpx+import pytest+from fastapi.testclient import TestClient++sys.path.insert(0, str(Path(__file__).resolve().parents[1]))+import app as gw # noqa: E402 (environment: conftest.py)++ORG = "local"+CLOUD = "https://cloud.test"+++class Cloud:+ """What the hosted gateway does, as far as this feature can see."""+ def __init__(self):+ self.keys = {"sk-hr-good": {"org": "org_e", "org_name": "Epsilla", "workspace": "ws_r", "workspace_name": "Research", "member": "richard"},+ "sk-hr-nows": {"org": "org_e", "org_name": "Epsilla", "workspace": "", "workspace_name": "", "member": "richard"}}+ self.harnesses: dict[str, dict] = {}+ self.calls: list[tuple[str, str]] = []++ def handle(self, req: httpx.Request) -> httpx.Response:+ self.calls.append((req.method, req.url.path))+ tok = req.headers.get("authorization", "").removeprefix("Bearer ")+ me = self.keys.get(tok)+ if not me:+ return httpx.Response(401, json={"error": {"message": "invalid key"}})+ if req.url.path == "/v1/me":+ return httpx.Response(200, json=me)+ if req.url.path.startswith("/v1/harnesses/") and req.method == "PUT":+ hid = req.url.path.rsplit("/", 1)[-1]+ body = json.loads(req.content)+ created = hid not in self.harnesses+ self.harnesses[hid] = {**body, "org": me["org"], "workspace": me["workspace"]}+ return httpx.Response(201 if created else 200, json={"id": hid, **body})+ return httpx.Response(404, json={"error": {"message": "no route"}})+++def cloud(monkeypatch):+ c = Cloud()+ real = httpx.AsyncClient++ class Patched(real):+ def __init__(self, *a, **kw):+ kw["transport"] = httpx.MockTransport(c.handle)+ super().__init__(*a, **kw)+ monkeypatch.setattr(gw.httpx, "AsyncClient", Patched)+ return c+++def api(monkeypatch):+ async def principal(request):+ return {"org": ORG, "member": "me@local"}+ monkeypatch.setattr(gw, "_principal", principal)+ asyncio.run(gw.BACKING.secrets.put(gw.GLOBAL_TENANT, gw._CLOUD_UPLOAD_KEY, "", require_encryption=True))+ asyncio.run(gw.BACKING.secrets.put(gw.GLOBAL_TENANT, gw._CLOUD_UPLOAD_RECORDS_KEY, ""))+ return TestClient(gw.app)+++def _harness(api, name="Philz one-pager", **extra) -> str:+ r = api.post("/v1/harnesses", json={"name": name, "base": "dsh", "default_model": "deepseek-v4-flash",+ "system_prompt": "Make decks.", **extra})+ assert r.status_code == 200, r.text+ return r.json()["id"]+++def test_nothing_is_configured_until_a_key_is_saved(api, cloud):+ assert api.get("/v1/cloud-upload/target").json()["configured"] is False+ r = api.post("/v1/harnesses/upload", json={"ids": ["chrn_" + "0" * 32]})+ assert r.status_code == 400 and "no cloud workspace" in r.text+ assert cloud.calls == []+++def test_test_resolves_the_key_to_a_destination_without_saving(api, cloud):+ r = api.post("/v1/cloud-upload/target/test", json={"api_key": "sk-hr-good", "base_url": CLOUD})+ assert r.status_code == 200 and r.json() == {"ok": True, "org": "org_e", "org_name": "Epsilla",+ "workspace": "ws_r", "workspace_name": "Research"}+ assert api.get("/v1/cloud-upload/target").json()["configured"] is False+++def test_a_bad_key_and_a_key_without_a_workspace_are_refused(api, cloud):+ assert api.put("/v1/cloud-upload/target", json={"api_key": "sk-hr-wrong", "base_url": CLOUD}).status_code == 401+ r = api.put("/v1/cloud-upload/target", json={"api_key": "sk-hr-nows", "base_url": CLOUD})+ assert r.status_code == 400 and "workspace" in r.text+++def test_saving_the_target_keeps_the_key_out_of_the_response(api, cloud):+ r = api.put("/v1/cloud-upload/target", json={"api_key": "sk-hr-good", "base_url": CLOUD})+ assert r.status_code == 200+ j = r.json()+ assert j["configured"] and j["workspace_name"] == "Research" and "sk-hr-good" not in json.dumps(j)+ assert j["key_hint"].startswith("sk-hr-") and "…" in j["key_hint"]+ # a later PUT without a key keeps the stored one+ assert api.put("/v1/cloud-upload/target", json={"base_url": CLOUD}).json()["configured"] is True+++def test_upload_creates_then_replaces_on_the_same_id(api, cloud):+ api.put("/v1/cloud-upload/target", json={"api_key": "sk-hr-good", "base_url": CLOUD})+ hid = _harness(api)+ r = api.post(f"/v1/harnesses/{hid}/upload")+ assert r.status_code == 200, r.text+ assert r.json()["action"] == "create" and r.json()["ok"] is True+ assert hid in cloud.harnesses # same id on the hosted side+ sent = cloud.harnesses[hid]+ assert sent["name"] == "Philz one-pager" and sent["base"] == "dsh" and sent["system_prompt"] == "Make decks."+ assert sent["source"] == "selfhost" and sent["workspace"] == "ws_r" # landed in the key's workspace+ assert "api_key" not in json.dumps(sent) # nothing secret travels+ st = api.get(f"/v1/harnesses/{hid}/upload").json()+ assert st["uploaded"] is True and st["changed"] is False and st["target"] == "Epsilla / Research"+ # edit locally: the chip says changed; upload again: replace, in place, same id+ api.put(f"/v1/harnesses/{hid}", json={"name": "Philz one-pager v2", "base": "dsh"})+ assert api.get(f"/v1/harnesses/{hid}/upload").json()["changed"] is True+ r = api.post(f"/v1/harnesses/{hid}/upload")+ assert r.json()["action"] == "replace" and cloud.harnesses[hid]["name"] == "Philz one-pager v2"+ assert len(cloud.harnesses) == 1+ assert api.get(f"/v1/harnesses/{hid}/upload").json()["changed"] is False+++def test_skills_travel_with_their_files_inlined(api, cloud):+ api.put("/v1/cloud-upload/target", json={"api_key": "sk-hr-good", "base_url": CLOUD})+ big = "x" * (gw._SKILL_INLINE_MAX + 100) # forces the local blob offload+ hid = _harness(api, skills=[{"name": "deck", "files": [{"path": "SKILL.md", "content": big}]}])+ assert "blob" in json.dumps(asyncio.run(gw._vertex_get(hid)).get("skills")) # offloaded locally+ assert api.post(f"/v1/harnesses/{hid}/upload").status_code == 200+ sk = cloud.harnesses[hid]["skills"][0]+ assert sk["name"] == "deck" and "blob" not in sk and sk["files"][0]["content"] == big+++def test_batch_runs_every_row_and_skips_builtins(api, cloud):+ api.put("/v1/cloud-upload/target", json={"api_key": "sk-hr-good", "base_url": CLOUD})+ a, b = _harness(api, "A"), _harness(api, "B")+ r = api.post("/v1/harnesses/upload", json={"ids": [a, "codex", b, "chrn_" + "f" * 32]})+ assert r.status_code == 200+ rows = {x["id"]: x for x in r.json()["results"]}+ assert rows[a]["ok"] and rows[a]["action"] == "create"+ assert rows[b]["ok"] and rows[b]["action"] == "create"+ assert rows["codex"]["action"] == "skip" and rows["codex"]["error"] == "built-in"+ assert rows["chrn_" + "f" * 32]["action"] == "skip" and rows["chrn_" + "f" * 32]["error"] == "not found"+ assert set(cloud.harnesses) == {a, b}+ st = api.get("/v1/cloud-upload/status").json()["harnesses"]+ assert st[a]["uploaded"] and st[b]["uploaded"]+++def test_a_cloud_error_on_one_row_does_not_stop_the_others(api, cloud, monkeypatch):+ api.put("/v1/cloud-upload/target", json={"api_key": "sk-hr-good", "base_url": CLOUD})+ a, b = _harness(api, "A"), _harness(api, "B")+ real = cloud.handle++ def flaky(req):+ if req.method == "PUT" and req.url.path.endswith(a):+ return httpx.Response(500, json={"error": {"message": "hosted hiccup"}})+ return real(req)+ cloud.handle = flaky+ rows = {x["id"]: x for x in api.post("/v1/harnesses/upload", json={"ids": [a, b]}).json()["results"]}+ assert rows[a]["ok"] is False and "hosted hiccup" in rows[a]["error"]+ assert rows[b]["ok"] is True+ assert api.get(f"/v1/harnesses/{a}/upload").json()["uploaded"] is False # a failed upload leaves no record