agent-relay 3.2.3 → 3.2.4

package/packages/sdk-py/tests/communicate/test_core.py

@@ -0,0 +1,331 @@
+"""Wave 1.3 tests for the communicate Relay core."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+from inspect import isawaitable
+
+import pytest
+
+from agent_relay.communicate.types import Message, RelayConfig
+
+
+def _core_module():
+    return importlib.import_module("agent_relay.communicate.core")
+
+
+async def _wait_for(predicate, timeout: float = 1.0) -> None:
+    deadline = asyncio.get_running_loop().time() + timeout
+    while asyncio.get_running_loop().time() < deadline:
+        if predicate():
+            return
+        await asyncio.sleep(0.01)
+    raise AssertionError("Timed out waiting for async condition.")
+
+
+@pytest.fixture
+def core_harness(monkeypatch):
+    core = _core_module()
+    registered_atexit: list[object] = []
+
+    class FakeTransport:
+        instances: list["FakeTransport"] = []
+
+        def __init__(self, agent_name: str, config: RelayConfig) -> None:
+            self.agent_name = agent_name
+            self.config = config
+            self.connect_count = 0
+            self.disconnect_count = 0
+            self.send_dm_calls: list[tuple[str, str]] = []
+            self.post_message_calls: list[tuple[str, str]] = []
+            self.reply_calls: list[tuple[str, str]] = []
+            self.list_agents_calls = 0
+            self.list_agents_result = ["Review-Core", "Impl-Core"]
+            self.ws_callback = None
+            self.connected = False
+            FakeTransport.instances.append(self)
+
+        async def connect(self) -> None:
+            self.connect_count += 1
+            await asyncio.sleep(0)
+            self.connected = True
+
+        async def disconnect(self) -> None:
+            self.disconnect_count += 1
+            self.connected = False
+
+        async def send_dm(self, to: str, text: str) -> str:
+            self.send_dm_calls.append((to, text))
+            return "message-send"
+
+        async def post_message(self, channel: str, text: str) -> str:
+            self.post_message_calls.append((channel, text))
+            return "message-post"
+
+        async def reply(self, message_id: str, text: str) -> str:
+            self.reply_calls.append((message_id, text))
+            return "message-reply"
+
+        async def list_agents(self) -> list[str]:
+            self.list_agents_calls += 1
+            return list(self.list_agents_result)
+
+        def on_ws_message(self, callback) -> None:
+            self.ws_callback = callback
+
+        async def emit_message(self, message: Message) -> None:
+            if self.ws_callback is None:
+                raise AssertionError("Relay did not register a transport WS callback.")
+            result = self.ws_callback(message)
+            if isawaitable(result):
+                await result
+
+    monkeypatch.setattr(core, "RelayTransport", FakeTransport)
+    monkeypatch.setattr(core.atexit, "register", lambda callback: registered_atexit.append(callback))
+
+    return core, FakeTransport, registered_atexit
+
+
+def test_init_is_lazy_and_registers_atexit_cleanup(core_harness):
+    core, FakeTransport, registered_atexit = core_harness
+
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=True))
+
+    assert sum(transport.connect_count for transport in FakeTransport.instances) == 0
+    assert len(registered_atexit) == 1
+    assert getattr(registered_atexit[0], "__self__", None) is relay
+    assert getattr(registered_atexit[0], "__name__", None) == "close_sync"
+
+
+def test_init_skips_atexit_cleanup_when_disabled(core_harness):
+    core, _FakeTransport, registered_atexit = core_harness
+
+    core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+
+    assert registered_atexit == []
+
+
+@pytest.mark.asyncio
+async def test_send_lazy_connects_and_delegates_to_transport(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+
+    result = await relay.send("Impl-Core", "hello")
+
+    assert result is None
+    assert transport.connect_count == 1
+    assert transport.send_dm_calls == [("Impl-Core", "hello")]
+
+
+@pytest.mark.asyncio
+async def test_post_lazy_connects_and_delegates_to_transport(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+
+    result = await relay.post("core-py", "status update")
+
+    assert result is None
+    assert transport.connect_count == 1
+    assert transport.post_message_calls == [("core-py", "status update")]
+
+
+@pytest.mark.asyncio
+async def test_reply_lazy_connects_and_delegates_to_transport(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+
+    result = await relay.reply("message-123", "thread response")
+
+    assert result is None
+    assert transport.connect_count == 1
+    assert transport.reply_calls == [("message-123", "thread response")]
+
+
+@pytest.mark.asyncio
+async def test_inbox_drains_pending_buffer_and_does_not_poll_transport(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+    relay._pending.extend(
+        [
+            Message(sender="Review-Core", text="one", message_id="message-1"),
+            Message(sender="Impl-Core", text="two", message_id="message-2"),
+        ]
+    )
+
+    first = await relay.inbox()
+    second = await relay.inbox()
+
+    assert first == [
+        Message(sender="Review-Core", text="one", message_id="message-1"),
+        Message(sender="Impl-Core", text="two", message_id="message-2"),
+    ]
+    assert second == []
+    assert relay._pending == []
+    assert transport.connect_count == 1
+
+
+@pytest.mark.asyncio
+async def test_on_message_registers_callback_and_unsubscribe_restores_buffering(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+
+    received: list[Message] = []
+    unsubscribe = relay.on_message(lambda message: received.append(message))
+
+    await _wait_for(lambda: transport.connect_count == 1)
+
+    callback_message = Message(sender="Review-Core", text="callback", message_id="message-cb")
+    buffered_message = Message(sender="Impl-Core", text="buffered", message_id="message-buffer")
+
+    await transport.emit_message(callback_message)
+    unsubscribe()
+    await transport.emit_message(buffered_message)
+    inbox_messages = await relay.inbox()
+
+    assert received == [callback_message]
+    # "both" case: callback messages are also buffered per spec Section 5.3
+    assert inbox_messages == [callback_message, buffered_message]
+
+
+@pytest.mark.asyncio
+async def test_pending_buffer_caps_at_ten_thousand_and_drops_oldest_with_warning(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+
+    await relay.agents()
+
+    with pytest.warns(UserWarning, match="10,000|10000|buffer"):
+        for index in range(10_001):
+            await transport.emit_message(
+                Message(
+                    sender="Review-Core",
+                    text=f"message-{index}",
+                    message_id=f"message-{index}",
+                )
+            )
+
+    messages = await relay.inbox()
+
+    assert len(messages) == 10_000
+    assert messages[0].message_id == "message-1"
+    assert messages[-1].message_id == "message-10000"
+
+
+@pytest.mark.asyncio
+async def test_agents_returns_transport_agent_list(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+    transport.list_agents_result = ["Review-Core", "Impl-Core", "CoreTester"]
+
+    agents = await relay.agents()
+
+    assert agents == ["Review-Core", "Impl-Core", "CoreTester"]
+    assert transport.connect_count == 1
+    assert transport.list_agents_calls == 1
+
+
+@pytest.mark.asyncio
+async def test_close_disconnects_transport(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+
+    await relay.send("Impl-Core", "hello")
+    await relay.close()
+
+    assert transport.disconnect_count == 1
+
+
+def test_sync_wrappers_delegate_to_async_methods(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    transport = FakeTransport.instances[0]
+    relay._pending.append(Message(sender="Review-Core", text="sync inbox", message_id="message-sync"))
+    transport.list_agents_result = ["Review-Core", "Impl-Core"]
+
+    relay.send_sync("Impl-Core", "sync hello")
+    relay.post_sync("core-py", "sync update")
+    inbox_messages = relay.inbox_sync()
+    agents = relay.agents_sync()
+    relay.close_sync()
+
+    assert transport.send_dm_calls == [("Impl-Core", "sync hello")]
+    assert transport.post_message_calls == [("core-py", "sync update")]
+    assert inbox_messages == [Message(sender="Review-Core", text="sync inbox", message_id="message-sync")]
+    assert agents == ["Review-Core", "Impl-Core"]
+    assert transport.disconnect_count == 1
+
+
+@pytest.mark.asyncio
+async def test_async_context_manager_closes_transport_on_exit(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+
+    async with core.Relay("CoreTester", RelayConfig(auto_cleanup=False)) as relay:
+        await relay.send("Impl-Core", "inside context")
+        transport = FakeTransport.instances[0]
+        assert transport.connect_count == 1
+
+    assert transport.disconnect_count == 1
+
+
+@pytest.mark.asyncio
+async def test_concurrent_inbox_calls_do_not_lose_messages(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    relay = core.Relay("CoreTester", RelayConfig(auto_cleanup=False))
+    relay._pending.extend(
+        [
+            Message(sender="one", text="first", message_id="message-1"),
+            Message(sender="two", text="second", message_id="message-2"),
+            Message(sender="three", text="third", message_id="message-3"),
+        ]
+    )
+
+    results = await asyncio.gather(relay.inbox(), relay.inbox())
+
+    combined = [message.message_id for batch in results for message in batch]
+    assert sorted(combined) == ["message-1", "message-2", "message-3"]
+    assert relay._pending == []
+
+
+@pytest.mark.asyncio
+async def test_multiple_relay_instances_are_independent(core_harness):
+    core, FakeTransport, _registered_atexit = core_harness
+    first = core.Relay("FirstRelay", RelayConfig(auto_cleanup=False))
+    second = core.Relay("SecondRelay", RelayConfig(auto_cleanup=False))
+    first_transport, second_transport = FakeTransport.instances
+
+    await first.agents()
+    await second.agents()
+
+    await first_transport.emit_message(
+        Message(sender="Review-Core", text="first only", message_id="message-first")
+    )
+    await second_transport.emit_message(
+        Message(sender="Impl-Core", text="second only", message_id="message-second")
+    )
+
+    assert await first.inbox() == [
+        Message(sender="Review-Core", text="first only", message_id="message-first")
+    ]
+    assert await second.inbox() == [
+        Message(sender="Impl-Core", text="second only", message_id="message-second")
+    ]
+    assert first_transport is not second_transport
+
+
+def test_communicate_package_reexports_public_core_symbols():
+    core = _core_module()
+    communicate = importlib.reload(importlib.import_module("agent_relay.communicate"))
+
+    assert communicate.Relay is core.Relay
+    assert communicate.Message is Message
+    assert communicate.RelayConfig is RelayConfig
+    assert hasattr(communicate, "on_relay")

package/packages/sdk-py/tests/communicate/test_transport.py

@@ -0,0 +1,373 @@
+"""Tests for the RelayTransport HTTP/WS client against real Relaycast API surface."""
+
+from __future__ import annotations
+
+import asyncio
+import importlib
+
+import pytest
+
+from agent_relay.communicate.types import (
+    Message,
+    RelayAuthError,
+    RelayConfigError,
+    RelayConnectionError,
+)
+
+_ORIGINAL_ASYNCIO_SLEEP = asyncio.sleep
+
+
+def _transport_module():
+    return importlib.import_module("agent_relay.communicate.transport")
+
+
+def _transport_class():
+    return _transport_module().RelayTransport
+
+
+async def _wait_for(predicate, timeout: float = 1.0) -> None:
+    deadline = asyncio.get_running_loop().time() + timeout
+    while asyncio.get_running_loop().time() < deadline:
+        if predicate():
+            return
+        await _ORIGINAL_ASYNCIO_SLEEP(0.01)
+
+    raise AssertionError("Timed out waiting for async condition.")
+
+
+@pytest.mark.asyncio
+async def test_register_agent_and_unregister_agent_manage_identity(relay_server):
+    RelayTransport = _transport_class()
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+
+    await transport.register_agent()
+
+    assert transport.agent_id in relay_server.registered_agents
+    assert transport.token == relay_server.registered_agents[transport.agent_id]["token"]
+    register_payload = relay_server.requests["register_agent"][-1]["json"]
+    assert register_payload["name"] == "TransportTester"
+
+    agent_id = transport.agent_id
+    await transport.unregister_agent()
+
+    assert relay_server.request_count("unregister_agent") == 1
+    assert agent_id not in relay_server.registered_agents
+
+
+@pytest.mark.asyncio
+async def test_connect_and_disconnect_manage_registration_and_websocket(relay_server):
+    RelayTransport = _transport_class()
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+
+    await transport.connect()
+
+    assert relay_server.request_count("register_agent") == 1
+    assert transport.agent_id is not None
+    await relay_server.wait_for_ws_connections(transport.agent_id, count=1)
+    assert relay_server.websocket_connected(transport.agent_id)
+
+    agent_id = transport.agent_id
+    await transport.disconnect()
+
+    assert relay_server.request_count("unregister_agent") == 1
+    assert agent_id not in relay_server.registered_agents
+    assert not relay_server.websocket_connected(agent_id)
+
+
+@pytest.mark.asyncio
+async def test_send_dm_posts_to_correct_endpoint(relay_server):
+    RelayTransport = _transport_class()
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    await transport.connect()
+
+    try:
+        message_id = await transport.send_dm("Review-Core", "hello")
+    finally:
+        await transport.disconnect()
+
+    assert message_id.startswith("message-")
+    dm_req = relay_server.requests["send_dm"][-1]
+    assert dm_req["json"]["to"] == "Review-Core"
+    assert dm_req["json"]["text"] == "hello"
+    assert dm_req["path"] == "/v1/dm"
+
+
+@pytest.mark.asyncio
+async def test_post_message_posts_to_channel_endpoint(relay_server):
+    RelayTransport = _transport_class()
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    await transport.connect()
+
+    try:
+        message_id = await transport.post_message("core-py", "status update")
+    finally:
+        await transport.disconnect()
+
+    assert message_id.startswith("message-")
+    ch_req = relay_server.requests["post_message"][-1]
+    assert ch_req["json"]["text"] == "status update"
+    assert "/v1/channels/core-py/messages" in ch_req["path"]
+
+
+@pytest.mark.asyncio
+async def test_reply_posts_to_replies_endpoint(relay_server):
+    RelayTransport = _transport_class()
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    await transport.connect()
+
+    try:
+        message_id = await transport.reply("message-123", "thread reply")
+    finally:
+        await transport.disconnect()
+
+    assert message_id.startswith("message-")
+    reply_req = relay_server.requests["reply"][-1]
+    assert reply_req["json"]["text"] == "thread reply"
+    assert "/v1/messages/message-123/replies" in reply_req["path"]
+
+
+@pytest.mark.asyncio
+async def test_check_inbox_returns_message_objects_and_drains_server_inbox(relay_server):
+    RelayTransport = _transport_class()
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    await transport.connect()
+
+    try:
+        queued = relay_server.queue_inbox_message(
+            transport.agent_id,
+            sender="Impl-Core",
+            text="transport ready",
+            channel="core-py",
+            thread_id="thread-1",
+            message_id="message-inbox-1",
+            timestamp=1710300000.5,
+        )
+
+        messages = await transport.check_inbox()
+        empty = await transport.check_inbox()
+    finally:
+        await transport.disconnect()
+
+    assert len(messages) == 1
+    assert messages[0].sender == "Impl-Core"
+    assert messages[0].text == "transport ready"
+    assert messages[0].message_id == "message-inbox-1"
+    assert empty == []
+
+
+@pytest.mark.asyncio
+async def test_list_agents_returns_online_agent_names(relay_server):
+    RelayTransport = _transport_class()
+    relay_server.add_agent("Review-Core")
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    await transport.connect()
+
+    try:
+        agents = await transport.list_agents()
+    finally:
+        await transport.disconnect()
+
+    assert set(agents) == {"Review-Core", "TransportTester"}
+
+
+@pytest.mark.asyncio
+async def test_websocket_messages_are_decoded_and_delivered_to_callback(relay_server):
+    RelayTransport = _transport_class()
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+
+    received: list[Message] = []
+    delivered = asyncio.Event()
+
+    async def on_message(message: Message) -> None:
+        received.append(message)
+        delivered.set()
+
+    transport.on_ws_message(on_message)
+    await transport.connect()
+
+    try:
+        await relay_server.push_ws_message(
+            transport.agent_id,
+            sender="Review-Core",
+            text="looks good",
+            channel="core-py",
+            message_id="message-ws-1",
+        )
+        await asyncio.wait_for(delivered.wait(), timeout=1.0)
+    finally:
+        await transport.disconnect()
+
+    assert len(received) == 1
+    assert received[0].sender == "Review-Core"
+    assert received[0].text == "looks good"
+    assert received[0].channel == "core-py"
+    assert received[0].message_id == "message-ws-1"
+
+
+@pytest.mark.asyncio
+async def test_transport_reconnects_after_websocket_disconnect(relay_server, monkeypatch):
+    transport_module = _transport_module()
+    RelayTransport = transport_module.RelayTransport
+    sleep_calls: list[float] = []
+
+    async def fake_sleep(delay: float) -> None:
+        sleep_calls.append(delay)
+        await _ORIGINAL_ASYNCIO_SLEEP(0)
+
+    monkeypatch.setattr(transport_module.asyncio, "sleep", fake_sleep)
+
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    received: list[Message] = []
+    delivered = asyncio.Event()
+
+    def on_message(message: Message) -> None:
+        received.append(message)
+        delivered.set()
+
+    transport.on_ws_message(on_message)
+    await transport.connect()
+
+    try:
+        agent_id = transport.agent_id
+        await relay_server.close_ws(agent_id)
+        await relay_server.wait_for_ws_connections(agent_id, count=2)
+
+        await relay_server.push_ws_message(
+            agent_id,
+            sender="Impl-Core",
+            text="reconnected",
+            message_id="message-reconnect-1",
+        )
+        await asyncio.wait_for(delivered.wait(), timeout=1.0)
+    finally:
+        await transport.disconnect()
+
+    assert received[-1].sender == "Impl-Core"
+    assert received[-1].text == "reconnected"
+    assert [delay for delay in sleep_calls if delay >= 1][:1] == [1]
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("workspace", "api_key", "missing_name"),
+    [
+        ("test-workspace", None, "RELAY_API_KEY"),
+        (None, "test-key", "RELAY_WORKSPACE"),
+    ],
+)
+async def test_connect_requires_workspace_and_api_key(
+    relay_server,
+    monkeypatch,
+    workspace,
+    api_key,
+    missing_name,
+):
+    RelayTransport = _transport_class()
+    monkeypatch.delenv("RELAY_WORKSPACE", raising=False)
+    monkeypatch.delenv("RELAY_API_KEY", raising=False)
+
+    transport = RelayTransport(
+        "TransportTester",
+        relay_server.make_config(workspace=workspace, api_key=api_key),
+    )
+
+    with pytest.raises(RelayConfigError, match=missing_name):
+        await transport.connect()
+
+
+@pytest.mark.asyncio
+async def test_register_agent_raises_relay_auth_error_on_401(relay_server):
+    RelayTransport = _transport_class()
+    relay_server.queue_http_error("register_agent", status=401, message="Unauthorized")
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+
+    with pytest.raises(RelayAuthError, match="Unauthorized"):
+        await transport.register_agent()
+
+
+@pytest.mark.asyncio
+async def test_send_dm_raises_connection_error_on_client_error(relay_server):
+    RelayTransport = _transport_class()
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    await transport.connect()
+
+    try:
+        relay_server.queue_http_error("send_dm", status=404, message="Recipient not found")
+
+        with pytest.raises(RelayConnectionError, match="Recipient not found") as exc_info:
+            await transport.send_dm("Missing-Agent", "hello")
+    finally:
+        await transport.disconnect()
+
+    assert exc_info.value.status_code == 404
+
+
+@pytest.mark.asyncio
+async def test_send_dm_retries_transient_server_errors_before_succeeding(
+    relay_server,
+    monkeypatch,
+):
+    transport_module = _transport_module()
+    RelayTransport = transport_module.RelayTransport
+    sleep_calls: list[float] = []
+
+    async def fake_sleep(delay: float) -> None:
+        sleep_calls.append(delay)
+        await _ORIGINAL_ASYNCIO_SLEEP(0)
+
+    monkeypatch.setattr(transport_module.asyncio, "sleep", fake_sleep)
+
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    await transport.connect()
+
+    try:
+        relay_server.queue_http_error(
+            "send_dm",
+            status=503,
+            message="Temporary failure",
+            repeat=2,
+        )
+
+        message_id = await transport.send_dm("Review-Core", "retry me")
+    finally:
+        await transport.disconnect()
+
+    assert message_id.startswith("message-")
+    assert relay_server.request_count("send_dm") == 3
+    assert [delay for delay in sleep_calls if delay >= 1][:2] == [1, 2]
+
+
+@pytest.mark.asyncio
+async def test_send_dm_raises_after_exhausting_server_error_retries(
+    relay_server,
+    monkeypatch,
+):
+    transport_module = _transport_module()
+    RelayTransport = transport_module.RelayTransport
+    sleep_calls: list[float] = []
+
+    async def fake_sleep(delay: float) -> None:
+        sleep_calls.append(delay)
+        await _ORIGINAL_ASYNCIO_SLEEP(0)
+
+    monkeypatch.setattr(transport_module.asyncio, "sleep", fake_sleep)
+
+    transport = RelayTransport("TransportTester", relay_server.make_config())
+    await transport.connect()
+
+    try:
+        relay_server.queue_http_error(
+            "send_dm",
+            status=503,
+            message="Still failing",
+            repeat=3,
+        )
+
+        with pytest.raises(RelayConnectionError, match="Still failing") as exc_info:
+            await transport.send_dm("Review-Core", "retry me")
+    finally:
+        await transport.disconnect()
+
+    assert exc_info.value.status_code == 503
+    assert relay_server.request_count("send_dm") == 3
+    assert [delay for delay in sleep_calls if delay >= 1][:2] == [1, 2]