agenthub/backend/tests/test_driver_openclaw.py

246 lines
10 KiB
Python

"""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