agent-relay 3.2.13 → 3.2.15

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)
+            }
+        }
+    }
+}

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

@@ -0,0 +1,143 @@
+import Foundation
+
+// MARK: - RelayObserverEventType
+
+public enum RelayObserverEventType: String, Codable, Sendable {
+    case agentSpawned = "agent_spawned"
+    case agentReleased = "agent_released"
+    case agentIdle = "agent_idle"
+    case agentStatus = "agent_status"
+    case workerStream = "worker_stream"
+    case delivery = "delivery"
+    case channelMessage = "channel_message"
+    case stepStarted = "step_started"
+    case stepCompleted = "step_completed"
+    case runCompleted = "run_completed"
+    case relayConfig = "relay_config"
+    case relayWorkspace = "relay_workspace"
+    case commentPollTick = "comment_poll_tick"
+    case commentDetected = "comment_detected"
+    case error = "error"
+    case ack = "ack"
+    case connected = "connected"
+    case subscribed = "subscribed"
+    case pong = "pong"
+}
+
+// MARK: - RelayObserverEvent
+
+public struct RelayObserverEvent: Decodable, Sendable {
+    public let type: RelayObserverEventType
+
+    // agent_spawned fields
+    public let name: String?
+    public let agentName: String?
+    public let cli: String?
+    public let channels: [String]?
+
+    // agent_released fields
+    public let reason: String?
+
+    // agent_idle fields
+    public let idleSecs: Int?
+
+    // agent_status fields
+    public let status: String?
+
+    // worker_stream fields
+    public let agent: String?
+    public let data: String?
+    public let stream: String?
+
+    // delivery fields
+    public let id: String?
+    public let from: String?
+    public let to: String?
+    public let text: String?
+    public let state: String?
+
+    // channel_message fields
+    public let channel: String?
+    public let timestamp: String?
+
+    // step_started / step_completed fields
+    public let step: String?
+    public let stepName: String?
+    public let output: String?
+
+    // run_completed fields
+    public let runId: String?
+
+    // relay_config fields
+    public let observerUrl: String?
+
+    // relay_workspace fields
+    public let workspaceId: String?
+
+    // comment_poll_tick fields
+    public let checkedAt: String?
+    public let intervalSeconds: Int?
+
+    // comment_detected / error fields
+    public let message: String?
+
+    enum CodingKeys: String, CodingKey {
+        case type
+        case name
+        case agentName = "agent_name"
+        case cli, channels, reason
+        case idleSecs = "idle_secs"
+        case status, agent, data, stream
+        case id, from, to, text, state
+        case channel, timestamp
+        case step
+        case stepName = "step_name"
+        case output
+        case runId = "run_id"
+        case observerUrl = "observer_url"
+        case workspaceId = "workspace_id"
+        case checkedAt = "checked_at"
+        case intervalSeconds = "interval_seconds"
+        case message
+    }
+}
+
+// MARK: - RelayObserverError
+
+public enum RelayObserverError: LocalizedError, Sendable {
+    case notConnected
+    case encodingFailed
+
+    public var errorDescription: String? {
+        switch self {
+        case .notConnected: return "Relay not connected"
+        case .encodingFailed: return "Message encoding failed"
+        }
+    }
+}
+
+// MARK: - Outbound Message Structs (internal)
+
+struct ObserverSubscribeMessage: Encodable {
+    let type: String = "subscribe"
+    let channel: String
+}
+
+struct ObserverChannelSendMessage: Encodable {
+    let type: String = "channel_send"
+    let channel: String
+    let text: String
+    let personas: [String]?
+    let cliPreferences: [String: String]?
+
+    enum CodingKeys: String, CodingKey {
+        case type, channel, text, personas
+        case cliPreferences = "cli_preferences"
+    }
+}
+
+struct ObserverDirectSendMessage: Encodable {
+    let type: String = "send"
+    let to: String
+    let text: String
+}

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

@@ -0,0 +1,220 @@
+import Foundation
+
+public actor RelayTransport {
+    public enum ConnectionState: Sendable {
+        case disconnected
+        case connecting
+        case connected
+        case reconnecting
+    }
+
+    public enum TransportError: Error, Sendable {
+        case invalidResponse
+        case notConnected
+        case sendFailed(String)
+        case connectionFailed(String)
+    }
+
+    public nonisolated let inbound: AsyncStream<Data>
+
+    private let baseURL: URL
+    private let session: URLSession
+    private let authToken: String
+    private var webSocketTask: URLSessionWebSocketTask?
+    private var receiveTask: Task<Void, Never>?
+    private var pingTask: Task<Void, Never>?
+    private var reconnectTask: Task<Void, Never>?
+    private var inboundContinuation: AsyncStream<Data>.Continuation?
+    private var state: ConnectionState = .disconnected
+    private var manuallyDisconnected = false
+    private var reconnectAttempt = 0
+    private var lastPongAt = Date()
+    private var onConnect: (@Sendable () async -> Void)?
+
+    public init(baseURL: URL, authToken: String, session: URLSession = .shared) {
+        self.baseURL = baseURL
+        self.authToken = authToken
+        self.session = session
+        var continuationRef: AsyncStream<Data>.Continuation?
+        self.inbound = AsyncStream<Data> { continuation in
+            continuationRef = continuation
+        }
+        self.inboundContinuation = continuationRef
+    }
+
+    public func setOnConnect(_ handler: @escaping @Sendable () async -> Void) {
+        self.onConnect = handler
+    }
+
+    public func connect() async throws {
+        switch state {
+        case .connected, .connecting:
+            return
+        case .disconnected, .reconnecting:
+            break
+        }
+
+        manuallyDisconnected = false
+        state = reconnectAttempt == 0 ? .connecting : .reconnecting
+
+        let isReconnect = reconnectAttempt > 0
+        let request = websocketRequest()
+        let task = session.webSocketTask(with: request)
+        webSocketTask = task
+        task.resume()
+        state = .connected
+        reconnectAttempt = 0
+        lastPongAt = Date()
+
+        startReceiveLoop()
+        startPingLoop()
+        if isReconnect, let onConnect {
+            await onConnect()
+        }
+    }
+
+    public func disconnect() {
+        manuallyDisconnected = true
+        receiveTask?.cancel()
+        pingTask?.cancel()
+        reconnectTask?.cancel()
+        receiveTask = nil
+        pingTask = nil
+        reconnectTask = nil
+        webSocketTask?.cancel(with: .goingAway, reason: nil)
+        webSocketTask = nil
+        state = .disconnected
+    }
+
+    public func send(_ message: Data) async throws {
+        guard let task = webSocketTask, state == .connected else {
+            throw TransportError.notConnected
+        }
+
+        do {
+            try await task.send(.data(message))
+        } catch {
+            throw TransportError.sendFailed(String(describing: error))
+        }
+    }
+
+    private func websocketRequest() -> URLRequest {
+        var components = URLComponents(url: baseURL, resolvingAgainstBaseURL: false)
+        if components?.scheme == "http" { components?.scheme = "ws" }
+        if components?.scheme == "https" { components?.scheme = "wss" }
+        if components?.path.isEmpty ?? true { components?.path = "/v1/ws" }
+        if !(components?.path.hasSuffix("/v1/ws") ?? false) && !(components?.path.hasSuffix("/ws") ?? false) {
+            components?.path = "/v1/ws"
+        }
+        let existingItems = components?.queryItems ?? []
+        components?.queryItems = existingItems + [URLQueryItem(name: "token", value: authToken)]
+
+        var request = URLRequest(url: components?.url ?? baseURL)
+        request.setValue("Bearer \(authToken)", forHTTPHeaderField: "Authorization")
+        request.setValue(authToken, forHTTPHeaderField: "X-API-Key")
+        return request
+    }
+
+    private func startReceiveLoop() {
+        receiveTask?.cancel()
+        receiveTask = Task { [weak self] in
+            guard let self else { return }
+            while !Task.isCancelled {
+                do {
+                    guard let task = await self.webSocketTask else { return }
+                    let message = try await task.receive()
+                    await self.handle(message)
+                } catch {
+                    await self.handleDisconnect(error: error)
+                    return
+                }
+            }
+        }
+    }
+
+    private func startPingLoop() {
+        pingTask?.cancel()
+        pingTask = Task { [weak self] in
+            guard let self else { return }
+            while !Task.isCancelled {
+                try? await Task.sleep(for: .seconds(20))
+                if Task.isCancelled { return }
+                do {
+                    try await self.sendPing()
+                } catch {
+                    await self.handleDisconnect(error: error)
+                    return
+                }
+            }
+        }
+    }
+
+    private func sendPing() async throws {
+        guard let task = webSocketTask else { throw TransportError.notConnected }
+        let before = Date()
+        try await withCheckedThrowingContinuation { (continuation: CheckedContinuation<Void, Error>) in
+            task.sendPing { error in
+                if let error {
+                    continuation.resume(throwing: error)
+                } else {
+                    continuation.resume(returning: ())
+                }
+            }
+        }
+        lastPongAt = Date()
+        if lastPongAt.timeIntervalSince(before) > 10 {
+            throw TransportError.connectionFailed("Pong exceeded watchdog")
+        }
+    }
+
+    private func handle(_ message: URLSessionWebSocketTask.Message) {
+        switch message {
+        case .data(let data):
+            inboundContinuation?.yield(data)
+        case .string(let string):
+            if let data = string.data(using: .utf8) {
+                inboundContinuation?.yield(data)
+            }
+        @unknown default:
+            break
+        }
+    }
+
+    private func handleDisconnect(error: Error) async {
+        receiveTask?.cancel()
+        pingTask?.cancel()
+        webSocketTask?.cancel(with: .goingAway, reason: nil)
+        webSocketTask = nil
+
+        guard !manuallyDisconnected else {
+            state = .disconnected
+            return
+        }
+
+        state = .reconnecting
+        let delay = reconnectDelay(for: reconnectAttempt)
+        reconnectAttempt += 1
+        reconnectTask?.cancel()
+        reconnectTask = Task { [weak self] in
+            guard let self else { return }
+            try? await Task.sleep(for: .milliseconds(delay))
+            do {
+                try await self.connect()
+            } catch {
+                await self.handleDisconnect(error: error)
+            }
+        }
+    }
+
+    private func reconnectDelay(for attempt: Int) -> Int {
+        switch attempt {
+        case 0: return 500
+        case 1: return 1_000
+        case 2: return 2_000
+        case 3: return 4_000
+        case 4: return 8_000
+        case 5: return 16_000
+        default: return 30_000
+        }
+    }
+}