agent-relay 3.2.14 → 3.2.15

package/dist/index.cjs

@@ -54954,7 +54954,12 @@ var CLI_REGISTRY = {
   },
   codex: {
     binaries: ["codex"],
-    nonInteractiveArgs: (task, extra = []) => ["exec", task, ...extra],
+    nonInteractiveArgs: (task, extra = []) => [
+      "exec",
+      "--dangerously-bypass-approvals-and-sandbox",
+      task,
+      ...extra
+    ],
     bypassFlag: "--dangerously-bypass-approvals-and-sandbox",
     bypassAliases: ["--full-auto"],
     searchPaths: ["~/.local/bin"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-relay",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Real-time agent-to-agent communication system",
   "type": "module",
   "main": "dist/index.cjs",
@@ -176,13 +176,13 @@
   },
   "homepage": "https://github.com/AgentWorkforce/relay#readme",
   "dependencies": {
-    "@agent-relay/config": "3.2.14",
-    "@agent-relay/hooks": "3.2.14",
-    "@agent-relay/sdk": "3.2.14",
-    "@agent-relay/telemetry": "3.2.14",
-    "@agent-relay/trajectory": "3.2.14",
-    "@agent-relay/user-directory": "3.2.14",
-    "@agent-relay/utils": "3.2.14",
+    "@agent-relay/config": "3.2.15",
+    "@agent-relay/hooks": "3.2.15",
+    "@agent-relay/sdk": "3.2.15",
+    "@agent-relay/telemetry": "3.2.15",
+    "@agent-relay/trajectory": "3.2.15",
+    "@agent-relay/user-directory": "3.2.15",
+    "@agent-relay/utils": "3.2.15",
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@relaycast/mcp": "1.0.0",
     "@relaycast/sdk": "1.0.0",

package/packages/acp-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/acp-bridge",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "ACP (Agent Client Protocol) bridge for Agent Relay - expose relay agents to ACP-compatible editors like Zed",
   "type": "module",
   "main": "dist/index.js",
@@ -46,7 +46,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@agent-relay/sdk": "3.2.14",
+    "@agent-relay/sdk": "3.2.15",
     "@agentclientprotocol/sdk": "^0.12.0"
   },
   "devDependencies": {

package/packages/config/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/config",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Shared configuration schemas and loaders for Agent Relay",
   "type": "module",
   "main": "dist/index.js",

package/packages/hooks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/hooks",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Hook emitter, registry, and trajectory hooks for Agent Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -37,9 +37,9 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.14",
-    "@agent-relay/trajectory": "3.2.14",
-    "@agent-relay/sdk": "3.2.14"
+    "@agent-relay/config": "3.2.15",
+    "@agent-relay/trajectory": "3.2.15",
+    "@agent-relay/sdk": "3.2.15"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/memory",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Semantic memory storage and retrieval system for agent-relay with multiple backend support",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/hooks": "3.2.14"
+    "@agent-relay/hooks": "3.2.15"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/openclaw/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/openclaw",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Relaycast bridge for OpenClaw — messaging, identity, runtime setup, and local spawning",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,7 @@
     "postinstall": "node -e \"try{require('child_process').execSync('ldd --version 2>&1',{stdio:'pipe'})}catch{try{require('child_process').execSync('apk info gcompat 2>/dev/null',{stdio:'pipe'})}catch{console.warn('\\n\\u26a0\\ufe0f  @agent-relay/openclaw: Alpine detected without gcompat. Spawning requires glibc.\\n   Install with: apk add gcompat libstdc++\\n')}}\""
   },
   "dependencies": {
-    "@agent-relay/sdk": "3.2.14",
+    "@agent-relay/sdk": "3.2.15",
     "@relaycast/sdk": "^1.0.0",
     "ws": "^8.0.0"
   },

package/packages/policy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/policy",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Agent policy management with multi-level fallback (repo, local PRPM, cloud workspace)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.14"
+    "@agent-relay/config": "3.2.15"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/sdk/dist/cli-registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-registry.d.ts","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIrD,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0DAA0D;IAC1D,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IACrE,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,sGAAsG;IACtG,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAID;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,UAQ/B,CAAC;AAwFF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAGvE;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAE1E"}
+{"version":3,"file":"cli-registry.d.ts","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAIrD,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,0DAA0D;IAC1D,kBAAkB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,EAAE,CAAC;IACrE,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,sGAAsG;IACtG,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAID;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,UAQ/B,CAAC;AA6FF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAGvE;AAED;;GAEG;AACH,wBAAgB,cAAc,IAAI,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC,CAE1E"}

package/packages/sdk/dist/cli-registry.js

@@ -41,7 +41,12 @@ const CLI_REGISTRY = {
     },
     codex: {
         binaries: ['codex'],
-        nonInteractiveArgs: (task, extra = []) => ['exec', task, ...extra],
+        nonInteractiveArgs: (task, extra = []) => [
+            'exec',
+            '--dangerously-bypass-approvals-and-sandbox',
+            task,
+            ...extra,
+        ],
         bypassFlag: '--dangerously-bypass-approvals-and-sandbox',
         bypassAliases: ['--full-auto'],
         searchPaths: ['~/.local/bin'],

package/packages/sdk/dist/cli-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-registry.js","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-registry.js","sourceRoot":"","sources":["../src/cli-registry.ts"],"names":[],"mappings":"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"}

package/packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/sdk",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -102,7 +102,7 @@
     "typescript": "^5.7.3"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.14",
+    "@agent-relay/config": "3.2.15",
     "@relaycast/sdk": "^1.0.0",
     "@sinclair/typebox": "^0.34.48",
     "chalk": "^4.1.2",

package/packages/sdk/src/__tests__/workflow-runner.test.ts

@@ -983,10 +983,10 @@ agents:
       expect(args).toEqual(['-p', '--dangerously-skip-permissions', 'Do the thing']);
     });
 
-    it('should build codex command with exec subcommand', () => {
+    it('should build codex command with exec subcommand and bypass flag', () => {
       const { cmd, args } = WorkflowRunner.buildNonInteractiveCommand('codex', 'Build it');
       expect(cmd).toBe('codex');
-      expect(args).toEqual(['exec', 'Build it']);
+      expect(args).toEqual(['exec', '--dangerously-bypass-approvals-and-sandbox', 'Build it']);
     });
 
     it('should build gemini command with -p flag', () => {

package/packages/sdk/src/cli-registry.ts

@@ -64,7 +64,12 @@ const CLI_REGISTRY: Record<AgentCli, CliDefinition> = {
   },
   codex: {
     binaries: ['codex'],
-    nonInteractiveArgs: (task, extra = []) => ['exec', task, ...extra],
+    nonInteractiveArgs: (task, extra = []) => [
+      'exec',
+      '--dangerously-bypass-approvals-and-sandbox',
+      task,
+      ...extra,
+    ],
     bypassFlag: '--dangerously-bypass-approvals-and-sandbox',
     bypassAliases: ['--full-auto'],
     searchPaths: ['~/.local/bin'],

package/packages/sdk-py/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-relay-sdk"
-version = "3.2.14"
+version = "3.2.15"
 description = "Python SDK for Agent Relay workflows"
 readme = "README.md"
 license = "Apache-2.0"

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/Tests/AgentRelaySDKTests/RelayObserverTests.swift

@@ -0,0 +1,526 @@
+import XCTest
+@testable import AgentRelaySDK
+
+// MARK: - Helpers
+
+private func jsonData(_ jsonString: String) -> Data {
+    jsonString.data(using: .utf8)!
+}
+
+private func decodeEvent(_ json: String) throws -> RelayObserverEvent {
+    let decoder = JSONDecoder()
+    return try decoder.decode(RelayObserverEvent.self, from: jsonData(json))
+}
+
+private func encodeToDict<T: Encodable>(_ value: T) throws -> [String: Any] {
+    let encoder = JSONEncoder()
+    encoder.keyEncodingStrategy = .convertToSnakeCase
+    let data = try encoder.encode(value)
+    return try JSONSerialization.jsonObject(with: data) as! [String: Any]
+}
+
+// MARK: - Event Type Raw Values
+
+final class RelayObserverEventTypeTests: XCTestCase {
+
+    func testAllRawValues() {
+        let expected: [(RelayObserverEventType, String)] = [
+            (.agentSpawned, "agent_spawned"),
+            (.agentReleased, "agent_released"),
+            (.agentIdle, "agent_idle"),
+            (.agentStatus, "agent_status"),
+            (.workerStream, "worker_stream"),
+            (.delivery, "delivery"),
+            (.channelMessage, "channel_message"),
+            (.stepStarted, "step_started"),
+            (.stepCompleted, "step_completed"),
+            (.runCompleted, "run_completed"),
+            (.relayConfig, "relay_config"),
+            (.relayWorkspace, "relay_workspace"),
+            (.commentPollTick, "comment_poll_tick"),
+            (.commentDetected, "comment_detected"),
+            (.error, "error"),
+            (.ack, "ack"),
+            (.connected, "connected"),
+            (.subscribed, "subscribed"),
+            (.pong, "pong"),
+        ]
+
+        XCTAssertEqual(expected.count, 19, "Should cover all 19 event types")
+
+        for (eventType, rawValue) in expected {
+            XCTAssertEqual(eventType.rawValue, rawValue, "Raw value mismatch for \(eventType)")
+        }
+    }
+
+    func testRoundTripCodable() throws {
+        let encoder = JSONEncoder()
+        let decoder = JSONDecoder()
+        for eventType in [RelayObserverEventType.agentSpawned, .delivery, .pong, .error] {
+            let data = try encoder.encode(eventType)
+            let decoded = try decoder.decode(RelayObserverEventType.self, from: data)
+            XCTAssertEqual(decoded, eventType)
+        }
+    }
+}
+
+// MARK: - Event Decoding Tests
+
+final class RelayObserverEventDecodingTests: XCTestCase {
+
+    // MARK: agent_spawned
+
+    func testAgentSpawnedWithName() throws {
+        let event = try decodeEvent("""
+        {
+            "type": "agent_spawned",
+            "name": "worker-1",
+            "cli": "claude",
+            "channels": ["ch-1", "ch-2"]
+        }
+        """)
+        XCTAssertEqual(event.type, .agentSpawned)
+        XCTAssertEqual(event.name, "worker-1")
+        XCTAssertNil(event.agentName)
+        XCTAssertEqual(event.cli, "claude")
+        XCTAssertEqual(event.channels, ["ch-1", "ch-2"])
+    }
+
+    func testAgentSpawnedWithAgentName() throws {
+        let event = try decodeEvent("""
+        {
+            "type": "agent_spawned",
+            "agent_name": "worker-2",
+            "cli": "codex",
+            "channels": ["ch-3"]
+        }
+        """)
+        XCTAssertEqual(event.type, .agentSpawned)
+        XCTAssertNil(event.name)
+        XCTAssertEqual(event.agentName, "worker-2")
+        XCTAssertEqual(event.cli, "codex")
+        XCTAssertEqual(event.channels, ["ch-3"])
+    }
+
+    func testAgentSpawnedWithBothNames() throws {
+        let event = try decodeEvent("""
+        {
+            "type": "agent_spawned",
+            "name": "worker-a",
+            "agent_name": "worker-b",
+            "cli": "claude",
+            "channels": []
+        }
+        """)
+        XCTAssertEqual(event.name, "worker-a")
+        XCTAssertEqual(event.agentName, "worker-b")
+    }
+
+    // MARK: agent_released
+
+    func testAgentReleased() throws {
+        let event = try decodeEvent("""
+        {"type": "agent_released", "name": "worker-1", "reason": "task_complete"}
+        """)
+        XCTAssertEqual(event.type, .agentReleased)
+        XCTAssertEqual(event.name, "worker-1")
+        XCTAssertEqual(event.reason, "task_complete")
+    }
+
+    // MARK: agent_idle
+
+    func testAgentIdle() throws {
+        let event = try decodeEvent("""
+        {"type": "agent_idle", "name": "worker-1", "idle_secs": 120}
+        """)
+        XCTAssertEqual(event.type, .agentIdle)
+        XCTAssertEqual(event.name, "worker-1")
+        XCTAssertEqual(event.idleSecs, 120)
+    }
+
+    // MARK: agent_status
+
+    func testAgentStatus() throws {
+        let event = try decodeEvent("""
+        {"type": "agent_status", "name": "worker-1", "status": "busy"}
+        """)
+        XCTAssertEqual(event.type, .agentStatus)
+        XCTAssertEqual(event.name, "worker-1")
+        XCTAssertEqual(event.status, "busy")
+    }
+
+    // MARK: worker_stream
+
+    func testWorkerStream() throws {
+        let event = try decodeEvent("""
+        {"type": "worker_stream", "agent": "worker-1", "data": "hello world", "stream": "stdout"}
+        """)
+        XCTAssertEqual(event.type, .workerStream)
+        XCTAssertEqual(event.agent, "worker-1")
+        XCTAssertEqual(event.data, "hello world")
+        XCTAssertEqual(event.stream, "stdout")
+    }
+
+    // MARK: delivery
+
+    func testDeliveryCompleted() throws {
+        let event = try decodeEvent("""
+        {
+            "type": "delivery",
+            "id": "msg-1",
+            "from": "lead",
+            "to": "worker-1",
+            "text": "do this task",
+            "state": "completed"
+        }
+        """)
+        XCTAssertEqual(event.type, .delivery)
+        XCTAssertEqual(event.id, "msg-1")
+        XCTAssertEqual(event.from, "lead")
+        XCTAssertEqual(event.to, "worker-1")
+        XCTAssertEqual(event.text, "do this task")
+        XCTAssertEqual(event.state, "completed")
+    }
+
+    func testDeliveryFailed() throws {
+        let event = try decodeEvent("""
+        {
+            "type": "delivery",
+            "id": "msg-2",
+            "from": "lead",
+            "to": "worker-2",
+            "text": "another task",
+            "state": "failed"
+        }
+        """)
+        XCTAssertEqual(event.type, .delivery)
+        XCTAssertEqual(event.state, "failed")
+    }
+
+    // MARK: channel_message
+
+    func testChannelMessage() throws {
+        let event = try decodeEvent("""
+        {
+            "type": "channel_message",
+            "channel": "general",
+            "from": "user-1",
+            "text": "hey team",
+            "timestamp": "2026-03-23T10:00:00Z"
+        }
+        """)
+        XCTAssertEqual(event.type, .channelMessage)
+        XCTAssertEqual(event.channel, "general")
+        XCTAssertEqual(event.from, "user-1")
+        XCTAssertEqual(event.text, "hey team")
+        XCTAssertEqual(event.timestamp, "2026-03-23T10:00:00Z")
+    }
+
+    // MARK: step_started
+
+    func testStepStartedWithStep() throws {
+        let event = try decodeEvent("""
+        {"type": "step_started", "step": "build"}
+        """)
+        XCTAssertEqual(event.type, .stepStarted)
+        XCTAssertEqual(event.step, "build")
+        XCTAssertNil(event.stepName)
+    }
+
+    func testStepStartedWithStepName() throws {
+        let event = try decodeEvent("""
+        {"type": "step_started", "step_name": "compile"}
+        """)
+        XCTAssertEqual(event.type, .stepStarted)
+        XCTAssertNil(event.step)
+        XCTAssertEqual(event.stepName, "compile")
+    }
+
+    func testStepStartedWithBothStepFields() throws {
+        let event = try decodeEvent("""
+        {"type": "step_started", "step": "step-1", "step_name": "Build App"}
+        """)
+        XCTAssertEqual(event.step, "step-1")
+        XCTAssertEqual(event.stepName, "Build App")
+    }
+
+    // MARK: step_completed
+
+    func testStepCompleted() throws {
+        let event = try decodeEvent("""
+        {"type": "step_completed", "step": "build", "step_name": "Build App", "output": "success"}
+        """)
+        XCTAssertEqual(event.type, .stepCompleted)
+        XCTAssertEqual(event.step, "build")
+        XCTAssertEqual(event.stepName, "Build App")
+        XCTAssertEqual(event.output, "success")
+    }
+
+    // MARK: run_completed
+
+    func testRunCompleted() throws {
+        let event = try decodeEvent("""
+        {"type": "run_completed", "run_id": "run-abc-123"}
+        """)
+        XCTAssertEqual(event.type, .runCompleted)
+        XCTAssertEqual(event.runId, "run-abc-123")
+    }
+
+    // MARK: relay_config
+
+    func testRelayConfig() throws {
+        let event = try decodeEvent("""
+        {"type": "relay_config", "observer_url": "wss://relay.example.com/observe"}
+        """)
+        XCTAssertEqual(event.type, .relayConfig)
+        XCTAssertEqual(event.observerUrl, "wss://relay.example.com/observe")
+    }
+
+    // MARK: relay_workspace
+
+    func testRelayWorkspace() throws {
+        let event = try decodeEvent("""
+        {"type": "relay_workspace", "workspace_id": "ws-42"}
+        """)
+        XCTAssertEqual(event.type, .relayWorkspace)
+        XCTAssertEqual(event.workspaceId, "ws-42")
+    }
+
+    // MARK: comment_poll_tick
+
+    func testCommentPollTick() throws {
+        let event = try decodeEvent("""
+        {"type": "comment_poll_tick", "checked_at": "2026-03-23T12:00:00Z", "interval_seconds": 30}
+        """)
+        XCTAssertEqual(event.type, .commentPollTick)
+        XCTAssertEqual(event.checkedAt, "2026-03-23T12:00:00Z")
+        XCTAssertEqual(event.intervalSeconds, 30)
+    }
+
+    // MARK: comment_detected
+
+    func testCommentDetected() throws {
+        let event = try decodeEvent("""
+        {"type": "comment_detected", "message": "New comment on PR #42"}
+        """)
+        XCTAssertEqual(event.type, .commentDetected)
+        XCTAssertEqual(event.message, "New comment on PR #42")
+    }
+
+    // MARK: error
+
+    func testError() throws {
+        let event = try decodeEvent("""
+        {"type": "error", "message": "something went wrong"}
+        """)
+        XCTAssertEqual(event.type, .error)
+        XCTAssertEqual(event.message, "something went wrong")
+    }
+
+    // MARK: ack
+
+    func testAck() throws {
+        let event = try decodeEvent("""
+        {"type": "ack"}
+        """)
+        XCTAssertEqual(event.type, .ack)
+    }
+
+    // MARK: connected
+
+    func testConnected() throws {
+        let event = try decodeEvent("""
+        {"type": "connected"}
+        """)
+        XCTAssertEqual(event.type, .connected)
+    }
+
+    // MARK: subscribed
+
+    func testSubscribed() throws {
+        let event = try decodeEvent("""
+        {"type": "subscribed", "channel": "ops"}
+        """)
+        XCTAssertEqual(event.type, .subscribed)
+        XCTAssertEqual(event.channel, "ops")
+    }
+
+    // MARK: pong
+
+    func testPong() throws {
+        let event = try decodeEvent("""
+        {"type": "pong"}
+        """)
+        XCTAssertEqual(event.type, .pong)
+    }
+}
+
+// MARK: - Optional Fields (minimal event)
+
+final class RelayObserverEventOptionalFieldsTests: XCTestCase {
+
+    func testMinimalAckHasAllOptionalsNil() throws {
+        let event = try decodeEvent("""
+        {"type": "ack"}
+        """)
+        XCTAssertEqual(event.type, .ack)
+        XCTAssertNil(event.name)
+        XCTAssertNil(event.agentName)
+        XCTAssertNil(event.cli)
+        XCTAssertNil(event.channels)
+        XCTAssertNil(event.reason)
+        XCTAssertNil(event.idleSecs)
+        XCTAssertNil(event.status)
+        XCTAssertNil(event.agent)
+        XCTAssertNil(event.data)
+        XCTAssertNil(event.stream)
+        XCTAssertNil(event.id)
+        XCTAssertNil(event.from)
+        XCTAssertNil(event.to)
+        XCTAssertNil(event.text)
+        XCTAssertNil(event.state)
+        XCTAssertNil(event.channel)
+        XCTAssertNil(event.timestamp)
+        XCTAssertNil(event.step)
+        XCTAssertNil(event.stepName)
+        XCTAssertNil(event.output)
+        XCTAssertNil(event.runId)
+        XCTAssertNil(event.observerUrl)
+        XCTAssertNil(event.workspaceId)
+        XCTAssertNil(event.checkedAt)
+        XCTAssertNil(event.intervalSeconds)
+        XCTAssertNil(event.message)
+    }
+}
+
+// MARK: - Outbound Message Encoding
+
+final class RelayObserverOutboundEncodingTests: XCTestCase {
+
+    func testSubscribeMessage() throws {
+        let msg = ObserverSubscribeMessage(channel: "ops")
+        let dict = try encodeToDict(msg)
+        XCTAssertEqual(dict["type"] as? String, "subscribe")
+        XCTAssertEqual(dict["channel"] as? String, "ops")
+        XCTAssertEqual(dict.count, 2)
+    }
+
+    func testChannelSendMessageFull() throws {
+        let msg = ObserverChannelSendMessage(
+            channel: "general",
+            text: "hello",
+            personas: ["lead", "worker"],
+            cliPreferences: ["model": "opus"]
+        )
+        let dict = try encodeToDict(msg)
+        XCTAssertEqual(dict["type"] as? String, "channel_send")
+        XCTAssertEqual(dict["channel"] as? String, "general")
+        XCTAssertEqual(dict["text"] as? String, "hello")
+        XCTAssertEqual(dict["personas"] as? [String], ["lead", "worker"])
+        let prefs = dict["cli_preferences"] as? [String: String]
+        XCTAssertEqual(prefs?["model"], "opus")
+    }
+
+    func testChannelSendMessageMinimal() throws {
+        let msg = ObserverChannelSendMessage(
+            channel: "ops",
+            text: "ping",
+            personas: nil,
+            cliPreferences: nil
+        )
+        let dict = try encodeToDict(msg)
+        XCTAssertEqual(dict["type"] as? String, "channel_send")
+        XCTAssertEqual(dict["channel"] as? String, "ops")
+        XCTAssertEqual(dict["text"] as? String, "ping")
+        // nil optionals should not be present
+        XCTAssertNil(dict["personas"])
+        XCTAssertNil(dict["cli_preferences"])
+    }
+
+    func testDirectSendMessage() throws {
+        let msg = ObserverDirectSendMessage(to: "worker-1", text: "do it")
+        let dict = try encodeToDict(msg)
+        XCTAssertEqual(dict["type"] as? String, "send")
+        XCTAssertEqual(dict["to"] as? String, "worker-1")
+        XCTAssertEqual(dict["text"] as? String, "do it")
+        XCTAssertEqual(dict.count, 3)
+    }
+}
+
+// MARK: - RelayObserverError Tests
+
+final class RelayObserverErrorTests: XCTestCase {
+
+    func testNotConnectedDescription() {
+        let error = RelayObserverError.notConnected
+        XCTAssertEqual(error.errorDescription, "Relay not connected")
+        XCTAssertEqual(error.localizedDescription, "Relay not connected")
+    }
+
+    func testEncodingFailedDescription() {
+        let error = RelayObserverError.encodingFailed
+        XCTAssertEqual(error.errorDescription, "Message encoding failed")
+        XCTAssertEqual(error.localizedDescription, "Message encoding failed")
+    }
+}
+
+// MARK: - ConnectionState Tests
+
+final class RelayObserverConnectionStateTests: XCTestCase {
+
+    func testEquatable() {
+        XCTAssertEqual(RelayObserver.ConnectionState.disconnected, .disconnected)
+        XCTAssertEqual(RelayObserver.ConnectionState.connecting, .connecting)
+        XCTAssertEqual(RelayObserver.ConnectionState.connected, .connected)
+        XCTAssertEqual(
+            RelayObserver.ConnectionState.reconnecting(attempt: 3),
+            .reconnecting(attempt: 3)
+        )
+    }
+
+    func testNotEqual() {
+        XCTAssertNotEqual(RelayObserver.ConnectionState.disconnected, .connecting)
+        XCTAssertNotEqual(RelayObserver.ConnectionState.connected, .disconnected)
+        XCTAssertNotEqual(
+            RelayObserver.ConnectionState.reconnecting(attempt: 1),
+            .reconnecting(attempt: 2)
+        )
+        XCTAssertNotEqual(
+            RelayObserver.ConnectionState.reconnecting(attempt: 1),
+            .connected
+        )
+    }
+}
+
+// MARK: - RelayObserver Init Tests
+
+final class RelayObserverInitTests: XCTestCase {
+
+    func testDefaultState() {
+        let observer = RelayObserver()
+        XCTAssertEqual(observer.connectionState, .disconnected)
+        XCTAssertEqual(observer.eventCounter, 0)
+        XCTAssertNil(observer.lastEvent)
+    }
+
+    func testCustomInit() {
+        let observer = RelayObserver(maxReconnectAttempts: 3, baseReconnectDelay: 2.0)
+        XCTAssertEqual(observer.connectionState, .disconnected)
+        XCTAssertEqual(observer.eventCounter, 0)
+        XCTAssertNil(observer.lastEvent)
+    }
+
+    func testSendChannelThrowsWhenDisconnected() {
+        let observer = RelayObserver()
+        XCTAssertThrowsError(try observer.sendChannel(channel: "ops", text: "hi")) { error in
+            XCTAssertEqual(error as? RelayObserverError, .notConnected)
+        }
+    }
+
+    func testSendDirectThrowsWhenDisconnected() {
+        let observer = RelayObserver()
+        XCTAssertThrowsError(try observer.sendDirect(to: "agent", text: "hi")) { error in
+            XCTAssertEqual(error as? RelayObserverError, .notConnected)
+        }
+    }
+}

package/packages/telemetry/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/telemetry",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Anonymous telemetry for Agent Relay usage analytics",
   "type": "module",
   "main": "dist/index.js",

package/packages/trajectory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/trajectory",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Trajectory integration utilities (trail/PDERO) for Relay",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.14"
+    "@agent-relay/config": "3.2.15"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/user-directory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/user-directory",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "User directory service for agent-relay (per-user credential storage)",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
-    "@agent-relay/utils": "3.2.14"
+    "@agent-relay/utils": "3.2.15"
   },
   "devDependencies": {
     "@types/node": "^22.19.3",

package/packages/utils/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-relay/utils",
-  "version": "3.2.14",
+  "version": "3.2.15",
   "description": "Shared utilities for agent-relay: logging, name generation, command resolution, update checking",
   "type": "module",
   "main": "dist/cjs/index.js",
@@ -112,7 +112,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@agent-relay/config": "3.2.14",
+    "@agent-relay/config": "3.2.15",
     "compare-versions": "^6.1.1"
   },
   "publishConfig": {