hypercli-sdk 1.0.3__tar.gz → 2026.3.10__tar.gz

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/.gitignore

@@ -49,3 +49,4 @@ next-env.d.ts
 
 # Turbo
 .turbo
+.netlify

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypercli-sdk
-Version: 1.0.3
+Version: 2026.3.10
 Summary: Python SDK for HyperCLI - GPU orchestration and LLM API
 Project-URL: Homepage, https://hypercli.com
 Project-URL: Documentation, https://docs.hypercli.com

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/hypercli/__init__.py

@@ -14,7 +14,7 @@ from .shell import ShellSession, shell_connect
 from .claw import Claw, ClawKey, ClawPlan, ClawModel
 from .gateway import GatewayClient, GatewayError, ChatEvent
 
-__version__ = "1.0.0"
+__version__ = "2026.3.10"
 __all__ = [
     "HyperCLI",
     "configure",

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/hypercli/agents.py

@@ -9,7 +9,7 @@ runtime key generation, and DB persistence.
 """
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Optional, Any, AsyncIterator
 
@@ -41,6 +41,7 @@ class ReefPod:
     last_error: Optional[str] = None
     created_at: Optional[datetime] = None
     updated_at: Optional[datetime] = None
+    ports: list[dict] = field(default_factory=list)
 
     @classmethod
     def from_dict(cls, data: dict) -> ReefPod:
@@ -67,6 +68,7 @@ class ReefPod:
             last_error=data.get("last_error"),
             created_at=_parse_dt(data.get("created_at")),
             updated_at=_parse_dt(data.get("updated_at")),
+            ports=data.get("ports") or [],
         )
 
     @property
@@ -205,6 +207,8 @@ class Agents:
         cpu: int = None,
         memory: int = None,
         config: dict = None,
+        env: dict = None,
+        ports: list = None,
         start: bool = True,
     ) -> ReefPod:
         """Create a new agent (provisions a reef pod via the backend).
@@ -215,6 +219,8 @@ class Agents:
             cpu: Custom CPU in cores (overrides size).
             memory: Custom memory in GB (overrides size).
             config: Optional config overrides.
+            env: Optional environment variables to pass through to the pod.
+            ports: Optional exposed ports config.
             start: Start the agent immediately (default: True).
 
         Returns:
@@ -229,6 +235,10 @@ class Agents:
             body["cpu"] = cpu
         if memory is not None:
             body["memory"] = memory
+        if env is not None:
+            body["env"] = env
+        if ports is not None:
+            body["ports"] = ports
         data = self._post("/api/agents", json=body)
         return ReefPod.from_dict(data)
 
@@ -331,22 +341,20 @@ class Agents:
         return h
 
     def exec(self, pod: ReefPod, command: str, timeout: int = 30) -> ExecResult:
-        """Execute a one-shot command on a reef pod via the executor API.
+        """Execute a one-shot command on a reef pod via lagoon exec API.
 
         Args:
-            pod: ReefPod to execute on (needs jwt_token).
+            pod: ReefPod to execute on.
             command: Shell command to run.
             timeout: Command timeout in seconds.
 
         Returns:
             ExecResult with exit_code, stdout, stderr.
         """
-        if not pod.executor_url:
-            raise ValueError("Pod has no executor URL (missing hostname)")
-        with httpx.Client(timeout=max(timeout + 5, 35)) as client:
+        with httpx.Client(timeout=max(timeout + 10, 35)) as client:
             resp = client.post(
-                f"{pod.executor_url}/exec",
-                headers=self._executor_headers(pod),
+                f"{self._api_base}/api/agents/{pod.id}/exec",
+                headers=self._headers,
                 json={"command": command, "timeout": timeout},
             )
         if resp.status_code >= 400:

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/hypercli/claw.py

@@ -53,12 +53,13 @@ class ClawPlan:
     
     @classmethod
     def from_dict(cls, data: dict) -> "ClawPlan":
+        price = data.get("price_usd", data.get("price", 0))
         return cls(
             id=data["id"],
-            name=data["name"],
-            price_usd=data["price_usd"],
-            tpm_limit=data["tpm_limit"],
-            rpm_limit=data["rpm_limit"],
+            name=data.get("name", data["id"]),
+            price_usd=float(price or 0),
+            tpm_limit=int(data.get("tpm_limit", 0)),
+            rpm_limit=int(data.get("rpm_limit", 0)),
         )
 
 

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/hypercli/gateway.py

@@ -88,7 +88,7 @@ class GatewayClient:
         gateway_token: str = "traefik-forwarded-auth-not-used",
         client_id: str = "openclaw-control-ui",
         client_mode: str = "webchat",
-        origin: str = "https://hyperclaw.app",
+        origin: str = "https://sdk.hyperclaw.app",
         timeout: float = DEFAULT_TIMEOUT,
     ):
         self.url = url
@@ -270,22 +270,31 @@ class GatewayClient:
                 self._pending.pop(req_id, None)
                 raise GatewayError("TIMEOUT", f"Streaming {method} timed out")
 
-            # Check if final response arrived
+            # Drain any queued events first (before checking done, to avoid dropping buffered content)
+            try:
+                event = await asyncio.wait_for(self._event_queue.get(), timeout=min(remaining, 0.1))
+                if event_filter is None or event.get("event", "").startswith(event_filter):
+                    yield event
+                continue
+            except asyncio.TimeoutError:
+                pass
+
+            # Check if final response arrived (only after queue is drained for this tick)
             if fut.done():
+                # Drain any remaining events that arrived with the response
+                while not self._event_queue.empty():
+                    try:
+                        event = self._event_queue.get_nowait()
+                        if event_filter is None or event.get("event", "").startswith(event_filter):
+                            yield event
+                    except asyncio.QueueEmpty:
+                        break
                 resp = fut.result()
                 if not resp.get("ok"):
                     err = resp.get("error", {})
                     raise GatewayError(err.get("code", "RPC_ERROR"), err.get("message", ""))
                 return
 
-            # Drain events
-            try:
-                event = await asyncio.wait_for(self._event_queue.get(), timeout=min(remaining, 1.0))
-                if event_filter is None or event.get("event", "").startswith(event_filter):
-                    yield event
-            except asyncio.TimeoutError:
-                continue
-
     # -----------------------------------------------------------------------
     # Config
     # -----------------------------------------------------------------------
@@ -299,12 +308,21 @@ class GatewayClient:
         """Get the JSON schema + uiHints for the config."""
         return await self.call("config.schema")
 
-    async def config_patch(self, patch: dict) -> dict:
+    async def config_patch(self, patch: dict, base_hash: str = None) -> dict:
         """Patch the gateway configuration (merges with existing).
 
+        Fetches current config to get baseHash if not provided.
         The gateway will restart after applying the patch.
         """
-        return await self.call("config.patch", {"patch": patch}, timeout=30)
+        import json as _json
+        if base_hash is None:
+            raw_result = await self.call("config.get")
+            base_hash = raw_result.get("hash") or raw_result.get("baseHash", "")
+        return await self.call(
+            "config.patch",
+            {"raw": _json.dumps(patch), "baseHash": base_hash},
+            timeout=30,
+        )
 
     async def config_apply(self, config: dict) -> dict:
         """Replace the entire gateway configuration.
@@ -397,40 +415,75 @@ class GatewayClient:
         result = await self.call("chat.history", params)
         return result.get("messages", [])
 
+    async def _listen_events(self, event_name: str, deadline: float) -> AsyncIterator[dict]:
+        """Yield broadcast events matching event_name until deadline."""
+        while asyncio.get_event_loop().time() < deadline:
+            remaining = deadline - asyncio.get_event_loop().time()
+            try:
+                event = await asyncio.wait_for(self._event_queue.get(), timeout=min(remaining, 1.0))
+                if event.get("event") == event_name:
+                    yield event
+            except asyncio.TimeoutError:
+                continue
+
     async def chat_send(self, message: str, session_key: str = None, agent_id: str = None) -> AsyncIterator[ChatEvent]:
         """Send a chat message and stream the response.
 
-        Yields ChatEvent objects as the agent responds.
+        Gateway chat events arrive as broadcast {"event": "chat"} messages with
+        payload.state = "delta" | "final" | "error" | "aborted".
+        The RPC response for chat.send is an immediate ACK; content follows as broadcasts.
         """
         import uuid as _uuid
-        params: dict = {"message": message, "idempotencyKey": str(_uuid.uuid4())}
+        run_id = str(_uuid.uuid4())
+        params: dict = {"message": message, "idempotencyKey": run_id}
         if session_key:
             params["sessionKey"] = session_key
         if agent_id:
             params["agentId"] = agent_id
 
-        async for event in self._call_streaming("chat.send", params, event_filter="chat."):
-            evt = event.get("event", "")
+        # Send RPC and wait for ACK (gateway confirms message queued)
+        ack = await self.call("chat.send", params, timeout=30)
+        if not ack.get("ok", True) is False:
+            pass  # ACK is just confirmation, not content
+
+        # Now listen for broadcast "chat" events matching our runId.
+        # The gateway may emit multiple "final" events for a single run:
+        #   1. An intermediate final with no text (tool-call turn, agent used exec/tools)
+        #   2. The real final with the assistant's text response after tool execution
+        # We keep listening until we get a final with actual text content, or an
+        # empty final that isn't followed by more events (simple text-only response).
+        deadline = asyncio.get_event_loop().time() + CHAT_TIMEOUT
+        got_text = False
+        async for event in self._listen_events(event_name="chat", deadline=deadline):
             payload = event.get("payload", {})
-
-            if evt == "chat.content":
-                yield ChatEvent(type="content", text=payload.get("text", ""))
-            elif evt == "chat.thinking":
-                yield ChatEvent(type="thinking", text=payload.get("text", ""))
-            elif evt == "chat.tool_call":
+            if payload.get("runId") != run_id:
+                continue  # Different chat run, skip
+
+            state = payload.get("state", "")
+            if state == "delta":
+                # Deltas are incremental streaming tokens — yield for low-latency consumers
+                msg = payload.get("message", {})
+                for part in (msg.get("content") or []):
+                    if isinstance(part, dict) and part.get("type") == "text" and part.get("text"):
+                        yield ChatEvent(type="delta", text=part["text"])
+                        got_text = True
+            elif state == "final":
+                msg = payload.get("message", {})
+                has_text = False
+                for part in (msg.get("content") or []):
+                    if isinstance(part, dict) and part.get("type") == "text" and part.get("text"):
+                        yield ChatEvent(type="content", text=part["text"])
+                        has_text = True
+
+                if has_text or got_text:
+                    # Real final with content (or we already streamed deltas) — done
+                    yield ChatEvent(type="done", data=payload)
+                    return
+                # Empty final (tool-call turn) — keep listening for the real response
                 yield ChatEvent(type="tool_call", data=payload)
-            elif evt == "chat.tool_result":
-                yield ChatEvent(type="tool_result", data=payload)
-            elif evt == "chat.done":
-                yield ChatEvent(type="done", data=payload)
-                return
-            elif evt == "chat.error":
-                yield ChatEvent(type="error", text=payload.get("message", ""))
+            elif state in ("error", "aborted"):
+                yield ChatEvent(type="error", text=payload.get("errorMessage", state))
                 return
-            elif evt == "chat.status":
-                yield ChatEvent(type="status", text=payload.get("status", ""))
-            else:
-                yield ChatEvent(type=evt, data=payload)
 
     async def chat_abort(self, session_key: str = None) -> dict:
         """Abort the current chat generation."""

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/hypercli/jobs.py

@@ -20,6 +20,11 @@ class Job:
     price_per_second: float
     docker_image: str
     runtime: int
+    elapsed: int = 0
+    time_left: int = 0
+    command: str | None = None
+    env_vars: dict[str, str] | None = None
+    tags: dict[str, str] | None = None
     hostname: str | None = None
     cold_boot: bool = True
     created_at: float | None = None
@@ -28,6 +33,13 @@ class Job:
 
     @classmethod
     def from_dict(cls, data: dict) -> "Job":
+        command_b64 = data.get("command")
+        command = None
+        if isinstance(command_b64, str) and command_b64:
+            try:
+                command = base64.b64decode(command_b64).decode()
+            except Exception:
+                command = command_b64
         return cls(
             job_id=data.get("job_id", ""),
             job_key=data.get("job_key", ""),
@@ -39,7 +51,12 @@ class Job:
             price_per_hour=data.get("price_per_hour", 0),
             price_per_second=data.get("price_per_second", 0),
             docker_image=data.get("docker_image", ""),
+            command=command,
+            env_vars=data.get("env_vars"),
+            tags=data.get("tags"),
             runtime=data.get("runtime", 0),
+            elapsed=data.get("elapsed", 0),
+            time_left=data.get("time_left", 0),
             hostname=data.get("hostname"),
             cold_boot=data.get("cold_boot", True),
             created_at=data.get("created_at"),
@@ -127,9 +144,15 @@ class Jobs:
     def __init__(self, http: "HTTPClient"):
         self._http = http
 
-    def list(self, state: str = None) -> list[Job]:
+    def list(self, state: str = None, tags: dict[str, str] | None = None) -> list[Job]:
         """List all jobs"""
-        params = {"state": state} if state else None
+        params = {}
+        if state:
+            params["state"] = state
+        if tags:
+            params["tag"] = [f"{key}:{value}" for key, value in tags.items()]
+        if not params:
+            params = None
         data = self._http.get("/api/jobs", params=params)
         # API returns {"jobs": [...], "total_count": ...}
         jobs = data.get("jobs", []) if isinstance(data, dict) else data
@@ -153,6 +176,7 @@ class Jobs:
         ports: dict[str, int] = None,
         auth: bool = False,
         registry_auth: dict[str, str] = None,
+        tags: dict[str, str] = None,
         dockerfile: str = None,
         dry_run: bool = False,
     ) -> Job:
@@ -192,6 +216,8 @@ class Jobs:
             payload["auth"] = auth
         if registry_auth:
             payload["registry_auth"] = registry_auth
+        if tags:
+            payload["tags"] = tags
         if dockerfile:
             payload["dockerfile"] = dockerfile
         if dry_run:

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hypercli-sdk"
-version = "1.0.3"
+version = "2026.3.10"
 description = "Python SDK for HyperCLI - GPU orchestration and LLM API"
 readme = "README.md"
 requires-python = ">=3.10"

{hypercli_sdk-1.0.3 → hypercli_sdk-2026.3.10}/tests/test_agents.py

@@ -36,6 +36,7 @@ def test_reef_pod_from_dict():
         "last_error": None,
         "created_at": "2026-02-24T09:00:00Z",
         "updated_at": "2026-02-24T10:00:00Z",
+        "ports": [{"port": 18789, "auth": False, "prefix": "openclaw"}],
     }
 
     pod = ReefPod.from_dict(data)
@@ -57,6 +58,7 @@ def test_reef_pod_from_dict():
     assert pod.last_error is None
     assert isinstance(pod.created_at, datetime)
     assert isinstance(pod.updated_at, datetime)
+    assert pod.ports == [{"port": 18789, "auth": False, "prefix": "openclaw"}]
 
 
 def test_reef_pod_from_dict_minimal():
@@ -76,6 +78,7 @@ def test_reef_pod_from_dict_minimal():
     assert pod.name is None
     assert pod.cpu == 0
     assert pod.memory == 0
+    assert pod.ports == []
 
 
 def test_reef_pod_urls():
@@ -264,6 +267,8 @@ def test_agents_create(agents_client):
             size="medium",
             cpu=4,
             memory=16,
+            env={"FOO": "bar"},
+            ports=[{"port": 18789, "auth": False}],
             start=True,
         )
 
@@ -277,6 +282,8 @@ def test_agents_create(agents_client):
         assert posted_json["size"] == "medium"
         assert posted_json["cpu"] == 4
         assert posted_json["memory"] == 16
+        assert posted_json["env"] == {"FOO": "bar"}
+        assert posted_json["ports"] == [{"port": 18789, "auth": False}]
         assert posted_json["start"] is True
 
         # Verify response parsing

hypercli_sdk-2026.3.10/tests/test_exec_shell_dryrun.py

@@ -0,0 +1,151 @@
+import pytest
+
+from hypercli.jobs import Jobs
+from hypercli.agents import Agents, ReefPod
+
+
+class DummyHTTP:
+    def __init__(self):
+        self.api_key = "hyper_api_test"
+        self.base_url = "https://api.hypercli.com"
+        self.calls = []
+
+    def post(self, path, json=None, timeout=None):
+        self.calls.append(("post", path, json, timeout))
+        if path.endswith("/exec"):
+            return {"job_id": "job-1", "stdout": "ok\n", "stderr": "", "exit_code": 0}
+        return {
+            "job_id": "job-1",
+            "job_key": "job-key-123",
+            "state": "running",
+            "gpu_type": "l40s",
+            "gpu_count": 1,
+            "region": "oh",
+            "interruptible": True,
+            "price_per_hour": 1.2,
+            "price_per_second": 0.0003,
+            "docker_image": "nvidia/cuda",
+            "command": "ZWNobyBoaQ==",
+            "env_vars": {"FOO": "bar"},
+            "runtime": 120,
+            "cold_boot": False,
+        }
+
+    def get(self, path, params=None):
+        if path == "/api/jobs/job-1":
+            return {
+                "job_id": "job-1",
+                "job_key": "job-key-123",
+                "state": "running",
+                "gpu_type": "l40s",
+                "gpu_count": 1,
+                "region": "oh",
+                "interruptible": True,
+                "price_per_hour": 1.2,
+                "price_per_second": 0.0003,
+                "docker_image": "nvidia/cuda",
+                "command": "ZWNobyBoaQ==",
+                "env_vars": {"FOO": "bar"},
+                "runtime": 120,
+            }
+        return {}
+
+
+def test_jobs_create_dry_run_payload():
+    http = DummyHTTP()
+    jobs = Jobs(http)
+
+    jobs.create(image="nvidia/cuda:12.0", command="echo hi", dry_run=True)
+
+    _, path, payload, _ = http.calls[0]
+    assert path == "/api/jobs"
+    assert payload["dry_run"] is True
+    assert "command" in payload
+
+
+def test_jobs_exec():
+    http = DummyHTTP()
+    jobs = Jobs(http)
+
+    result = jobs.exec("job-1", "echo ok", timeout=15)
+
+    assert result.exit_code == 0
+    assert result.stdout == "ok\n"
+    assert http.calls[0][1] == "/api/jobs/job-1/exec"
+
+
+def test_jobs_get_decodes_command_and_preserves_env():
+    http = DummyHTTP()
+    jobs = Jobs(http)
+
+    job = jobs.get("job-1")
+
+    assert job.command == "echo hi"
+    assert job.env_vars == {"FOO": "bar"}
+
+
+@pytest.mark.asyncio
+async def test_jobs_shell_connect(monkeypatch):
+    http = DummyHTTP()
+    jobs = Jobs(http)
+    captured = {}
+
+    async def fake_connect(url, ping_interval=20, ping_timeout=20):
+        captured["url"] = url
+        return "ws-conn"
+
+    monkeypatch.setattr("websockets.connect", fake_connect)
+
+    ws = await jobs.shell_connect("job-1", shell="/bin/sh")
+
+    assert ws == "ws-conn"
+    assert captured["url"] == "wss://api.hypercli.com/orchestra/ws/shell/job-1?token=job-key-123&shell=/bin/sh"
+
+
+def test_agents_exec(monkeypatch):
+    class FakeResponse:
+        status_code = 200
+
+        def json(self):
+            return {"exit_code": 0, "stdout": "done", "stderr": ""}
+
+    class FakeClient:
+        def __init__(self, timeout=None):
+            self.timeout = timeout
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc, tb):
+            return False
+
+        def post(self, url, headers=None, json=None):
+            assert url.endswith("/api/agents/agent-1/exec")
+            assert json["command"] == "ls"
+            return FakeResponse()
+
+    monkeypatch.setattr("hypercli.agents.httpx.Client", FakeClient)
+
+    agents = Agents(DummyHTTP(), claw_api_key="sk-test")
+    pod = ReefPod(id="agent-1", user_id="u1", pod_id="p1", pod_name="pod", state="running")
+
+    result = agents.exec(pod, "ls", timeout=10)
+    assert result.exit_code == 0
+    assert result.stdout == "done"
+
+
+@pytest.mark.asyncio
+async def test_agents_shell_connect(monkeypatch):
+    agents = Agents(DummyHTTP(), claw_api_key="sk-test")
+    monkeypatch.setattr(agents, "_post", lambda path, json=None: {"token": "jwt-abc"})
+    captured = {}
+
+    async def fake_connect(url, ping_interval=20, ping_timeout=20):
+        captured["url"] = url
+        return "agent-ws"
+
+    monkeypatch.setattr("websockets.connect", fake_connect)
+
+    ws = await agents.shell_connect("agent-1")
+    assert ws == "agent-ws"
+    assert captured["url"] == "wss://api.hyperclaw.app/ws/shell/agent-1?jwt=jwt-abc"

hypercli_sdk-2026.3.10/tests/test_jobs.py

@@ -0,0 +1,93 @@
+from hypercli.jobs import Job, Jobs
+
+
+class DummyHTTP:
+    def __init__(self):
+        self.calls = []
+
+    def get(self, path, params=None):
+        self.calls.append(("get", path, params))
+        return {
+            "jobs": [
+                {
+                    "job_id": "job-1",
+                    "job_key": "job-key-123",
+                    "state": "running",
+                    "gpu_type": "l40s",
+                    "gpu_count": 1,
+                    "region": "oh",
+                    "interruptible": True,
+                    "price_per_hour": 1.2,
+                    "price_per_second": 0.0003,
+                    "docker_image": "nvidia/cuda",
+                    "runtime": 120,
+                    "tags": {"team": "ml", "env": "prod"},
+                }
+            ]
+        }
+
+    def post(self, path, json=None, timeout=None):
+        self.calls.append(("post", path, json, timeout))
+        return {
+            "job_id": "job-1",
+            "job_key": "job-key-123",
+            "state": "running",
+            "gpu_type": "l40s",
+            "gpu_count": 1,
+            "region": "oh",
+            "interruptible": True,
+            "price_per_hour": 1.2,
+            "price_per_second": 0.0003,
+            "docker_image": "nvidia/cuda",
+            "runtime": 120,
+            "tags": json.get("tags"),
+        }
+
+
+def test_job_from_dict_preserves_tags():
+    job = Job.from_dict(
+        {
+            "job_id": "job-1",
+            "job_key": "job-key-123",
+            "state": "running",
+            "gpu_type": "l40s",
+            "gpu_count": 1,
+            "region": "oh",
+            "interruptible": True,
+            "price_per_hour": 1.2,
+            "price_per_second": 0.0003,
+            "docker_image": "nvidia/cuda",
+            "runtime": 120,
+            "tags": {"team": "ml"},
+        }
+    )
+
+    assert job.tags == {"team": "ml"}
+
+
+def test_jobs_list_sends_repeated_tag_filters():
+    http = DummyHTTP()
+    jobs = Jobs(http)
+
+    result = jobs.list(state="running", tags={"team": "ml", "env": "prod"})
+
+    assert result[0].tags == {"team": "ml", "env": "prod"}
+    assert http.calls[0] == (
+        "get",
+        "/api/jobs",
+        {"state": "running", "tag": ["team:ml", "env:prod"]},
+    )
+
+
+def test_jobs_create_includes_tags():
+    http = DummyHTTP()
+    jobs = Jobs(http)
+
+    result = jobs.create(
+        image="nvidia/cuda:12.0",
+        command="echo hi",
+        tags={"team": "ml", "env": "prod"},
+    )
+
+    assert result.tags == {"team": "ml", "env": "prod"}
+    assert http.calls[0][2]["tags"] == {"team": "ml", "env": "prod"}