hypercli-sdk 2026.4.22__tar.gz → 2026.5.5__tar.gz

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypercli-sdk
-Version: 2026.4.22
+Version: 2026.5.5
 Summary: Python SDK for HyperCLI - GPU orchestration and HyperAgent API
 Project-URL: Homepage, https://hypercli.com
 Project-URL: Documentation, https://docs.hypercli.com
@@ -120,6 +120,7 @@ from openai import OpenAI
 
 sdk = HyperCLI(api_key="hyper_api_key", agent_api_key="sk-agent")
 plans = sdk.agent.plans()
+activation = sdk.agent.redeem_grant_code("PROMO123")
 
 client = OpenAI(
     api_key="your_hyperagent_api_key",
@@ -132,6 +133,8 @@ response = client.chat.completions.create(
 )
 ```
 
+`redeem_grant_code()` applies a promo/activation code to the current HyperClaw account and returns the created entitlement.
+
 ## OpenClaw Agents
 
 OpenClaw uses the generic deployment launch surface. `registry_url`, `registry_auth`, `sync_root`, and `sync_enabled` are generic deployment options; the OpenClaw helpers only add defaults such as routes, image, and `sync_root=/home/node`.

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/README.md

@@ -89,6 +89,7 @@ from openai import OpenAI
 
 sdk = HyperCLI(api_key="hyper_api_key", agent_api_key="sk-agent")
 plans = sdk.agent.plans()
+activation = sdk.agent.redeem_grant_code("PROMO123")
 
 client = OpenAI(
     api_key="your_hyperagent_api_key",
@@ -101,6 +102,8 @@ response = client.chat.completions.create(
 )
 ```
 
+`redeem_grant_code()` applies a promo/activation code to the current HyperClaw account and returns the created entitlement.
+
 ## OpenClaw Agents
 
 OpenClaw uses the generic deployment launch surface. `registry_url`, `registry_auth`, `sync_root`, and `sync_enabled` are generic deployment options; the OpenClaw helpers only add defaults such as routes, image, and `sync_root=/home/node`.

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/hypercli/__init__.py

@@ -78,7 +78,7 @@ from .gateway import (
     extract_gateway_chat_tool_calls,
     normalize_gateway_chat_message,
 )
-__version__ = "2026.4.22"
+__version__ = "2026.5.5"
 __all__ = [
     "HyperCLI",
     "configure",

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/hypercli/agent.py

@@ -911,6 +911,15 @@ class HyperAgent:
         response.raise_for_status()
         return response.json()
 
+    def redeem_grant_code(self, code: str) -> Dict[str, Any]:
+        response = self._http._session.post(
+            f"{self._control_base_url}/billing/grants/redeem",
+            headers={"Authorization": f"Bearer {self._api_key}"},
+            json={"code": str(code)},
+        )
+        response.raise_for_status()
+        return response.json()
+
     def purchase_via_x402(
         self,
         plan_id: str,

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/hypercli/agents.py

@@ -296,6 +296,18 @@ def _agent_kwargs_from_dict(data: dict) -> dict[str, Any]:
     }
 
 
+def _is_openclaw_agent_data(data: dict) -> bool:
+    routes = data.get("routes")
+    if isinstance(routes, dict) and routes.get("openclaw"):
+        return True
+    launch_config = data.get("launch_config")
+    if isinstance(launch_config, dict):
+        launch_routes = launch_config.get("routes")
+        if isinstance(launch_routes, dict) and launch_routes.get("openclaw"):
+            return True
+    return False
+
+
 @dataclass
 class Agent:
     """Generic agent returned by the HyperClaw backend."""
@@ -428,20 +440,20 @@ class Agent:
     def health(self) -> dict:
         return self._require_deployments().health(self)
 
-    def files_list(self, path: str = "") -> list[dict]:
-        return self._require_deployments().files_list(self, path)
+    def files_list(self, path: str = "", source: str = "auto") -> list[dict]:
+        return self._require_deployments().files_list(self, path, source=source)
 
-    def file_read_bytes(self, path: str) -> bytes:
-        return self._require_deployments().file_read_bytes(self, path)
+    def file_read_bytes(self, path: str, source: str = "auto") -> bytes:
+        return self._require_deployments().file_read_bytes(self, path, source=source)
 
-    def file_read(self, path: str) -> str:
-        return self._require_deployments().file_read(self, path)
+    def file_read(self, path: str, source: str = "auto") -> str:
+        return self._require_deployments().file_read(self, path, source=source)
 
-    def file_write_bytes(self, path: str, content: bytes) -> dict:
-        return self._require_deployments().file_write_bytes(self, path, content)
+    def file_write_bytes(self, path: str, content: bytes, destination: str = "auto") -> dict:
+        return self._require_deployments().file_write_bytes(self, path, content, destination=destination)
 
-    def file_write(self, path: str, content: str) -> dict:
-        return self._require_deployments().file_write(self, path, content)
+    def file_write(self, path: str, content: str, destination: str = "auto") -> dict:
+        return self._require_deployments().file_write(self, path, content, destination=destination)
 
     def file_delete(self, path: str, recursive: bool = False) -> dict:
         return self._require_deployments().file_delete(self, path, recursive)
@@ -473,32 +485,85 @@ class OpenClawAgent(Agent):
     def from_dict(cls, data: dict) -> "OpenClawAgent":
         return cls(
             **_agent_kwargs_from_dict(data),
-            gateway_url=(
-                data.get("openclaw_url")
-                or data.get("gateway_url")
-                or (f"wss://{data['hostname']}" if data.get("hostname") else None)
-            ),
+            gateway_url=None,
             gateway_token=data.get("gateway_token"),
         )
 
+    @staticmethod
+    def _gateway_url_from_hostname(hostname: str | None) -> str | None:
+        value = str(hostname or "").strip()
+        return f"wss://{value}" if value else None
+
+    def _current_gateway_hostname(self) -> str | None:
+        if self.hostname:
+            return self.hostname
+        if not self.gateway_url:
+            return None
+        raw = str(self.gateway_url).strip().replace("wss://", "").replace("ws://", "")
+        return raw.split("/", 1)[0] or None
+
+    def wait_for_gateway_context(self, timeout: float = 30.0, retry_interval: float = 1.0) -> dict[str, Any]:
+        """
+        Resolve gateway context through the deployment record plus `/env`.
+
+        Agent startup is eventually consistent: the deployment record can lag
+        behind hostname attachment, and runtime env can lag behind both. The
+        SDK derives the gateway URL from the attached hostname and reads the
+        gateway token from `OPENCLAW_GATEWAY_TOKEN` in the env route.
+        """
+        if self.gateway_token and self.gateway_url:
+            return {
+                "agent_id": self.id,
+                "hostname": self._current_gateway_hostname(),
+                "gateway_token": self.gateway_token,
+            }
+        deadline = time.monotonic() + timeout
+        last_error: Exception | None = None
+        while True:
+            try:
+                refreshed = self._require_deployments().get(self.id)
+                hostname = getattr(refreshed, "hostname", None)
+                gateway_url = self._gateway_url_from_hostname(hostname)
+                env_data = self._require_deployments().env(self.id)
+                gateway_token = (
+                    (env_data.get("env") or {}).get("OPENCLAW_GATEWAY_TOKEN", "").strip()
+                    if isinstance(env_data, dict)
+                    else None
+                )
+                if gateway_token and gateway_url:
+                    self.gateway_token = gateway_token
+                    self.gateway_url = gateway_url
+                    return {
+                        "agent_id": self.id,
+                        "hostname": hostname,
+                        "gateway_token": gateway_token,
+                    }
+                last_error = RuntimeError("missing gateway context")
+            except Exception as exc:
+                last_error = exc
+            if time.monotonic() >= deadline:
+                if last_error is not None:
+                    raise last_error
+                raise RuntimeError("Timed out waiting for OpenClaw gateway context")
+            time.sleep(retry_interval)
+
     def resolve_gateway_token(self) -> str | None:
-        """Resolve the gateway token. Fetches from pod env if not set locally."""
-        if self.gateway_token:
-            return self.gateway_token
-        token_data = self._require_deployments().inference_token(self.id)
+        """Resolve the gateway token through the deployment env route."""
+        token_data = self.wait_for_gateway_context()
         self.gateway_token = token_data.get("gateway_token")
-        self.gateway_url = token_data.get("openclaw_url") or self.gateway_url
         return self.gateway_token
 
     def gateway(self, **kwargs) -> "GatewayClient":
         """Create a GatewayClient for this OpenClaw agent."""
         from .gateway import GatewayClient
+        if not self.gateway_url:
+            self.wait_for_gateway_context()
         if not self.gateway_url:
             raise ValueError("Agent has no OpenClaw gateway URL")
         deployments = self._require_deployments()
         if "gateway_token" not in kwargs:
             if not self.gateway_token:
-                self.resolve_gateway_token()
+                self.wait_for_gateway_context()
             if self.gateway_token:
                 kwargs["gateway_token"] = self.gateway_token
         kwargs.setdefault("deployment_id", self.id)
@@ -531,6 +596,8 @@ class OpenClawAgent(Agent):
         probe: str = "config",
         **kwargs,
     ) -> dict:
+        if not self.gateway_url or ("gateway_token" not in kwargs and not self.gateway_token):
+            self.wait_for_gateway_context()
         gw = self.gateway(**kwargs)
         try:
             return await gw.wait_ready(timeout=timeout, retry_interval=retry_interval, probe=probe)
@@ -933,7 +1000,7 @@ class Deployments:
         )
 
     def _hydrate_agent(self, data: dict) -> Agent:
-        if data.get("openclaw_url") or data.get("gateway_url"):
+        if _is_openclaw_agent_data(data):
             agent = OpenClawAgent.from_dict(data)
         else:
             agent = Agent.from_dict(data)
@@ -1342,10 +1409,6 @@ class Deployments:
         """
         return self._get(f"{AGENTS_API_PREFIX}/{agent_id}/token")
 
-    def inference_token(self, agent_id: str) -> dict:
-        """Fetch the scoped OpenClaw gateway token for an agent."""
-        return self._get(f"{AGENTS_API_PREFIX}/{agent_id}/inference/token")
-
     def create_scoped_key(self, agent_id: str, name: str | None = None) -> dict:
         payload = {"name": name} if name is not None else {}
         return self._post(f"{AGENTS_API_PREFIX}/{agent_id}/keys", json=payload or None)
@@ -1422,7 +1485,7 @@ class Deployments:
             raise APIError(resp.status_code, resp.text)
         return resp.json()
 
-    def files_list(self, pod: Agent | str, path: str = "") -> list[dict]:
+    def files_list(self, pod: Agent | str, path: str = "", source: str = "auto") -> list[dict]:
         """List files on an agent via the backend file API."""
         agent_id = self._agent_id_for_target(pod)
         with httpx.Client(timeout=10) as client:
@@ -1431,19 +1494,21 @@ class Deployments:
                 if path
                 else f"{self._api_base}{AGENTS_API_PREFIX}/{agent_id}/files",
                 headers=self._file_headers(),
+                params={"source": source},
             )
         if resp.status_code >= 400:
             raise APIError(resp.status_code, resp.text)
         payload = resp.json()
         return [*(payload.get("directories") or []), *(payload.get("files") or [])]
 
-    def file_read_bytes(self, pod: Agent | str, path: str) -> bytes:
+    def file_read_bytes(self, pod: Agent | str, path: str, source: str = "auto") -> bytes:
         """Read a file from an agent via the backend file API."""
         agent_id = self._agent_id_for_target(pod)
         with httpx.Client(timeout=10) as client:
             resp = client.get(
                 f"{self._api_base}{AGENTS_API_PREFIX}/{agent_id}/files/{self._encode_file_path(path)}",
                 headers=self._file_headers(),
+                params={"source": source},
             )
         if resp.status_code >= 400:
             raise APIError(resp.status_code, resp.text)
@@ -1457,26 +1522,27 @@ class Deployments:
                 raise ValueError(f"Path is a directory: {path}. Use files_list(path) instead.")
         return resp.content
 
-    def file_read(self, pod: Agent | str, path: str) -> str:
+    def file_read(self, pod: Agent | str, path: str, source: str = "auto") -> str:
         """Read a UTF-8 text file from an agent."""
-        return self.file_read_bytes(pod, path).decode(errors="replace")
+        return self.file_read_bytes(pod, path, source=source).decode(errors="replace")
 
-    def file_write_bytes(self, pod: Agent | str, path: str, content: bytes) -> dict:
+    def file_write_bytes(self, pod: Agent | str, path: str, content: bytes, destination: str = "auto") -> dict:
         """Write raw bytes to an agent via the backend file API."""
         agent_id = self._agent_id_for_target(pod)
         with httpx.Client(timeout=10) as client:
-            resp = client.put(
+            resp = client.post(
                 f"{self._api_base}{AGENTS_API_PREFIX}/{agent_id}/files/{self._encode_file_path(path)}",
                 headers=self._file_headers(content_type="application/octet-stream"),
+                params={"destination": destination},
                 content=content,
             )
         if resp.status_code >= 400:
             raise APIError(resp.status_code, resp.text)
         return resp.json()
 
-    def file_write(self, pod: Agent | str, path: str, content: str) -> dict:
+    def file_write(self, pod: Agent | str, path: str, content: str, destination: str = "auto") -> dict:
         """Write a UTF-8 text file to an agent."""
-        return self.file_write_bytes(pod, path, content.encode())
+        return self.file_write_bytes(pod, path, content.encode(), destination=destination)
 
     def file_delete(self, pod: Agent | str, path: str, recursive: bool = False) -> dict:
         """Delete a file or directory from an agent."""

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/hypercli/openclaw/gateway.py

@@ -71,6 +71,9 @@ def _storage_scope_key(scope: str, role: str) -> str:
     return f"{scope.strip()}|{role.strip()}"
 
 
+GatewayConnectionState = Literal["disconnected", "connecting", "connected"]
+
+
 @dataclass
 class DeviceTokenEntry:
     token: str
@@ -763,8 +766,10 @@ class GatewayClient:
         self._pending: dict[str, asyncio.Future] = {}
         self._event_queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
         self._event_handlers: set[Callable[[dict[str, Any]], None]] = set()
+        self._connection_state_handlers: set[Callable[[GatewayConnectionState], None]] = set()
         self._reader_task: asyncio.Task | None = None
         self._connected = False
+        self._connection_state: GatewayConnectionState = "disconnected"
         self._closed = False
         self._version: str | None = None
         self._protocol: int | None = None
@@ -784,10 +789,28 @@ class GatewayClient:
     def is_connected(self) -> bool:
         return self._connected
 
+    @property
+    def connection_state(self) -> GatewayConnectionState:
+        return self._connection_state
+
     @property
     def pending_pairing(self) -> GatewayPairingState | None:
         return self._pending_pairing
 
+    def on_connection_state(self, handler: Callable[[GatewayConnectionState], None]) -> Callable[[], None]:
+        self._connection_state_handlers.add(handler)
+        return lambda: self._connection_state_handlers.discard(handler)
+
+    def _set_connection_state(self, state: GatewayConnectionState) -> None:
+        if self._connection_state == state:
+            return
+        self._connection_state = state
+        for handler in list(self._connection_state_handlers):
+            try:
+                handler(state)
+            except Exception:
+                pass
+
     def set_gateway_token(self, token: str | None) -> None:
         self.gateway_token = token.strip() if isinstance(token, str) and token.strip() else None
 
@@ -870,6 +893,7 @@ class GatewayClient:
             )
         finally:
             self._connected = False
+            self._set_connection_state("disconnected")
             self._ws = None
             close_error = close_info.error if close_info and close_info.error else GatewayError(
                 "UNAVAILABLE",
@@ -1002,6 +1026,7 @@ class GatewayClient:
         self._closed = False
         if self._connected:
             return
+        self._set_connection_state("connecting")
 
         delay = INITIAL_RECONNECT_DELAY
         deadline = asyncio.get_running_loop().time() + max(self.timeout, 30.0)
@@ -1026,6 +1051,7 @@ class GatewayClient:
                 self._version = hello.get("server", {}).get("version") or hello.get("version")
                 self._protocol = hello.get("protocol")
                 self._connected = True
+                self._set_connection_state("connected")
                 self._update_pairing_state(None)
                 self._last_seq = None
                 self._reader_task = asyncio.create_task(self._reader_loop())
@@ -1142,6 +1168,7 @@ class GatewayClient:
     async def close(self) -> None:
         self._closed = True
         self._connected = False
+        self._set_connection_state("disconnected")
         reader = self._reader_task
         self._reader_task = None
         if reader:

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/pyproject.toml

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

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/tests/test_agents.py

@@ -97,7 +97,6 @@ def test_openclaw_agent_from_dict():
             "pod_name": "test-pod",
             "state": "running",
             "hostname": "test.hypercli.com",
-            "openclaw_url": "wss://openclaw-test.hypercli.com",
             "gateway_token": "gw123",
             "jwt_token": "jwt123",
             "jwt_expires_at": "2026-03-01T12:00:00Z",
@@ -111,7 +110,7 @@ def test_openclaw_agent_from_dict():
         }
     )
 
-    assert agent.gateway_url == "wss://openclaw-test.hypercli.com"
+    assert agent.gateway_url is None
     assert agent.gateway_token == "gw123"
     assert agent.jwt_token == "jwt123"
     assert isinstance(agent.jwt_expires_at, datetime)
@@ -122,7 +121,7 @@ def test_openclaw_agent_from_dict():
     assert agent.entrypoint == ["/bin/sh", "-c"]
 
 
-def test_openclaw_agent_from_dict_falls_back_to_root_gateway_host():
+def test_openclaw_agent_from_dict_does_not_guess_gateway_url_from_hostname():
     agent = OpenClawAgent.from_dict(
         {
             "id": "agent-123",
@@ -134,7 +133,7 @@ def test_openclaw_agent_from_dict_falls_back_to_root_gateway_host():
         }
     )
 
-    assert agent.gateway_url == "wss://test.hypercli.com"
+    assert agent.gateway_url is None
 
 
 def test_openclaw_agent_gateway_requires_url():
@@ -145,7 +144,7 @@ def test_openclaw_agent_gateway_requires_url():
         pod_name="test-pod",
         state="running",
     )
-    with pytest.raises(ValueError, match="OpenClaw gateway URL"):
+    with pytest.raises(ValueError, match="Deployments client"):
         agent.gateway()
 
 def test_openclaw_agent_gateway_allows_jwtless_when_route_auth_disabled():
@@ -196,6 +195,39 @@ def test_openclaw_agent_gateway_ignores_jwt_and_uses_bound_tokens():
     assert gw.api_base == "https://api.test.hypercli.com"
 
 
+def test_openclaw_agent_wait_running_still_delegates_to_deployments():
+    manager = Mock()
+    ready = OpenClawAgent(
+        id="agent-123",
+        user_id="user-456",
+        pod_id="pod-ready",
+        pod_name="ready-pod",
+        state="running",
+        hostname="ready.hypercli.com",
+    )
+    ready._deployments = manager
+    manager.wait_running.return_value = ready
+
+    agent = OpenClawAgent(
+        id="agent-123",
+        user_id="user-456",
+        pod_id="pod-pending",
+        pod_name="pending-pod",
+        state="starting",
+        hostname="ready.hypercli.com",
+        _deployments=manager,
+    )
+    agent.wait_for_gateway_context = Mock(side_effect=AssertionError("wait_for_gateway_context should not be used by wait_running"))
+
+    result = agent.wait_running(timeout=42, poll_interval=1.5)
+
+    manager.wait_running.assert_called_once_with("agent-123", timeout=42, poll_interval=1.5)
+    agent.wait_for_gateway_context.assert_not_called()
+    assert result is agent
+    assert agent.state == "running"
+    assert agent.pod_id == "pod-ready"
+
+
 def test_agent_wait_running_delegates_to_deployments():
     manager = Mock()
     ready = Agent(
@@ -466,7 +498,8 @@ def test_create_openclaw_defaults_routes_when_omitted(agents_client):
             "pod_id": "pod-789",
             "pod_name": "test-pod",
             "state": "starting",
-            "openclaw_url": "wss://test.hypercli.com",
+            "hostname": "test.hypercli.com",
+            "routes": {"openclaw": {"port": 18789, "auth": False, "prefix": ""}},
         }
         mock_client.post.return_value = mock_response
         mock_client.__enter__.return_value = mock_client
@@ -560,7 +593,8 @@ def test_agents_create_returns_openclaw_agent(agents_client):
             "state": "starting",
             "cpu": 2,
             "memory": 8,
-            "openclaw_url": "wss://openclaw-test.hypercli.com",
+            "hostname": "openclaw-test.hypercli.com",
+            "routes": {"openclaw": {"port": 18789, "auth": False, "prefix": ""}},
         }
         mock_client.post.return_value = mock_response
         mock_client.__enter__.return_value = mock_client
@@ -606,7 +640,7 @@ def test_agents_create_returns_openclaw_agent(agents_client):
         assert posted_json["registry_auth"] == {"username": "u", "password": "p"}
         assert isinstance(agent, OpenClawAgent)
         assert agent.gateway_token == "gw-token-123"
-        assert agent.gateway_url == "wss://openclaw-test.hypercli.com"
+        assert agent.gateway_url is None
         assert agent.meta_ui is None
         assert agent._deployments is agents_client
 
@@ -622,7 +656,8 @@ def test_create_openclaw_defaults_sync_root(agents_client):
             "pod_id": "pod-789",
             "pod_name": "test-pod",
             "state": "starting",
-            "openclaw_url": "wss://openclaw-test.hypercli.com",
+            "hostname": "openclaw-test.hypercli.com",
+            "routes": {"openclaw": {"port": 18789, "auth": False, "prefix": ""}},
         }
         mock_client.post.return_value = mock_response
         mock_client.__enter__.return_value = mock_client
@@ -648,7 +683,8 @@ def test_start_openclaw_defaults_sync_root(agents_client):
             "pod_id": "pod-789",
             "pod_name": "test-pod",
             "state": "starting",
-            "openclaw_url": "wss://openclaw-test.hypercli.com",
+            "hostname": "openclaw-test.hypercli.com",
+            "routes": {"openclaw": {"port": 18789, "auth": False, "prefix": ""}},
         }
         mock_client.post.return_value = mock_response
         mock_client.__enter__.return_value = mock_client
@@ -711,14 +747,16 @@ def test_agents_file_ops_use_backend_file_api(agents_client):
 
         def get(self, url, headers=None, params=None, follow_redirects=None):
             if url.endswith("/deployments/agent-123/files"):
-                assert params is None
+                assert params == {"source": "auto"}
                 return FakeResponse(json_data={"directories": [{"name": "dir", "type": "directory"}], "files": [{"name": "a.txt", "type": "file"}]})
             if url.endswith("/deployments/agent-123/files/workspace"):
-                assert params is None
+                assert params == {"source": "auto"}
                 return FakeResponse(json_data={"directories": [{"name": "dir", "type": "directory"}], "files": [{"name": "a.txt", "type": "file"}]})
             if url.endswith("/deployments/agent-123/files/workspace/a.txt"):
+                assert params == {"source": "auto"}
                 return FakeResponse(content=b"hello")
             if url.endswith("/deployments/agent-123/files/.openclaw"):
+                assert params == {"source": "auto"}
                 return FakeResponse(
                     json_data={
                         "type": "directory",
@@ -731,8 +769,9 @@ def test_agents_file_ops_use_backend_file_api(agents_client):
                 )
             raise AssertionError(url)
 
-        def put(self, url, headers=None, content=None):
+        def post(self, url, headers=None, params=None, content=None):
             assert url.endswith("/deployments/agent-123/files/workspace/a.txt")
+            assert params == {"destination": "auto"}
             assert content == b"payload"
             return FakeResponse(json_data={"status": "ok"})
 
@@ -802,7 +841,8 @@ def test_agents_start_stop_delete(agents_client):
             "pod_id": "pod-789",
             "pod_name": "test-pod",
             "state": "starting",
-            "openclaw_url": "wss://openclaw-test.hypercli.com",
+            "hostname": "openclaw-test.hypercli.com",
+            "routes": {"openclaw": {"port": 18789, "auth": False, "prefix": ""}},
         }
         mock_client.post.return_value = mock_response
         mock_client.__enter__.return_value = mock_client
@@ -990,27 +1030,6 @@ def test_agents_refresh_token(agents_client):
         assert result["token"] == "jwt-new-token"
 
 
-def test_agents_inference_token(agents_client):
-    with patch("httpx.Client") as mock_client_class:
-        mock_client = MagicMock()
-        mock_response = Mock()
-        mock_response.status_code = 200
-        mock_response.json.return_value = {
-            "agent_id": "agent-123",
-            "openclaw_url": "wss://openclaw-test.hypercli.com",
-            "gateway_token": "gw-inference",
-        }
-        mock_client.get.return_value = mock_response
-        mock_client.__enter__.return_value = mock_client
-        mock_client.__exit__.return_value = False
-        mock_client_class.return_value = mock_client
-
-        result = agents_client.inference_token("agent-123")
-
-        assert result["gateway_token"] == "gw-inference"
-        assert mock_client.get.call_args[0][0].endswith("/deployments/agent-123/inference/token")
-
-
 def test_agents_create_scoped_key(agents_client):
     with patch("httpx.Client") as mock_client_class:
         mock_client = MagicMock()
@@ -1076,12 +1095,18 @@ def test_agents_redeem_grant_code(agents_client):
         assert mock_client.post.call_args[1]["json"] == {"code": "promo-123"}
 
 
-def test_openclaw_agent_resolve_gateway_token_uses_inference_endpoint():
+def test_openclaw_agent_resolve_gateway_token_uses_env_route():
     manager = Mock()
-    manager.inference_token.return_value = {
-        "openclaw_url": "wss://openclaw-test.hypercli.com",
-        "gateway_token": "gw-fetched",
-    }
+    manager.get.return_value = OpenClawAgent.from_dict({
+        "id": "agent-123",
+        "user_id": "user-456",
+        "pod_id": "pod-789",
+        "pod_name": "test-pod",
+        "state": "running",
+        "hostname": "openclaw-test.hypercli.com",
+        "routes": {"openclaw": {"port": 18789, "auth": False}},
+    })
+    manager.env.return_value = {"env": {"OPENCLAW_GATEWAY_TOKEN": "gw-fetched"}}
     agent = OpenClawAgent(
         id="agent-123",
         user_id="user-456",
@@ -1096,7 +1121,87 @@ def test_openclaw_agent_resolve_gateway_token_uses_inference_endpoint():
     assert token == "gw-fetched"
     assert agent.gateway_token == "gw-fetched"
     assert agent.gateway_url == "wss://openclaw-test.hypercli.com"
-    manager.inference_token.assert_called_once_with("agent-123")
+    manager.get.assert_called_once_with("agent-123")
+    manager.env.assert_called_once_with("agent-123")
+
+
+def test_openclaw_agent_wait_for_gateway_context_retries_until_ready(monkeypatch):
+    manager = Mock()
+    manager.get.side_effect = [
+        OpenClawAgent.from_dict({
+            "id": "agent-123",
+            "user_id": "user-456",
+            "pod_id": "pod-789",
+            "pod_name": "test-pod",
+            "state": "running",
+            "hostname": None,
+            "routes": {"openclaw": {"port": 18789, "auth": False}},
+        }),
+        OpenClawAgent.from_dict({
+            "id": "agent-123",
+            "user_id": "user-456",
+            "pod_id": "pod-789",
+            "pod_name": "test-pod",
+            "state": "running",
+            "hostname": "openclaw-test.hypercli.com",
+            "routes": {"openclaw": {"port": 18789, "auth": False}},
+        }),
+    ]
+    manager.env.side_effect = [
+        {"env": {"OPENCLAW_GATEWAY_TOKEN": "gw-fetched"}},
+        {"env": {"OPENCLAW_GATEWAY_TOKEN": "gw-fetched"}},
+    ]
+    agent = OpenClawAgent(
+        id="agent-123",
+        user_id="user-456",
+        pod_id="pod-789",
+        pod_name="test-pod",
+        state="running",
+        _deployments=manager,
+    )
+    monkeypatch.setattr("hypercli.agents.time.sleep", lambda _seconds: None)
+
+    context = agent.wait_for_gateway_context(timeout=0.1, retry_interval=0)
+
+    assert context["gateway_token"] == "gw-fetched"
+    assert context["hostname"] == "openclaw-test.hypercli.com"
+    assert agent.gateway_token == "gw-fetched"
+    assert agent.gateway_url == "wss://openclaw-test.hypercli.com"
+    assert manager.get.call_count == 2
+    assert manager.env.call_count == 2
+
+
+def test_openclaw_agent_gateway_resolves_missing_url_via_env_route():
+    manager = Mock()
+    manager._api_key = "sk-hyper-test123"
+    manager._api_base = "https://api.test.hypercli.com"
+    manager.get.return_value = OpenClawAgent.from_dict({
+        "id": "agent-123",
+        "user_id": "user-456",
+        "pod_id": "pod-789",
+        "pod_name": "test-pod",
+        "state": "running",
+        "hostname": "openclaw-test.hypercli.com",
+        "routes": {"openclaw": {"port": 18789, "auth": False}},
+    })
+    manager.env.return_value = {"env": {"OPENCLAW_GATEWAY_TOKEN": "gw-fetched"}}
+    agent = OpenClawAgent(
+        id="agent-123",
+        user_id="user-456",
+        pod_id="pod-789",
+        pod_name="test-pod",
+        state="running",
+        gateway_token="gw-inline",
+        _deployments=manager,
+    )
+
+    gw = agent.gateway()
+
+    assert gw.url == "wss://openclaw-test.hypercli.com"
+    assert agent.gateway_url == "wss://openclaw-test.hypercli.com"
+    assert agent.gateway_token == "gw-fetched"
+    manager.get.assert_called_once_with("agent-123")
+    manager.env.assert_called_once_with("agent-123")
 
 
 def test_agents_api_error(agents_client):

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/tests/test_claw.py

@@ -318,6 +318,23 @@ class TestHyperAgentClient:
             "https://api.hypercli.com/agents/subscriptions/sub-1/cancel",
             headers={"Authorization": "Bearer sk-hyper-test"},
         )
+
+    def test_redeem_grant_code(self, mock_http):
+        mock_http._session.post.return_value.json.return_value = {
+            "grant": {"id": "grant-1", "code": "promo-123"},
+            "entitlement": {"id": "ent-1", "plan_id": "basic"},
+        }
+        mock_http._session.post.return_value.raise_for_status = Mock()
+
+        agent = HyperAgent(mock_http, agent_api_key="sk-hyper-test", agents_api_base_url="https://api.hypercli.com/agents")
+        result = agent.redeem_grant_code("promo-123")
+
+        assert result["grant"]["code"] == "promo-123"
+        mock_http._session.post.assert_called_with(
+            "https://api.hypercli.com/agents/billing/grants/redeem",
+            headers={"Authorization": "Bearer sk-hyper-test"},
+            json={"code": "promo-123"},
+        )
     
     def test_openai_client_creation(self, mock_http):
         """Test that OpenAI client is created with correct config."""

{hypercli_sdk-2026.4.22 → hypercli_sdk-2026.5.5}/tests/test_gateway.py

@@ -36,6 +36,63 @@ class MockConnection:
         return await self.recv()
 
 
+
+
+@pytest.mark.asyncio
+async def test_connection_state_transitions(monkeypatch: pytest.MonkeyPatch) -> None:
+    sockets: list[MockConnection] = []
+
+    async def fake_connect(*args, **kwargs):
+        conn = MockConnection()
+        sockets.append(conn)
+        return conn
+
+    monkeypatch.setattr("hypercli.openclaw.gateway.websockets.connect", fake_connect)
+
+    client = GatewayClient(
+        url="wss://openclaw-agent.example",
+        token="jwt-token",
+        gateway_token="gw-token",
+    )
+    seen: list[str] = []
+    unsubscribe = client.on_connection_state(lambda state: seen.append(state))
+
+    connect_task = asyncio.create_task(client.connect())
+    assert client.connection_state == "connecting"
+
+    while not sockets:
+        await asyncio.sleep(0)
+
+    first = sockets[0]
+    first.push({"type": "event", "event": "connect.challenge", "payload": {"nonce": "nonce-1"}})
+    while not first.sent:
+        await asyncio.sleep(0)
+    connect_request = first.sent[0]
+    first.push({
+        "type": "res",
+        "id": connect_request["id"],
+        "ok": True,
+        "payload": {
+            "protocol": 3,
+            "server": {"version": "test"},
+            "auth": {
+                "deviceToken": "device-token-1",
+                "role": "operator",
+                "scopes": ["operator.admin"],
+            },
+        },
+    })
+
+    await connect_task
+    assert client.connection_state == "connected"
+
+    await client.close()
+    assert client.connection_state == "disconnected"
+    assert "connecting" in seen
+    assert "connected" in seen
+    assert "disconnected" in seen
+    unsubscribe()
+
 @pytest.mark.asyncio
 async def test_connect_auto_approves_pairing_and_reconnects(monkeypatch: pytest.MonkeyPatch) -> None:
     sockets: list[MockConnection] = []