agent-relay 3.2.14 → 3.2.16

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

@@ -1,4 +1,4 @@
-"""Tests for the RelayTransport HTTP/WS client against real Relaycast API surface."""
+"""Wave 1.2 tests for the RelayTransport HTTP/WS client."""
 
 from __future__ import annotations
 
@@ -44,8 +44,10 @@ async def test_register_agent_and_unregister_agent_manage_identity(relay_server)
 
     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"
+    assert relay_server.requests["register_agent"][-1]["json"] == {
+        "name": "TransportTester",
+        "workspace": relay_server.workspace,
+    }
 
     agent_id = transport.agent_id
     await transport.unregister_agent()
@@ -75,55 +77,47 @@ async def test_connect_and_disconnect_manage_registration_and_websocket(relay_se
 
 
 @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):
+@pytest.mark.parametrize(
+    ("method_name", "args", "operation", "expected_payload"),
+    [
+        (
+            "send_dm",
+            ("Review-Core", "hello"),
+            "send_dm",
+            {"to": "Review-Core", "text": "hello", "from": "TransportTester"},
+        ),
+        (
+            "post_message",
+            ("core-py", "status update"),
+            "post_message",
+            {"channel": "core-py", "text": "status update", "from": "TransportTester"},
+        ),
+        (
+            "reply",
+            ("message-123", "thread reply"),
+            "reply",
+            {"message_id": "message-123", "text": "thread reply", "from": "TransportTester"},
+        ),
+    ],
+)
+async def test_send_methods_use_expected_http_payload(
+    relay_server,
+    method_name,
+    args,
+    operation,
+    expected_payload,
+):
     RelayTransport = _transport_class()
     transport = RelayTransport("TransportTester", relay_server.make_config())
     await transport.connect()
 
     try:
-        message_id = await transport.reply("message-123", "thread reply")
+        message_id = await getattr(transport, method_name)(*args)
     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"]
+    assert relay_server.requests[operation][-1]["json"] == expected_payload
 
 
 @pytest.mark.asyncio
@@ -148,10 +142,16 @@ async def test_check_inbox_returns_message_objects_and_drains_server_inbox(relay
     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 messages == [
+        Message(
+            sender=queued["sender"],
+            text=queued["text"],
+            channel=queued["channel"],
+            thread_id=queued["thread_id"],
+            timestamp=queued["timestamp"],
+            message_id=queued["message_id"],
+        )
+    ]
     assert empty == []
 
 
@@ -197,11 +197,16 @@ async def test_websocket_messages_are_decoded_and_delivered_to_callback(relay_se
     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"
+    assert received == [
+        Message(
+            sender="Review-Core",
+            text="looks good",
+            channel="core-py",
+            thread_id=None,
+            timestamp=None,
+            message_id="message-ws-1",
+        )
+    ]
 
 
 @pytest.mark.asyncio
@@ -242,8 +247,14 @@ async def test_transport_reconnects_after_websocket_disconnect(relay_server, mon
     finally:
         await transport.disconnect()
 
-    assert received[-1].sender == "Impl-Core"
-    assert received[-1].text == "reconnected"
+    assert received[-1] == Message(
+        sender="Impl-Core",
+        text="reconnected",
+        channel=None,
+        thread_id=None,
+        timestamp=None,
+        message_id="message-reconnect-1",
+    )
     assert [delay for delay in sleep_calls if delay >= 1][:1] == [1]
 
 

package/packages/sdk-py/tests/test_send_message_mode.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from agent_relay.client import AgentRelayClient
+from agent_relay.relay import AgentRelay, HumanHandle
+
+
+@pytest.mark.asyncio
+async def test_client_send_message_includes_mode_in_payload():
+    client = AgentRelayClient(binary_path="agent-relay-broker")
+    client.start_client = AsyncMock()
+
+    payloads: list[dict] = []
+
+    async def fake_request_ok(type_: str, payload: dict):
+        assert type_ == "send_message"
+        payloads.append(payload)
+        return {"event_id": "evt-1", "targets": ["Worker"]}
+
+    client._request_ok = fake_request_ok  # type: ignore[method-assign]
+
+    result = await client.send_message(
+        to="Worker",
+        text="hello",
+        from_="system",
+        thread_id="thread-1",
+        priority=5,
+        data={"k": "v"},
+        mode="steer",
+    )
+
+    assert result["event_id"] == "evt-1"
+    assert payloads == [
+        {
+            "to": "Worker",
+            "text": "hello",
+            "from": "system",
+            "thread_id": "thread-1",
+            "priority": 5,
+            "data": {"k": "v"},
+            "mode": "steer",
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_human_send_message_passes_mode_and_sets_message_mode():
+    relay = AgentRelay()
+    client = AsyncMock()
+    client.send_message = AsyncMock(return_value={"event_id": "evt-2"})
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    human = HumanHandle("system", relay)
+    msg = await human.send_message(to="Worker", text="status?", mode="wait")
+
+    assert msg.mode == "wait"
+    client.send_message.assert_awaited_once_with(
+        to="Worker",
+        text="status?",
+        from_="system",
+        thread_id=None,
+        priority=None,
+        data=None,
+        mode="wait",
+    )
+
+
+@pytest.mark.asyncio
+async def test_agent_send_message_passes_mode_and_sets_message_mode():
+    relay = AgentRelay()
+    client = AsyncMock()
+    client.spawn_pty = AsyncMock(return_value={"name": "Worker", "runtime": "pty"})
+    client.send_message = AsyncMock(return_value={"event_id": "evt-3"})
+    relay._ensure_started = AsyncMock(return_value=client)
+
+    agent = await relay.spawn("Worker", "claude")
+    msg = await agent.send_message(to="Reviewer", text="ready", mode="steer")
+
+    assert msg.mode == "steer"
+    client.send_message.assert_awaited_with(
+        to="Reviewer",
+        text="ready",
+        from_="Worker",
+        thread_id=None,
+        priority=None,
+        data=None,
+        mode="steer",
+    )

package/packages/sdk-swift/Sources/AgentRelaySDK/RelayObserver.swift

@@ -0,0 +1,323 @@
+import Foundation
+
+// MARK: - Delegate
+
+@MainActor
+public protocol RelayObserverDelegate: AnyObject {
+    func relayObserver(_ observer: RelayObserver, didReceiveEvent event: RelayObserverEvent)
+    func relayObserverDidConnect(_ observer: RelayObserver)
+    func relayObserverDidDisconnect(_ observer: RelayObserver, error: Error?)
+}
+
+// MARK: - RelayObserver
+
+public final class RelayObserver: NSObject, URLSessionWebSocketDelegate, @unchecked Sendable {
+
+    // MARK: - ConnectionState
+
+    public enum ConnectionState: Equatable, Sendable {
+        case disconnected
+        case connecting
+        case connected
+        case reconnecting(attempt: Int)
+    }
+
+    // MARK: - Public Properties (thread-safe via queue)
+
+    public var connectionState: ConnectionState {
+        queue.sync { _connectionState }
+    }
+    public var lastEvent: RelayObserverEvent? {
+        queue.sync { _lastEvent }
+    }
+    public var eventCounter: Int {
+        queue.sync { _eventCounter }
+    }
+    public weak var delegate: RelayObserverDelegate?
+
+    // MARK: - AsyncStream
+
+    public var events: AsyncStream<RelayObserverEvent> {
+        queue.sync {
+            _eventsContinuation?.finish()
+            return AsyncStream { continuation in
+                self._eventsContinuation = continuation
+            }
+        }
+    }
+
+    // MARK: - Private Properties
+
+    private let queue = DispatchQueue(label: "com.agentrelay.observer", qos: .userInitiated)
+    private var _connectionState: ConnectionState = .disconnected
+    private var _lastEvent: RelayObserverEvent?
+    private var _eventCounter: Int = 0
+    private var webSocketTask: URLSessionWebSocketTask?
+    private var urlSession: URLSession?
+    private let maxReconnectAttempts: Int
+    private let baseReconnectDelay: TimeInterval
+    private var reconnectAttempts: Int = 0
+    private var reconnectTask: Task<Void, Never>?
+    private var subscribedChannel: String?
+    private var pendingOutbound: [String] = []
+    private var isConnectionReady: Bool = false
+    private var activeURL: URL?
+    private var _eventsContinuation: AsyncStream<RelayObserverEvent>.Continuation?
+
+    private let jsonEncoder: JSONEncoder = {
+        let encoder = JSONEncoder()
+        encoder.keyEncodingStrategy = .convertToSnakeCase
+        return encoder
+    }()
+
+    private let jsonDecoder: JSONDecoder = {
+        // NOT using convertFromSnakeCase — we use explicit CodingKeys
+        // because of dual-name fields (name/agent_name, step/step_name)
+        let decoder = JSONDecoder()
+        return decoder
+    }()
+
+    // MARK: - Init
+
+    public init(maxReconnectAttempts: Int = 8, baseReconnectDelay: TimeInterval = 1.0) {
+        self.maxReconnectAttempts = maxReconnectAttempts
+        self.baseReconnectDelay = baseReconnectDelay
+        super.init()
+    }
+
+    // MARK: - Public Methods
+
+    /// Connect to a WebSocket proxy URL and subscribe to a channel on open.
+    public func connect(url: URL, channel: String) {
+        queue.sync {
+            self.subscribedChannel = channel
+            self._openSocket(url: url)
+        }
+    }
+
+    /// Connect to a WebSocket proxy URL without channel subscription.
+    public func connect(url: URL) {
+        queue.sync {
+            self.subscribedChannel = nil
+            self._openSocket(url: url)
+        }
+    }
+
+    /// Disconnect — closes socket, cancels reconnect, clears state.
+    public func disconnect() {
+        queue.sync {
+            reconnectTask?.cancel()
+            reconnectTask = nil
+            reconnectAttempts = 0
+            isConnectionReady = false
+            subscribedChannel = nil
+            pendingOutbound.removeAll()
+            activeURL = nil
+            _closeSocket(code: .goingAway, reason: nil)
+            _connectionState = .disconnected
+            _eventsContinuation?.finish()
+            _eventsContinuation = nil
+        }
+    }
+
+    /// Send a message to a channel through the proxy.
+    public func sendChannel(
+        channel: String,
+        text: String,
+        personas: [String]? = nil,
+        cliPreferences: [String: String]? = nil
+    ) throws {
+        let msg = ObserverChannelSendMessage(
+            channel: channel,
+            text: text,
+            personas: personas,
+            cliPreferences: cliPreferences
+        )
+        try queue.sync {
+            try _sendEncodable(msg)
+        }
+    }
+
+    /// Send a direct message to a specific agent through the proxy.
+    public func sendDirect(to: String, text: String) throws {
+        let msg = ObserverDirectSendMessage(to: to, text: text)
+        try queue.sync {
+            try _sendEncodable(msg)
+        }
+    }
+
+    // MARK: - Private Methods (must be called on queue)
+
+    private func _openSocket(url: URL) {
+        _closeSocket(code: .goingAway, reason: nil)
+        activeURL = url
+        _connectionState = .connecting
+        isConnectionReady = false
+
+        let delegateQueue = OperationQueue()
+        delegateQueue.underlyingQueue = queue
+        delegateQueue.maxConcurrentOperationCount = 1
+
+        let session = URLSession(
+            configuration: .default,
+            delegate: self,
+            delegateQueue: delegateQueue
+        )
+        self.urlSession = session
+        let task = session.webSocketTask(with: url)
+        self.webSocketTask = task
+        task.resume()
+        _scheduleReceive()
+    }
+
+    private func _closeSocket(code: URLSessionWebSocketTask.CloseCode, reason: Data?) {
+        webSocketTask?.cancel(with: code, reason: reason)
+        webSocketTask = nil
+        urlSession?.invalidateAndCancel()
+        urlSession = nil
+    }
+
+    private func _scheduleReceive() {
+        webSocketTask?.receive { [weak self] result in
+            guard let self else { return }
+            // Callback arrives on our queue via delegateQueue
+            switch result {
+            case .success(let message):
+                self._handleMessage(message)
+                self._scheduleReceive()
+            case .failure(let error):
+                self._handleSocketError(error)
+            }
+        }
+    }
+
+    private func _handleMessage(_ message: URLSessionWebSocketTask.Message) {
+        let data: Data
+        switch message {
+        case .string(let text):
+            guard let d = text.data(using: .utf8) else { return }
+            data = d
+        case .data(let d):
+            data = d
+        @unknown default:
+            return
+        }
+
+        guard let event = try? jsonDecoder.decode(RelayObserverEvent.self, from: data) else { return }
+
+        _lastEvent = event
+        _eventCounter += 1
+
+        if let delegate {
+            Task { @MainActor in
+                delegate.relayObserver(self, didReceiveEvent: event)
+            }
+        }
+
+        _eventsContinuation?.yield(event)
+    }
+
+    private func _handleSocketError(_ error: Error) {
+        guard reconnectAttempts < maxReconnectAttempts else {
+            _connectionState = .disconnected
+            let delegate = self.delegate
+            Task { @MainActor in
+                delegate?.relayObserverDidDisconnect(self, error: error)
+            }
+            return
+        }
+
+        reconnectAttempts += 1
+        _connectionState = .reconnecting(attempt: reconnectAttempts)
+
+        let delay = baseReconnectDelay * pow(2.0, Double(reconnectAttempts - 1))
+
+        reconnectTask?.cancel()
+        reconnectTask = Task { [weak self] in
+            try? await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
+            guard !Task.isCancelled, let self else { return }
+            self.queue.sync {
+                guard let url = self.activeURL else { return }
+                self._openSocket(url: url)
+            }
+        }
+    }
+
+    private func _sendSubscription() {
+        guard let channel = subscribedChannel else { return }
+        let msg = ObserverSubscribeMessage(channel: channel)
+        if let data = try? jsonEncoder.encode(msg),
+           let str = String(data: data, encoding: .utf8) {
+            webSocketTask?.send(.string(str)) { _ in }
+        }
+    }
+
+    private func _sendEncodable<T: Encodable>(_ value: T) throws {
+        guard let task = webSocketTask else {
+            throw RelayObserverError.notConnected
+        }
+        guard let data = try? jsonEncoder.encode(value),
+              let str = String(data: data, encoding: .utf8) else {
+            throw RelayObserverError.encodingFailed
+        }
+
+        if isConnectionReady {
+            task.send(.string(str)) { _ in }
+        } else {
+            pendingOutbound.append(str)
+        }
+    }
+
+    private func _flushPendingOutbound() {
+        guard let task = webSocketTask else { return }
+        for str in pendingOutbound {
+            task.send(.string(str)) { _ in }
+        }
+        pendingOutbound.removeAll()
+    }
+
+    // MARK: - URLSessionWebSocketDelegate (callbacks arrive on queue via delegateQueue)
+
+    public func urlSession(
+        _ session: URLSession,
+        webSocketTask: URLSessionWebSocketTask,
+        didOpenWithProtocol protocol: String?
+    ) {
+        _connectionState = .connected
+        reconnectAttempts = 0
+        isConnectionReady = true
+
+        _flushPendingOutbound()
+        _sendSubscription()
+
+        let delegate = self.delegate
+        Task { @MainActor in
+            delegate?.relayObserverDidConnect(self)
+        }
+    }
+
+    public func urlSession(
+        _ session: URLSession,
+        webSocketTask: URLSessionWebSocketTask,
+        didCloseWith closeCode: URLSessionWebSocketTask.CloseCode,
+        reason: Data?
+    ) {
+        isConnectionReady = false
+
+        if closeCode != .goingAway && closeCode != .normalClosure {
+            _handleSocketError(
+                NSError(
+                    domain: "RelayObserver",
+                    code: Int(closeCode.rawValue),
+                    userInfo: [NSLocalizedDescriptionKey: "WebSocket closed with code \(closeCode.rawValue)"]
+                )
+            )
+        } else {
+            _connectionState = .disconnected
+            let delegate = self.delegate
+            Task { @MainActor in
+                delegate?.relayObserverDidDisconnect(self, error: nil)
+            }
+        }
+    }
+}