refactor: migrate iOS gateway to unified ws

apps/shared/ClawdbotKit/Package.swift

@@ -9,6 +9,7 @@ let package = Package(
         .macOS(.v15),
     ],
     products: [
+        .library(name: "ClawdbotProtocol", targets: ["ClawdbotProtocol"]),
         .library(name: "ClawdbotKit", targets: ["ClawdbotKit"]),
         .library(name: "ClawdbotChatUI", targets: ["ClawdbotChatUI"]),
     ],
@@ -17,9 +18,15 @@ let package = Package(
         .package(url: "https://github.com/gonzalezreal/textual", exact: "0.2.0"),
     ],
     targets: [
+        .target(
+            name: "ClawdbotProtocol",
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+            ]),
         .target(
             name: "ClawdbotKit",
             dependencies: [
+                "ClawdbotProtocol",
                 .product(name: "ElevenLabsKit", package: "ElevenLabsKit"),
             ],
             resources: [

apps/shared/ClawdbotKit/Sources/ClawdbotKit/DeviceIdentity.swift

@@ -0,0 +1,103 @@
+import CryptoKit
+import Foundation
+
+struct DeviceIdentity: Codable, Sendable {
+    var deviceId: String
+    var publicKey: String
+    var privateKey: String
+    var createdAtMs: Int
+}
+
+enum DeviceIdentityPaths {
+    private static let stateDirEnv = "CLAWDBOT_STATE_DIR"
+
+    static func stateDirURL() -> URL {
+        if let raw = getenv(self.stateDirEnv) {
+            let value = String(cString: raw).trimmingCharacters(in: .whitespacesAndNewlines)
+            if !value.isEmpty {
+                return URL(fileURLWithPath: value, isDirectory: true)
+            }
+        }
+
+        if let appSupport = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first {
+            return appSupport.appendingPathComponent("clawdbot", isDirectory: true)
+        }
+
+        return FileManager.default.temporaryDirectory.appendingPathComponent("clawdbot", isDirectory: true)
+    }
+}
+
+enum DeviceIdentityStore {
+    private static let fileName = "device.json"
+
+    static func loadOrCreate() -> DeviceIdentity {
+        let url = self.fileURL()
+        if let data = try? Data(contentsOf: url),
+           let decoded = try? JSONDecoder().decode(DeviceIdentity.self, from: data),
+           !decoded.deviceId.isEmpty,
+           !decoded.publicKey.isEmpty,
+           !decoded.privateKey.isEmpty {
+            return decoded
+        }
+        let identity = self.generate()
+        self.save(identity)
+        return identity
+    }
+
+    static func signPayload(_ payload: String, identity: DeviceIdentity) -> String? {
+        guard let privateKeyData = Data(base64Encoded: identity.privateKey) else { return nil }
+        do {
+            let privateKey = try Curve25519.Signing.PrivateKey(rawRepresentation: privateKeyData)
+            let signature = try privateKey.signature(for: Data(payload.utf8))
+            return self.base64UrlEncode(signature)
+        } catch {
+            return nil
+        }
+    }
+
+    private static func generate() -> DeviceIdentity {
+        let privateKey = Curve25519.Signing.PrivateKey()
+        let publicKey = privateKey.publicKey
+        let publicKeyData = publicKey.rawRepresentation
+        let privateKeyData = privateKey.rawRepresentation
+        let deviceId = SHA256.hash(data: publicKeyData).compactMap { String(format: "%02x", $0) }.joined()
+        return DeviceIdentity(
+            deviceId: deviceId,
+            publicKey: publicKeyData.base64EncodedString(),
+            privateKey: privateKeyData.base64EncodedString(),
+            createdAtMs: Int(Date().timeIntervalSince1970 * 1000))
+    }
+
+    private static func base64UrlEncode(_ data: Data) -> String {
+        let base64 = data.base64EncodedString()
+        return base64
+            .replacingOccurrences(of: "+", with: "-")
+            .replacingOccurrences(of: "/", with: "_")
+            .replacingOccurrences(of: "=", with: "")
+    }
+
+    static func publicKeyBase64Url(_ identity: DeviceIdentity) -> String? {
+        guard let data = Data(base64Encoded: identity.publicKey) else { return nil }
+        return self.base64UrlEncode(data)
+    }
+
+    private static func save(_ identity: DeviceIdentity) {
+        let url = self.fileURL()
+        do {
+            try FileManager.default.createDirectory(
+                at: url.deletingLastPathComponent(),
+                withIntermediateDirectories: true)
+            let data = try JSONEncoder().encode(identity)
+            try data.write(to: url, options: [.atomic])
+        } catch {
+            // best-effort only
+        }
+    }
+
+    private static func fileURL() -> URL {
+        let base = DeviceIdentityPaths.stateDirURL()
+        return base
+            .appendingPathComponent("identity", isDirectory: true)
+            .appendingPathComponent(fileName, isDirectory: false)
+    }
+}

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayChannel.swift

@@ -0,0 +1,572 @@
+import ClawdbotProtocol
+import Foundation
+import OSLog
+
+public protocol WebSocketTasking: AnyObject {
+    var state: URLSessionTask.State { get }
+    func resume()
+    func cancel(with closeCode: URLSessionWebSocketTask.CloseCode, reason: Data?)
+    func send(_ message: URLSessionWebSocketTask.Message) async throws
+    func receive() async throws -> URLSessionWebSocketTask.Message
+    func receive(completionHandler: @escaping @Sendable (Result<URLSessionWebSocketTask.Message, Error>) -> Void)
+}
+
+extension URLSessionWebSocketTask: WebSocketTasking {}
+
+public struct WebSocketTaskBox: @unchecked Sendable {
+    public let task: any WebSocketTasking
+
+    public var state: URLSessionTask.State { self.task.state }
+
+    public func resume() { self.task.resume() }
+
+    public func cancel(with closeCode: URLSessionWebSocketTask.CloseCode, reason: Data?) {
+        self.task.cancel(with: closeCode, reason: reason)
+    }
+
+    public func send(_ message: URLSessionWebSocketTask.Message) async throws {
+        try await self.task.send(message)
+    }
+
+    public func receive() async throws -> URLSessionWebSocketTask.Message {
+        try await self.task.receive()
+    }
+
+    public func receive(
+        completionHandler: @escaping @Sendable (Result<URLSessionWebSocketTask.Message, Error>) -> Void)
+    {
+        self.task.receive(completionHandler: completionHandler)
+    }
+}
+
+public protocol WebSocketSessioning: AnyObject {
+    func makeWebSocketTask(url: URL) -> WebSocketTaskBox
+}
+
+extension URLSession: WebSocketSessioning {
+    func makeWebSocketTask(url: URL) -> WebSocketTaskBox {
+        let task = self.webSocketTask(with: url)
+        // Avoid "Message too long" receive errors for large snapshots / history payloads.
+        task.maximumMessageSize = 16 * 1024 * 1024 // 16 MB
+        return WebSocketTaskBox(task: task)
+    }
+}
+
+public struct WebSocketSessionBox: @unchecked Sendable {
+    public let session: any WebSocketSessioning
+}
+
+public struct GatewayConnectOptions: Sendable {
+    public var role: String
+    public var scopes: [String]
+    public var caps: [String]
+    public var commands: [String]
+    public var permissions: [String: Bool]
+    public var clientId: String
+    public var clientMode: String
+    public var clientDisplayName: String?
+
+    public init(
+        role: String,
+        scopes: [String],
+        caps: [String],
+        commands: [String],
+        permissions: [String: Bool],
+        clientId: String,
+        clientMode: String,
+        clientDisplayName: String?)
+    {
+        self.role = role
+        self.scopes = scopes
+        self.caps = caps
+        self.commands = commands
+        self.permissions = permissions
+        self.clientId = clientId
+        self.clientMode = clientMode
+        self.clientDisplayName = clientDisplayName
+    }
+}
+
+// Avoid ambiguity with the app's own AnyCodable type.
+private typealias ProtoAnyCodable = ClawdbotProtocol.AnyCodable
+
+public actor GatewayChannelActor {
+    private let logger = Logger(subsystem: "com.clawdbot", category: "gateway")
+    private var task: WebSocketTaskBox?
+    private var pending: [String: CheckedContinuation<GatewayFrame, Error>] = [:]
+    private var connected = false
+    private var isConnecting = false
+    private var connectWaiters: [CheckedContinuation<Void, Error>] = []
+    private var url: URL
+    private var token: String?
+    private var password: String?
+    private let session: WebSocketSessioning
+    private var backoffMs: Double = 500
+    private var shouldReconnect = true
+    private var lastSeq: Int?
+    private var lastTick: Date?
+    private var tickIntervalMs: Double = 30000
+    private let decoder = JSONDecoder()
+    private let encoder = JSONEncoder()
+    private let connectTimeoutSeconds: Double = 6
+    private var watchdogTask: Task<Void, Never>?
+    private var tickTask: Task<Void, Never>?
+    private let defaultRequestTimeoutMs: Double = 15000
+    private let pushHandler: (@Sendable (GatewayPush) async -> Void)?
+    private let connectOptions: GatewayConnectOptions?
+    private let disconnectHandler: (@Sendable (String) async -> Void)?
+
+    public init(
+        url: URL,
+        token: String?,
+        password: String? = nil,
+        session: WebSocketSessionBox? = nil,
+        pushHandler: (@Sendable (GatewayPush) async -> Void)? = nil,
+        connectOptions: GatewayConnectOptions? = nil,
+        disconnectHandler: (@Sendable (String) async -> Void)? = nil)
+    {
+        self.url = url
+        self.token = token
+        self.password = password
+        self.session = session?.session ?? URLSession(configuration: .default)
+        self.pushHandler = pushHandler
+        self.connectOptions = connectOptions
+        self.disconnectHandler = disconnectHandler
+        Task { [weak self] in
+            await self?.startWatchdog()
+        }
+    }
+
+    public func shutdown() async {
+        self.shouldReconnect = false
+        self.connected = false
+
+        self.watchdogTask?.cancel()
+        self.watchdogTask = nil
+
+        self.tickTask?.cancel()
+        self.tickTask = nil
+
+        self.task?.cancel(with: .goingAway, reason: nil)
+        self.task = nil
+
+        await self.failPending(NSError(
+            domain: "Gateway",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "gateway channel shutdown"]))
+
+        let waiters = self.connectWaiters
+        self.connectWaiters.removeAll()
+        for waiter in waiters {
+            waiter.resume(throwing: NSError(
+                domain: "Gateway",
+                code: 0,
+                userInfo: [NSLocalizedDescriptionKey: "gateway channel shutdown"]))
+        }
+    }
+
+    private func startWatchdog() {
+        self.watchdogTask?.cancel()
+        self.watchdogTask = Task { [weak self] in
+            guard let self else { return }
+            await self.watchdogLoop()
+        }
+    }
+
+    private func watchdogLoop() async {
+        // Keep nudging reconnect in case exponential backoff stalls.
+        while self.shouldReconnect {
+            try? await Task.sleep(nanoseconds: 30 * 1_000_000_000) // 30s cadence
+            guard self.shouldReconnect else { return }
+            if self.connected { continue }
+            do {
+                try await self.connect()
+            } catch {
+                let wrapped = self.wrap(error, context: "gateway watchdog reconnect")
+                self.logger.error("gateway watchdog reconnect failed \(wrapped.localizedDescription, privacy: .public)")
+            }
+        }
+    }
+
+    public func connect() async throws {
+        if self.connected, self.task?.state == .running { return }
+        if self.isConnecting {
+            try await withCheckedThrowingContinuation { cont in
+                self.connectWaiters.append(cont)
+            }
+            return
+        }
+        self.isConnecting = true
+        defer { self.isConnecting = false }
+
+        self.task?.cancel(with: .goingAway, reason: nil)
+        self.task = self.session.makeWebSocketTask(url: self.url)
+        self.task?.resume()
+        do {
+            try await AsyncTimeout.withTimeout(
+                seconds: self.connectTimeoutSeconds,
+                onTimeout: {
+                    NSError(
+                        domain: "Gateway",
+                        code: 1,
+                        userInfo: [NSLocalizedDescriptionKey: "connect timed out"])
+                },
+                operation: { try await self.sendConnect() })
+        } catch {
+            let wrapped = self.wrap(error, context: "connect to gateway @ \(self.url.absoluteString)")
+            self.connected = false
+            self.task?.cancel(with: .goingAway, reason: nil)
+            await self.disconnectHandler?("connect failed: \(wrapped.localizedDescription)")
+            let waiters = self.connectWaiters
+            self.connectWaiters.removeAll()
+            for waiter in waiters {
+                waiter.resume(throwing: wrapped)
+            }
+            self.logger.error("gateway ws connect failed \(wrapped.localizedDescription, privacy: .public)")
+            throw wrapped
+        }
+        self.listen()
+        self.connected = true
+        self.backoffMs = 500
+        self.lastSeq = nil
+
+        let waiters = self.connectWaiters
+        self.connectWaiters.removeAll()
+        for waiter in waiters {
+            waiter.resume(returning: ())
+        }
+    }
+
+    private func sendConnect() async throws {
+        let platform = InstanceIdentity.platformString
+        let primaryLocale = Locale.preferredLanguages.first ?? Locale.current.identifier
+        let options = self.connectOptions ?? GatewayConnectOptions(
+            role: "operator",
+            scopes: ["operator.admin", "operator.approvals", "operator.pairing"],
+            caps: [],
+            commands: [],
+            permissions: [:],
+            clientId: "clawdbot-macos",
+            clientMode: "ui",
+            clientDisplayName: InstanceIdentity.displayName)
+        let clientDisplayName = options.clientDisplayName ?? InstanceIdentity.displayName
+        let clientId = options.clientId
+        let clientMode = options.clientMode
+
+        let reqId = UUID().uuidString
+        var client: [String: ProtoAnyCodable] = [
+            "id": ProtoAnyCodable(clientId),
+            "displayName": ProtoAnyCodable(clientDisplayName),
+            "version": ProtoAnyCodable(
+                Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "dev"),
+            "platform": ProtoAnyCodable(platform),
+            "mode": ProtoAnyCodable(clientMode),
+            "instanceId": ProtoAnyCodable(InstanceIdentity.instanceId),
+        ]
+        client["deviceFamily"] = ProtoAnyCodable(InstanceIdentity.deviceFamily)
+        if let model = InstanceIdentity.modelIdentifier {
+            client["modelIdentifier"] = ProtoAnyCodable(model)
+        }
+        var params: [String: ProtoAnyCodable] = [
+            "minProtocol": ProtoAnyCodable(GATEWAY_PROTOCOL_VERSION),
+            "maxProtocol": ProtoAnyCodable(GATEWAY_PROTOCOL_VERSION),
+            "client": ProtoAnyCodable(client),
+            "caps": ProtoAnyCodable(options.caps),
+            "locale": ProtoAnyCodable(primaryLocale),
+            "userAgent": ProtoAnyCodable(ProcessInfo.processInfo.operatingSystemVersionString),
+            "role": ProtoAnyCodable(options.role),
+            "scopes": ProtoAnyCodable(options.scopes),
+        ]
+        if !options.commands.isEmpty {
+            params["commands"] = ProtoAnyCodable(options.commands)
+        }
+        if !options.permissions.isEmpty {
+            params["permissions"] = ProtoAnyCodable(options.permissions)
+        }
+        if let token = self.token {
+            params["auth"] = ProtoAnyCodable(["token": ProtoAnyCodable(token)])
+        } else if let password = self.password {
+            params["auth"] = ProtoAnyCodable(["password": ProtoAnyCodable(password)])
+        }
+        let identity = DeviceIdentityStore.loadOrCreate()
+        let signedAtMs = Int(Date().timeIntervalSince1970 * 1000)
+        let scopes = options.scopes.joined(separator: ",")
+        let payload = [
+            "v1",
+            identity.deviceId,
+            clientId,
+            clientMode,
+            options.role,
+            scopes,
+            String(signedAtMs),
+            self.token ?? "",
+        ].joined(separator: "|")
+        if let signature = DeviceIdentityStore.signPayload(payload, identity: identity),
+           let publicKey = DeviceIdentityStore.publicKeyBase64Url(identity) {
+            params["device"] = ProtoAnyCodable([
+                "id": ProtoAnyCodable(identity.deviceId),
+                "publicKey": ProtoAnyCodable(publicKey),
+                "signature": ProtoAnyCodable(signature),
+                "signedAt": ProtoAnyCodable(signedAtMs),
+            ])
+        }
+
+        let frame = RequestFrame(
+            type: "req",
+            id: reqId,
+            method: "connect",
+            params: ProtoAnyCodable(params))
+        let data = try self.encoder.encode(frame)
+        try await self.task?.send(.data(data))
+        guard let msg = try await task?.receive() else {
+            throw NSError(
+                domain: "Gateway",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "connect failed (no response)"])
+        }
+        try await self.handleConnectResponse(msg, reqId: reqId)
+    }
+
+    private func handleConnectResponse(_ msg: URLSessionWebSocketTask.Message, reqId: String) async throws {
+        let data: Data? = switch msg {
+        case let .data(d): d
+        case let .string(s): s.data(using: .utf8)
+        @unknown default: nil
+        }
+        guard let data else {
+            throw NSError(
+                domain: "Gateway",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "connect failed (empty response)"])
+        }
+        let decoder = JSONDecoder()
+        guard let frame = try? decoder.decode(GatewayFrame.self, from: data) else {
+            throw NSError(
+                domain: "Gateway",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "connect failed (invalid response)"])
+        }
+        guard case let .res(res) = frame, res.id == reqId else {
+            throw NSError(
+                domain: "Gateway",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "connect failed (unexpected response)"])
+        }
+        if res.ok == false {
+            let msg = (res.error?["message"]?.value as? String) ?? "gateway connect failed"
+            throw NSError(domain: "Gateway", code: 1008, userInfo: [NSLocalizedDescriptionKey: msg])
+        }
+        guard let payload = res.payload else {
+            throw NSError(
+                domain: "Gateway",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "connect failed (missing payload)"])
+        }
+        let payloadData = try self.encoder.encode(payload)
+        let ok = try decoder.decode(HelloOk.self, from: payloadData)
+        if let tick = ok.policy["tickIntervalMs"]?.value as? Double {
+            self.tickIntervalMs = tick
+        } else if let tick = ok.policy["tickIntervalMs"]?.value as? Int {
+            self.tickIntervalMs = Double(tick)
+        }
+        self.lastTick = Date()
+        self.tickTask?.cancel()
+        self.tickTask = Task { [weak self] in
+            guard let self else { return }
+            await self.watchTicks()
+        }
+        await self.pushHandler?(.snapshot(ok))
+    }
+
+    private func listen() {
+        self.task?.receive { [weak self] result in
+            guard let self else { return }
+            switch result {
+            case let .failure(err):
+                Task { await self.handleReceiveFailure(err) }
+            case let .success(msg):
+                Task {
+                    await self.handle(msg)
+                    await self.listen()
+                }
+            }
+        }
+    }
+
+    private func handleReceiveFailure(_ err: Error) async {
+        let wrapped = self.wrap(err, context: "gateway receive")
+        self.logger.error("gateway ws receive failed \(wrapped.localizedDescription, privacy: .public)")
+        self.connected = false
+        await self.disconnectHandler?("receive failed: \(wrapped.localizedDescription)")
+        await self.failPending(wrapped)
+        await self.scheduleReconnect()
+    }
+
+    private func handle(_ msg: URLSessionWebSocketTask.Message) async {
+        let data: Data? = switch msg {
+        case let .data(d): d
+        case let .string(s): s.data(using: .utf8)
+        @unknown default: nil
+        }
+        guard let data else { return }
+        guard let frame = try? self.decoder.decode(GatewayFrame.self, from: data) else {
+            self.logger.error("gateway decode failed")
+            return
+        }
+        switch frame {
+        case let .res(res):
+            let id = res.id
+            if let waiter = pending.removeValue(forKey: id) {
+                waiter.resume(returning: .res(res))
+            }
+        case let .event(evt):
+            if let seq = evt.seq {
+                if let last = lastSeq, seq > last + 1 {
+                    await self.pushHandler?(.seqGap(expected: last + 1, received: seq))
+                }
+                self.lastSeq = seq
+            }
+            if evt.event == "tick" { self.lastTick = Date() }
+            await self.pushHandler?(.event(evt))
+        default:
+            break
+        }
+    }
+
+    private func watchTicks() async {
+        let tolerance = self.tickIntervalMs * 2
+        while self.connected {
+            try? await Task.sleep(nanoseconds: UInt64(tolerance * 1_000_000))
+            guard self.connected else { return }
+            if let last = self.lastTick {
+                let delta = Date().timeIntervalSince(last) * 1000
+                if delta > tolerance {
+                    self.logger.error("gateway tick missed; reconnecting")
+                    self.connected = false
+                    await self.failPending(
+                        NSError(
+                            domain: "Gateway",
+                            code: 4,
+                            userInfo: [NSLocalizedDescriptionKey: "gateway tick missed; reconnecting"]))
+                    await self.scheduleReconnect()
+                    return
+                }
+            }
+        }
+    }
+
+    private func scheduleReconnect() async {
+        guard self.shouldReconnect else { return }
+        let delay = self.backoffMs / 1000
+        self.backoffMs = min(self.backoffMs * 2, 30000)
+        try? await Task.sleep(nanoseconds: UInt64(delay * 1_000_000_000))
+        guard self.shouldReconnect else { return }
+        do {
+            try await self.connect()
+        } catch {
+            let wrapped = self.wrap(error, context: "gateway reconnect")
+            self.logger.error("gateway reconnect failed \(wrapped.localizedDescription, privacy: .public)")
+            await self.scheduleReconnect()
+        }
+    }
+
+    public func request(
+        method: String,
+        params: [String: ClawdbotProtocol.AnyCodable]?,
+        timeoutMs: Double? = nil) async throws -> Data
+    {
+        do {
+            try await self.connect()
+        } catch {
+            throw self.wrap(error, context: "gateway connect")
+        }
+        let id = UUID().uuidString
+        let effectiveTimeout = timeoutMs ?? self.defaultRequestTimeoutMs
+        // Encode request using the generated models to avoid JSONSerialization/ObjC bridging pitfalls.
+        let paramsObject: ProtoAnyCodable? = params.map { entries in
+            let dict = entries.reduce(into: [String: ProtoAnyCodable]()) { dict, entry in
+                dict[entry.key] = ProtoAnyCodable(entry.value.value)
+            }
+            return ProtoAnyCodable(dict)
+        }
+        let frame = RequestFrame(
+            type: "req",
+            id: id,
+            method: method,
+            params: paramsObject)
+        let data = try self.encoder.encode(frame)
+        let response = try await withCheckedThrowingContinuation { (cont: CheckedContinuation<GatewayFrame, Error>) in
+            self.pending[id] = cont
+            Task { [weak self] in
+                guard let self else { return }
+                try? await Task.sleep(nanoseconds: UInt64(effectiveTimeout * 1_000_000))
+                await self.timeoutRequest(id: id, timeoutMs: effectiveTimeout)
+            }
+            Task {
+                do {
+                    try await self.task?.send(.data(data))
+                } catch {
+                    let wrapped = self.wrap(error, context: "gateway send \(method)")
+                    let waiter = self.pending.removeValue(forKey: id)
+                    // Treat send failures as a broken socket: mark disconnected and trigger reconnect.
+                    self.connected = false
+                    self.task?.cancel(with: .goingAway, reason: nil)
+                    Task { [weak self] in
+                        guard let self else { return }
+                        await self.scheduleReconnect()
+                    }
+                    if let waiter { waiter.resume(throwing: wrapped) }
+                }
+            }
+        }
+        guard case let .res(res) = response else {
+            throw NSError(domain: "Gateway", code: 2, userInfo: [NSLocalizedDescriptionKey: "unexpected frame"])
+        }
+        if res.ok == false {
+            let code = res.error?["code"]?.value as? String
+            let msg = res.error?["message"]?.value as? String
+            let details: [String: ClawdbotProtocol.AnyCodable] = (res.error ?? [:]).reduce(into: [:]) { acc, pair in
+                acc[pair.key] = ClawdbotProtocol.AnyCodable(pair.value.value)
+            }
+            throw GatewayResponseError(method: method, code: code, message: msg, details: details)
+        }
+        if let payload = res.payload {
+            // Encode back to JSON with Swift's encoder to preserve types and avoid ObjC bridging exceptions.
+            return try self.encoder.encode(payload)
+        }
+        return Data() // Should not happen, but tolerate empty payloads.
+    }
+
+    // Wrap low-level URLSession/WebSocket errors with context so UI can surface them.
+    private func wrap(_ error: Error, context: String) -> Error {
+        if let urlError = error as? URLError {
+            let desc = urlError.localizedDescription.isEmpty ? "cancelled" : urlError.localizedDescription
+            return NSError(
+                domain: URLError.errorDomain,
+                code: urlError.errorCode,
+                userInfo: [NSLocalizedDescriptionKey: "\(context): \(desc)"])
+        }
+        let ns = error as NSError
+        let desc = ns.localizedDescription.isEmpty ? "unknown" : ns.localizedDescription
+        return NSError(domain: ns.domain, code: ns.code, userInfo: [NSLocalizedDescriptionKey: "\(context): \(desc)"])
+    }
+
+    private func failPending(_ error: Error) async {
+        let waiters = self.pending
+        self.pending.removeAll()
+        for (_, waiter) in waiters {
+            waiter.resume(throwing: error)
+        }
+    }
+
+    private func timeoutRequest(id: String, timeoutMs: Double) async {
+        guard let waiter = self.pending.removeValue(forKey: id) else { return }
+        let err = NSError(
+            domain: "Gateway",
+            code: 5,
+            userInfo: [NSLocalizedDescriptionKey: "gateway request timed out after \(Int(timeoutMs))ms"])
+        waiter.resume(throwing: err)
+    }
+}
+
+// Intentionally no `GatewayChannel` wrapper: the app should use the single shared `GatewayConnection`.

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayEndpointID.swift

@@ -0,0 +1,25 @@
+import Foundation
+import Network
+
+public enum GatewayEndpointID {
+    public static func stableID(_ endpoint: NWEndpoint) -> String {
+        switch endpoint {
+        case let .service(name, type, domain, _):
+            // Keep stable across encoded/decoded differences (e.g. \032 for spaces).
+            let normalizedName = Self.normalizeServiceNameForID(name)
+            return "\(type)|\(domain)|\(normalizedName)"
+        default:
+            return String(describing: endpoint)
+        }
+    }
+
+    public static func prettyDescription(_ endpoint: NWEndpoint) -> String {
+        BonjourEscapes.decode(String(describing: endpoint))
+    }
+
+    private static func normalizeServiceNameForID(_ rawName: String) -> String {
+        let decoded = BonjourEscapes.decode(rawName)
+        let normalized = decoded.split(whereSeparator: \.isWhitespace).joined(separator: " ")
+        return normalized.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayErrors.swift

@@ -0,0 +1,33 @@
+import ClawdbotProtocol
+import Foundation
+
+/// Structured error surfaced when the gateway responds with `{ ok: false }`.
+public struct GatewayResponseError: LocalizedError, @unchecked Sendable {
+    public let method: String
+    public let code: String
+    public let message: String
+    public let details: [String: AnyCodable]
+
+    public init(method: String, code: String?, message: String?, details: [String: AnyCodable]?) {
+        self.method = method
+        self.code = (code?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false)
+            ? code!.trimmingCharacters(in: .whitespacesAndNewlines)
+            : "GATEWAY_ERROR"
+        self.message = (message?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false)
+            ? message!.trimmingCharacters(in: .whitespacesAndNewlines)
+            : "gateway error"
+        self.details = details ?? [:]
+    }
+
+    public var errorDescription: String? {
+        if self.code == "GATEWAY_ERROR" { return "\(self.method): \(self.message)" }
+        return "\(self.method): [\(self.code)] \(self.message)"
+    }
+}
+
+public struct GatewayDecodingError: LocalizedError, Sendable {
+    public let method: String
+    public let message: String
+
+    public var errorDescription: String? { "\(self.method): \(self.message)" }
+}

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayNodeSession.swift

@@ -0,0 +1,225 @@
+import ClawdbotProtocol
+import Foundation
+import OSLog
+
+private struct NodeInvokeRequestPayload: Codable, Sendable {
+    var id: String
+    var nodeId: String
+    var command: String
+    var paramsJSON: String?
+    var timeoutMs: Int?
+    var idempotencyKey: String?
+}
+
+public actor GatewayNodeSession {
+    private let logger = Logger(subsystem: "com.clawdbot", category: "node.gateway")
+    private let decoder = JSONDecoder()
+    private let encoder = JSONEncoder()
+    private var channel: GatewayChannelActor?
+    private var activeURL: URL?
+    private var activeToken: String?
+    private var activePassword: String?
+    private var connectOptions: GatewayConnectOptions?
+    private var onConnected: (@Sendable () async -> Void)?
+    private var onDisconnected: (@Sendable (String) async -> Void)?
+    private var onInvoke: (@Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse)?
+    private var serverEventSubscribers: [UUID: AsyncStream<EventFrame>.Continuation] = [:]
+    private var canvasHostUrl: String?
+
+    public func connect(
+        url: URL,
+        token: String?,
+        password: String?,
+        connectOptions: GatewayConnectOptions,
+        sessionBox: WebSocketSessionBox?,
+        onConnected: @escaping @Sendable () async -> Void,
+        onDisconnected: @escaping @Sendable (String) async -> Void,
+        onInvoke: @escaping @Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse
+    ) async throws {
+        let shouldReconnect = self.activeURL != url ||
+            self.activeToken != token ||
+            self.activePassword != password ||
+            self.channel == nil
+
+        self.connectOptions = connectOptions
+        self.onConnected = onConnected
+        self.onDisconnected = onDisconnected
+        self.onInvoke = onInvoke
+
+        if shouldReconnect {
+            if let existing = self.channel {
+                await existing.shutdown()
+            }
+            let channel = GatewayChannelActor(
+                url: url,
+                token: token,
+                password: password,
+                session: sessionBox,
+                pushHandler: { [weak self] push in
+                    await self?.handlePush(push)
+                },
+                connectOptions: connectOptions,
+                disconnectHandler: { [weak self] reason in
+                    await self?.onDisconnected?(reason)
+                })
+            self.channel = channel
+            self.activeURL = url
+            self.activeToken = token
+            self.activePassword = password
+        }
+
+        guard let channel = self.channel else {
+            throw NSError(domain: "Gateway", code: 0, userInfo: [
+                NSLocalizedDescriptionKey: "gateway channel unavailable",
+            ])
+        }
+
+        do {
+            try await channel.connect()
+            await onConnected()
+        } catch {
+            await onDisconnected(error.localizedDescription)
+            throw error
+        }
+    }
+
+    public func disconnect() async {
+        await self.channel?.shutdown()
+        self.channel = nil
+        self.activeURL = nil
+        self.activeToken = nil
+        self.activePassword = nil
+    }
+
+    public func currentCanvasHostUrl() -> String? {
+        self.canvasHostUrl
+    }
+
+    public func currentRemoteAddress() -> String? {
+        guard let url = self.activeURL else { return nil }
+        guard let host = url.host else { return url.absoluteString }
+        let port = url.port ?? (url.scheme == "wss" ? 443 : 80)
+        if host.contains(":") {
+            return "[\(host)]:\(port)"
+        }
+        return "\(host):\(port)"
+    }
+
+    public func sendEvent(event: String, payloadJSON: String?) async {
+        guard let channel = self.channel else { return }
+        let params: [String: ClawdbotProtocol.AnyCodable] = [
+            "event": ClawdbotProtocol.AnyCodable(event),
+            "payloadJSON": ClawdbotProtocol.AnyCodable(payloadJSON ?? NSNull()),
+        ]
+        do {
+            _ = try await channel.request(method: "node.event", params: params, timeoutMs: 8000)
+        } catch {
+            self.logger.error("node event failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    public func request(method: String, paramsJSON: String?, timeoutSeconds: Int = 15) async throws -> Data {
+        guard let channel = self.channel else {
+            throw NSError(domain: "Gateway", code: 11, userInfo: [
+                NSLocalizedDescriptionKey: "not connected",
+            ])
+        }
+
+        let params = try self.decodeParamsJSON(paramsJSON)
+        return try await channel.request(
+            method: method,
+            params: params,
+            timeoutMs: Double(timeoutSeconds * 1000))
+    }
+
+    public func subscribeServerEvents(bufferingNewest: Int = 200) -> AsyncStream<EventFrame> {
+        let id = UUID()
+        let session = self
+        return AsyncStream(bufferingPolicy: .bufferingNewest(bufferingNewest)) { continuation in
+            self.serverEventSubscribers[id] = continuation
+            continuation.onTermination = { @Sendable _ in
+                Task { await session.removeServerEventSubscriber(id) }
+            }
+        }
+    }
+
+    private func handlePush(_ push: GatewayPush) async {
+        switch push {
+        case let .snapshot(ok):
+            let raw = ok.canvashosturl?.trimmingCharacters(in: .whitespacesAndNewlines)
+            self.canvasHostUrl = (raw?.isEmpty == false) ? raw : nil
+            await self.onConnected?()
+        case let .event(evt):
+            await self.handleEvent(evt)
+        default:
+            break
+        }
+    }
+
+    private func handleEvent(_ evt: EventFrame) async {
+        self.broadcastServerEvent(evt)
+        guard evt.event == "node.invoke.request" else { return }
+        guard let payload = evt.payload else { return }
+        do {
+            let data = try self.encoder.encode(payload)
+            let request = try self.decoder.decode(NodeInvokeRequestPayload.self, from: data)
+            guard let onInvoke else { return }
+            let req = BridgeInvokeRequest(id: request.id, command: request.command, paramsJSON: request.paramsJSON)
+            let response = await onInvoke(req)
+            await self.sendInvokeResult(request: request, response: response)
+        } catch {
+            self.logger.error("node invoke decode failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func sendInvokeResult(request: NodeInvokeRequestPayload, response: BridgeInvokeResponse) async {
+        guard let channel = self.channel else { return }
+        var params: [String: ClawdbotProtocol.AnyCodable] = [
+            "id": ClawdbotProtocol.AnyCodable(request.id),
+            "nodeId": ClawdbotProtocol.AnyCodable(request.nodeId),
+            "ok": ClawdbotProtocol.AnyCodable(response.ok),
+            "payloadJSON": ClawdbotProtocol.AnyCodable(response.payloadJSON ?? NSNull()),
+        ]
+        if let error = response.error {
+            params["error"] = ClawdbotProtocol.AnyCodable([
+                "code": ClawdbotProtocol.AnyCodable(error.code.rawValue),
+                "message": ClawdbotProtocol.AnyCodable(error.message),
+            ])
+        }
+        do {
+            _ = try await channel.request(method: "node.invoke.result", params: params, timeoutMs: 15000)
+        } catch {
+            self.logger.error("node invoke result failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func decodeParamsJSON(
+        _ paramsJSON: String?) throws -> [String: ClawdbotProtocol.AnyCodable]?
+    {
+        guard let paramsJSON, !paramsJSON.isEmpty else { return nil }
+        guard let data = paramsJSON.data(using: .utf8) else {
+            throw NSError(domain: "Gateway", code: 12, userInfo: [
+                NSLocalizedDescriptionKey: "paramsJSON not UTF-8",
+            ])
+        }
+        let raw = try JSONSerialization.jsonObject(with: data)
+        guard let dict = raw as? [String: Any] else {
+            return nil
+        }
+        return dict.reduce(into: [:]) { acc, entry in
+            acc[entry.key] = ClawdbotProtocol.AnyCodable(entry.value)
+        }
+    }
+
+    private func broadcastServerEvent(_ evt: EventFrame) {
+        for (id, continuation) in self.serverEventSubscribers {
+            if continuation.yield(evt) == .terminated {
+                self.serverEventSubscribers.removeValue(forKey: id)
+            }
+        }
+    }
+
+    private func removeServerEventSubscriber(_ id: UUID) {
+        self.serverEventSubscribers.removeValue(forKey: id)
+    }
+}

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayPayloadDecoding.swift

@@ -0,0 +1,20 @@
+import ClawdbotProtocol
+import Foundation
+
+public enum GatewayPayloadDecoding {
+    public static func decode<T: Decodable>(
+        _ payload: ClawdbotProtocol.AnyCodable,
+        as _: T.Type = T.self) throws -> T
+    {
+        let data = try JSONEncoder().encode(payload)
+        return try JSONDecoder().decode(T.self, from: data)
+    }
+
+    public static func decodeIfPresent<T: Decodable>(
+        _ payload: ClawdbotProtocol.AnyCodable?,
+        as _: T.Type = T.self) throws -> T?
+    {
+        guard let payload else { return nil }
+        return try self.decode(payload, as: T.self)
+    }
+}

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayPush.swift

@@ -0,0 +1,13 @@
+import ClawdbotProtocol
+
+/// Server-push messages from the gateway websocket.
+///
+/// This is the in-process replacement for the legacy `NotificationCenter` fan-out.
+public enum GatewayPush: Sendable {
+    /// A full snapshot that arrives on connect (or reconnect).
+    case snapshot(HelloOk)
+    /// A server push event frame.
+    case event(EventFrame)
+    /// A detected sequence gap (`expected...received`) for event frames.
+    case seqGap(expected: Int, received: Int)
+}

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayTLSPinning.swift

@@ -0,0 +1,112 @@
+import CryptoKit
+import Foundation
+import Security
+
+public struct GatewayTLSParams: Sendable {
+    public let required: Bool
+    public let expectedFingerprint: String?
+    public let allowTOFU: Bool
+    public let storeKey: String?
+
+    public init(required: Bool, expectedFingerprint: String?, allowTOFU: Bool, storeKey: String?) {
+        self.required = required
+        self.expectedFingerprint = expectedFingerprint
+        self.allowTOFU = allowTOFU
+        self.storeKey = storeKey
+    }
+}
+
+public enum GatewayTLSStore {
+    private static let suiteName = "com.clawdbot.shared"
+    private static let keyPrefix = "gateway.tls."
+
+    private static var defaults: UserDefaults {
+        UserDefaults(suiteName: suiteName) ?? .standard
+    }
+
+    public static func loadFingerprint(stableID: String) -> String? {
+        let key = self.keyPrefix + stableID
+        let raw = self.defaults.string(forKey: key)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return raw?.isEmpty == false ? raw : nil
+    }
+
+    public static func saveFingerprint(_ value: String, stableID: String) {
+        let key = self.keyPrefix + stableID
+        self.defaults.set(value, forKey: key)
+    }
+}
+
+public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLSessionDelegate {
+    private let params: GatewayTLSParams
+    private lazy var session: URLSession = {
+        let config = URLSessionConfiguration.default
+        config.waitsForConnectivity = true
+        return URLSession(configuration: config, delegate: self, delegateQueue: nil)
+    }()
+
+    public init(params: GatewayTLSParams) {
+        self.params = params
+        super.init()
+    }
+
+    public func makeWebSocketTask(url: URL) -> WebSocketTaskBox {
+        let task = self.session.webSocketTask(with: url)
+        task.maximumMessageSize = 16 * 1024 * 1024
+        return WebSocketTaskBox(task: task)
+    }
+
+    public func urlSession(
+        _ session: URLSession,
+        didReceive challenge: URLAuthenticationChallenge,
+        completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void
+    ) {
+        guard challenge.protectionSpace.authenticationMethod == NSURLAuthenticationMethodServerTrust,
+              let trust = challenge.protectionSpace.serverTrust
+        else {
+            completionHandler(.performDefaultHandling, nil)
+            return
+        }
+
+        let expected = params.expectedFingerprint.map(normalizeFingerprint)
+        if let fingerprint = certificateFingerprint(trust) {
+            if let expected {
+                if fingerprint == expected {
+                    completionHandler(.useCredential, URLCredential(trust: trust))
+                } else {
+                    completionHandler(.cancelAuthenticationChallenge, nil)
+                }
+                return
+            }
+            if params.allowTOFU {
+                if let storeKey = params.storeKey {
+                    GatewayTLSStore.saveFingerprint(fingerprint, stableID: storeKey)
+                }
+                completionHandler(.useCredential, URLCredential(trust: trust))
+                return
+            }
+        }
+
+        let ok = SecTrustEvaluateWithError(trust, nil)
+        if ok || !params.required {
+            completionHandler(.useCredential, URLCredential(trust: trust))
+        } else {
+            completionHandler(.cancelAuthenticationChallenge, nil)
+        }
+    }
+}
+
+private func certificateFingerprint(_ trust: SecTrust) -> String? {
+    let count = SecTrustGetCertificateCount(trust)
+    guard count > 0, let cert = SecTrustGetCertificateAtIndex(trust, 0) else { return nil }
+    let data = SecCertificateCopyData(cert) as Data
+    return sha256Hex(data)
+}
+
+private func sha256Hex(_ data: Data) -> String {
+    let digest = SHA256.hash(data: data)
+    return digest.map { String(format: "%02x", $0) }.joined()
+}
+
+private func normalizeFingerprint(_ raw: String) -> String {
+    raw.lowercased().filter(\.isHexDigit)
+}

apps/shared/ClawdbotKit/Sources/ClawdbotKit/InstanceIdentity.swift

@@ -0,0 +1,92 @@
+import Foundation
+
+#if canImport(UIKit)
+import UIKit
+#endif
+
+public enum InstanceIdentity {
+    private static let suiteName = "com.clawdbot.shared"
+    private static let instanceIdKey = "instanceId"
+
+    private static var defaults: UserDefaults {
+        UserDefaults(suiteName: suiteName) ?? .standard
+    }
+
+    public static let instanceId: String = {
+        let defaults = Self.defaults
+        if let existing = defaults.string(forKey: instanceIdKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+            !existing.isEmpty
+        {
+            return existing
+        }
+
+        let id = UUID().uuidString.lowercased()
+        defaults.set(id, forKey: instanceIdKey)
+        return id
+    }()
+
+    public static let displayName: String = {
+#if canImport(UIKit)
+        let name = UIDevice.current.name.trimmingCharacters(in: .whitespacesAndNewlines)
+        return name.isEmpty ? "clawdbot" : name
+#else
+        if let name = Host.current().localizedName?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !name.isEmpty
+        {
+            return name
+        }
+        return "clawdbot"
+#endif
+    }()
+
+    public static let modelIdentifier: String? = {
+#if canImport(UIKit)
+        var systemInfo = utsname()
+        uname(&systemInfo)
+        let machine = withUnsafeBytes(of: &systemInfo.machine) { ptr in
+            String(bytes: ptr.prefix { $0 != 0 }, encoding: .utf8)
+        }
+        let trimmed = machine?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+#else
+        var size = 0
+        guard sysctlbyname("hw.model", nil, &size, nil, 0) == 0, size > 1 else { return nil }
+
+        var buffer = [CChar](repeating: 0, count: size)
+        guard sysctlbyname("hw.model", &buffer, &size, nil, 0) == 0 else { return nil }
+
+        let bytes = buffer.prefix { $0 != 0 }.map { UInt8(bitPattern: $0) }
+        guard let raw = String(bytes: bytes, encoding: .utf8) else { return nil }
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+#endif
+    }()
+
+    public static let deviceFamily: String = {
+#if canImport(UIKit)
+        switch UIDevice.current.userInterfaceIdiom {
+        case .pad: return "iPad"
+        case .phone: return "iPhone"
+        default: return "iOS"
+        }
+#else
+        return "Mac"
+#endif
+    }()
+
+    public static let platformString: String = {
+        let v = ProcessInfo.processInfo.operatingSystemVersion
+#if canImport(UIKit)
+        let name: String
+        switch UIDevice.current.userInterfaceIdiom {
+        case .pad: name = "iPadOS"
+        case .phone: name = "iOS"
+        default: name = "iOS"
+        }
+        return "\(name) \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
+#else
+        return "macOS \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
+#endif
+    }()
+}

apps/shared/ClawdbotKit/Sources/ClawdbotProtocol/AnyCodable.swift

@@ -0,0 +1,54 @@
+import Foundation
+
+/// Lightweight `Codable` wrapper that round-trips heterogeneous JSON payloads.
+/// Marked `@unchecked Sendable` because it can hold reference types.
+public struct AnyCodable: Codable, @unchecked Sendable {
+    public let value: Any
+
+    public init(_ value: Any) { self.value = value }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.singleValueContainer()
+        if let intVal = try? container.decode(Int.self) { self.value = intVal; return }
+        if let doubleVal = try? container.decode(Double.self) { self.value = doubleVal; return }
+        if let boolVal = try? container.decode(Bool.self) { self.value = boolVal; return }
+        if let stringVal = try? container.decode(String.self) { self.value = stringVal; return }
+        if container.decodeNil() { self.value = NSNull(); return }
+        if let dict = try? container.decode([String: AnyCodable].self) { self.value = dict; return }
+        if let array = try? container.decode([AnyCodable].self) { self.value = array; return }
+        throw DecodingError.dataCorruptedError(
+            in: container,
+            debugDescription: "Unsupported type")
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.singleValueContainer()
+        switch self.value {
+        case let intVal as Int: try container.encode(intVal)
+        case let doubleVal as Double: try container.encode(doubleVal)
+        case let boolVal as Bool: try container.encode(boolVal)
+        case let stringVal as String: try container.encode(stringVal)
+        case is NSNull: try container.encodeNil()
+        case let dict as [String: AnyCodable]: try container.encode(dict)
+        case let array as [AnyCodable]: try container.encode(array)
+        case let dict as [String: Any]:
+            try container.encode(dict.mapValues { AnyCodable($0) })
+        case let array as [Any]:
+            try container.encode(array.map { AnyCodable($0) })
+        case let dict as NSDictionary:
+            var converted: [String: AnyCodable] = [:]
+            for (k, v) in dict {
+                guard let key = k as? String else { continue }
+                converted[key] = AnyCodable(v)
+            }
+            try container.encode(converted)
+        case let array as NSArray:
+            try container.encode(array.map { AnyCodable($0) })
+        default:
+            let context = EncodingError.Context(
+                codingPath: encoder.codingPath,
+                debugDescription: "Unsupported type")
+            throw EncodingError.invalidValue(self.value, context)
+        }
+    }
+}

apps/shared/ClawdbotKit/Sources/ClawdbotProtocol/WizardHelpers.swift

@@ -0,0 +1,106 @@
+import Foundation
+
+public struct WizardOption: Sendable {
+    public let value: AnyCodable?
+    public let label: String
+    public let hint: String?
+
+    public init(value: AnyCodable?, label: String, hint: String?) {
+        self.value = value
+        self.label = label
+        self.hint = hint
+    }
+}
+
+public func decodeWizardStep(_ raw: [String: AnyCodable]?) -> WizardStep? {
+    guard let raw else { return nil }
+    do {
+        let data = try JSONEncoder().encode(raw)
+        return try JSONDecoder().decode(WizardStep.self, from: data)
+    } catch {
+        return nil
+    }
+}
+
+public func parseWizardOptions(_ raw: [[String: AnyCodable]]?) -> [WizardOption] {
+    guard let raw else { return [] }
+    return raw.map { entry in
+        let value = entry["value"]
+        let label = (entry["label"]?.value as? String) ?? ""
+        let hint = entry["hint"]?.value as? String
+        return WizardOption(value: value, label: label, hint: hint)
+    }
+}
+
+public func wizardStatusString(_ value: AnyCodable?) -> String? {
+    (value?.value as? String)?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+}
+
+public func wizardStepType(_ step: WizardStep) -> String {
+    (step.type.value as? String) ?? ""
+}
+
+public func anyCodableString(_ value: AnyCodable?) -> String {
+    switch value?.value {
+    case let string as String:
+        string
+    case let int as Int:
+        String(int)
+    case let double as Double:
+        String(double)
+    case let bool as Bool:
+        bool ? "true" : "false"
+    default:
+        ""
+    }
+}
+
+public func anyCodableBool(_ value: AnyCodable?) -> Bool {
+    switch value?.value {
+    case let bool as Bool:
+        return bool
+    case let int as Int:
+        return int != 0
+    case let double as Double:
+        return double != 0
+    case let string as String:
+        let trimmed = string.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed == "true" || trimmed == "1" || trimmed == "yes"
+    default:
+        return false
+    }
+}
+
+public func anyCodableArray(_ value: AnyCodable?) -> [AnyCodable] {
+    switch value?.value {
+    case let arr as [AnyCodable]:
+        return arr
+    case let arr as [Any]:
+        return arr.map { AnyCodable($0) }
+    default:
+        return []
+    }
+}
+
+public func anyCodableEqual(_ lhs: AnyCodable?, _ rhs: AnyCodable?) -> Bool {
+    switch (lhs?.value, rhs?.value) {
+    case let (l as String, r as String):
+        l == r
+    case let (l as Int, r as Int):
+        l == r
+    case let (l as Double, r as Double):
+        l == r
+    case let (l as Bool, r as Bool):
+        l == r
+    case let (l as String, r as Int):
+        l == String(r)
+    case let (l as Int, r as String):
+        String(l) == r
+    case let (l as String, r as Double):
+        l == String(r)
+    case let (l as Double, r as String):
+        String(l) == r
+    default:
+        false
+    }
+}