gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/benchmark_hub/client.py

@@ -0,0 +1,992 @@
+"""Gateway benchmark-container push client.
+
+Drives the Gateway hub push flow end-to-end — the reimplemented (not Prime's
+CLI-welded) client, talking only to a Gateway host, never to Prime:
+
+    resolve (get-or-create container)
+      -> versions (create/dedup at content hash, get a presigned PUT)
+      -> PUT the source tarball (with the real object sha256 as the S3 checksum)
+      -> finalize (mark the version READY)
+
+Stdlib only (urllib/hashlib/base64/tarfile/tomllib) — no extra dependencies.
+
+The source content hash is byte-compatible with Prime's hub (vendored helper).
+The *tarball* object sha256 is computed separately and sent as the presign
+checksum (base64) — distinct from the content hash — which is what satisfies the
+x-amz-checksum-sha256 the Gateway presign bakes into the signature.
+"""
+
+from __future__ import annotations
+
+import base64
+import gzip
+import hashlib
+import io
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tarfile
+import urllib.error
+import urllib.parse
+import urllib.request
+import zipfile
+from email.parser import Parser
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+from urllib.parse import urlencode
+
+try:
+    import tomllib
+except ModuleNotFoundError:
+    import tomli as tomllib
+
+from ..environment._materialize import validate_schema_materialization
+from ..environment.schema.compiler import bundle_mode
+from ..environment.schema.validation import ContractError
+from ._archive import collect_archive_files, compute_content_hash
+from ._tar import safe_tar_extract
+from .versioning import (
+    bump_post_version,
+    bump_rc_version,
+    bump_version,
+    update_pyproject_version,
+)
+
+# ── Local working-copy metadata (.gateway/.env-metadata.json) ────────────────
+# The dir's link back to the hub: which container it came from, which VERSION
+# it was based on, and which BRANCH it tracks. `pull`/`checkout` write it,
+# `push` reads it (the fast-forward base) and rewrites it (your own push
+# becomes the new base) — the same role .git/HEAD plays for git.
+
+DEFAULT_BRANCH = "main"
+_META_RELPATH = Path(".gateway") / ".env-metadata.json"
+
+
+def read_local_meta(env_path: Path) -> Optional[Dict[str, Any]]:
+    """The dir's recorded base/branch, or None (an ad-hoc dir)."""
+    meta_path = Path(env_path) / _META_RELPATH
+    if not meta_path.is_file():
+        return None
+    try:
+        loaded = json.loads(meta_path.read_text())
+        return loaded if isinstance(loaded, dict) else None
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def snapshot_tree_hashes(env_path: Path) -> Dict[str, str]:
+    """rel path -> sha256 over the ARCHIVE-VISIBLE tree (collect_archive_files
+    rules). This is the working copy's base-file record: diffing against the
+    server manifest instead would surface phantom deletes, because the browser
+    manifest deliberately lists files (dotfiles, gitignored paths) that the
+    source tarball never contains."""
+    out: Dict[str, str] = {}
+    for file_path in collect_archive_files(env_path):
+        rel = str(file_path.relative_to(env_path)).replace("\\", "/")
+        out[rel] = hashlib.sha256(file_path.read_bytes()).hexdigest()
+    return out
+
+
+def local_tree_state(env_path: Path) -> Dict[str, Any]:
+    """The dir's hub link plus whether its ARCHIVE-VISIBLE tree still matches
+    the recorded base: ``{"meta", "dirty", "clean"}``. ``meta`` is None for an
+    ad-hoc dir (never pulled/pushed); ``dirty`` lists rel paths that changed,
+    appeared, or vanished vs the base snapshot; ``clean`` is True only when a
+    base exists AND nothing drifted — the one state where a local run can be
+    honestly pinned to the recorded version."""
+    meta = read_local_meta(Path(env_path))
+    base = meta.get("baseFiles") if meta else None
+    if not isinstance(base, dict):
+        return {"meta": meta, "dirty": [], "clean": False}
+    now = snapshot_tree_hashes(Path(env_path))
+    dirty = sorted({p for p, h in now.items() if base.get(p) != h} | {p for p in base if p not in now})
+    return {"meta": meta, "dirty": dirty, "clean": not dirty}
+
+
+def write_local_meta(env_path: Path, meta: Dict[str, Any]) -> None:
+    meta_dir = Path(env_path) / _META_RELPATH.parent
+    meta_dir.mkdir(exist_ok=True)
+    (Path(env_path) / _META_RELPATH).write_text(json.dumps(meta, indent=2))
+
+
+# Includes the build-artifact dirs the ARCHIVE collector prunes (_archive.py) —
+# otherwise `push --build-wheel` writes dist/<name>.whl BEFORE the manifest is
+# collected and the browser lists a file the source bundle cannot serve.
+_SKIP_DIRS = {
+    ".git",
+    "__pycache__",
+    "node_modules",
+    ".venv",
+    ".mypy_cache",
+    "dist",
+    "build",
+    "outputs",
+}
+
+
+class BenchmarkPushError(RuntimeError):
+    """Raised when any step of the push flow fails."""
+
+
+def read_pyproject(env_path: Path) -> Dict[str, Any]:
+    """Best-effort name/version/deps from pyproject.toml (empty dict if absent)."""
+    env_path = Path(env_path)
+    pp = env_path / "pyproject.toml"
+    if not pp.exists():
+        return {}
+    try:
+        data = tomllib.loads(pp.read_text())
+    except Exception:
+        return {}
+    project = data.get("project", {}) if isinstance(data, dict) else {}
+    meta: Dict[str, Any] = {}
+    for key, out in (
+        ("name", "name"),
+        ("version", "version"),
+        ("dependencies", "dependencies"),
+        ("requires-python", "requires_python"),
+    ):
+        if key in project:
+            meta[out] = project[key]
+    return meta
+
+
+def build_source_tarball(env_path: Path) -> bytes:
+    """A deterministic .tar.gz of the SOURCE files (the same set the content hash
+    covers), with cleared mtime/owner so identical source yields a stable bundle."""
+    env_path = Path(env_path)
+    files = sorted(
+        collect_archive_files(env_path),
+        key=lambda p: str(Path(p).relative_to(env_path)).replace("\\", "/"),
+    )
+    buf = io.BytesIO()
+    # Wrap the tar in a gzip stream with mtime=0 (tarfile's own "w:gz" stamps the
+    # current time into the gzip header) + clear per-entry mtime/owner, so
+    # identical source yields identical bytes.
+    gz = gzip.GzipFile(fileobj=buf, mode="wb", mtime=0, compresslevel=9)
+    try:
+        with tarfile.open(fileobj=gz, mode="w:") as tar:
+            for f in files:
+                rel = str(Path(f).relative_to(env_path)).replace("\\", "/")
+                payload = Path(f).read_bytes()
+                info = tarfile.TarInfo(name=rel)
+                info.size = len(payload)
+                info.mtime = 0
+                info.uid = info.gid = 0
+                info.uname = info.gname = ""
+                info.mode = 0o644
+                tar.addfile(info, io.BytesIO(payload))
+    finally:
+        gz.close()
+    return buf.getvalue()
+
+
+def build_file_manifest(env_path: Path) -> List[Dict[str, Any]]:
+    """The FULL file tree (configs, data, .github — not just source), decoupled
+    from the source-only content hash, to power the GitHub-style browser."""
+    env_path = Path(env_path)
+    entries: List[Dict[str, Any]] = []
+    for root, dirs, filenames in os.walk(env_path):
+        dirs[:] = sorted(d for d in dirs if d not in _SKIP_DIRS and not d.endswith(".egg-info"))
+        for fn in sorted(filenames):
+            p = Path(root) / fn
+            try:
+                payload = p.read_bytes()
+            except OSError:
+                continue
+            entries.append(
+                {
+                    "path": str(p.relative_to(env_path)).replace("\\", "/"),
+                    "isDirectory": False,
+                    "size": len(payload),
+                    "sha256": hashlib.sha256(payload).hexdigest(),
+                }
+            )
+    return entries
+
+
+def sha256_base64(data: bytes) -> str:
+    """Base64 of the raw sha256 digest — the format S3/MinIO want for
+    x-amz-checksum-sha256 (NOT hex)."""
+    return base64.b64encode(hashlib.sha256(data).digest()).decode("ascii")
+
+
+def normalize_package_name(name: str) -> str:
+    """PyPI-normalized module/dist name (the pip target uses underscores)."""
+    return name.replace("-", "_").lower()
+
+
+def build_wheel(env_path: Path) -> Path:
+    """Build a wheel from the env dir via ``uv build --wheel`` (fallback
+    ``python -m build --wheel``). Cleans dist/ first; returns the wheel path."""
+    env_path = Path(env_path)
+    dist = env_path / "dist"
+    if dist.exists():
+        shutil.rmtree(dist)
+    try:
+        if shutil.which("uv"):
+            subprocess.run(
+                ["uv", "build", "--wheel", "--out-dir", "dist"],
+                cwd=env_path,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        else:
+            subprocess.run(
+                [sys.executable, "-m", "build", "--wheel", str(env_path)],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+    except subprocess.CalledProcessError as e:
+        raise BenchmarkPushError(f"wheel build failed: {(e.stderr or e.stdout or str(e))[:500]}") from None
+    wheels = sorted(dist.glob("*.whl"))
+    if not wheels:
+        raise BenchmarkPushError("wheel build produced no .whl")
+    return wheels[-1]
+
+
+def parse_wheel_requires_dist(wheel_path: Path) -> List[str]:
+    """The ``Requires-Dist`` lines from a wheel's ``*.dist-info/METADATA``."""
+    with zipfile.ZipFile(wheel_path) as zf:
+        metas = [n for n in zf.namelist() if n.endswith(".dist-info/METADATA")]
+        if not metas:
+            return []
+        text = zf.read(metas[0]).decode("utf-8", "replace")
+    return Parser().parsestr(text).get_all("Requires-Dist") or []
+
+
+class GatewayBenchmarkClient:
+    """Talks to a Gateway host's benchmark-container public API. Writes require a
+    secret key, so authenticate with the project's public + secret key (Basic)."""
+
+    def __init__(self, host: str, public_key: str, secret_key: str) -> None:
+        if not host:
+            raise ValueError("host is required (e.g. https://withgateway.ai)")
+        if not public_key or not secret_key:
+            raise ValueError("both public_key and secret_key are required")
+        self.host = host.rstrip("/")
+        self._auth = base64.b64encode(f"{public_key}:{secret_key}".encode("utf-8")).decode("ascii")
+
+    @classmethod
+    def from_env(cls, host: Optional[str] = None) -> "GatewayBenchmarkClient":
+        return cls(
+            host=host or os.environ.get("GATEWAY_HOST", ""),
+            public_key=os.environ.get("GATEWAY_PUBLIC_KEY", ""),
+            secret_key=os.environ.get("GATEWAY_SECRET_KEY", ""),
+        )
+
+    def _post(self, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        req = urllib.request.Request(
+            f"{self.host}{path}",
+            data=json.dumps(body).encode("utf-8"),
+            method="POST",
+            headers={
+                "Authorization": f"Basic {self._auth}",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=120) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:500]
+            raise BenchmarkPushError(f"POST {path} -> {e.code}: {detail}") from None
+
+    def _get(self, path: str) -> Dict[str, Any]:
+        req = urllib.request.Request(
+            f"{self.host}{path}",
+            method="GET",
+            headers={"Authorization": f"Basic {self._auth}"},
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=120) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:500]
+            raise BenchmarkPushError(f"GET {path} -> {e.code}: {detail}") from None
+
+    def _put_object(
+        self,
+        url: str,
+        data: bytes,
+        sha256_b64: str,
+        content_type: str = "application/gzip",
+    ) -> None:
+        req = urllib.request.Request(
+            url,
+            data=data,
+            method="PUT",
+            headers={
+                "Content-Type": content_type,
+                "x-amz-checksum-sha256": sha256_b64,
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=300) as resp:
+                resp.read()
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:500]
+            raise BenchmarkPushError(f"object PUT -> {e.code}: {detail}") from None
+
+    def push(
+        self,
+        env_path: str | Path,
+        *,
+        slug: Optional[str] = None,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        visibility: Optional[str] = None,
+        auto_bump: bool = False,
+        rc: bool = False,
+        post: bool = False,
+        image_ref: Optional[str] = None,
+        wheel: bool = False,
+        branch: Optional[str] = None,
+        force: bool = False,
+        message: Optional[str] = None,
+        author: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        env_path = Path(env_path)
+        if not env_path.is_dir():
+            raise BenchmarkPushError(f"Not a directory: {env_path}")
+
+        # Working-copy state: the base version this dir was pulled from and the
+        # branch it tracks. The server compare-and-sets the branch tip against
+        # the base at finalize — a stale base gets a 409 ("branch has moved"),
+        # never a silent overwrite. An ad-hoc dir (no metadata) declares
+        # base=None; `force` skips the check entirely.
+        local_meta = read_local_meta(env_path) or {}
+        push_branch = branch or local_meta.get("branch") or DEFAULT_BRANCH
+        base_version_id = local_meta.get("versionId")
+
+        # Optional semver bump (Prime `env push` parity): rewrite pyproject.toml's
+        # version BEFORE hashing/tarring so the bump lands in both the bundle and
+        # the semanticVersion sent to the hub. Mutates the working tree, like Prime.
+        if sum(bool(x) for x in (auto_bump, rc, post)) > 1:
+            raise BenchmarkPushError("--auto-bump, --rc and --post are mutually exclusive")
+        if auto_bump or rc or post:
+            current = read_pyproject(env_path).get("version")
+            if not current:
+                raise BenchmarkPushError("no [project].version in pyproject.toml to bump")
+            new_version = (
+                bump_version(current) if auto_bump else bump_rc_version(current) if rc else bump_post_version(current)
+            )
+            update_pyproject_version(env_path / "pyproject.toml", new_version)
+
+        try:
+            if bundle_mode(env_path) is not None:
+                validate_schema_materialization(env_path)
+        except ContractError as error:
+            raise BenchmarkPushError(f"Schema world check failed before push: {error}") from None
+
+        content_hash = compute_content_hash(env_path)
+        pyproject = read_pyproject(env_path)
+        slug = slug or pyproject.get("name") or env_path.name
+
+        # Optional wheel build (pip-install-by-name). Build BEFORE the versions POST
+        # so its object sha256 + Requires-Dist travel with the version request and we
+        # get a second presigned PUT back.
+        wheel_bytes: Optional[bytes] = None
+        wheel_sha256: Optional[str] = None
+        wheel_filename: Optional[str] = None
+        requires_dist: List[str] = []
+        if wheel:
+            wheel_path = build_wheel(env_path)
+            wheel_bytes = wheel_path.read_bytes()
+            wheel_sha256 = sha256_base64(wheel_bytes)
+            wheel_filename = wheel_path.name
+            requires_dist = parse_wheel_requires_dist(wheel_path)
+
+        resolve = self._post(
+            "/api/public/benchmark-containers/resolve",
+            {
+                "slug": slug,
+                "name": name or pyproject.get("name") or slug,
+                **({"description": description} if description else {}),
+                **({"tags": tags} if tags else {}),
+                **({"visibility": visibility} if visibility else {}),
+            },
+        )
+        container_id = resolve["containerId"]
+
+        tarball = build_source_tarball(env_path)
+        bundle_sha256 = sha256_base64(tarball)
+
+        version = self._post(
+            "/api/public/benchmark-containers/versions",
+            {
+                "containerId": container_id,
+                "contentHash": content_hash,
+                "bundleSha256": bundle_sha256,
+                "bundleSizeBytes": len(tarball),
+                **({"semanticVersion": pyproject["version"]} if pyproject.get("version") else {}),
+                "pyprojectMeta": pyproject,
+                "fileManifest": build_file_manifest(env_path),
+                "branch": push_branch,
+                "baseVersionId": base_version_id,
+                **({"force": True} if force else {}),
+                **({"changeReason": message} if message else {}),
+                **({"author": author} if author else {}),
+                **({"imageRef": image_ref} if image_ref else {}),
+                **(
+                    {
+                        "wheelSha256": wheel_sha256,
+                        "wheelSizeBytes": len(wheel_bytes),
+                        "wheelFilename": wheel_filename,
+                        "requiresDist": requires_dist,
+                    }
+                    if wheel_bytes is not None and wheel_sha256
+                    else {}
+                ),
+            },
+        )
+        version_id = version["versionId"]
+
+        if version.get("uploadUrl"):
+            self._put_object(version["uploadUrl"], tarball, bundle_sha256)
+        if version.get("wheelUploadUrl") and wheel_bytes is not None and wheel_sha256:
+            self._put_object(
+                version["wheelUploadUrl"],
+                wheel_bytes,
+                wheel_sha256,
+                content_type="application/octet-stream",
+            )
+
+        final = self._post(
+            f"/api/public/benchmark-containers/versions/{version_id}/finalize",
+            {
+                "branch": push_branch,
+                "baseVersionId": base_version_id,
+                **({"force": True} if force else {}),
+            },
+        )
+
+        # The push is the dir's new base — rewrite the metadata so the NEXT
+        # push fast-forwards instead of conflicting with your own work.
+        write_local_meta(
+            env_path,
+            {
+                "slug": slug,
+                "ref": push_branch,
+                "branch": push_branch,
+                "versionId": version_id,
+                "contentHash": content_hash,
+                "semanticVersion": pyproject.get("version"),
+                "forkedFromVersionId": base_version_id,
+                "baseFiles": snapshot_tree_hashes(env_path),
+            },
+        )
+
+        return {
+            "containerId": container_id,
+            "versionId": version_id,
+            "slug": slug,
+            "contentHash": content_hash,
+            "state": final.get("state"),
+            "branch": final.get("branch", push_branch),
+            "alreadyUploaded": bool(version.get("alreadyUploaded")),
+            "wheelBuilt": wheel_bytes is not None,
+        }
+
+    def dispatch_run_config(
+        self,
+        run_config_id: str,
+        *,
+        container_id: Optional[str] = None,
+        version_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Start a hosted run of a run config — the same dispatch the Run
+        button uses, parallelism included (the config's `parallelism` fans the
+        task list across that many containers per model). Returns
+        {versionLabel, runs: [{model, runId, ok, error?}]}."""
+        return self._post(
+            "/api/public/benchmark-containers/run-configs/dispatch",
+            {
+                "runConfigId": run_config_id,
+                **({"containerId": container_id} if container_id else {}),
+                **({"versionId": version_id} if version_id else {}),
+            },
+        )
+
+    def _json_request(self, method: str, path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+        req = urllib.request.Request(
+            f"{self.host}{path}",
+            data=json.dumps(body).encode("utf-8"),
+            method=method,
+            headers={
+                "Authorization": f"Basic {self._auth}",
+                "Content-Type": "application/json",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=120) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:500]
+            raise BenchmarkPushError(f"{method} {path} -> {e.code}: {detail}") from None
+
+    def list_run_configs(self) -> Dict[str, Any]:
+        """Run configs in the project — id, name, models, parallelism. The id
+        feeds dispatch_run_config; the name is how CI resolves it."""
+        return self._get("/api/public/benchmark-containers/run-configs")
+
+    def upsert_run_config(self, **fields: Any) -> Dict[str, Any]:
+        """Create a run config (or update, when ``id`` is given). Fields match
+        the Configs form: name, models, parallelism, numExamples,
+        rolloutsPerExample, timeoutMinutes, agent, taskSetDatasetId,
+        taskNames, worldTasks, autoRunOnPush. A config runs EITHER the bundle's
+        own scenarios (``taskNames`` / ``taskSetDatasetId``) OR the project's
+        stored tasks (``worldTasks``: ``[{"id": ..., "version"?: ...}]``, api
+        worlds only) — never both."""
+        return self._json_request("POST", "/api/public/benchmark-containers/run-configs", fields)
+
+    def delete_run_config(self, config_id: str) -> Dict[str, Any]:
+        return self._json_request(
+            "DELETE",
+            "/api/public/benchmark-containers/run-configs",
+            {"id": config_id},
+        )
+
+    def set_env_secret(self, slug: str, key: str, value: str) -> Dict[str, Any]:
+        """Set (or rotate) one environment secret — an env var every hosted
+        run of the world receives. Write-only: no API returns the value."""
+        return self._json_request(
+            "PUT",
+            "/api/public/benchmark-containers/secrets",
+            {"slug": slug, "key": key, "value": value},
+        )
+
+    def list_env_secret_keys(self, slug: str) -> Dict[str, Any]:
+        """Keys and rotation timestamps only — never values."""
+        return self._get(f"/api/public/benchmark-containers/secrets?slug={urllib.parse.quote(slug)}")
+
+    def delete_env_secret(self, slug: str, key: str) -> Dict[str, Any]:
+        return self._json_request(
+            "DELETE",
+            "/api/public/benchmark-containers/secrets",
+            {"slug": slug, "key": key},
+        )
+
+    def resolve_version(self, slug: str, ref: str = "latest") -> Dict[str, Any]:
+        """Resolve a container by slug + ref ('latest' | semver | contentHash
+        prefix) to a concrete READY version + a signed source-bundle URL."""
+        return self._post(
+            "/api/public/benchmark-containers/resolve-version",
+            {"slug": slug, **({"ref": ref} if ref else {})},
+        )
+
+    def pull(self, slug_ref: str, target: Optional[str] = None) -> Dict[str, Any]:
+        """Reconstruct a working dir from a version, addressed by name.
+
+        `slug_ref` is ``slug`` or ``slug@latest|@<semver>|@<hash-prefix>``. When
+        `target` is omitted the dir is `./<slug>`, de-duplicated with a ``-1``/``-2``
+        suffix (Prime `env pull` behavior). Writes `.gateway/.env-metadata.json`
+        (a dotdir, excluded from the content hash) so pull→edit→re-push is stable.
+        """
+        if "@" in slug_ref:
+            slug, ref = slug_ref.rsplit("@", 1)
+        else:
+            slug, ref = slug_ref, "latest"
+
+        details = self.resolve_version(slug, ref)
+        url = details.get("downloadUrl")
+        if not url:
+            raise BenchmarkPushError(f"{slug}@{ref} resolved but has no uploaded bundle")
+
+        base = Path(target) if target else Path.cwd() / slug
+        dst = base
+        if target is None and dst.exists():
+            i = 1
+            while dst.exists():
+                dst = base.parent / f"{base.name}-{i}"
+                i += 1
+        dst.mkdir(parents=True, exist_ok=True)
+
+        tmp = dst / ".bundle.tar.gz"
+        try:  # signed URL — no auth header
+            with urllib.request.urlopen(urllib.request.Request(url), timeout=300) as r:
+                bundle_bytes = r.read()
+        except urllib.error.HTTPError as e:
+            detail = e.read().decode("utf-8", "replace")[:300]
+            raise BenchmarkPushError(f"bundle download -> {e.code}: {detail}") from None
+
+        # Verify the downloaded bytes against the version's recorded object
+        # sha256, so a divergent bundle (overwritten object, corrupted transfer)
+        # fails loudly instead of silently extracting different content under a
+        # pinned "immutable" version. Older servers omit the field -> skip.
+        expected_sha = details.get("bundleSha256")
+        if expected_sha:
+            actual_sha = base64.b64encode(hashlib.sha256(bundle_bytes).digest()).decode()
+            if actual_sha != expected_sha:
+                raise BenchmarkPushError(
+                    f"bundle integrity check failed for {slug}@{ref}: downloaded "
+                    f"object sha256 ({actual_sha}) != recorded bundleSha256 "
+                    f"({expected_sha})"
+                )
+        tmp.write_bytes(bundle_bytes)
+
+        with tarfile.open(tmp, "r:gz") as tar:
+            safe_tar_extract(tar, dst)
+        tmp.unlink(missing_ok=True)
+
+        # Track the branch that answered the ref; a semver/hash pin is a
+        # detached checkout, which pushes onto main unless told otherwise.
+        branch = details.get("branch") or (DEFAULT_BRANCH if ref == "latest" else None)
+        write_local_meta(
+            dst,
+            {
+                "slug": slug,
+                "ref": ref,
+                "branch": branch or DEFAULT_BRANCH,
+                "versionId": details.get("versionId"),
+                "contentHash": details.get("contentHash"),
+                "semanticVersion": details.get("semanticVersion"),
+                "forkedFromVersionId": details.get("forkedFromVersionId"),
+                "baseFiles": snapshot_tree_hashes(dst),
+            },
+        )
+        return {
+            "slug": slug,
+            "ref": ref,
+            "branch": branch or DEFAULT_BRANCH,
+            "versionId": details.get("versionId"),
+            "contentHash": details.get("contentHash"),
+            "target": str(dst),
+        }
+
+    # ── Refs (branches + tags) ───────────────────────────────────────────
+
+    def list_refs(self, slug: str) -> Dict[str, Any]:
+        """Every branch and tag of a container with tip version info."""
+        qs = urlencode({"slug": slug})
+        return self._get(f"/api/public/benchmark-containers/refs?{qs}")
+
+    def create_ref(
+        self,
+        slug: str,
+        name: str,
+        *,
+        kind: str = "branch",
+        version_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a branch (movable, starts at the main tip unless pinned) or
+        an immutable tag (points at a concrete version forever)."""
+        return self._post(
+            "/api/public/benchmark-containers/refs",
+            {
+                "slug": slug,
+                "name": name,
+                "kind": kind,
+                **({"versionId": version_id} if version_id else {}),
+            },
+        )
+
+    def log(self, slug: str, *, branch: Optional[str] = None, limit: int = 50) -> Dict[str, Any]:
+        """A branch's version lineage, tip first (`bench log`)."""
+        qs = urlencode({"slug": slug, "limit": str(limit), **({"branch": branch} if branch else {})})
+        return self._get(f"/api/public/benchmark-containers/log?{qs}")
+
+    def status(self, env_path: str | Path) -> Dict[str, Any]:
+        """The working dir's position: branch, base, dirtiness, and whether
+        the remote branch tip has moved past the base (`bench status`)."""
+        env_path = Path(env_path)
+        meta = read_local_meta(env_path)
+        if not meta or not meta.get("slug"):
+            raise BenchmarkPushError(
+                f"{env_path} has no .gateway/.env-metadata.json — pull or push it "
+                "first so the dir knows which container/branch it tracks."
+            )
+        slug = meta["slug"]
+        branch = meta.get("branch") or DEFAULT_BRANCH
+        local_hash = compute_content_hash(env_path)
+        dirty = local_hash != meta.get("contentHash")
+
+        refs = self.list_refs(slug).get("refs", [])
+        tip = next((r for r in refs if r.get("name") == branch), None)
+        behind = bool(tip and tip.get("versionId") != meta.get("versionId"))
+        return {
+            "slug": slug,
+            "branch": branch,
+            "baseVersionId": meta.get("versionId"),
+            "baseContentHash": meta.get("contentHash"),
+            "localContentHash": local_hash,
+            "dirty": dirty,
+            "behind": behind,
+            "remoteTipVersionId": tip.get("versionId") if tip else None,
+            "remoteTipContentHash": tip.get("contentHash") if tip else None,
+        }
+
+    def propose(
+        self,
+        env_path: str | Path,
+        *,
+        title: str,
+        message: str,
+        target_branch: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """File the working dir's local edits as a change proposal ("PR to the
+        env") instead of pushing straight to the branch. The changeset is the
+        diff between the dir and its recorded base version's file manifest;
+        review + apply live on the environment homepage's Changes tab.
+
+        A dir sitting on a pushed BRANCH proposing into a different target is
+        a branch-backed PR (GitHub semantics): the diff is computed against
+        the TARGET branch's tip — diffing against the dir's own base right
+        after a push is empty by construction — and the branch is recorded
+        so runs of the proposal dispatch the branch tip directly."""
+        env_path = Path(env_path)
+        meta = read_local_meta(env_path)
+        if not meta or not meta.get("slug") or not meta.get("versionId"):
+            raise BenchmarkPushError(
+                f"{env_path} has no recorded base (.gateway/.env-metadata.json) — "
+                "a proposal is a diff against a base version, pull first."
+            )
+        slug = meta["slug"]
+        base_version_id = meta["versionId"]
+        recorded_branch = meta.get("branch") or meta.get("ref")
+        target = target_branch or DEFAULT_BRANCH
+
+        def _manifest_hashes(version_id: str) -> Dict[str, Any]:
+            # Server manifest as a base-file record. Dot-paths are dropped —
+            # the manifest deliberately lists files the source tarball never
+            # contained, which would read as phantom deletes here.
+            listed = self._get(f"/api/public/benchmark-containers/versions/{version_id}/files").get("files", [])
+            return {
+                f["path"]: f.get("sha256")
+                for f in listed
+                if not f.get("isDirectory") and not any(seg.startswith(".") for seg in f["path"].split("/"))
+            }
+
+        source_branch: Optional[str] = None
+        if recorded_branch and recorded_branch != target:
+            source_branch = str(recorded_branch)
+            try:
+                tip = self.resolve_version(slug, target)
+            except Exception as exc:
+                raise BenchmarkPushError(
+                    f"could not resolve target branch '{target}' to propose " f"against: {exc}"
+                ) from None
+            base_version_id = tip["versionId"]
+            base_by_path: Dict[str, Any] = _manifest_hashes(base_version_id)
+        else:
+            # Same-branch proposal: the tarball tree snapshotted at pull/push
+            # time; the manifest is only a pre-baseFiles fallback.
+            base_by_path = meta.get("baseFiles") or {}
+            if not base_by_path:
+                base_by_path = _manifest_hashes(base_version_id)
+
+        changes: List[Dict[str, Any]] = []
+        local_paths = set()
+        for file_path in collect_archive_files(env_path):
+            rel = str(file_path.relative_to(env_path)).replace("\\", "/")
+            local_paths.add(rel)
+            data = file_path.read_bytes()
+            digest = hashlib.sha256(data).hexdigest()
+            if base_by_path.get(rel) == digest:
+                continue
+            try:
+                text = data.decode("utf-8")
+            except UnicodeDecodeError:
+                raise BenchmarkPushError(
+                    f"{rel} is not utf-8 text — proposals carry text changesets; "
+                    "push binary changes directly to a branch instead."
+                ) from None
+            changes.append({"path": rel, "action": "write", "newContent": text})
+        for rel in sorted(set(base_by_path) - local_paths):
+            changes.append({"path": rel, "action": "delete"})
+
+        if not changes:
+            raise BenchmarkPushError(
+                f"No changes against {target} — nothing to propose."
+                + (f" (branch {source_branch} matches the target's tip)" if source_branch else "")
+            )
+
+        result = self._post(
+            "/api/public/benchmark-containers/proposals",
+            {
+                "slug": slug,
+                "title": title,
+                "changeReason": message,
+                "baseVersionId": base_version_id,
+                **({"targetBranch": target_branch} if target_branch else {}),
+                **({"sourceBranch": source_branch} if source_branch else {}),
+                "changes": changes,
+            },
+        )
+        return result
+
+    def fork(self, slug: str, target_slug: Optional[str] = None) -> Dict[str, Any]:
+        """Fork a container: create a new container whose head version copies the
+        source's latest READY version (shared bundle, recorded provenance). Forks
+        are container-level — pass a bare slug, not ``slug@version``."""
+        if "@" in slug:
+            raise BenchmarkPushError("fork a container head; omit the @version suffix")
+        return self._post(
+            "/api/public/benchmark-containers/fork",
+            {
+                "slug": slug,
+                **({"targetSlug": target_slug} if target_slug else {}),
+            },
+        )
+
+    def diff(self, base: str, head: str) -> Dict[str, Any]:
+        """Per-file diff (added/removed/modified/unchanged) between two version
+        ids, keyed on the stored per-file sha256."""
+        from urllib.parse import urlencode
+
+        qs = urlencode({"base": base, "head": head})
+        return self._get(f"/api/public/benchmark-containers/versions/diff?{qs}")
+
+    def install(self, slug_ref: str, *, tool: str = "uv", no_upgrade: bool = False) -> Dict[str, Any]:
+        """Install a version's built wheel by name (wheel-url-direct). Requires the
+        version to have been pushed with ``wheel=True``. ``tool`` is 'uv' or 'pip';
+        runs in the current Python environment (activate a venv first for uv)."""
+        if "@" in slug_ref:
+            slug, ref = slug_ref.rsplit("@", 1)
+        else:
+            slug, ref = slug_ref, "latest"
+        details = self.resolve_version(slug, ref)
+        version_id = details.get("versionId")
+        dl = self._get(f"/api/public/benchmark-containers/versions/{version_id}" "/download?artifact=wheel")
+        wheel_url = dl.get("downloadUrl")
+        if not wheel_url:
+            raise BenchmarkPushError(
+                f"{slug}@{ref} has no built wheel — push it with " "wheel=True (`gateway bench push --build-wheel`)"
+            )
+        # Download to a temp file with the canonical `.whl` basename (the object-key
+        # basename); a presigned URL basename carries a query string that pip/uv
+        # can't parse into a wheel name.
+        import tempfile
+        from urllib.parse import unquote, urlparse
+
+        wheel_name = os.path.basename(unquote(urlparse(wheel_url).path)) or "pkg.whl"
+        tmpdir = tempfile.mkdtemp(prefix="gateway-wheel-")
+        wheel_file = os.path.join(tmpdir, wheel_name)
+        try:
+            with (
+                urllib.request.urlopen(urllib.request.Request(wheel_url), timeout=300) as r,
+                open(wheel_file, "wb") as f,
+            ):
+                shutil.copyfileobj(r, f)
+        except urllib.error.HTTPError as e:
+            raise BenchmarkPushError(f"wheel download -> {e.code}") from None
+
+        if tool == "uv":
+            cmd = ["uv", "pip", "install"]
+            if not no_upgrade:
+                cmd.append("--reinstall")
+        else:
+            cmd = ["pip", "install"]
+            if not no_upgrade:
+                cmd.append("--upgrade")
+        cmd.append(wheel_file)
+        try:
+            subprocess.run(cmd, check=True)
+        except FileNotFoundError:
+            raise BenchmarkPushError(
+                f"'{cmd[0]}' is not installed or not on PATH — install it "
+                "(https://docs.astral.sh/uv/) or rerun with tool='pip' "
+                "(`gateway bench install --tool pip`)."
+            ) from None
+        except subprocess.CalledProcessError as e:
+            raise BenchmarkPushError(f"install failed (exit {e.returncode})") from None
+        finally:
+            shutil.rmtree(tmpdir, ignore_errors=True)
+        return {
+            "slug": slug,
+            "ref": ref,
+            "versionId": version_id,
+            "tool": tool,
+            "wheelFile": wheel_name,
+        }
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """`python -m gatewaysdk.benchmark_hub.client push ./env [--slug ...]`."""
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="gateway bench")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    push_p = sub.add_parser("push", help="Push a benchmark container to Gateway")
+    push_p.add_argument("path")
+    push_p.add_argument("--host", default=None)
+    push_p.add_argument("--slug", default=None)
+    push_p.add_argument("--name", default=None)
+    push_p.add_argument("--description", default=None)
+    push_p.add_argument("--tag", action="append", dest="tags", default=None)
+    push_p.add_argument("--visibility", choices=["PRIVATE", "PUBLIC"], default=None)
+    push_p.add_argument("--auto-bump", action="store_true", dest="auto_bump")
+    push_p.add_argument("--rc", action="store_true")
+    push_p.add_argument("--post", action="store_true")
+    push_p.add_argument("--image", dest="image_ref", default=None)
+    push_p.add_argument("--build-wheel", action="store_true", dest="build_wheel")
+
+    pull_p = sub.add_parser("pull", help="Reconstruct a container version's source dir by name")
+    pull_p.add_argument("slug", help="slug or slug@latest|@semver|@hash")
+    pull_p.add_argument("--host", default=None)
+    pull_p.add_argument("--target", "-t", default=None)
+
+    fork_p = sub.add_parser("fork", help="Fork a container head into a new container")
+    fork_p.add_argument("slug", help="source container slug (fork the head)")
+    fork_p.add_argument("--host", default=None)
+    fork_p.add_argument("--into", dest="target_slug", default=None)
+
+    diff_p = sub.add_parser("diff", help="Per-file diff between two version ids")
+    diff_p.add_argument("base", help="base version id")
+    diff_p.add_argument("head", help="head version id")
+    diff_p.add_argument("--host", default=None)
+
+    install_p = sub.add_parser("install", help="pip-install a version's wheel by name")
+    install_p.add_argument("slug", help="slug or slug@latest|@semver|@hash")
+    install_p.add_argument("--host", default=None)
+    install_p.add_argument("--tool", choices=["uv", "pip"], default="uv")
+    install_p.add_argument("--no-upgrade", action="store_true", dest="no_upgrade")
+    args = parser.parse_args(argv)
+
+    if args.cmd == "push":
+        client = GatewayBenchmarkClient.from_env(host=args.host)
+        result = client.push(
+            args.path,
+            slug=args.slug,
+            name=args.name,
+            description=args.description,
+            tags=args.tags,
+            visibility=args.visibility,
+            auto_bump=args.auto_bump,
+            rc=args.rc,
+            post=args.post,
+            image_ref=args.image_ref,
+            wheel=args.build_wheel,
+        )
+        print(json.dumps(result, indent=2))
+        return 0
+    if args.cmd == "pull":
+        client = GatewayBenchmarkClient.from_env(host=args.host)
+        result = client.pull(args.slug, target=args.target)
+        print(json.dumps(result, indent=2))
+        return 0
+    if args.cmd == "fork":
+        client = GatewayBenchmarkClient.from_env(host=args.host)
+        result = client.fork(args.slug, target_slug=args.target_slug)
+        print(json.dumps(result, indent=2))
+        return 0
+    if args.cmd == "diff":
+        client = GatewayBenchmarkClient.from_env(host=args.host)
+        result = client.diff(args.base, args.head)
+        print(json.dumps(result, indent=2))
+        return 0
+    if args.cmd == "install":
+        client = GatewayBenchmarkClient.from_env(host=args.host)
+        result = client.install(args.slug, tool=args.tool, no_upgrade=args.no_upgrade)
+        print(json.dumps(result, indent=2))
+        return 0
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())