"""OpenClaw driver contract: a scripted gateway peer, not upstream OpenClaw. The PyPI ``openclaw`` distribution ships a CLI binary rather than an importable gateway, so this peer enforces the frame contract documented in ``agenthub/adapters/openclaw.py``: ``connect.challenge`` -> ``connect`` req -> ``res``, then ``req``/``res`` calls with progress arriving as ``event`` frames. If the driver drifts away from that wire format, these tests fail. """ from __future__ import annotations import asyncio import json import threading from typing import Any import pytest try: # websockets >= 15 has the asyncio server; older releases do not from websockets.asyncio.server import serve as ws_serve except ImportError: # pragma: no cover - old websockets from websockets import serve as ws_serve # type: ignore[attr-defined,no-redef] from agenthub.adapters.base import AgentTarget, DriverError, Invocation from agenthub.adapters.openclaw import OpenClawDriver from tests.conftest import BASE, add_agent, task_status, wait_for DEFAULTS = {"models.list": {"res": {"models": []}}, "chat.abort": {"res": {"ok": True}}} class FakeGateway: """Minimal OpenClaw-style gateway: handshakes, then answers scripted methods.""" def __init__( self, *, replies: dict[str, Any] | None = None, challenge: bool = True, connect_ok: bool = True, connect_error: str = "unauthorized", ) -> None: self.replies = {**DEFAULTS, **(replies or {})} self.challenge = challenge self.connect_ok = connect_ok self.connect_error = connect_error self.requests: list[dict[str, Any]] = [] self._loop: asyncio.AbstractEventLoop | None = None self._ready = threading.Event() self._thread: threading.Thread | None = None self.port = 0 def __enter__(self) -> "FakeGateway": def run() -> None: self._loop = asyncio.new_event_loop() asyncio.set_event_loop(self._loop) self._loop.run_until_complete(self._serve()) self._loop.run_forever() self._thread = threading.Thread(target=run, daemon=True) self._thread.start() assert self._ready.wait(5), "fake gateway never bound" return self def __exit__(self, *exc: object) -> None: assert self._loop is not None and self._thread is not None self._loop.call_soon_threadsafe(self._loop.stop) self._thread.join(5) @property def url(self) -> str: return f"ws://127.0.0.1:{self.port}/" def calls(self, method: str) -> list[dict[str, Any]]: return [frame for frame in self.requests if frame.get("method") == method] async def _serve(self) -> None: server = await ws_serve(self._handle, "127.0.0.1", 0) self.port = server.sockets[0].getsockname()[1] self._ready.set() async def _handle(self, ws: Any) -> None: if self.challenge: await ws.send(json.dumps({"type": "event", "event": "connect.challenge", "payload": {"nonce": "n1"}})) try: async for raw in ws: frame = json.loads(raw) if not isinstance(frame, dict) or frame.get("type") != "req": continue method, request_id = frame.get("method"), frame.get("id") self.requests.append(frame) spec = {"res": {"protocol": 3}} if method == "connect" else self.replies.get(method, {}) if method == "connect" and not self.connect_ok: await ws.send( json.dumps({"type": "res", "id": request_id, "ok": False, "error": {"message": self.connect_error}}) ) continue for event in spec.get("events", []): await ws.send(json.dumps({"type": "event", "event": event["event"], "payload": event["payload"]})) if "res" in spec: await ws.send( json.dumps({"type": "res", "id": request_id, "ok": True, "payload": spec["res"]}) ) except Exception: # the client hangs up mid-script, which is the point pass def target(url: str, **config: Any) -> AgentTarget: return AgentTarget( id="agt_oc", name="claw", driver="openclaw", base_url=url, auth={"type": "token", "token": "tok-1"}, config=dict(config), ) async def ask(driver: OpenClawDriver, where: AgentTarget, prompt: str = "ship it"): events: list[tuple[str, dict]] = [] async def emit(kind: str, payload: dict) -> None: events.append((kind, payload)) invocation = Invocation(task_id="task-1", prompt=prompt, target=where, session_key="run-9") try: return await driver.invoke(invocation, emit), events finally: await driver.close() def test_handshake_answers_the_challenge_with_the_gateway_token(): with FakeGateway() as gateway: driver = OpenClawDriver() health = asyncio.run(driver.probe(target(gateway.url))) assert health["ok"] is True and health["runtime"] == "openclaw" connect = gateway.calls("connect")[0]["params"] assert connect["auth"]["token"] == "tok-1" assert connect["minProtocol"] == connect["maxProtocol"] == 3 assert connect["client"]["id"] == "agenthub" # probe kept the session alive long enough to try a real call assert gateway.calls("models.list") def test_describe_reports_the_models_the_gateway_lists(): script = {"models.list": {"res": {"models": [{"id": "claw-1"}, {"id": "claw-2"}, {"nope": 1}]}}} with FakeGateway(replies=script) as gateway: capabilities = asyncio.run(OpenClawDriver().describe(target(gateway.url))) assert capabilities["models"] == ["claw-1", "claw-2"] assert capabilities["streaming"] is True def test_invoke_forwards_agent_events_then_keeps_the_streamed_answer(): script = { "chat.send": { "events": [ {"event": "agent", "payload": {"stream": "lifecycle", "data": {"phase": "start"}}}, {"event": "agent", "payload": {"stream": "assistant", "data": {"delta": "hel"}}}, {"event": "agent", "payload": {"stream": "tool", "data": {"name": "shell"}}}, {"event": "agent", "payload": {"stream": "assistant", "data": {"delta": "lo"}}}, ], "res": {}, } } with FakeGateway(replies=script) as gateway: result, events = asyncio.run(ask(OpenClawDriver(), target(gateway.url, session_key="svc:42"))) assert result.text == "hello" assert result.meta == {"runtime": "openclaw", "session_key": "svc:42"} assert [kind for kind, _ in events] == ["status", "status", "delta", "tool", "delta"] sent = gateway.calls("chat.send")[0]["params"] assert sent == {"sessionKey": "svc:42", "message": "ship it", "idempotencyKey": sent["idempotencyKey"]} def test_a_final_chat_event_can_carry_the_answer_without_a_response_frame(): script = { "chat.send": { "events": [ { "event": "chat", "payload": {"state": "final", "message": {"content": [{"text": "from "}, {"text": "chat"}]}}, } ] } } with FakeGateway(replies=script) as gateway: result, events = asyncio.run(ask(OpenClawDriver(), target(gateway.url))) assert result.text == "from chat" assert [kind for kind, _ in events] == ["status", "delta"] def test_error_states_fail_the_task_with_the_gateway_message(): for event, payload, needle in ( ("chat", {"state": "error", "message": "quota exceeded"}, "quota exceeded"), ("agent", {"stream": "lifecycle", "data": {"phase": "error", "error": "boom"}}, "boom"), ): with FakeGateway(replies={"chat.send": {"events": [{"event": event, "payload": payload}]}}) as gateway: with pytest.raises(DriverError) as excinfo: asyncio.run(ask(OpenClawDriver(), target(gateway.url))) assert needle in str(excinfo.value) def test_a_closed_port_is_retryable_but_a_rejected_handshake_is_not(): with pytest.raises(DriverError) as unreachable: asyncio.run(OpenClawDriver().probe(target("ws://127.0.0.1:1/"))) assert unreachable.value.retryable is True assert "cannot reach OpenClaw gateway" in str(unreachable.value) with FakeGateway(connect_ok=False, connect_error="bad token") as gateway: with pytest.raises(DriverError) as rejected: asyncio.run(OpenClawDriver().probe(target(gateway.url))) # Presence must read this as degraded (config is wrong), not offline (host gone). assert rejected.value.retryable is False assert "bad token" in str(rejected.value) def test_cancel_aborts_the_invocation_the_hub_named(): with FakeGateway() as gateway: ok = asyncio.run(OpenClawDriver().cancel(target(gateway.url), "inv-9")) assert ok is True assert gateway.calls("chat.abort")[0]["params"] == {"idempotencyKey": "inv-9"} assert asyncio.run(OpenClawDriver().cancel(target("ws://127.0.0.1:1/"), "inv-9")) is False def test_an_openclaw_agent_serves_a_real_hub_task(hub): client = hub # The gateway answers chat.send with a res frame, which is the tersest # shape an actual OpenClaw build uses when it does not stream. with FakeGateway(replies={"chat.send": {"res": {"text": "hello claw"}}}) as gateway: agent = add_agent( client, "claw-1", driver="openclaw", base_url=gateway.url, deployment_kind="cloud", auth={"type": "token", "token": "tok-1"}, config={"session_key": "hub:1"}, ) task = client.post(f"{BASE}/tasks", json={"prompt": "hello claw", "agent_id": agent["id"]}).json() wait_for(lambda: task_status(client, task["id"]) in ("completed", "failed")) detail = client.get(f"{BASE}/tasks/{task['id']}").json() assert detail["status"] == "completed", detail.get("error") assert detail["result"] == "hello claw" assert gateway.calls("chat.send")[0]["params"]["sessionKey"] == "hub:1" streamed = client.get(f"{BASE}/tasks/{task['id']}/events").json() assert [row["kind"] for row in streamed].count("completed") == 1