Vendor OpenClaw source as Adolf fork baseline

Adolf is a fork/vendored clone of github.com/openclaw/openclaw (v2026.6.11),
free to diverge. Tree copied sans upstream .git; upstream remote added for
future syncs. Node pinned to 24 (.nvmrc); engines already require >=22.19.
Preserves docs/ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LeqyaxJF2nbRXJtae2kNB2

apps/shared/OpenClawKit/Package.swift

@@ -0,0 +1,60 @@
+// swift-tools-version: 6.2
+
+import PackageDescription
+
+let package = Package(
+    name: "OpenClawKit",
+    platforms: [
+        .iOS(.v18),
+        .macOS(.v15),
+    ],
+    products: [
+        .library(name: "OpenClawProtocol", targets: ["OpenClawProtocol"]),
+        .library(name: "OpenClawKit", targets: ["OpenClawKit"]),
+        .library(name: "OpenClawChatUI", targets: ["OpenClawChatUI"]),
+    ],
+    traits: [
+        .trait(name: "Talk", description: "ElevenLabs cloud TTS / talk support"),
+        .default(enabledTraits: ["Talk"]),
+    ],
+    dependencies: [
+        .package(url: "https://github.com/steipete/ElevenLabsKit", exact: "0.1.1"),
+    ],
+    targets: [
+        .target(
+            name: "OpenClawProtocol",
+            path: "Sources/OpenClawProtocol",
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+            ]),
+        .target(
+            name: "OpenClawKit",
+            dependencies: [
+                "OpenClawProtocol",
+                .product(name: "ElevenLabsKit", package: "ElevenLabsKit", condition: .when(traits: ["Talk"])),
+            ],
+            path: "Sources/OpenClawKit",
+            resources: [
+                .process("Resources"),
+            ],
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+            ]),
+        .target(
+            name: "OpenClawChatUI",
+            dependencies: [
+                "OpenClawKit",
+            ],
+            path: "Sources/OpenClawChatUI",
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+            ]),
+        .testTarget(
+            name: "OpenClawKitTests",
+            dependencies: ["OpenClawKit", "OpenClawChatUI"],
+            path: "Tests/OpenClawKitTests",
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+                .enableExperimentalFeature("SwiftTesting"),
+            ]),
+    ])

apps/shared/OpenClawKit/Sources/OpenClawChatUI/AssistantTextParser.swift

@@ -0,0 +1,151 @@
+import Foundation
+
+struct AssistantTextSegment: Identifiable {
+    enum Kind {
+        case thinking
+        case response
+    }
+
+    let id = UUID()
+    let kind: Kind
+    let text: String
+}
+
+enum AssistantTextParser {
+    static func segments(from raw: String, includeThinking: Bool = true) -> [AssistantTextSegment] {
+        let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return [] }
+        guard raw.contains("<") else {
+            return [AssistantTextSegment(kind: .response, text: trimmed)]
+        }
+
+        var segments: [AssistantTextSegment] = []
+        var cursor = raw.startIndex
+        var currentKind: AssistantTextSegment.Kind = .response
+        var matchedTag = false
+
+        while let match = self.nextTag(in: raw, from: cursor) {
+            matchedTag = true
+            if match.range.lowerBound > cursor {
+                self.appendSegment(kind: currentKind, text: raw[cursor..<match.range.lowerBound], to: &segments)
+            }
+
+            guard let tagEnd = raw.range(of: ">", range: match.range.upperBound..<raw.endIndex) else {
+                cursor = raw.endIndex
+                break
+            }
+
+            let isSelfClosing = self.isSelfClosingTag(in: raw, tagEnd: tagEnd)
+            cursor = tagEnd.upperBound
+            if isSelfClosing { continue }
+
+            if match.closing {
+                currentKind = .response
+            } else {
+                currentKind = match.kind == .think ? .thinking : .response
+            }
+        }
+
+        if cursor < raw.endIndex {
+            self.appendSegment(kind: currentKind, text: raw[cursor..<raw.endIndex], to: &segments)
+        }
+
+        guard matchedTag else {
+            return [AssistantTextSegment(kind: .response, text: trimmed)]
+        }
+
+        if includeThinking {
+            return segments
+        }
+
+        return segments.filter { $0.kind == .response }
+    }
+
+    static func visibleSegments(from raw: String) -> [AssistantTextSegment] {
+        self.segments(from: raw, includeThinking: false)
+    }
+
+    static func hasVisibleContent(in raw: String, includeThinking: Bool) -> Bool {
+        !self.segments(from: raw, includeThinking: includeThinking).isEmpty
+    }
+
+    static func hasVisibleContent(in raw: String) -> Bool {
+        self.hasVisibleContent(in: raw, includeThinking: false)
+    }
+
+    private enum TagKind {
+        case think
+        case final
+    }
+
+    private struct TagMatch {
+        let kind: TagKind
+        let closing: Bool
+        let range: Range<String.Index>
+    }
+
+    private static func nextTag(in text: String, from start: String.Index) -> TagMatch? {
+        let candidates: [TagMatch] = [
+            self.findTagStart(tag: "think", closing: false, in: text, from: start).map {
+                TagMatch(kind: .think, closing: false, range: $0)
+            },
+            self.findTagStart(tag: "think", closing: true, in: text, from: start).map {
+                TagMatch(kind: .think, closing: true, range: $0)
+            },
+            self.findTagStart(tag: "final", closing: false, in: text, from: start).map {
+                TagMatch(kind: .final, closing: false, range: $0)
+            },
+            self.findTagStart(tag: "final", closing: true, in: text, from: start).map {
+                TagMatch(kind: .final, closing: true, range: $0)
+            },
+        ].compactMap(\.self)
+
+        return candidates.min { $0.range.lowerBound < $1.range.lowerBound }
+    }
+
+    private static func findTagStart(
+        tag: String,
+        closing: Bool,
+        in text: String,
+        from start: String.Index) -> Range<String.Index>?
+    {
+        let token = closing ? "</\(tag)" : "<\(tag)"
+        var searchRange = start..<text.endIndex
+        while let range = text.range(
+            of: token,
+            options: [.caseInsensitive, .diacriticInsensitive],
+            range: searchRange)
+        {
+            let boundaryIndex = range.upperBound
+            guard boundaryIndex < text.endIndex else { return range }
+            let boundary = text[boundaryIndex]
+            let isBoundary = boundary == ">" || boundary.isWhitespace || (!closing && boundary == "/")
+            if isBoundary {
+                return range
+            }
+            searchRange = boundaryIndex..<text.endIndex
+        }
+        return nil
+    }
+
+    private static func isSelfClosingTag(in text: String, tagEnd: Range<String.Index>) -> Bool {
+        var cursor = tagEnd.lowerBound
+        while cursor > text.startIndex {
+            cursor = text.index(before: cursor)
+            let char = text[cursor]
+            if char.isWhitespace { continue }
+            return char == "/"
+        }
+        return false
+    }
+
+    private static func appendSegment(
+        kind: AssistantTextSegment.Kind,
+        text: Substring,
+        to segments: inout [AssistantTextSegment])
+    {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+        segments.append(AssistantTextSegment(kind: kind, text: trimmed))
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatEventText.swift

@@ -0,0 +1,78 @@
+import OpenClawKit
+
+public enum OpenClawChatEventText {
+    public static func assistantText(from event: OpenClawChatEventPayload) -> String? {
+        self.assistantText(fromMessage: event.message)
+    }
+
+    public static func assistantText(fromMessage message: AnyCodable?) -> String? {
+        guard let message else { return nil }
+        return self.assistantText(fromValue: message.value)
+    }
+
+    private static func assistantText(fromValue value: Any) -> String? {
+        if let text = value as? String {
+            return self.trimmed(text)
+        }
+
+        guard let object = self.dictionary(from: value) else { return nil }
+        if let role = self.stringValue(object["role"])?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !role.isEmpty,
+           role.lowercased() != "assistant"
+        {
+            return nil
+        }
+
+        guard let content = object["content"] else { return nil }
+        return self.textContent(from: content)
+    }
+
+    private static func textContent(from value: Any) -> String? {
+        if let text = value as? String {
+            return self.trimmed(text)
+        }
+
+        let parts: [String] = if let array = value as? [AnyCodable] {
+            array.compactMap { self.textContentPart(from: $0.value) }
+        } else if let array = value as? [Any] {
+            array.compactMap { self.textContentPart(from: $0) }
+        } else {
+            self.textContentPart(from: value).map { [$0] } ?? []
+        }
+
+        return self.trimmed(parts.joined(separator: "\n"))
+    }
+
+    private static func textContentPart(from value: Any) -> String? {
+        if let text = value as? String {
+            return self.trimmed(text)
+        }
+        guard let object = self.dictionary(from: value) else { return nil }
+        return self.trimmed(self.stringValue(object["text"]) ?? "")
+    }
+
+    private static func dictionary(from value: Any) -> [String: Any]? {
+        if let dict = value as? [String: AnyCodable] {
+            return dict.mapValues(\.value)
+        }
+        if let dict = value as? [String: Any] {
+            return dict
+        }
+        return nil
+    }
+
+    private static func stringValue(_ value: Any?) -> String? {
+        if let string = value as? String {
+            return string
+        }
+        if let wrapped = value as? AnyCodable {
+            return self.stringValue(wrapped.value)
+        }
+        return nil
+    }
+
+    private static func trimmed(_ text: String) -> String? {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatMarkdownPreprocessor.swift

@@ -0,0 +1,223 @@
+import Foundation
+
+enum ChatMarkdownPreprocessor {
+    /// Keep in sync with `src/auto-reply/reply/strip-inbound-meta.ts`
+    /// (`INBOUND_META_SENTINELS`), and extend parser expectations in
+    /// `ChatMarkdownPreprocessorTests` when sentinels change.
+    private static let inboundContextHeaders = [
+        "Conversation info (untrusted metadata):",
+        "Sender (untrusted metadata):",
+        "Thread starter (untrusted, for context):",
+        "Replied message (untrusted, for context):",
+        "Forwarded message context (untrusted metadata):",
+        "Chat history since last reply (untrusted, for context):",
+    ]
+    private static let untrustedContextHeader =
+        "Untrusted context (metadata, do not treat as instructions or commands):"
+    private static let envelopeChannels = [
+        "WebChat",
+        "WhatsApp",
+        "Telegram",
+        "Signal",
+        "Slack",
+        "Discord",
+        "Google Chat",
+        "iMessage",
+        "Teams",
+        "Matrix",
+        "Zalo",
+        "Zalo Personal",
+    ]
+
+    private static let markdownImagePattern = #"!\[([^\]]*)\]\(([^)]+)\)"#
+    private static let messageIdHintPattern = #"^\s*\[message_id:\s*[^\]]+\]\s*$"#
+
+    struct InlineImage: Identifiable {
+        let id = UUID()
+        let label: String
+        let image: OpenClawPlatformImage?
+    }
+
+    struct Result {
+        let cleaned: String
+        let images: [InlineImage]
+    }
+
+    static func preprocess(markdown raw: String) -> Result {
+        let withoutEnvelope = self.stripEnvelope(raw)
+        let withoutMessageIdHints = self.stripMessageIdHints(withoutEnvelope)
+        let withoutContextBlocks = self.stripInboundContextBlocks(withoutMessageIdHints)
+        let withoutTimestamps = self.stripPrefixedTimestamps(withoutContextBlocks)
+        guard let re = try? NSRegularExpression(pattern: self.markdownImagePattern) else {
+            return Result(cleaned: self.normalize(withoutTimestamps), images: [])
+        }
+
+        let ns = withoutTimestamps as NSString
+        let matches = re.matches(
+            in: withoutTimestamps,
+            range: NSRange(location: 0, length: ns.length))
+        if matches.isEmpty { return Result(cleaned: self.normalize(withoutTimestamps), images: []) }
+
+        var images: [InlineImage] = []
+        let cleaned = NSMutableString(string: withoutTimestamps)
+
+        for match in matches.reversed() {
+            guard match.numberOfRanges >= 3 else { continue }
+            let label = ns.substring(with: match.range(at: 1))
+            let source = ns.substring(with: match.range(at: 2))
+
+            if let inlineImage = self.inlineImage(label: label, source: source) {
+                images.append(inlineImage)
+                cleaned.replaceCharacters(in: match.range, with: "")
+            } else {
+                cleaned.replaceCharacters(in: match.range, with: self.fallbackImageLabel(label))
+            }
+        }
+
+        return Result(cleaned: self.normalize(cleaned as String), images: images.reversed())
+    }
+
+    private static func inlineImage(label: String, source: String) -> InlineImage? {
+        let trimmed = source.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let comma = trimmed.firstIndex(of: ","),
+              trimmed[..<comma].range(
+                  of: #"^data:image\/[^;]+;base64$"#,
+                  options: [.regularExpression, .caseInsensitive]) != nil
+        else {
+            return nil
+        }
+
+        let b64 = String(trimmed[trimmed.index(after: comma)...])
+        let image = Data(base64Encoded: b64).flatMap(OpenClawPlatformImage.init(data:))
+        return InlineImage(label: label, image: image)
+    }
+
+    private static func fallbackImageLabel(_ label: String) -> String {
+        let trimmed = label.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? "image" : trimmed
+    }
+
+    private static func stripEnvelope(_ raw: String) -> String {
+        guard let closeIndex = raw.firstIndex(of: "]"),
+              raw.first == "["
+        else {
+            return raw
+        }
+        let header = String(raw[raw.index(after: raw.startIndex)..<closeIndex])
+        guard self.looksLikeEnvelopeHeader(header) else {
+            return raw
+        }
+        return String(raw[raw.index(after: closeIndex)...])
+    }
+
+    private static func looksLikeEnvelopeHeader(_ header: String) -> Bool {
+        if header.range(of: #"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z\b"#, options: .regularExpression) != nil {
+            return true
+        }
+        if header.range(of: #"\d{4}-\d{2}-\d{2} \d{2}:\d{2}\b"#, options: .regularExpression) != nil {
+            return true
+        }
+        return self.envelopeChannels.contains(where: { header.hasPrefix("\($0) ") })
+    }
+
+    private static func stripMessageIdHints(_ raw: String) -> String {
+        guard raw.contains("[message_id:") else {
+            return raw
+        }
+        let lines = raw.replacingOccurrences(of: "\r\n", with: "\n").split(
+            separator: "\n",
+            omittingEmptySubsequences: false)
+        let filtered = lines.filter { line in
+            String(line).range(of: self.messageIdHintPattern, options: .regularExpression) == nil
+        }
+        guard filtered.count != lines.count else {
+            return raw
+        }
+        return filtered.map(String.init).joined(separator: "\n")
+    }
+
+    private static func stripInboundContextBlocks(_ raw: String) -> String {
+        guard self.inboundContextHeaders.contains(where: raw.contains) || raw.contains(self.untrustedContextHeader)
+        else {
+            return raw
+        }
+
+        let normalized = raw.replacingOccurrences(of: "\r\n", with: "\n")
+        let lines = normalized.split(separator: "\n", omittingEmptySubsequences: false).map(String.init)
+        var outputLines: [String] = []
+        var inMetaBlock = false
+        var inFencedJson = false
+
+        for index in lines.indices {
+            let currentLine = lines[index]
+
+            if !inMetaBlock, self.shouldStripTrailingUntrustedContext(lines: lines, index: index) {
+                break
+            }
+
+            if !inMetaBlock,
+               self.inboundContextHeaders.contains(currentLine.trimmingCharacters(in: .whitespacesAndNewlines))
+            {
+                let nextLine = index + 1 < lines.count ? lines[index + 1] : nil
+                if nextLine?.trimmingCharacters(in: .whitespacesAndNewlines) != "```json" {
+                    outputLines.append(currentLine)
+                    continue
+                }
+                inMetaBlock = true
+                inFencedJson = false
+                continue
+            }
+
+            if inMetaBlock {
+                if !inFencedJson, currentLine.trimmingCharacters(in: .whitespacesAndNewlines) == "```json" {
+                    inFencedJson = true
+                    continue
+                }
+
+                if inFencedJson {
+                    if currentLine.trimmingCharacters(in: .whitespacesAndNewlines) == "```" {
+                        inMetaBlock = false
+                        inFencedJson = false
+                    }
+                    continue
+                }
+
+                if currentLine.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                    continue
+                }
+
+                inMetaBlock = false
+            }
+
+            outputLines.append(currentLine)
+        }
+
+        return outputLines
+            .joined(separator: "\n")
+            .replacingOccurrences(of: #"^\n+"#, with: "", options: .regularExpression)
+    }
+
+    private static func shouldStripTrailingUntrustedContext(lines: [String], index: Int) -> Bool {
+        guard lines[index].trimmingCharacters(in: .whitespacesAndNewlines) == self.untrustedContextHeader else {
+            return false
+        }
+        let endIndex = min(lines.count, index + 8)
+        let probe = lines[(index + 1)..<endIndex].joined(separator: "\n")
+        return probe.range(
+            of: #"<<<EXTERNAL_UNTRUSTED_CONTENT|UNTRUSTED channel metadata \(|Source:\s+"#,
+            options: .regularExpression) != nil
+    }
+
+    private static func stripPrefixedTimestamps(_ raw: String) -> String {
+        let pattern = #"(?m)^\[[A-Za-z]{3}\s+\d{4}-\d{2}-\d{2}\s+\d{2}:\d{2}(?::\d{2})?\s+(?:GMT|UTC)[+-]?\d{0,2}\]\s*"#
+        return raw.replacingOccurrences(of: pattern, with: "", options: .regularExpression)
+    }
+
+    private static func normalize(_ raw: String) -> String {
+        var output = raw
+        output = output.replacingOccurrences(of: "\r\n", with: "\n")
+        output = output.replacingOccurrences(of: "\n\n\n", with: "\n\n")
+        output = output.replacingOccurrences(of: "\n\n\n", with: "\n\n")
+        return output.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatMarkdownRenderer.swift

@@ -0,0 +1,241 @@
+import Foundation
+import SwiftUI
+
+public enum ChatMarkdownVariant: String, CaseIterable, Sendable {
+    case standard
+    case compact
+}
+
+@MainActor
+struct ChatMarkdownRenderer: View {
+    enum Context {
+        case user
+        case assistant
+    }
+
+    let text: String
+    let context: Context
+    let variant: ChatMarkdownVariant
+    let font: Font
+    let textColor: Color
+
+    var body: some View {
+        let processed = ChatMarkdownPreprocessor.preprocess(markdown: self.text)
+        let renderMarkdown = ChatMarkdownDisplayPreprocessor.preserveChatSoftBreaks(in: processed.cleaned)
+        VStack(alignment: .leading, spacing: 10) {
+            Text(self.markdownText(renderMarkdown))
+                .font(self.font)
+                .foregroundStyle(self.textColor)
+                .tint(self.linkColor)
+                .textSelection(.enabled)
+                .lineSpacing(self.variant == .compact ? 2 : 4)
+
+            if !processed.images.isEmpty {
+                InlineImageList(images: processed.images)
+            }
+        }
+    }
+
+    private var linkColor: Color {
+        self.context == .user ? self.textColor : OpenClawChatTheme.accent
+    }
+
+    private func markdownText(_ markdown: String) -> AttributedString {
+        let options = AttributedString.MarkdownParsingOptions(
+            interpretedSyntax: .full,
+            failurePolicy: .returnPartiallyParsedIfPossible)
+        return (try? AttributedString(markdown: markdown, options: options)) ?? AttributedString(markdown)
+    }
+}
+
+enum ChatMarkdownDisplayPreprocessor {
+    static func preserveChatSoftBreaks(in markdown: String) -> String {
+        let normalized = markdown.replacingOccurrences(of: "\r\n", with: "\n")
+        let lines = normalized.split(separator: "\n", omittingEmptySubsequences: false).map(String.init)
+        guard lines.count > 1 else { return normalized }
+
+        var output = ""
+        var fence: Fence?
+        let tableRows = self.tableRowIndices(in: lines)
+
+        for index in lines.indices {
+            let line = lines[index]
+            let wasInFence = fence != nil
+            let fenceBoundary = self.fenceBoundary(in: line, activeFence: fence)
+            if case let .open(nextFence) = fenceBoundary {
+                fence = nextFence
+            } else if case .close = fenceBoundary {
+                fence = nil
+            }
+
+            output += line
+
+            guard index < lines.index(before: lines.endIndex) else {
+                continue
+            }
+
+            let nextLine = lines[lines.index(after: index)]
+            let nextIndex = lines.index(after: index)
+            if self.shouldPreserveSoftBreak(
+                after: line,
+                before: nextLine,
+                inTable: tableRows.contains(index) || tableRows.contains(nextIndex),
+                inFence: wasInFence,
+                fenceBoundary: fenceBoundary)
+            {
+                output += "  \n"
+            } else {
+                output += "\n"
+            }
+        }
+
+        return output
+    }
+
+    private enum FenceBoundary {
+        case none
+        case open(Fence)
+        case close
+    }
+
+    private struct Fence {
+        let character: Character
+        let count: Int
+        let hasOnlyTrailingWhitespace: Bool
+    }
+
+    private static func shouldPreserveSoftBreak(
+        after line: String,
+        before nextLine: String,
+        inTable: Bool,
+        inFence: Bool,
+        fenceBoundary: FenceBoundary) -> Bool
+    {
+        guard !inTable else { return false }
+        guard !inFence else { return false }
+        guard case .none = fenceBoundary else { return false }
+
+        let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
+        let nextTrimmed = nextLine.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty, !nextTrimmed.isEmpty else { return false }
+        guard !self.hasMarkdownHardBreak(line) else { return false }
+        guard !self.isBlockMarkdownLine(line), !self.isBlockMarkdownLine(nextLine) else { return false }
+        return true
+    }
+
+    private static func hasMarkdownHardBreak(_ line: String) -> Bool {
+        line.hasSuffix("\\") || line.hasSuffix("  ")
+    }
+
+    private static func isBlockMarkdownLine(_ line: String) -> Bool {
+        let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return false }
+
+        return self.matches(line, #"^\s{0,3}#{1,6}(\s|$)"#)
+            || self.matches(line, #"^\s{0,3}>"#)
+            || self.matches(line, #"^\s{0,3}([-+*])\s+"#)
+            || self.matches(line, #"^\s{0,3}\d{1,9}[.)]\s+"#)
+            || self.matches(line, #"^( {4}|\t)"#)
+            || self.matches(line, #"^\s{0,3}((\*\s*){3,}|(-\s*){3,}|(_\s*){3,}|={3,})$"#)
+    }
+
+    private static func tableRowIndices(in lines: [String]) -> Set<Int> {
+        var indices = Set<Int>()
+        for index in lines.indices where index > lines.startIndex {
+            guard self.isTableDelimiterLine(lines[index]), lines[lines.index(before: index)].contains("|") else {
+                continue
+            }
+
+            indices.insert(lines.index(before: index))
+            indices.insert(index)
+
+            var cursor = lines.index(after: index)
+            while cursor < lines.endIndex, lines[cursor].contains("|") {
+                indices.insert(cursor)
+                cursor = lines.index(after: cursor)
+            }
+        }
+        return indices
+    }
+
+    private static func isTableDelimiterLine(_ line: String) -> Bool {
+        self.matches(line, #"^\s{0,3}\|?\s*:?-{3,}:?\s*(\|\s*:?-{3,}:?\s*)+\|?\s*$"#)
+    }
+
+    private static func fenceBoundary(in line: String, activeFence: Fence?) -> FenceBoundary {
+        guard let candidate = self.fenceCandidate(in: line) else {
+            return .none
+        }
+
+        guard let activeFence else {
+            return .open(candidate)
+        }
+
+        if candidate.character == activeFence.character,
+           candidate.count >= activeFence.count,
+           candidate.hasOnlyTrailingWhitespace
+        {
+            return .close
+        }
+        return .none
+    }
+
+    private static func fenceCandidate(in line: String) -> Fence? {
+        var cursor = line.startIndex
+        var spaces = 0
+        while cursor < line.endIndex, line[cursor] == " ", spaces < 4 {
+            spaces += 1
+            cursor = line.index(after: cursor)
+        }
+        guard spaces <= 3, cursor < line.endIndex else {
+            return nil
+        }
+
+        let character = line[cursor]
+        guard character == "`" || character == "~" else {
+            return nil
+        }
+
+        var count = 0
+        while cursor < line.endIndex, line[cursor] == character {
+            count += 1
+            cursor = line.index(after: cursor)
+        }
+        guard count >= 3 else {
+            return nil
+        }
+        let trailing = line[cursor...]
+        return Fence(
+            character: character,
+            count: count,
+            hasOnlyTrailingWhitespace: trailing.allSatisfy(\.isWhitespace))
+    }
+
+    private static func matches(_ line: String, _ pattern: String) -> Bool {
+        line.range(of: pattern, options: .regularExpression) != nil
+    }
+}
+
+@MainActor
+private struct InlineImageList: View {
+    let images: [ChatMarkdownPreprocessor.InlineImage]
+
+    var body: some View {
+        ForEach(self.images, id: \.id) { item in
+            if let img = item.image {
+                OpenClawPlatformImageFactory.image(img)
+                    .resizable()
+                    .scaledToFit()
+                    .frame(maxHeight: 260)
+                    .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
+                    .overlay(
+                        RoundedRectangle(cornerRadius: 12, style: .continuous)
+                            .strokeBorder(Color.white.opacity(0.12), lineWidth: 1))
+            } else {
+                Text(item.label.isEmpty ? "Image" : item.label)
+                    .font(OpenClawChatTypography.footnote)
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatMessageViews.swift

@@ -0,0 +1,807 @@
+import Foundation
+import OpenClawKit
+import SwiftUI
+
+private enum ChatUIConstants {
+    static let bubbleMaxWidth: CGFloat = 560
+    static let bubbleCorner: CGFloat = 18
+}
+
+struct ChatAgentAvatar: View {
+    let text: String?
+    let name: String?
+    let tint: Color?
+    var size: CGFloat = 30
+
+    var body: some View {
+        Text(self.displayText)
+            .font(OpenClawChatTypography.avatar(size: self.fontSize))
+            .foregroundStyle(.white)
+            .minimumScaleFactor(0.6)
+            .lineLimit(1)
+            .frame(width: self.size, height: self.size)
+            .background(
+                Circle()
+                    .fill(
+                        LinearGradient(
+                            colors: [
+                                (self.tint ?? OpenClawChatTheme.accent).opacity(0.95),
+                                Color(red: 38 / 255.0, green: 40 / 255.0, blue: 43 / 255.0),
+                            ],
+                            startPoint: .topLeading,
+                            endPoint: .bottomTrailing)))
+            .overlay(
+                Circle()
+                    .strokeBorder(Color.white.opacity(0.18), lineWidth: 1))
+            .shadow(color: (self.tint ?? OpenClawChatTheme.accent).opacity(0.18), radius: 8, y: 4)
+            .accessibilityLabel(self.name.map { "\($0) avatar" } ?? "Agent avatar")
+    }
+
+    private var displayText: String {
+        if let text = self.text?.trimmingCharacters(in: .whitespacesAndNewlines), !text.isEmpty {
+            return String(text.prefix(3))
+        }
+        if let name = self.name?.trimmingCharacters(in: .whitespacesAndNewlines), !name.isEmpty {
+            let words = name.split(whereSeparator: { $0.isWhitespace || $0 == "-" || $0 == "_" }).prefix(2)
+            let initials = words.compactMap(\.first).map(String.init).joined()
+            if !initials.isEmpty {
+                return initials.uppercased()
+            }
+        }
+        return "OC"
+    }
+
+    private var fontSize: CGFloat {
+        self.displayText.count > 2 ? self.size * 0.34 : self.size * 0.42
+    }
+}
+
+private struct ChatBubbleShape: InsettableShape {
+    enum Tail {
+        case left
+        case right
+        case none
+    }
+
+    let cornerRadius: CGFloat
+    let tail: Tail
+    var insetAmount: CGFloat = 0
+
+    private let tailWidth: CGFloat = 7
+    private let tailBaseHeight: CGFloat = 9
+
+    func inset(by amount: CGFloat) -> ChatBubbleShape {
+        var copy = self
+        copy.insetAmount += amount
+        return copy
+    }
+
+    func path(in rect: CGRect) -> Path {
+        let rect = rect.insetBy(dx: self.insetAmount, dy: self.insetAmount)
+        switch self.tail {
+        case .left:
+            return self.leftTailPath(in: rect, radius: self.cornerRadius)
+        case .right:
+            return self.rightTailPath(in: rect, radius: self.cornerRadius)
+        case .none:
+            return Path(roundedRect: rect, cornerRadius: self.cornerRadius)
+        }
+    }
+
+    private func rightTailPath(in rect: CGRect, radius r: CGFloat) -> Path {
+        var path = Path()
+        let bubbleMinX = rect.minX
+        let bubbleMaxX = rect.maxX - self.tailWidth
+        let bubbleMinY = rect.minY
+        let bubbleMaxY = rect.maxY
+
+        let available = max(4, bubbleMaxY - bubbleMinY - 2 * r)
+        let baseH = min(tailBaseHeight, available)
+        let baseBottomY = bubbleMaxY - max(r * 0.45, 6)
+        let baseTopY = baseBottomY - baseH
+        let midY = (baseTopY + baseBottomY) / 2
+
+        let baseTop = CGPoint(x: bubbleMaxX, y: baseTopY)
+        let baseBottom = CGPoint(x: bubbleMaxX, y: baseBottomY)
+        let tip = CGPoint(x: bubbleMaxX + self.tailWidth, y: midY)
+
+        path.move(to: CGPoint(x: bubbleMinX + r, y: bubbleMinY))
+        path.addLine(to: CGPoint(x: bubbleMaxX - r, y: bubbleMinY))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMaxX, y: bubbleMinY + r),
+            control: CGPoint(x: bubbleMaxX, y: bubbleMinY))
+        path.addLine(to: baseTop)
+        path.addCurve(
+            to: tip,
+            control1: CGPoint(x: bubbleMaxX + self.tailWidth * 0.2, y: baseTopY + baseH * 0.05),
+            control2: CGPoint(x: bubbleMaxX + self.tailWidth * 0.95, y: midY - baseH * 0.15))
+        path.addCurve(
+            to: baseBottom,
+            control1: CGPoint(x: bubbleMaxX + self.tailWidth * 0.95, y: midY + baseH * 0.15),
+            control2: CGPoint(x: bubbleMaxX + self.tailWidth * 0.2, y: baseBottomY - baseH * 0.05))
+        self.addBottomEdge(
+            path: &path,
+            bubbleMinX: bubbleMinX,
+            bubbleMaxX: bubbleMaxX,
+            bubbleMaxY: bubbleMaxY,
+            radius: r)
+        path.addLine(to: CGPoint(x: bubbleMinX, y: bubbleMinY + r))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMinX + r, y: bubbleMinY),
+            control: CGPoint(x: bubbleMinX, y: bubbleMinY))
+
+        return path
+    }
+
+    private func leftTailPath(in rect: CGRect, radius r: CGFloat) -> Path {
+        var path = Path()
+        let bubbleMinX = rect.minX + self.tailWidth
+        let bubbleMaxX = rect.maxX
+        let bubbleMinY = rect.minY
+        let bubbleMaxY = rect.maxY
+
+        let available = max(4, bubbleMaxY - bubbleMinY - 2 * r)
+        let baseH = min(tailBaseHeight, available)
+        let baseBottomY = bubbleMaxY - max(r * 0.45, 6)
+        let baseTopY = baseBottomY - baseH
+        let midY = (baseTopY + baseBottomY) / 2
+
+        let baseTop = CGPoint(x: bubbleMinX, y: baseTopY)
+        let baseBottom = CGPoint(x: bubbleMinX, y: baseBottomY)
+        let tip = CGPoint(x: bubbleMinX - self.tailWidth, y: midY)
+
+        path.move(to: CGPoint(x: bubbleMinX + r, y: bubbleMinY))
+        path.addLine(to: CGPoint(x: bubbleMaxX - r, y: bubbleMinY))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMaxX, y: bubbleMinY + r),
+            control: CGPoint(x: bubbleMaxX, y: bubbleMinY))
+        path.addLine(to: CGPoint(x: bubbleMaxX, y: bubbleMaxY - r))
+        self.addBottomEdge(
+            path: &path,
+            bubbleMinX: bubbleMinX,
+            bubbleMaxX: bubbleMaxX,
+            bubbleMaxY: bubbleMaxY,
+            radius: r)
+        path.addLine(to: baseBottom)
+        path.addCurve(
+            to: tip,
+            control1: CGPoint(x: bubbleMinX - self.tailWidth * 0.2, y: baseBottomY - baseH * 0.05),
+            control2: CGPoint(x: bubbleMinX - self.tailWidth * 0.95, y: midY + baseH * 0.15))
+        path.addCurve(
+            to: baseTop,
+            control1: CGPoint(x: bubbleMinX - self.tailWidth * 0.95, y: midY - baseH * 0.15),
+            control2: CGPoint(x: bubbleMinX - self.tailWidth * 0.2, y: baseTopY + baseH * 0.05))
+        path.addLine(to: CGPoint(x: bubbleMinX, y: bubbleMinY + r))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMinX + r, y: bubbleMinY),
+            control: CGPoint(x: bubbleMinX, y: bubbleMinY))
+
+        return path
+    }
+
+    private func addBottomEdge(
+        path: inout Path,
+        bubbleMinX: CGFloat,
+        bubbleMaxX: CGFloat,
+        bubbleMaxY: CGFloat,
+        radius: CGFloat)
+    {
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMaxX - radius, y: bubbleMaxY),
+            control: CGPoint(x: bubbleMaxX, y: bubbleMaxY))
+        path.addLine(to: CGPoint(x: bubbleMinX + radius, y: bubbleMaxY))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMinX, y: bubbleMaxY - radius),
+            control: CGPoint(x: bubbleMinX, y: bubbleMaxY))
+    }
+}
+
+@MainActor
+struct ChatMessageBubble: View {
+    let message: OpenClawChatMessage
+    let style: OpenClawChatView.Style
+    let markdownVariant: ChatMarkdownVariant
+    let userAccent: Color?
+    let showsAssistantTrace: Bool
+    let assistantName: String?
+    let assistantAvatarText: String?
+    let assistantAvatarTint: Color?
+    let showsAssistantAvatar: Bool
+    let isClean: Bool
+
+    var body: some View {
+        if self.isUser {
+            self.messageBody
+                .frame(maxWidth: ChatUIConstants.bubbleMaxWidth, alignment: .trailing)
+                .frame(maxWidth: .infinity, alignment: .trailing)
+                .padding(.horizontal, 2)
+        } else {
+            HStack(alignment: .top, spacing: 8) {
+                if self.showsAssistantAvatar {
+                    ChatAgentAvatar(
+                        text: self.assistantAvatarText,
+                        name: self.assistantName,
+                        tint: self.assistantAvatarTint)
+                        .padding(.top, 1)
+                }
+
+                self.messageBody
+                    .frame(maxWidth: ChatUIConstants.bubbleMaxWidth, alignment: .leading)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(.horizontal, 2)
+        }
+    }
+
+    private var isUser: Bool {
+        self.message.role.lowercased() == "user"
+    }
+
+    private var messageBody: some View {
+        ChatMessageBody(
+            message: self.message,
+            isUser: self.isUser,
+            style: self.style,
+            markdownVariant: self.markdownVariant,
+            userAccent: self.userAccent,
+            showsAssistantTrace: self.showsAssistantTrace,
+            isClean: self.isClean)
+    }
+}
+
+@MainActor
+private struct ChatMessageBody: View {
+    @Environment(\.openClawAssistantBubblesInCleanChrome) private var assistantBubblesInClean
+    let message: OpenClawChatMessage
+    let isUser: Bool
+    let style: OpenClawChatView.Style
+    let markdownVariant: ChatMarkdownVariant
+    let userAccent: Color?
+    let showsAssistantTrace: Bool
+    let isClean: Bool
+
+    var body: some View {
+        let text = self.primaryText
+        let textColor = self.isUser ? OpenClawChatTheme.userText : OpenClawChatTheme.assistantText
+
+        if self.usesBubble {
+            self.messageContent(text: text, textColor: textColor)
+                .padding(.vertical, 10)
+                .padding(.horizontal, 12)
+                .background(self.bubbleBackground)
+                .clipShape(self.bubbleShape)
+                .overlay(self.bubbleBorder)
+                .shadow(
+                    color: self.bubbleShadowColor,
+                    radius: self.bubbleShadowRadius,
+                    y: self.bubbleShadowYOffset)
+                .padding(.leading, self.tailPaddingLeading)
+                .padding(.trailing, self.tailPaddingTrailing)
+        } else {
+            self.messageContent(text: text, textColor: textColor)
+                .padding(.vertical, 5)
+                .padding(.horizontal, 4)
+        }
+    }
+
+    private func messageContent(text: String, textColor: Color) -> some View {
+        VStack(alignment: .leading, spacing: 10) {
+            if self.isToolResultMessage, self.showsAssistantTrace {
+                if !text.isEmpty {
+                    ToolResultCard(
+                        title: self.toolResultTitle,
+                        text: text,
+                        isUser: self.isUser,
+                        toolName: self.message.toolName)
+                }
+            } else if self.isUser {
+                ChatMarkdownRenderer(
+                    text: text,
+                    context: .user,
+                    variant: self.markdownVariant,
+                    font: OpenClawChatTypography.body,
+                    textColor: textColor)
+            } else {
+                ChatAssistantTextBody(
+                    text: text,
+                    markdownVariant: self.markdownVariant,
+                    includesThinking: self.showsAssistantTrace)
+            }
+
+            if !self.inlineAttachments.isEmpty {
+                ForEach(self.inlineAttachments.indices, id: \.self) { idx in
+                    AttachmentRow(att: self.inlineAttachments[idx], isUser: self.isUser)
+                }
+            }
+
+            if self.showsAssistantTrace, !self.toolCalls.isEmpty {
+                ForEach(self.toolCalls.indices, id: \.self) { idx in
+                    ToolCallCard(
+                        content: self.toolCalls[idx],
+                        isUser: self.isUser)
+                }
+            }
+
+            if self.showsAssistantTrace, !self.inlineToolResults.isEmpty {
+                ForEach(self.inlineToolResults.indices, id: \.self) { idx in
+                    let toolResult = self.inlineToolResults[idx]
+                    let display = ToolDisplayRegistry.resolve(name: toolResult.name ?? "tool", args: nil)
+                    ToolResultCard(
+                        title: "\(display.emoji) \(display.title)",
+                        text: toolResult.text ?? "",
+                        isUser: self.isUser,
+                        toolName: toolResult.name)
+                }
+            }
+        }
+        .textSelection(.enabled)
+        .foregroundStyle(textColor)
+    }
+
+    private var usesBubble: Bool {
+        // Keep the guarded base condition; iOS additionally opts assistant
+        // messages into bubbles via the clean-chrome environment flag.
+        self.isUser || self.style == .onboarding || !self.isClean || self.assistantBubblesInClean
+    }
+
+    private var primaryText: String {
+        let parts = self.message.content.compactMap { content -> String? in
+            let kind = (content.type ?? "text").lowercased()
+            guard kind == "text" || kind.isEmpty else { return nil }
+            return content.text
+        }
+        return OpenClawChatMessage.displayText(
+            contentText: parts.joined(separator: "\n"),
+            role: self.message.role,
+            stopReason: self.message.stopReason,
+            errorMessage: self.message.errorMessage)
+    }
+
+    private var inlineAttachments: [OpenClawChatMessageContent] {
+        self.message.content.filter { content in
+            switch content.type ?? "text" {
+            case "file", "attachment":
+                true
+            default:
+                false
+            }
+        }
+    }
+
+    private var toolCalls: [OpenClawChatMessageContent] {
+        self.message.content.filter { content in
+            let kind = (content.type ?? "").lowercased()
+            if ["toolcall", "tool_call", "tooluse", "tool_use"].contains(kind) {
+                return true
+            }
+            return content.name != nil && content.arguments != nil
+        }
+    }
+
+    private var inlineToolResults: [OpenClawChatMessageContent] {
+        self.message.content.filter { content in
+            let kind = (content.type ?? "").lowercased()
+            return kind == "toolresult" || kind == "tool_result"
+        }
+    }
+
+    private var isToolResultMessage: Bool {
+        let role = self.message.role.lowercased()
+        return role == "toolresult" || role == "tool_result"
+    }
+
+    private var toolResultTitle: String {
+        if let name = self.message.toolName, !name.isEmpty {
+            let display = ToolDisplayRegistry.resolve(name: name, args: nil)
+            return "\(display.emoji) \(display.title)"
+        }
+        let display = ToolDisplayRegistry.resolve(name: "tool", args: nil)
+        return "\(display.emoji) \(display.title)"
+    }
+
+    private var bubbleFillColor: Color {
+        if self.isUser {
+            return self.userAccent ?? OpenClawChatTheme.userBubble
+        }
+        if self.style == .onboarding {
+            return OpenClawChatTheme.onboardingAssistantBubble
+        }
+        return OpenClawChatTheme.assistantBubble
+    }
+
+    private var bubbleBackground: AnyShapeStyle {
+        AnyShapeStyle(self.bubbleFillColor)
+    }
+
+    private var bubbleBorderColor: Color {
+        if self.isUser {
+            return Color.white.opacity(0.12)
+        }
+        if self.style == .onboarding {
+            return OpenClawChatTheme.onboardingAssistantBorder
+        }
+        return Color.white.opacity(0.08)
+    }
+
+    private var bubbleBorderWidth: CGFloat {
+        if self.isUser { return 0.5 }
+        if self.style == .onboarding { return 0.8 }
+        return 1
+    }
+
+    private var bubbleBorder: some View {
+        self.bubbleShape.strokeBorder(self.bubbleBorderColor, lineWidth: self.bubbleBorderWidth)
+    }
+
+    private var bubbleShape: ChatBubbleShape {
+        ChatBubbleShape(cornerRadius: ChatUIConstants.bubbleCorner, tail: self.bubbleTail)
+    }
+
+    private var bubbleTail: ChatBubbleShape.Tail {
+        guard self.style == .onboarding else { return .none }
+        return self.isUser ? .right : .left
+    }
+
+    private var tailPaddingLeading: CGFloat {
+        self.style == .onboarding && !self.isUser ? 8 : 0
+    }
+
+    private var tailPaddingTrailing: CGFloat {
+        self.style == .onboarding && self.isUser ? 8 : 0
+    }
+
+    private var bubbleShadowColor: Color {
+        self.style == .onboarding && !self.isUser ? Color.black.opacity(0.28) : .clear
+    }
+
+    private var bubbleShadowRadius: CGFloat {
+        self.style == .onboarding && !self.isUser ? 6 : 0
+    }
+
+    private var bubbleShadowYOffset: CGFloat {
+        self.style == .onboarding && !self.isUser ? 2 : 0
+    }
+}
+
+private struct AttachmentRow: View {
+    let att: OpenClawChatMessageContent
+    let isUser: Bool
+
+    var body: some View {
+        HStack(spacing: 8) {
+            Image(systemName: "paperclip")
+            Text(self.att.fileName ?? "Attachment")
+                .font(OpenClawChatTypography.footnote)
+                .lineLimit(1)
+                .foregroundStyle(self.isUser ? OpenClawChatTheme.userText : OpenClawChatTheme.assistantText)
+            Spacer()
+        }
+        .padding(10)
+        .background(self.isUser ? Color.white.opacity(0.2) : Color.black.opacity(0.04))
+        .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
+    }
+}
+
+private struct ToolCallCard: View {
+    let content: OpenClawChatMessageContent
+    let isUser: Bool
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            HStack(spacing: 6) {
+                Text(self.toolName)
+                    .font(OpenClawChatTypography.footnoteSemiBold)
+                Spacer(minLength: 0)
+            }
+
+            if let summary = self.summary, !summary.isEmpty {
+                Text(summary)
+                    .font(OpenClawChatTypography.mono(size: 13, relativeTo: .footnote))
+                    .foregroundStyle(.secondary)
+                    .lineLimit(2)
+            }
+        }
+        .padding(10)
+        .background(
+            RoundedRectangle(cornerRadius: 12, style: .continuous)
+                .fill(OpenClawChatTheme.subtleCard)
+                .overlay(
+                    RoundedRectangle(cornerRadius: 12, style: .continuous)
+                        .strokeBorder(Color.white.opacity(0.08), lineWidth: 1)))
+    }
+
+    private var toolName: String {
+        "\(self.display.emoji) \(self.display.title)"
+    }
+
+    private var summary: String? {
+        self.display.detailLine
+    }
+
+    private var display: ToolDisplaySummary {
+        ToolDisplayRegistry.resolve(name: self.content.name ?? "tool", args: self.content.arguments)
+    }
+}
+
+private struct ToolResultCard: View {
+    let title: String
+    let text: String
+    let isUser: Bool
+    let toolName: String?
+    @State private var expanded = false
+
+    var body: some View {
+        if !self.displayContent.isEmpty {
+            VStack(alignment: .leading, spacing: 8) {
+                HStack(spacing: 6) {
+                    Text(self.title)
+                        .font(OpenClawChatTypography.footnoteSemiBold)
+                    Spacer(minLength: 0)
+                }
+
+                Text(self.displayText)
+                    .font(OpenClawChatTypography.mono(size: 13, relativeTo: .footnote))
+                    .foregroundStyle(self.isUser ? OpenClawChatTheme.userText : OpenClawChatTheme.assistantText)
+                    .lineLimit(self.expanded ? nil : Self.previewLineLimit)
+
+                if self.shouldShowToggle {
+                    Button(self.expanded ? "Show less" : "Show full output") {
+                        self.expanded.toggle()
+                    }
+                    .buttonStyle(.plain)
+                    .font(OpenClawChatTypography.caption)
+                    .foregroundStyle(.secondary)
+                }
+            }
+            .padding(10)
+            .background(
+                RoundedRectangle(cornerRadius: 12, style: .continuous)
+                    .fill(OpenClawChatTheme.subtleCard)
+                    .overlay(
+                        RoundedRectangle(cornerRadius: 12, style: .continuous)
+                            .strokeBorder(Color.white.opacity(0.08), lineWidth: 1)))
+        }
+    }
+
+    private static let previewLineLimit = 8
+
+    private var displayContent: String {
+        ToolResultTextFormatter.format(text: self.text, toolName: self.toolName)
+    }
+
+    private var lines: [Substring] {
+        self.displayContent.components(separatedBy: .newlines).map { Substring($0) }
+    }
+
+    private var displayText: String {
+        guard !self.expanded, self.lines.count > Self.previewLineLimit else { return self.displayContent }
+        return self.lines.prefix(Self.previewLineLimit).joined(separator: "\n") + "\n…"
+    }
+
+    private var shouldShowToggle: Bool {
+        self.lines.count > Self.previewLineLimit
+    }
+}
+
+@MainActor
+struct ChatTypingIndicatorBubble: View {
+    let style: OpenClawChatView.Style
+    let assistantName: String?
+    let assistantAvatarText: String?
+    let assistantAvatarTint: Color?
+    let showsAssistantAvatar: Bool
+    let isClean: Bool
+
+    var body: some View {
+        HStack(alignment: .center, spacing: 8) {
+            if self.showsAssistantAvatar {
+                ChatAgentAvatar(
+                    text: self.assistantAvatarText,
+                    name: self.assistantName,
+                    tint: self.assistantAvatarTint,
+                    size: 28)
+            }
+
+            HStack(spacing: 9) {
+                TypingDots()
+                Text("Writing")
+                    .font(OpenClawChatTypography.captionSemiBold)
+                    .foregroundStyle(.secondary)
+            }
+            .padding(.vertical, self.isClean ? 5 : (self.style == .standard ? 10 : 9))
+            .padding(.horizontal, self.isClean ? 4 : (self.style == .standard ? 12 : 14))
+            .assistantBubbleContainerStyle(isClean: self.isClean, cornerRadius: 15)
+            .fixedSize(horizontal: true, vertical: false)
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+        .focusable(false)
+    }
+}
+
+extension ChatTypingIndicatorBubble: @MainActor Equatable {
+    static func == (lhs: Self, rhs: Self) -> Bool {
+        lhs.style == rhs.style &&
+            lhs.assistantName == rhs.assistantName &&
+            lhs.assistantAvatarText == rhs.assistantAvatarText &&
+            lhs.showsAssistantAvatar == rhs.showsAssistantAvatar &&
+            lhs.isClean == rhs.isClean
+    }
+}
+
+extension EnvironmentValues {
+    /// Clients that want iMessage-style assistant bubbles in the clean chrome
+    /// (the iOS app) opt in; the default keeps the plain clean look elsewhere.
+    @Entry public var openClawAssistantBubblesInCleanChrome: Bool = false
+}
+
+private struct AssistantBubbleContainerStyle: ViewModifier {
+    let isClean: Bool
+    let cornerRadius: CGFloat
+
+    @Environment(\.openClawAssistantBubblesInCleanChrome) private var bubblesInClean
+
+    func body(content: Content) -> some View {
+        if self.isClean, !self.bubblesInClean {
+            content
+        } else {
+            content
+                // Clean call sites pre-pad only ~4pt; bubbles need room to breathe.
+                    .padding(self.isClean ? 8 : 0)
+                    .background(
+                        RoundedRectangle(cornerRadius: self.cornerRadius, style: .continuous)
+                            .fill(OpenClawChatTheme.assistantBubble))
+                    .overlay(
+                        RoundedRectangle(cornerRadius: self.cornerRadius, style: .continuous)
+                            .strokeBorder(Color.white.opacity(0.08), lineWidth: 1))
+        }
+    }
+}
+
+extension View {
+    fileprivate func assistantBubbleContainerStyle(isClean: Bool, cornerRadius: CGFloat = 16) -> some View {
+        self.modifier(AssistantBubbleContainerStyle(isClean: isClean, cornerRadius: cornerRadius))
+            .frame(maxWidth: ChatUIConstants.bubbleMaxWidth, alignment: .leading)
+            .focusable(false)
+    }
+}
+
+@MainActor
+struct ChatStreamingAssistantBubble: View {
+    let text: String
+    let markdownVariant: ChatMarkdownVariant
+    let showsAssistantTrace: Bool
+    let assistantName: String?
+    let assistantAvatarText: String?
+    let assistantAvatarTint: Color?
+    let showsAssistantAvatar: Bool
+    let isClean: Bool
+
+    var body: some View {
+        HStack(alignment: .top, spacing: 8) {
+            if self.showsAssistantAvatar {
+                ChatAgentAvatar(
+                    text: self.assistantAvatarText,
+                    name: self.assistantName,
+                    tint: self.assistantAvatarTint)
+                    .padding(.top, 1)
+            }
+
+            VStack(alignment: .leading, spacing: 10) {
+                ChatAssistantTextBody(
+                    text: self.text,
+                    markdownVariant: self.markdownVariant,
+                    includesThinking: self.showsAssistantTrace)
+            }
+            .padding(self.isClean ? 4 : 12)
+            .assistantBubbleContainerStyle(isClean: self.isClean)
+        }
+        .frame(maxWidth: .infinity, alignment: .leading)
+    }
+}
+
+@MainActor
+struct ChatPendingToolsBubble: View {
+    let toolCalls: [OpenClawChatPendingToolCall]
+    let isClean: Bool
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Label("Running tools…", systemImage: "hammer")
+                .font(OpenClawChatTypography.caption)
+                .foregroundStyle(.secondary)
+
+            ForEach(self.toolCalls) { call in
+                let display = ToolDisplayRegistry.resolve(name: call.name, args: call.args)
+                VStack(alignment: .leading, spacing: 4) {
+                    HStack(alignment: .firstTextBaseline, spacing: 8) {
+                        Text("\(display.emoji) \(display.label)")
+                            .font(OpenClawChatTypography.mono(size: 13, relativeTo: .footnote))
+                            .lineLimit(1)
+                        Spacer(minLength: 0)
+                        ProgressView().controlSize(.mini)
+                    }
+                    if let detail = display.detailLine, !detail.isEmpty {
+                        Text(detail)
+                            .font(OpenClawChatTypography.mono(size: 12, relativeTo: .caption))
+                            .foregroundStyle(.secondary)
+                            .lineLimit(2)
+                    }
+                }
+                .padding(10)
+                .background(Color.white.opacity(0.06))
+                .clipShape(RoundedRectangle(cornerRadius: 12, style: .continuous))
+            }
+        }
+        .padding(self.isClean ? 4 : 12)
+        .assistantBubbleContainerStyle(isClean: self.isClean)
+    }
+}
+
+extension ChatPendingToolsBubble: @MainActor Equatable {
+    static func == (lhs: Self, rhs: Self) -> Bool {
+        lhs.toolCalls == rhs.toolCalls && lhs.isClean == rhs.isClean
+    }
+}
+
+@MainActor
+private struct TypingDots: View {
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @Environment(\.scenePhase) private var scenePhase
+    @State private var animate = false
+
+    var body: some View {
+        HStack(spacing: 5) {
+            ForEach(0..<3, id: \.self) { idx in
+                Circle()
+                    .fill(Color.secondary.opacity(0.55))
+                    .frame(width: 7, height: 7)
+                    .scaleEffect(self.reduceMotion ? 0.85 : (self.animate ? 1.05 : 0.70))
+                    .opacity(self.reduceMotion ? 0.55 : (self.animate ? 0.95 : 0.30))
+                    .animation(
+                        self.reduceMotion ? nil : .easeInOut(duration: 0.55)
+                            .repeatForever(autoreverses: true)
+                            .delay(Double(idx) * 0.16),
+                        value: self.animate)
+            }
+        }
+        .onAppear { self.updateAnimationState() }
+        .onDisappear { self.animate = false }
+        .onChange(of: self.scenePhase) { _, _ in
+            self.updateAnimationState()
+        }
+        .onChange(of: self.reduceMotion) { _, _ in
+            self.updateAnimationState()
+        }
+    }
+
+    private func updateAnimationState() {
+        guard !self.reduceMotion, self.scenePhase == .active else {
+            self.animate = false
+            return
+        }
+        self.animate = true
+    }
+}
+
+private struct ChatAssistantTextBody: View {
+    let text: String
+    let markdownVariant: ChatMarkdownVariant
+    let includesThinking: Bool
+
+    var body: some View {
+        let segments = AssistantTextParser.segments(from: self.text, includeThinking: self.includesThinking)
+        VStack(alignment: .leading, spacing: 10) {
+            ForEach(segments) { segment in
+                let font = segment.kind == .thinking
+                    ? OpenClawChatTypography.callout.italic()
+                    : OpenClawChatTypography.body
+                ChatMarkdownRenderer(
+                    text: segment.text,
+                    context: .assistant,
+                    variant: self.markdownVariant,
+                    font: font,
+                    textColor: OpenClawChatTheme.assistantText)
+            }
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatModels.swift

@@ -0,0 +1,476 @@
+import Foundation
+import OpenClawKit
+
+// NOTE: keep this file lightweight; decode must be resilient to varying transcript formats.
+
+#if canImport(AppKit)
+import AppKit
+
+public typealias OpenClawPlatformImage = NSImage
+#elseif canImport(UIKit)
+import UIKit
+
+public typealias OpenClawPlatformImage = UIImage
+#endif
+
+public enum OpenClawChatCommandFilter: String, CaseIterable, Sendable {
+    case all = "All"
+    case commands = "Commands"
+    case skills = "Skills"
+}
+
+public struct OpenClawChatCommandChoice: Identifiable, Hashable, Sendable {
+    public enum Source: String, Sendable {
+        case command
+        case skill
+        case plugin
+        case unknown
+    }
+
+    public let id: String
+    public let name: String
+    public let textAliases: [String]
+    public let description: String
+    public let source: Source
+    public let acceptsArgs: Bool
+
+    public init(
+        id: String,
+        name: String,
+        textAliases: [String],
+        description: String,
+        source: Source,
+        acceptsArgs: Bool)
+    {
+        self.id = id
+        self.name = name
+        self.textAliases = textAliases
+        self.description = description
+        self.source = source
+        self.acceptsArgs = acceptsArgs
+    }
+
+    public var preferredInvocation: String {
+        self.textAliases.first { $0.trimmingCharacters(in: .whitespacesAndNewlines).hasPrefix("/") }
+            ?? "/\(self.name)"
+    }
+
+    public var displayInvocation: String {
+        self.preferredInvocation.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}
+
+public struct OpenClawChatUsageCost: Codable, Hashable, Sendable {
+    public let input: Double?
+    public let output: Double?
+    public let cacheRead: Double?
+    public let cacheWrite: Double?
+    public let total: Double?
+}
+
+public struct OpenClawChatUsage: Codable, Hashable, Sendable {
+    public let input: Int?
+    public let output: Int?
+    public let cacheRead: Int?
+    public let cacheWrite: Int?
+    public let cost: OpenClawChatUsageCost?
+    public let total: Int?
+
+    enum CodingKeys: String, CodingKey {
+        case input
+        case output
+        case cacheRead
+        case cacheWrite
+        case cost
+        case total
+        case totalTokens
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        self.input = try container.decodeIfPresent(Int.self, forKey: .input)
+        self.output = try container.decodeIfPresent(Int.self, forKey: .output)
+        self.cacheRead = try container.decodeIfPresent(Int.self, forKey: .cacheRead)
+        self.cacheWrite = try container.decodeIfPresent(Int.self, forKey: .cacheWrite)
+        self.cost = try container.decodeIfPresent(OpenClawChatUsageCost.self, forKey: .cost)
+        self.total =
+            try container.decodeIfPresent(Int.self, forKey: .total) ??
+            container.decodeIfPresent(Int.self, forKey: .totalTokens)
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encodeIfPresent(self.input, forKey: .input)
+        try container.encodeIfPresent(self.output, forKey: .output)
+        try container.encodeIfPresent(self.cacheRead, forKey: .cacheRead)
+        try container.encodeIfPresent(self.cacheWrite, forKey: .cacheWrite)
+        try container.encodeIfPresent(self.cost, forKey: .cost)
+        try container.encodeIfPresent(self.total, forKey: .total)
+    }
+}
+
+public struct OpenClawChatMessageContent: Codable, Hashable, Sendable {
+    public let type: String?
+    public let text: String?
+    public let thinking: String?
+    public let thinkingSignature: String?
+    public let mimeType: String?
+    public let fileName: String?
+    public let content: AnyCodable?
+
+    // Tool-call fields (when `type == "toolCall"` or similar)
+    public let id: String?
+    public let name: String?
+    public let arguments: AnyCodable?
+
+    public init(
+        type: String?,
+        text: String?,
+        thinking: String? = nil,
+        thinkingSignature: String? = nil,
+        mimeType: String?,
+        fileName: String?,
+        content: AnyCodable?,
+        id: String? = nil,
+        name: String? = nil,
+        arguments: AnyCodable? = nil)
+    {
+        self.type = type
+        self.text = text
+        self.thinking = thinking
+        self.thinkingSignature = thinkingSignature
+        self.mimeType = mimeType
+        self.fileName = fileName
+        self.content = content
+        self.id = id
+        self.name = name
+        self.arguments = arguments
+    }
+
+    enum CodingKeys: String, CodingKey {
+        case type
+        case text
+        case thinking
+        case thinkingSignature
+        case mimeType
+        case fileName
+        case content
+        case id
+        case name
+        case arguments
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        self.type = try container.decodeIfPresent(String.self, forKey: .type)
+        self.text = try container.decodeIfPresent(String.self, forKey: .text)
+        self.thinking = try container.decodeIfPresent(String.self, forKey: .thinking)
+        self.thinkingSignature = try container.decodeIfPresent(String.self, forKey: .thinkingSignature)
+        self.mimeType = try container.decodeIfPresent(String.self, forKey: .mimeType)
+        self.fileName = try container.decodeIfPresent(String.self, forKey: .fileName)
+        self.id = try container.decodeIfPresent(String.self, forKey: .id)
+        self.name = try container.decodeIfPresent(String.self, forKey: .name)
+        self.arguments = try container.decodeIfPresent(AnyCodable.self, forKey: .arguments)
+
+        if let any = try container.decodeIfPresent(AnyCodable.self, forKey: .content) {
+            self.content = any
+        } else if let str = try container.decodeIfPresent(String.self, forKey: .content) {
+            self.content = AnyCodable(str)
+        } else {
+            self.content = nil
+        }
+    }
+}
+
+public struct OpenClawChatMessage: Codable, Hashable, Identifiable, Sendable {
+    private struct OpenClawMetadata: Codable {
+        let idempotencyKey: String?
+    }
+
+    public var id: UUID = .init()
+    public let role: String
+    public let content: [OpenClawChatMessageContent]
+    public let timestamp: Double?
+    public let idempotencyKey: String?
+    public let toolCallId: String?
+    public let toolName: String?
+    public let usage: OpenClawChatUsage?
+    public let stopReason: String?
+    public let errorMessage: String?
+
+    enum CodingKeys: String, CodingKey {
+        case role
+        case content
+        case timestamp
+        case idempotencyKey
+        case openClaw = "__openclaw"
+        case toolCallId
+        case tool_call_id
+        case toolName
+        case tool_name
+        case usage
+        case stopReason
+        case errorMessage
+    }
+
+    public init(
+        id: UUID = .init(),
+        role: String,
+        content: [OpenClawChatMessageContent],
+        timestamp: Double?,
+        idempotencyKey: String? = nil,
+        toolCallId: String? = nil,
+        toolName: String? = nil,
+        usage: OpenClawChatUsage? = nil,
+        stopReason: String? = nil,
+        errorMessage: String? = nil)
+    {
+        self.id = id
+        self.role = role
+        self.content = content
+        self.timestamp = timestamp
+        self.idempotencyKey = idempotencyKey
+        self.toolCallId = toolCallId
+        self.toolName = toolName
+        self.usage = usage
+        self.stopReason = stopReason
+        self.errorMessage = errorMessage
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        let decodedRole = try container.decode(String.self, forKey: .role)
+        let decodedTimestamp = try container.decodeIfPresent(Double.self, forKey: .timestamp)
+        let decodedOpenClaw = try container.decodeIfPresent(OpenClawMetadata.self, forKey: .openClaw)
+        let decodedIdempotencyKey = try decodedOpenClaw?.idempotencyKey ??
+            container.decodeIfPresent(String.self, forKey: .idempotencyKey)
+        let decodedToolCallId =
+            try container.decodeIfPresent(String.self, forKey: .toolCallId) ??
+            container.decodeIfPresent(String.self, forKey: .tool_call_id)
+        let decodedToolName =
+            try container.decodeIfPresent(String.self, forKey: .toolName) ??
+            container.decodeIfPresent(String.self, forKey: .tool_name)
+        let decodedUsage = try container.decodeIfPresent(OpenClawChatUsage.self, forKey: .usage)
+        let decodedStopReason = try container.decodeIfPresent(String.self, forKey: .stopReason)
+        let decodedErrorMessage = try container.decodeIfPresent(String.self, forKey: .errorMessage)
+
+        self.role = decodedRole
+        self.timestamp = decodedTimestamp
+        self.idempotencyKey = decodedIdempotencyKey
+        self.toolCallId = decodedToolCallId
+        self.toolName = decodedToolName
+        self.usage = decodedUsage
+        self.stopReason = decodedStopReason
+        self.errorMessage = decodedErrorMessage
+
+        if let decoded = try? container.decode([OpenClawChatMessageContent].self, forKey: .content) {
+            self.content = decoded
+            return
+        }
+
+        // Some session log formats store `content` as a plain string.
+        if let text = try? container.decode(String.self, forKey: .content) {
+            self.content = [
+                OpenClawChatMessageContent(
+                    type: "text",
+                    text: text,
+                    thinking: nil,
+                    thinkingSignature: nil,
+                    mimeType: nil,
+                    fileName: nil,
+                    content: nil,
+                    id: nil,
+                    name: nil,
+                    arguments: nil),
+            ]
+            return
+        }
+
+        self.content = []
+    }
+
+    static func displayText(
+        contentText: String,
+        role: String,
+        stopReason: String?,
+        errorMessage: String?) -> String
+    {
+        let text = contentText.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard let errorText = Self.errorDisplayText(
+            role: role,
+            stopReason: stopReason,
+            errorMessage: errorMessage)
+        else {
+            return text
+        }
+        if text.isEmpty || text == Self.streamErrorFallbackText {
+            return errorText
+        }
+        return text
+    }
+
+    static func errorDisplayText(role: String, stopReason: String?, errorMessage: String?) -> String? {
+        let normalizedRole = role.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        let normalizedStopReason = stopReason?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        guard normalizedRole == "assistant",
+              normalizedStopReason == "error",
+              let text = errorMessage?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !text.isEmpty
+        else {
+            return nil
+        }
+        return text
+    }
+
+    private static let streamErrorFallbackText = "[assistant turn failed before producing content]"
+
+    public func encode(to encoder: Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode(self.role, forKey: .role)
+        try container.encodeIfPresent(self.timestamp, forKey: .timestamp)
+        try container.encodeIfPresent(self.idempotencyKey, forKey: .idempotencyKey)
+        try container.encodeIfPresent(self.toolCallId, forKey: .toolCallId)
+        try container.encodeIfPresent(self.toolName, forKey: .toolName)
+        try container.encodeIfPresent(self.usage, forKey: .usage)
+        try container.encodeIfPresent(self.stopReason, forKey: .stopReason)
+        try container.encodeIfPresent(self.errorMessage, forKey: .errorMessage)
+        try container.encode(self.content, forKey: .content)
+    }
+}
+
+public struct OpenClawChatHistoryPayload: Codable, Sendable {
+    public let sessionKey: String
+    public let sessionId: String?
+    public let messages: [AnyCodable]?
+    public let thinkingLevel: String?
+}
+
+public struct OpenClawSessionPreviewItem: Codable, Hashable, Sendable {
+    public let role: String
+    public let text: String
+}
+
+public struct OpenClawSessionPreviewEntry: Codable, Sendable {
+    public let key: String
+    public let status: String
+    public let items: [OpenClawSessionPreviewItem]
+}
+
+public struct OpenClawSessionsPreviewPayload: Codable, Sendable {
+    public let ts: Int
+    public let previews: [OpenClawSessionPreviewEntry]
+
+    public init(ts: Int, previews: [OpenClawSessionPreviewEntry]) {
+        self.ts = ts
+        self.previews = previews
+    }
+}
+
+public struct OpenClawChatSendResponse: Codable, Sendable {
+    public let runId: String
+    public let status: String
+}
+
+public struct OpenClawChatCreateSessionResponse: Codable, Sendable {
+    public let ok: Bool?
+    public let key: String
+    public let sessionId: String?
+}
+
+public struct OpenClawChatEventPayload: Codable, Sendable {
+    public let runId: String?
+    public let sessionKey: String?
+    public let state: String?
+    public let message: AnyCodable?
+    public let errorMessage: String?
+}
+
+public struct OpenClawSessionMessageEventPayload: Codable, Sendable {
+    public let sessionKey: String?
+    public let agentId: String?
+    public let message: OpenClawChatMessage?
+    public let messageId: String?
+    public let messageSeq: Int?
+
+    public init(
+        sessionKey: String?,
+        agentId: String? = nil,
+        message: OpenClawChatMessage?,
+        messageId: String?,
+        messageSeq: Int?)
+    {
+        self.sessionKey = sessionKey
+        self.agentId = agentId
+        self.message = message
+        self.messageId = messageId
+        self.messageSeq = messageSeq
+    }
+}
+
+public struct OpenClawAgentEventPayload: Codable, Sendable, Identifiable {
+    public var id: String {
+        "\(self.runId)-\(self.seq ?? -1)"
+    }
+
+    public let runId: String
+    public let seq: Int?
+    public let stream: String
+    public let ts: Int?
+    public let data: [String: AnyCodable]
+}
+
+public struct OpenClawChatPendingToolCall: Identifiable, Hashable, Sendable {
+    public var id: String {
+        self.toolCallId
+    }
+
+    public let toolCallId: String
+    public let name: String
+    public let args: AnyCodable?
+    public let startedAt: Double?
+    public let isError: Bool?
+}
+
+public struct OpenClawGatewayHealthOK: Codable, Sendable {
+    public let ok: Bool?
+}
+
+public struct OpenClawPendingAttachment: Identifiable {
+    public let id = UUID()
+    public let url: URL?
+    public let data: Data
+    public let fileName: String
+    public let mimeType: String
+    public let type: String
+    public let preview: OpenClawPlatformImage?
+
+    public init(
+        url: URL?,
+        data: Data,
+        fileName: String,
+        mimeType: String,
+        type: String = "file",
+        preview: OpenClawPlatformImage?)
+    {
+        self.url = url
+        self.data = data
+        self.fileName = fileName
+        self.mimeType = mimeType
+        self.type = type
+        self.preview = preview
+    }
+}
+
+public struct OpenClawChatAttachmentPayload: Codable, Sendable, Hashable {
+    public let type: String
+    public let mimeType: String
+    public let fileName: String
+    public let content: String
+
+    public init(type: String, mimeType: String, fileName: String, content: String) {
+        self.type = type
+        self.mimeType = mimeType
+        self.fileName = fileName
+        self.content = content
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatPayloadDecoding.swift

@@ -0,0 +1,9 @@
+import Foundation
+import OpenClawKit
+
+enum ChatPayloadDecoding {
+    static func decode<T: Decodable>(_ payload: AnyCodable, as _: T.Type = T.self) throws -> T {
+        let data = try JSONEncoder().encode(payload)
+        return try JSONDecoder().decode(T.self, from: data)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSessions.swift

@@ -0,0 +1,174 @@
+import Foundation
+
+public struct OpenClawChatThinkingLevelOption: Codable, Identifiable, Sendable, Hashable {
+    public let id: String
+    public let label: String
+
+    public init(id: String, label: String) {
+        self.id = id
+        self.label = label
+    }
+}
+
+public struct OpenClawChatModelChoice: Identifiable, Codable, Sendable, Hashable {
+    public var id: String {
+        self.selectionID
+    }
+
+    public let modelID: String
+    public let name: String
+    public let provider: String
+    public let contextWindow: Int?
+
+    public init(modelID: String, name: String, provider: String, contextWindow: Int?) {
+        self.modelID = modelID
+        self.name = name
+        self.provider = provider
+        self.contextWindow = contextWindow
+    }
+
+    /// Provider-qualified model ref used for picker identity and selection tags.
+    public var selectionID: String {
+        let trimmedProvider = self.provider.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedProvider.isEmpty else { return self.modelID }
+        let providerPrefix = "\(trimmedProvider)/"
+        if self.modelID.hasPrefix(providerPrefix) {
+            return self.modelID
+        }
+        return "\(trimmedProvider)/\(self.modelID)"
+    }
+
+    public var displayLabel: String {
+        self.selectionID
+    }
+}
+
+public struct OpenClawChatSessionsDefaults: Codable, Sendable {
+    public let modelProvider: String?
+    public let model: String?
+    public let contextTokens: Int?
+    public let thinkingLevels: [OpenClawChatThinkingLevelOption]?
+    public let thinkingOptions: [String]?
+    public let thinkingDefault: String?
+    public let mainSessionKey: String?
+
+    public init(
+        modelProvider: String? = nil,
+        model: String?,
+        contextTokens: Int?,
+        thinkingLevels: [OpenClawChatThinkingLevelOption]? = nil,
+        thinkingOptions: [String]? = nil,
+        thinkingDefault: String? = nil,
+        mainSessionKey: String? = nil)
+    {
+        self.modelProvider = modelProvider
+        self.model = model
+        self.contextTokens = contextTokens
+        self.thinkingLevels = thinkingLevels
+        self.thinkingOptions = thinkingOptions
+        self.thinkingDefault = thinkingDefault
+        self.mainSessionKey = mainSessionKey
+    }
+}
+
+public struct OpenClawChatSessionEntry: Codable, Identifiable, Sendable, Hashable {
+    public var id: String {
+        self.key
+    }
+
+    public let key: String
+    public let kind: String?
+    public let displayName: String?
+    public let surface: String?
+    public let subject: String?
+    public let room: String?
+    public let space: String?
+    public let updatedAt: Double?
+    public let sessionId: String?
+
+    public let systemSent: Bool?
+    public let abortedLastRun: Bool?
+    public let thinkingLevel: String?
+    public let verboseLevel: String?
+
+    public let inputTokens: Int?
+    public let outputTokens: Int?
+    public let totalTokens: Int?
+
+    public let modelProvider: String?
+    public let model: String?
+    public let contextTokens: Int?
+    public let thinkingLevels: [OpenClawChatThinkingLevelOption]?
+    public let thinkingOptions: [String]?
+    public let thinkingDefault: String?
+
+    public init(
+        key: String,
+        kind: String?,
+        displayName: String?,
+        surface: String?,
+        subject: String?,
+        room: String?,
+        space: String?,
+        updatedAt: Double?,
+        sessionId: String?,
+        systemSent: Bool?,
+        abortedLastRun: Bool?,
+        thinkingLevel: String?,
+        verboseLevel: String?,
+        inputTokens: Int?,
+        outputTokens: Int?,
+        totalTokens: Int?,
+        modelProvider: String?,
+        model: String?,
+        contextTokens: Int?,
+        thinkingLevels: [OpenClawChatThinkingLevelOption]? = nil,
+        thinkingOptions: [String]? = nil,
+        thinkingDefault: String? = nil)
+    {
+        self.key = key
+        self.kind = kind
+        self.displayName = displayName
+        self.surface = surface
+        self.subject = subject
+        self.room = room
+        self.space = space
+        self.updatedAt = updatedAt
+        self.sessionId = sessionId
+        self.systemSent = systemSent
+        self.abortedLastRun = abortedLastRun
+        self.thinkingLevel = thinkingLevel
+        self.verboseLevel = verboseLevel
+        self.inputTokens = inputTokens
+        self.outputTokens = outputTokens
+        self.totalTokens = totalTokens
+        self.modelProvider = modelProvider
+        self.model = model
+        self.contextTokens = contextTokens
+        self.thinkingLevels = thinkingLevels
+        self.thinkingOptions = thinkingOptions
+        self.thinkingDefault = thinkingDefault
+    }
+}
+
+public struct OpenClawChatSessionsListResponse: Codable, Sendable {
+    public let ts: Double?
+    public let path: String?
+    public let count: Int?
+    public let defaults: OpenClawChatSessionsDefaults?
+    public let sessions: [OpenClawChatSessionEntry]
+
+    public init(
+        ts: Double?,
+        path: String?,
+        count: Int?,
+        defaults: OpenClawChatSessionsDefaults?,
+        sessions: [OpenClawChatSessionEntry])
+    {
+        self.ts = ts
+        self.path = path
+        self.count = count
+        self.defaults = defaults
+        self.sessions = sessions
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatSheets.swift

@@ -0,0 +1,69 @@
+import Observation
+import SwiftUI
+
+@MainActor
+struct ChatSessionsSheet: View {
+    @Bindable var viewModel: OpenClawChatViewModel
+    @Environment(\.dismiss) private var dismiss
+
+    var body: some View {
+        NavigationStack {
+            List(self.viewModel.sessions) { session in
+                Button {
+                    self.viewModel.switchSession(to: session.key)
+                    self.dismiss()
+                } label: {
+                    VStack(alignment: .leading, spacing: 4) {
+                        Text(session.displayName ?? session.key)
+                            .font(OpenClawChatTypography.mono(size: 17, relativeTo: .body))
+                            .lineLimit(1)
+                        if let updatedAt = session.updatedAt, updatedAt > 0 {
+                            Text(Date(timeIntervalSince1970: updatedAt / 1000).formatted(
+                                date: .abbreviated,
+                                time: .shortened))
+                                .font(OpenClawChatTypography.caption)
+                                .foregroundStyle(.secondary)
+                        }
+                    }
+                }
+            }
+            .navigationTitle("Sessions")
+            .toolbar {
+                #if os(macOS)
+                ToolbarItem(placement: .automatic) {
+                    Button {
+                        self.viewModel.refreshSessions(limit: 200)
+                    } label: {
+                        Image(systemName: "arrow.clockwise")
+                    }
+                }
+                ToolbarItem(placement: .primaryAction) {
+                    Button {
+                        self.dismiss()
+                    } label: {
+                        Image(systemName: "xmark")
+                    }
+                }
+                #else
+                ToolbarItem(placement: .topBarLeading) {
+                    Button {
+                        self.viewModel.refreshSessions(limit: 200)
+                    } label: {
+                        Image(systemName: "arrow.clockwise")
+                    }
+                }
+                ToolbarItem(placement: .topBarTrailing) {
+                    Button {
+                        self.dismiss()
+                    } label: {
+                        Image(systemName: "xmark")
+                    }
+                }
+                #endif
+            }
+            .onAppear {
+                self.viewModel.refreshSessions(limit: 200)
+            }
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatTheme.swift

@@ -0,0 +1,241 @@
+import SwiftUI
+
+#if os(macOS)
+import AppKit
+#else
+import UIKit
+#endif
+
+#if os(macOS)
+extension NSAppearance {
+    fileprivate var isDarkAqua: Bool {
+        self.bestMatch(from: [.aqua, .darkAqua]) == .darkAqua
+    }
+}
+#endif
+
+enum OpenClawChatTheme {
+    #if !os(macOS)
+    private enum IOSPalette {
+        static let lightCanvasTop = UIColor(red: 246 / 255.0, green: 247 / 255.0, blue: 249 / 255.0, alpha: 1)
+        static let lightCanvasMiddle = UIColor(red: 250 / 255.0, green: 251 / 255.0, blue: 252 / 255.0, alpha: 1)
+        static let lightCanvasBottom = UIColor.white
+        static let lightAccent = UIColor(red: 220 / 255.0, green: 38 / 255.0, blue: 38 / 255.0, alpha: 1)
+        static let lightAccentHot = UIColor(red: 239 / 255.0, green: 68 / 255.0, blue: 68 / 255.0, alpha: 1)
+        static let darkCanvasTop = UIColor(red: 12 / 255.0, green: 13 / 255.0, blue: 15 / 255.0, alpha: 1)
+        static let darkCanvasMiddle = UIColor(red: 7 / 255.0, green: 8 / 255.0, blue: 10 / 255.0, alpha: 1)
+        static let darkCanvasBottom = UIColor(red: 4 / 255.0, green: 5 / 255.0, blue: 6 / 255.0, alpha: 1)
+        static let darkPanel = UIColor(red: 10 / 255.0, green: 12 / 255.0, blue: 14 / 255.0, alpha: 1)
+        static let darkPanelRaised = UIColor(red: 17 / 255.0, green: 18 / 255.0, blue: 21 / 255.0, alpha: 1)
+        static let darkComposer = UIColor(red: 24 / 255.0, green: 25 / 255.0, blue: 28 / 255.0, alpha: 1)
+        static let darkAccent = UIColor(red: 198 / 255.0, green: 49 / 255.0, blue: 42 / 255.0, alpha: 1)
+        static let darkAccentHot = UIColor(red: 239 / 255.0, green: 62 / 255.0, blue: 82 / 255.0, alpha: 1)
+    }
+
+    private static func adaptiveColor(
+        light: UIColor,
+        dark: UIColor) -> Color
+    {
+        Color(uiColor: UIColor { traits in
+            traits.userInterfaceStyle == .dark ? dark : light
+        })
+    }
+    #endif
+
+    #if os(macOS)
+    static func resolvedAssistantBubbleColor(for appearance: NSAppearance) -> NSColor {
+        // NSColor semantic colors don't reliably resolve for arbitrary NSAppearance in SwiftPM.
+        // Use explicit light/dark values so the bubble updates when the system appearance flips.
+        appearance.isDarkAqua
+            ? NSColor(calibratedWhite: 0.18, alpha: 0.88)
+            : NSColor(calibratedWhite: 0.94, alpha: 0.92)
+    }
+
+    static func resolvedOnboardingAssistantBubbleColor(for appearance: NSAppearance) -> NSColor {
+        appearance.isDarkAqua
+            ? NSColor(calibratedWhite: 0.20, alpha: 0.94)
+            : NSColor(calibratedWhite: 0.97, alpha: 0.98)
+    }
+
+    static let assistantBubbleDynamicNSColor = NSColor(
+        name: NSColor.Name("OpenClawChatTheme.assistantBubble"),
+        dynamicProvider: resolvedAssistantBubbleColor(for:))
+
+    static let onboardingAssistantBubbleDynamicNSColor = NSColor(
+        name: NSColor.Name("OpenClawChatTheme.onboardingAssistantBubble"),
+        dynamicProvider: resolvedOnboardingAssistantBubbleColor(for:))
+    #endif
+
+    static var surface: Color {
+        #if os(macOS)
+        Color(nsColor: .windowBackgroundColor)
+        #else
+        Color(uiColor: .systemBackground)
+        #endif
+    }
+
+    @ViewBuilder
+    static var background: some View {
+        #if os(macOS)
+        ZStack {
+            Rectangle()
+                .fill(.ultraThinMaterial)
+            LinearGradient(
+                colors: [
+                    Color.white.opacity(0.12),
+                    Color(nsColor: .windowBackgroundColor).opacity(0.35),
+                    Color.black.opacity(0.35),
+                ],
+                startPoint: .topLeading,
+                endPoint: .bottomTrailing)
+            RadialGradient(
+                colors: [
+                    Color(nsColor: .systemOrange).opacity(0.14),
+                    .clear,
+                ],
+                center: .topLeading,
+                startRadius: 40,
+                endRadius: 320)
+            RadialGradient(
+                colors: [
+                    Color(nsColor: .systemTeal).opacity(0.12),
+                    .clear,
+                ],
+                center: .topTrailing,
+                startRadius: 40,
+                endRadius: 280)
+            Color.black.opacity(0.08)
+        }
+        #else
+        ZStack {
+            LinearGradient(
+                colors: [
+                    self.adaptiveColor(
+                        light: IOSPalette.lightCanvasTop,
+                        dark: IOSPalette.darkCanvasTop),
+                    self.adaptiveColor(
+                        light: IOSPalette.lightCanvasMiddle,
+                        dark: IOSPalette.darkCanvasMiddle),
+                    self.adaptiveColor(
+                        light: IOSPalette.lightCanvasBottom,
+                        dark: IOSPalette.darkCanvasBottom),
+                ],
+                startPoint: .topLeading,
+                endPoint: .bottomTrailing)
+        }
+        #endif
+    }
+
+    static var card: Color {
+        #if os(macOS)
+        Color(nsColor: .textBackgroundColor)
+        #else
+        self.adaptiveColor(light: .secondarySystemBackground, dark: IOSPalette.darkPanel)
+        #endif
+    }
+
+    static var subtleCard: AnyShapeStyle {
+        #if os(macOS)
+        AnyShapeStyle(.ultraThinMaterial)
+        #else
+        AnyShapeStyle(self.adaptiveColor(light: .tertiarySystemBackground, dark: IOSPalette.darkPanelRaised))
+        #endif
+    }
+
+    static var userBubble: Color {
+        #if os(macOS)
+        Color(red: 127 / 255.0, green: 184 / 255.0, blue: 212 / 255.0)
+        #else
+        self.adaptiveColor(
+            light: IOSPalette.lightAccent,
+            dark: IOSPalette.darkAccent)
+        #endif
+    }
+
+    static var accent: Color {
+        self.userBubble
+    }
+
+    static var danger: Color {
+        #if os(macOS)
+        Color(nsColor: .systemRed)
+        #else
+        Color(uiColor: .systemRed)
+        #endif
+    }
+
+    static var assistantBubble: Color {
+        #if os(macOS)
+        Color(nsColor: self.assistantBubbleDynamicNSColor)
+        #else
+        // iMessage-style grey receiver bubble: clearly visible on the white chat surface.
+        self.adaptiveColor(light: .systemGray5, dark: IOSPalette.darkPanelRaised)
+        #endif
+    }
+
+    static var onboardingAssistantBubble: Color {
+        #if os(macOS)
+        Color(nsColor: self.onboardingAssistantBubbleDynamicNSColor)
+        #else
+        self.adaptiveColor(light: .secondarySystemBackground, dark: IOSPalette.darkPanelRaised)
+        #endif
+    }
+
+    static var onboardingAssistantBorder: Color {
+        #if os(macOS)
+        Color.white.opacity(0.12)
+        #else
+        Color.white.opacity(0.12)
+        #endif
+    }
+
+    static var userText: Color {
+        .white
+    }
+
+    static var assistantText: Color {
+        #if os(macOS)
+        Color(nsColor: .labelColor)
+        #else
+        Color(uiColor: .label)
+        #endif
+    }
+
+    static var composerBackground: AnyShapeStyle {
+        #if os(macOS)
+        AnyShapeStyle(.ultraThinMaterial)
+        #else
+        AnyShapeStyle(self.adaptiveColor(light: .secondarySystemGroupedBackground, dark: IOSPalette.darkPanel))
+        #endif
+    }
+
+    static var composerField: AnyShapeStyle {
+        #if os(macOS)
+        AnyShapeStyle(.thinMaterial)
+        #else
+        AnyShapeStyle(self.adaptiveColor(light: .secondarySystemBackground, dark: IOSPalette.darkComposer))
+        #endif
+    }
+
+    static var composerBorder: Color {
+        #if os(macOS)
+        Color.white.opacity(0.12)
+        #else
+        self.adaptiveColor(light: .separator, dark: UIColor.white.withAlphaComponent(0.14))
+        #endif
+    }
+
+    static var divider: Color {
+        Color.secondary.opacity(0.2)
+    }
+}
+
+enum OpenClawPlatformImageFactory {
+    static func image(_ image: OpenClawPlatformImage) -> Image {
+        #if os(macOS)
+        Image(nsImage: image)
+        #else
+        Image(uiImage: image)
+        #endif
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatTransport.swift

@@ -0,0 +1,117 @@
+import Foundation
+
+public enum OpenClawChatTransportEvent: Sendable {
+    case health(ok: Bool)
+    case tick
+    case chat(OpenClawChatEventPayload)
+    case sessionMessage(OpenClawSessionMessageEventPayload)
+    case agent(OpenClawAgentEventPayload)
+    case seqGap
+}
+
+public protocol OpenClawChatTransport: Sendable {
+    func createSession(
+        key: String,
+        label: String?,
+        parentSessionKey: String?) async throws -> OpenClawChatCreateSessionResponse
+
+    func requestHistory(sessionKey: String) async throws -> OpenClawChatHistoryPayload
+    func listModels() async throws -> [OpenClawChatModelChoice]
+    var supportsSlashCommandCatalog: Bool { get }
+    func listCommands(sessionKey: String) async throws -> [OpenClawChatCommandChoice]
+    func sendMessage(
+        sessionKey: String,
+        message: String,
+        thinking: String,
+        idempotencyKey: String,
+        attachments: [OpenClawChatAttachmentPayload]) async throws -> OpenClawChatSendResponse
+
+    func abortRun(sessionKey: String, runId: String) async throws
+    func listSessions(limit: Int?) async throws -> OpenClawChatSessionsListResponse
+    func setSessionModel(sessionKey: String, model: String?) async throws
+    func setSessionThinking(sessionKey: String, thinkingLevel: String) async throws
+
+    func requestHealth(timeoutMs: Int) async throws -> Bool
+    func waitForRunCompletion(runId: String, timeoutMs: Int) async -> Bool
+    func events() -> AsyncStream<OpenClawChatTransportEvent>
+
+    func setActiveSessionKey(_ sessionKey: String) async throws
+    func resetSession(sessionKey: String) async throws
+    func compactSession(sessionKey: String) async throws
+}
+
+extension OpenClawChatTransport {
+    public func createSession(
+        key _: String,
+        label _: String?,
+        parentSessionKey _: String?) async throws -> OpenClawChatCreateSessionResponse
+    {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.create not supported by this transport"])
+    }
+
+    public func setActiveSessionKey(_: String) async throws {}
+
+    public func waitForRunCompletion(runId _: String, timeoutMs _: Int) async -> Bool {
+        false
+    }
+
+    public func resetSession(sessionKey _: String) async throws {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.reset not supported by this transport"])
+    }
+
+    public func compactSession(sessionKey _: String) async throws {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.compact not supported by this transport"])
+    }
+
+    public func abortRun(sessionKey _: String, runId _: String) async throws {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "chat.abort not supported by this transport"])
+    }
+
+    public func listSessions(limit _: Int?) async throws -> OpenClawChatSessionsListResponse {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.list not supported by this transport"])
+    }
+
+    public func listModels() async throws -> [OpenClawChatModelChoice] {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "models.list not supported by this transport"])
+    }
+
+    public var supportsSlashCommandCatalog: Bool {
+        false
+    }
+
+    public func listCommands(sessionKey _: String) async throws -> [OpenClawChatCommandChoice] {
+        []
+    }
+
+    public func setSessionModel(sessionKey _: String, model _: String?) async throws {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.patch(model) not supported by this transport"])
+    }
+
+    public func setSessionThinking(sessionKey _: String, thinkingLevel _: String) async throws {
+        throw NSError(
+            domain: "OpenClawChatTransport",
+            code: 0,
+            userInfo: [NSLocalizedDescriptionKey: "sessions.patch(thinkingLevel) not supported by this transport"])
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatTypography.swift

@@ -0,0 +1,98 @@
+import Foundation
+import SwiftUI
+#if os(macOS)
+import AppKit
+#endif
+
+enum OpenClawChatTypography {
+    static var title3: Font {
+        display(size: 22, weight: .bold, relativeTo: .title2)
+    }
+
+    static var title3SemiBold: Font {
+        display(size: 22, weight: .semibold, relativeTo: .title2)
+    }
+
+    static var headline: Font {
+        display(size: 17, weight: .semibold, relativeTo: .headline)
+    }
+
+    static var callout: Font {
+        body(size: 16, weight: .regular, relativeTo: .callout)
+    }
+
+    static var body: Font {
+        body(size: 17, weight: .regular, relativeTo: .body)
+    }
+
+    static var footnote: Font {
+        body(size: 13, weight: .regular, relativeTo: .footnote)
+    }
+
+    static var footnoteSemiBold: Font {
+        body(size: 13, weight: .semibold, relativeTo: .footnote)
+    }
+
+    static var caption: Font {
+        body(size: 12, weight: .regular, relativeTo: .caption)
+    }
+
+    static var captionSemiBold: Font {
+        body(size: 12, weight: .semibold, relativeTo: .caption)
+    }
+
+    static var caption2: Font {
+        body(size: 11, weight: .regular, relativeTo: .caption2)
+    }
+
+    static func avatar(size: CGFloat) -> Font {
+        self.body(size: size, weight: .bold, relativeTo: .caption)
+    }
+
+    static func body(size: CGFloat, weight: Font.Weight, relativeTo textStyle: Font.TextStyle) -> Font {
+        #if os(iOS)
+        Font.custom(self.bodyPostScriptName, size: size, relativeTo: textStyle).weight(weight)
+        #elseif os(macOS)
+        Font.custom(self.macSystemFontName(size: size), size: size, relativeTo: textStyle).weight(weight)
+        #else
+        Font.system(size: size, weight: weight)
+        #endif
+    }
+
+    static func display(size: CGFloat, weight: Font.Weight, relativeTo textStyle: Font.TextStyle) -> Font {
+        #if os(iOS)
+        Font.custom(self.displayPostScriptName, size: size, relativeTo: textStyle).weight(weight)
+        #elseif os(macOS)
+        Font.custom(self.macSystemFontName(size: size), size: size, relativeTo: textStyle).weight(weight)
+        #else
+        Font.system(size: size, weight: weight)
+        #endif
+    }
+
+    static func mono(size: CGFloat, weight: Font.Weight = .regular, relativeTo textStyle: Font.TextStyle) -> Font {
+        #if os(iOS)
+        let name = weight == .semibold ? Self.monoSemiBoldPostScriptName : Self.monoPostScriptName
+        return Font.custom(name, size: size, relativeTo: textStyle)
+        #elseif os(macOS)
+        return Font.custom(self.macMonospacedSystemFontName(size: size), size: size, relativeTo: textStyle)
+            .weight(weight)
+        #else
+        return Font.system(size: size, weight: weight, design: .monospaced)
+        #endif
+    }
+
+    private static let displayPostScriptName = "RedHatDisplay-Regular"
+    private static let bodyPostScriptName = "Inter-Regular"
+    private static let monoPostScriptName = "JetBrainsMono-Regular"
+    private static let monoSemiBoldPostScriptName = "JetBrainsMono-SemiBold"
+
+    #if os(macOS)
+    private static func macSystemFontName(size: CGFloat) -> String {
+        NSFont.systemFont(ofSize: size).fontName
+    }
+
+    private static func macMonospacedSystemFontName(size: CGFloat) -> String {
+        NSFont.monospacedSystemFont(ofSize: size, weight: .regular).fontName
+    }
+    #endif
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView+Previews.swift

@@ -0,0 +1,256 @@
+import Foundation
+import OpenClawKit
+import SwiftUI
+
+private struct OpenClawChatPreviewTransport: OpenClawChatTransport {
+    enum Scenario {
+        case connected
+        case empty
+        case loading
+        case error
+    }
+
+    let scenario: Scenario
+
+    init(scenario: Scenario = .connected) {
+        self.scenario = scenario
+    }
+
+    func requestHistory(sessionKey: String) async throws -> OpenClawChatHistoryPayload {
+        switch self.scenario {
+        case .connected:
+            break
+        case .empty:
+            return OpenClawChatHistoryPayload(
+                sessionKey: sessionKey,
+                sessionId: "preview-empty-session",
+                messages: [],
+                thinkingLevel: "medium")
+        case .loading:
+            try await Task.sleep(nanoseconds: 60_000_000_000)
+            return OpenClawChatHistoryPayload(
+                sessionKey: sessionKey,
+                sessionId: "preview-loading-session",
+                messages: [],
+                thinkingLevel: "medium")
+        case .error:
+            throw NSError(
+                domain: "OpenClawChatPreviewTransport",
+                code: 1,
+                userInfo: [NSLocalizedDescriptionKey: "Gateway not connected. Check Tailscale and retry."])
+        }
+
+        return OpenClawChatHistoryPayload(
+            sessionKey: sessionKey,
+            sessionId: "preview-session",
+            messages: [
+                Self.message(
+                    role: "user",
+                    text: "Can you check the gateway status and summarize anything risky?",
+                    timestamp: 1),
+                Self.message(
+                    role: "assistant",
+                    text: "Gateway is reachable. The only notable item is that push relay is still using local distribution, so device tests should stay on the local lane.",
+                    timestamp: 2),
+                Self.toolCall(
+                    id: "tool-preview-1",
+                    name: "gateway.status",
+                    arguments: ["deep": AnyCodable(true)],
+                    timestamp: 3),
+                Self.toolResult(
+                    toolCallId: "tool-preview-1",
+                    name: "gateway.status",
+                    text: "status=ok, channels=ios,macos, lastHeartbeat=12s",
+                    timestamp: 4),
+            ],
+            thinkingLevel: "medium")
+    }
+
+    func listModels() async throws -> [OpenClawChatModelChoice] {
+        [
+            OpenClawChatModelChoice(
+                modelID: "gpt-5.5",
+                name: "GPT-5.5",
+                provider: "openai",
+                contextWindow: 400_000),
+            OpenClawChatModelChoice(
+                modelID: "sonnet-4.6",
+                name: "Claude Sonnet 4.6",
+                provider: "anthropic",
+                contextWindow: 200_000),
+        ]
+    }
+
+    func sendMessage(
+        sessionKey _: String,
+        message _: String,
+        thinking _: String,
+        idempotencyKey: String,
+        attachments _: [OpenClawChatAttachmentPayload]) async throws -> OpenClawChatSendResponse
+    {
+        OpenClawChatSendResponse(runId: idempotencyKey, status: "ok")
+    }
+
+    func listSessions(limit _: Int?) async throws -> OpenClawChatSessionsListResponse {
+        OpenClawChatSessionsListResponse(
+            ts: 0,
+            path: nil,
+            count: 2,
+            defaults: OpenClawChatSessionsDefaults(
+                modelProvider: "openai",
+                model: "gpt-5.5",
+                contextTokens: 400_000,
+                thinkingLevels: [
+                    OpenClawChatThinkingLevelOption(id: "off", label: "off"),
+                    OpenClawChatThinkingLevelOption(id: "medium", label: "medium"),
+                    OpenClawChatThinkingLevelOption(id: "high", label: "high"),
+                ],
+                thinkingDefault: "medium",
+                mainSessionKey: "main"),
+            sessions: [
+                Self.session(key: "main", displayName: "Main", updatedAt: 2),
+                Self.session(key: "ios-preview", displayName: "iOS preview", updatedAt: 1),
+            ])
+    }
+
+    func requestHealth(timeoutMs _: Int) async throws -> Bool {
+        switch self.scenario {
+        case .connected, .empty, .loading:
+            true
+        case .error:
+            false
+        }
+    }
+
+    func events() -> AsyncStream<OpenClawChatTransportEvent> {
+        AsyncStream { continuation in
+            continuation.finish()
+        }
+    }
+
+    func setActiveSessionKey(_: String) async throws {}
+
+    private static func message(role: String, text: String, timestamp: Double) -> AnyCodable {
+        AnyCodable([
+            "role": role,
+            "content": [["type": "text", "text": text]],
+            "timestamp": timestamp,
+        ])
+    }
+
+    private static func toolCall(
+        id: String,
+        name: String,
+        arguments: [String: AnyCodable],
+        timestamp: Double) -> AnyCodable
+    {
+        AnyCodable([
+            "role": "assistant",
+            "content": [
+                [
+                    "type": "toolCall",
+                    "id": id,
+                    "name": name,
+                    "arguments": AnyCodable(arguments),
+                ],
+            ],
+            "timestamp": timestamp,
+        ])
+    }
+
+    private static func toolResult(
+        toolCallId: String,
+        name: String,
+        text: String,
+        timestamp: Double) -> AnyCodable
+    {
+        AnyCodable([
+            "role": "tool",
+            "content": [["type": "text", "text": text]],
+            "timestamp": timestamp,
+            "toolCallId": toolCallId,
+            "toolName": name,
+        ])
+    }
+
+    private static func session(
+        key: String,
+        displayName: String,
+        updatedAt: Double) -> OpenClawChatSessionEntry
+    {
+        OpenClawChatSessionEntry(
+            key: key,
+            kind: nil,
+            displayName: displayName,
+            surface: "ios",
+            subject: nil,
+            room: nil,
+            space: nil,
+            updatedAt: updatedAt,
+            sessionId: nil,
+            systemSent: nil,
+            abortedLastRun: nil,
+            thinkingLevel: "medium",
+            verboseLevel: nil,
+            inputTokens: 2500,
+            outputTokens: 900,
+            totalTokens: 3400,
+            modelProvider: "openai",
+            model: "gpt-5.5",
+            contextTokens: 400_000)
+    }
+}
+
+#Preview("Chat") {
+    OpenClawChatPreview(scenario: .connected)
+}
+
+#Preview("Chat connected") {
+    OpenClawChatPreview(scenario: .connected)
+}
+
+#Preview("Chat empty") {
+    OpenClawChatPreview(
+        scenario: .empty,
+        sessionKey: "empty-preview")
+}
+
+#Preview("Chat loading") {
+    OpenClawChatPreview(
+        scenario: .loading,
+        sessionKey: "loading-preview")
+}
+
+#Preview("Chat gateway error") {
+    OpenClawChatPreview(
+        scenario: .error,
+        sessionKey: "error-preview")
+}
+
+#Preview("Onboarding chat") {
+    OpenClawChatView(
+        viewModel: OpenClawChatViewModel(
+            sessionKey: "ios-preview",
+            transport: OpenClawChatPreviewTransport()),
+        showsSessionSwitcher: false,
+        style: .onboarding,
+        markdownVariant: .standard,
+        userAccent: OpenClawChatTheme.accent)
+}
+
+private struct OpenClawChatPreview: View {
+    let scenario: OpenClawChatPreviewTransport.Scenario
+    var sessionKey: String = "main"
+
+    var body: some View {
+        OpenClawChatView(
+            viewModel: OpenClawChatViewModel(
+                sessionKey: self.sessionKey,
+                transport: OpenClawChatPreviewTransport(scenario: self.scenario)),
+            showsSessionSwitcher: true,
+            style: .standard,
+            markdownVariant: .standard,
+            userAccent: OpenClawChatTheme.accent,
+            showsAssistantTrace: true)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatView.swift

@@ -0,0 +1,972 @@
+import SwiftUI
+#if canImport(UIKit)
+import UIKit
+#endif
+
+enum ChatReaderUserTransition: Equatable {
+    case unchanged
+    case added(UUID)
+    case removed(latestRemainingID: UUID?)
+}
+
+func chatReaderUserTransition(
+    previousID: UUID?,
+    visibleIDs: [UUID]) -> ChatReaderUserTransition
+{
+    let latestID = visibleIDs.last
+    if let previousID, !visibleIDs.contains(previousID) {
+        return .removed(latestRemainingID: latestID)
+    }
+    if let latestID, latestID != previousID {
+        return .added(latestID)
+    }
+    return .unchanged
+}
+
+func chatReaderHasNewerContent(
+    after messageID: UUID,
+    visibleIDs: [UUID],
+    hasTransientContent: Bool) -> Bool
+{
+    guard let messageIndex = visibleIDs.firstIndex(of: messageID) else { return false }
+    return messageIndex < visibleIDs.index(before: visibleIDs.endIndex) || hasTransientContent
+}
+
+@MainActor
+public struct OpenClawChatView: View {
+    public enum Style {
+        case standard
+        case onboarding
+    }
+
+    public enum ComposerChrome {
+        case full
+        case clean
+    }
+
+    public struct StarterPrompt: Hashable, Identifiable, Sendable {
+        public let id: String
+        public let title: String
+        public let prompt: String
+
+        public init(id: String, title: String, prompt: String) {
+            self.id = id
+            self.title = title
+            self.prompt = prompt
+        }
+    }
+
+    @State private var viewModel: OpenClawChatViewModel
+    @Environment(\.scenePhase) private var scenePhase
+    @State private var scrollerBottomID = UUID()
+    @State private var scrollPosition: UUID?
+    @State private var showSessions = false
+    @State private var hasPerformedInitialScroll = false
+    @State private var lastUserMessageID: UUID?
+    @State private var hasNewerContentBelow = false
+    @State private var followTarget: ScrollFollowTarget? = .latest
+    @State private var isAtLiveEdge = true
+    @State private var isUserScrolling = false
+    private let showsSessionSwitcher: Bool
+    private let drawsBackground: Bool
+    private let style: Style
+    private let markdownVariant: ChatMarkdownVariant
+    private let userAccent: Color?
+    private let showsAssistantTrace: Bool
+    private let assistantName: String?
+    private let assistantAvatarText: String?
+    private let assistantAvatarTint: Color?
+    private let showsAssistantAvatars: Bool
+    private let composerChrome: ComposerChrome
+    private let isComposerEnabled: Bool
+    private let messagePlaceholder: String?
+    private let emptyAssistantIntro: String?
+    private let emptyAssistantPrompts: [StarterPrompt]
+    private let talkControl: OpenClawChatTalkControl?
+
+    private enum ScrollFollowTarget: Equatable {
+        case latest
+        case user(UUID)
+    }
+
+    private enum Layout {
+        #if os(macOS)
+        static let outerPaddingHorizontal: CGFloat = 6
+        static let outerPaddingVertical: CGFloat = 0
+        static let composerPaddingHorizontal: CGFloat = 0
+        static let stackSpacing: CGFloat = 0
+        static let messageSpacing: CGFloat = 6
+        static let messageListPaddingTop: CGFloat = 12
+        static let messageListPaddingBottom: CGFloat = 16
+        static let messageListPaddingHorizontal: CGFloat = 6
+        static let newTurnAnchor = UnitPoint(x: 0.5, y: 0.18)
+        static let liveEdgeThreshold: CGFloat = 48
+        #else
+        static let outerPaddingHorizontal: CGFloat = 6
+        static let outerPaddingVertical: CGFloat = 6
+        static let composerPaddingHorizontal: CGFloat = 6
+        static let stackSpacing: CGFloat = 6
+        static let messageSpacing: CGFloat = 12
+        static let messageListPaddingTop: CGFloat = 10
+        static let messageListPaddingBottom: CGFloat = 6
+        static let messageListPaddingHorizontal: CGFloat = 8
+        static let newTurnAnchor = UnitPoint(x: 0.5, y: 0.18)
+        static let liveEdgeThreshold: CGFloat = 48
+        #endif
+    }
+
+    public init(
+        viewModel: OpenClawChatViewModel,
+        drawsBackground: Bool = true,
+        showsSessionSwitcher: Bool = false,
+        style: Style = .standard,
+        markdownVariant: ChatMarkdownVariant = .standard,
+        userAccent: Color? = nil,
+        showsAssistantTrace: Bool = false,
+        assistantName: String? = nil,
+        assistantAvatarText: String? = nil,
+        assistantAvatarTint: Color? = nil,
+        showsAssistantAvatars: Bool = true,
+        composerChrome: ComposerChrome = .full,
+        isComposerEnabled: Bool = true,
+        messagePlaceholder: String? = nil,
+        emptyAssistantIntro: String? = nil,
+        emptyAssistantPrompts: [StarterPrompt] = [],
+        talkControl: OpenClawChatTalkControl? = nil)
+    {
+        _viewModel = State(initialValue: viewModel)
+        self.drawsBackground = drawsBackground
+        self.showsSessionSwitcher = showsSessionSwitcher
+        self.style = style
+        self.markdownVariant = markdownVariant
+        self.userAccent = userAccent
+        self.showsAssistantTrace = showsAssistantTrace
+        self.assistantName = assistantName
+        self.assistantAvatarText = assistantAvatarText
+        self.assistantAvatarTint = assistantAvatarTint
+        self.showsAssistantAvatars = showsAssistantAvatars
+        self.composerChrome = composerChrome
+        self.isComposerEnabled = isComposerEnabled
+        self.messagePlaceholder = messagePlaceholder
+        self.emptyAssistantIntro = emptyAssistantIntro
+        self.emptyAssistantPrompts = emptyAssistantPrompts
+        self.talkControl = talkControl
+    }
+
+    public var body: some View {
+        ZStack {
+            if self.drawsBackground, self.style == .standard {
+                OpenClawChatTheme.background
+                    .ignoresSafeArea()
+            }
+
+            self.content
+        }
+        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
+        .onAppear { self.viewModel.load() }
+        .sheet(isPresented: self.$showSessions) {
+            if self.showsSessionSwitcher {
+                ChatSessionsSheet(viewModel: self.viewModel)
+            }
+        }
+    }
+
+    @ViewBuilder
+    private var content: some View {
+        #if os(macOS)
+        VStack(spacing: Layout.stackSpacing) {
+            self.messageList
+                .padding(.horizontal, Layout.outerPaddingHorizontal)
+            self.composer
+                .padding(.horizontal, Layout.composerPaddingHorizontal)
+        }
+        .padding(.vertical, Layout.outerPaddingVertical)
+        .frame(maxWidth: .infinity)
+        .frame(maxHeight: .infinity, alignment: .top)
+        #else
+        VStack(spacing: 0) {
+            self.messageList
+                .padding(.horizontal, Layout.outerPaddingHorizontal)
+            self.composer
+                .padding(.horizontal, Layout.composerPaddingHorizontal)
+                .padding(.top, Layout.stackSpacing)
+                .padding(.bottom, Layout.outerPaddingVertical)
+        }
+        .padding(.top, Layout.outerPaddingVertical)
+        .frame(maxWidth: .infinity)
+        .frame(maxHeight: .infinity, alignment: .top)
+        #endif
+    }
+
+    private var composer: some View {
+        OpenClawChatComposer(
+            viewModel: self.viewModel,
+            style: self.style,
+            showsSessionSwitcher: self.showsSessionSwitcher,
+            userAccent: self.userAccent,
+            assistantName: self.assistantName,
+            assistantAvatarText: self.assistantAvatarText,
+            assistantAvatarTint: self.assistantAvatarTint,
+            composerChrome: self.composerChrome,
+            isComposerEnabled: self.isComposerEnabled,
+            messagePlaceholder: self.messagePlaceholder,
+            talkControl: self.talkControl)
+    }
+
+    private var messageList: some View {
+        ZStack {
+            ScrollView {
+                LazyVStack(spacing: Layout.messageSpacing) {
+                    self.messageListRows
+
+                    Color.clear
+                    #if os(macOS)
+                        .frame(height: Layout.messageListPaddingBottom)
+                    #else
+                        .frame(height: Layout.messageListPaddingBottom + 1)
+                    #endif
+                        .id(self.scrollerBottomID)
+                }
+                // Use scroll targets for stable auto-scroll without ScrollViewReader relayout glitches.
+                .scrollTargetLayout()
+                .padding(.top, Layout.messageListPaddingTop)
+                .padding(.horizontal, Layout.messageListPaddingHorizontal)
+            }
+            #if !os(macOS)
+            .scrollDismissesKeyboard(.interactively)
+            #endif
+            .safeAreaInset(edge: .top, spacing: 0) {
+                self.messageListNoticeBanner
+            }
+            .scrollPosition(id: self.$scrollPosition, anchor: .bottom)
+            .onScrollGeometryChange(for: Bool.self) { geometry in
+                let distanceFromBottom = geometry.contentSize.height - geometry.visibleRect.maxY
+                return distanceFromBottom <= Layout.liveEdgeThreshold
+            } action: { _, isAtLiveEdge in
+                self.isAtLiveEdge = isAtLiveEdge
+                guard self.hasPerformedInitialScroll else { return }
+                if isAtLiveEdge, !self.isUserScrolling, !self.isFollowingUserTurn {
+                    self.followTarget = .latest
+                    self.hasNewerContentBelow = false
+                }
+            }
+            .onScrollPhaseChange { _, phase in
+                guard self.hasPerformedInitialScroll else { return }
+                if phase == .interacting {
+                    self.isUserScrolling = true
+                    self.followTarget = nil
+                } else if phase == .idle, self.isUserScrolling {
+                    self.isUserScrolling = false
+                    if self.isAtLiveEdge {
+                        self.followTarget = .latest
+                        self.hasNewerContentBelow = false
+                    } else {
+                        self.hasNewerContentBelow = true
+                    }
+                }
+            }
+
+            if self.viewModel.isLoading, self.composerChrome == .full {
+                ProgressView()
+                    .controlSize(.large)
+                    .frame(maxWidth: .infinity, maxHeight: .infinity)
+            }
+
+            self.messageListOverlay
+
+            if self.showsJumpToLatest {
+                self.jumpToLatestButton
+                    .padding(.bottom, 12)
+                    .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .bottom)
+                    .transition(.move(edge: .bottom).combined(with: .opacity))
+            }
+        }
+        // Ensure the message list claims vertical space on the first layout pass.
+        .frame(maxHeight: .infinity, alignment: .top)
+        .layoutPriority(1)
+        .simultaneousGesture(
+            TapGesture().onEnded {
+                self.dismissKeyboardIfNeeded()
+            })
+        .onChange(of: self.viewModel.isLoading) { _, isLoading in
+            guard !isLoading, !self.hasPerformedInitialScroll else { return }
+            self.restoreInitialScrollPosition()
+            self.hasPerformedInitialScroll = true
+            self.lastUserMessageID = self.latestVisibleUserMessageID
+        }
+        .onChange(of: self.viewModel.sessionKey) { _, _ in
+            self.hasPerformedInitialScroll = false
+            self.followTarget = .latest
+            self.isAtLiveEdge = true
+            self.isUserScrolling = false
+            self.hasNewerContentBelow = false
+            self.lastUserMessageID = nil
+        }
+        .onChange(of: self.scenePhase) { _, newValue in
+            guard newValue == .active else { return }
+            self.viewModel.resumeFromForeground()
+        }
+        .onChange(of: self.viewModel.timelineRevision) { _, _ in
+            self.handleTimelineChange()
+        }
+    }
+
+    @ViewBuilder
+    private var messageListRows: some View {
+        if let introText = visibleEmptyAssistantIntro {
+            ChatAssistantIntroCard(
+                text: introText,
+                prompts: self.emptyAssistantPrompts,
+                onPrompt: { prompt in
+                    self.viewModel.input = prompt.prompt
+                    self.viewModel.send()
+                })
+                .frame(maxWidth: .infinity, alignment: .leading)
+        }
+
+        if self.showsCleanLoadingPlaceholder {
+            ChatLoadingBubble()
+                .frame(maxWidth: .infinity, alignment: .leading)
+        }
+
+        ForEach(self.visibleMessages) { msg in
+            ChatMessageBubble(
+                message: msg,
+                style: self.style,
+                markdownVariant: self.markdownVariant,
+                userAccent: self.userAccent,
+                showsAssistantTrace: self.showsAssistantTrace,
+                assistantName: self.assistantName,
+                assistantAvatarText: self.assistantAvatarText,
+                assistantAvatarTint: self.assistantAvatarTint,
+                showsAssistantAvatar: self.showsAssistantAvatars,
+                isClean: self.composerChrome == .clean)
+                .frame(
+                    maxWidth: .infinity,
+                    alignment: msg.role.lowercased() == "user" ? .trailing : .leading)
+        }
+
+        if self.viewModel.pendingRunCount > 0 {
+            ChatTypingIndicatorBubble(
+                style: self.style,
+                assistantName: self.assistantName,
+                assistantAvatarText: self.assistantAvatarText,
+                assistantAvatarTint: self.assistantAvatarTint,
+                showsAssistantAvatar: self.showsAssistantAvatars,
+                isClean: self.composerChrome == .clean)
+                .equatable()
+        }
+
+        if !self.viewModel.pendingToolCalls.isEmpty {
+            ChatPendingToolsBubble(
+                toolCalls: self.viewModel.pendingToolCalls,
+                isClean: self.composerChrome == .clean)
+                .equatable()
+                .frame(maxWidth: .infinity, alignment: .leading)
+        }
+
+        if let text = viewModel.streamingAssistantText,
+           AssistantTextParser.hasVisibleContent(in: text, includeThinking: self.showsAssistantTrace)
+        {
+            ChatStreamingAssistantBubble(
+                text: text,
+                markdownVariant: self.markdownVariant,
+                showsAssistantTrace: self.showsAssistantTrace,
+                assistantName: self.assistantName,
+                assistantAvatarText: self.assistantAvatarText,
+                assistantAvatarTint: self.assistantAvatarTint,
+                showsAssistantAvatar: self.showsAssistantAvatars,
+                isClean: self.composerChrome == .clean)
+                .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    private var visibleMessages: [OpenClawChatMessage] {
+        let base: [OpenClawChatMessage]
+        if self.style == .onboarding {
+            guard let first = viewModel.messages.first else { return [] }
+            base = first.role.lowercased() == "user" ? Array(self.viewModel.messages.dropFirst()) : self.viewModel
+                .messages
+        } else {
+            base = self.viewModel.messages
+        }
+        return self.mergeToolResults(in: base).filter(self.shouldDisplayMessage(_:))
+    }
+
+    private var latestVisibleUserMessageID: UUID? {
+        self.visibleUserMessageIDs.last
+    }
+
+    private var visibleUserMessageIDs: [UUID] {
+        self.visibleMessages.compactMap { message in
+            message.role.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() == "user"
+                ? message.id
+                : nil
+        }
+    }
+
+    private var isFollowingUserTurn: Bool {
+        if case .user = self.followTarget {
+            return true
+        }
+        return false
+    }
+
+    private var showsJumpToLatest: Bool {
+        self.hasNewerContentBelow && self.hasVisibleMessageListContent && !self.viewModel.isLoading
+    }
+
+    private var jumpToLatestButton: some View {
+        Button {
+            self.followTarget = .latest
+            self.hasNewerContentBelow = false
+            self.moveScrollPosition(to: self.scrollerBottomID)
+        } label: {
+            Label("Jump to latest", systemImage: "arrow.down")
+                .font(OpenClawChatTypography.body(size: 16, weight: .semibold, relativeTo: .callout))
+                .padding(.horizontal, 13)
+                .padding(.vertical, 8)
+        }
+        .buttonStyle(.plain)
+        .foregroundStyle(OpenClawChatTheme.assistantText)
+        .background(
+            Capsule()
+                .fill(OpenClawChatTheme.subtleCard)
+                .shadow(color: .black.opacity(0.16), radius: 10, y: 4))
+        .accessibilityLabel("Jump to latest reply")
+    }
+
+    @ViewBuilder
+    private var messageListOverlay: some View {
+        if self.viewModel.isLoading {
+            EmptyView()
+        } else if self.composerChrome == .clean, self.visibleEmptyAssistantIntro != nil {
+            EmptyView()
+        } else if self.showsCleanLoadingPlaceholder {
+            EmptyView()
+        } else if let error = activeErrorText {
+            if self.hasVisibleMessageListContent {
+                EmptyView()
+            } else {
+                let presentation = self.errorPresentation(for: error)
+                ChatNoticeCard(
+                    systemImage: presentation.systemImage,
+                    title: presentation.title,
+                    message: presentation.message,
+                    actionTitle: "Refresh",
+                    action: { self.viewModel.refresh() })
+                    .padding(.horizontal, 24)
+                    .frame(maxWidth: .infinity, maxHeight: .infinity)
+            }
+        } else if self.showsEmptyState {
+            ChatNoticeCard(
+                systemImage: "bubble.left.and.bubble.right.fill",
+                title: self.emptyStateTitle,
+                message: self.emptyStateMessage,
+                actionTitle: nil,
+                action: nil)
+                .padding(.horizontal, 24)
+                .frame(maxWidth: .infinity, maxHeight: .infinity)
+        }
+    }
+
+    private var activeErrorText: String? {
+        guard let text = viewModel.errorText?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+            !text.isEmpty
+        else {
+            return nil
+        }
+        return text
+    }
+
+    private var hasVisibleMessageListContent: Bool {
+        if !self.visibleMessages.isEmpty {
+            return true
+        }
+        return self.hasVisibleTransientContent
+    }
+
+    private var hasVisibleTransientContent: Bool {
+        self.viewModel.pendingRunCount > 0 ||
+            !self.viewModel.pendingToolCalls.isEmpty ||
+            (self.viewModel.streamingAssistantText.map {
+                AssistantTextParser.hasVisibleContent(in: $0, includeThinking: self.showsAssistantTrace)
+            } ?? false)
+    }
+
+    @ViewBuilder
+    private var messageListNoticeBanner: some View {
+        if let error = activeErrorText,
+           hasVisibleMessageListContent,
+           !self.viewModel.isLoading,
+           visibleEmptyAssistantIntro == nil,
+           !self.showsCleanLoadingPlaceholder
+        {
+            let presentation = self.errorPresentation(for: error)
+            ChatNoticeBanner(
+                systemImage: presentation.systemImage,
+                title: presentation.title,
+                message: error,
+                tint: presentation.tint,
+                dismiss: { self.viewModel.errorText = nil },
+                refresh: { self.viewModel.refresh() })
+                .padding(.horizontal, 10)
+                .padding(.top, 8)
+                .padding(.bottom, 8)
+        }
+    }
+
+    private var showsCleanLoadingPlaceholder: Bool {
+        self.composerChrome == .clean &&
+            self.viewModel.isLoading &&
+            self.visibleEmptyAssistantIntro == nil &&
+            self.activeErrorText == nil &&
+            !self.hasVisibleMessageListContent
+    }
+
+    private var visibleEmptyAssistantIntro: String? {
+        guard self.composerChrome == .clean,
+              self.showsEmptyState,
+              !self.viewModel.isLoading,
+              self.activeErrorText == nil,
+              self.isComposerEnabled
+        else {
+            return nil
+        }
+        guard let text = emptyAssistantIntro?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !text.isEmpty
+        else {
+            return nil
+        }
+        return text
+    }
+
+    private var showsEmptyState: Bool {
+        self.viewModel.messages.isEmpty &&
+            !(self.viewModel.streamingAssistantText.map {
+                AssistantTextParser.hasVisibleContent(in: $0, includeThinking: self.showsAssistantTrace)
+            } ?? false) &&
+            self.viewModel.pendingRunCount == 0 &&
+            self.viewModel.pendingToolCalls.isEmpty
+    }
+
+    private var emptyStateTitle: String {
+        #if os(macOS)
+        "Web Chat"
+        #else
+        "Chat"
+        #endif
+    }
+
+    private var emptyStateMessage: String {
+        #if os(macOS)
+        "Type a message below to start.\nReturn sends • Shift-Return adds a line break."
+        #else
+        "Type a message below to start."
+        #endif
+    }
+
+    private func errorPresentation(
+        for error: String) -> (title: String, message: String, systemImage: String, tint: Color)
+    {
+        let lower = error.lowercased()
+        if lower.contains("not connected") || lower.contains("socket") {
+            return ("Disconnected", "Reconnect to your gateway to continue.", "wifi.slash", .orange)
+        }
+        if lower.contains("timed out") {
+            return ("Timed out", "The gateway took too long to respond.", "clock.badge.exclamationmark", .orange)
+        }
+        // Unknown errors: keep the raw text as the description so it stays actionable.
+        return ("Something went wrong", error, "exclamationmark.triangle.fill", .orange)
+    }
+
+    private func restoreInitialScrollPosition() {
+        if let latestUserMessageID = latestVisibleUserMessageID {
+            self.followTarget = nil
+            self.hasNewerContentBelow = chatReaderHasNewerContent(
+                after: latestUserMessageID,
+                visibleIDs: self.visibleMessages.map(\.id),
+                hasTransientContent: self.hasVisibleTransientContent)
+            self.moveScrollPosition(to: latestUserMessageID, anchor: Layout.newTurnAnchor)
+        } else {
+            self.followTarget = .latest
+            self.hasNewerContentBelow = false
+            self.moveScrollPosition(to: self.scrollerBottomID)
+        }
+    }
+
+    private func handleTimelineChange() {
+        guard self.hasPerformedInitialScroll else { return }
+        if self.viewModel.messages.isEmpty,
+           self.viewModel.pendingRunCount == 0,
+           self.viewModel.pendingToolCalls.isEmpty,
+           self.viewModel.streamingAssistantText == nil
+        {
+            self.lastUserMessageID = nil
+            self.followTarget = .latest
+            self.hasNewerContentBelow = false
+            self.moveScrollPosition(to: self.scrollerBottomID)
+            return
+        }
+        let visibleMessages = self.visibleMessages
+        let visibleUserMessageIDs = visibleMessages.compactMap { message in
+            message.role.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() == "user"
+                ? message.id
+                : nil
+        }
+        switch chatReaderUserTransition(
+            previousID: self.lastUserMessageID,
+            visibleIDs: visibleUserMessageIDs)
+        {
+        case let .removed(latestRemainingID):
+            self.lastUserMessageID = latestRemainingID
+            if case let .user(messageID) = followTarget,
+               !visibleUserMessageIDs.contains(messageID)
+            {
+                self.followTarget = nil
+                self.hasNewerContentBelow = false
+            }
+            return
+        case let .added(latestUserMessageID):
+            self.lastUserMessageID = latestUserMessageID
+            self.followTarget = .user(latestUserMessageID)
+            self.hasNewerContentBelow = false
+            self.moveScrollPosition(to: latestUserMessageID, anchor: Layout.newTurnAnchor)
+            return
+        case .unchanged:
+            break
+        }
+
+        switch self.followTarget {
+        case .latest:
+            self.hasNewerContentBelow = false
+            self.moveScrollPosition(to: self.scrollerBottomID)
+        case let .user(messageID):
+            // Reader policy stays on this turn after the one-shot scroll binding is released. Reissuing
+            // that target for every streaming delta can loop SwiftUI layout and starve interaction.
+            self.hasNewerContentBelow = chatReaderHasNewerContent(
+                after: messageID,
+                visibleIDs: visibleMessages.map(\.id),
+                hasTransientContent: self.hasVisibleTransientContent)
+        case nil:
+            self.hasNewerContentBelow = true
+        }
+    }
+
+    private func moveScrollPosition(
+        to id: UUID,
+        anchor: UnitPoint = .bottom)
+    {
+        var transaction = Transaction(animation: nil)
+        transaction.scrollTargetAnchor = anchor
+        withTransaction(transaction) {
+            self.scrollPosition = id
+        }
+        DispatchQueue.main.async {
+            guard self.scrollPosition == id else { return }
+            // Reader policy lives in followTarget. The binding is only a one-shot positioning request;
+            // keeping an overflowing transcript bound to any row can loop SwiftUI scroll layout.
+            self.scrollPosition = nil
+        }
+    }
+
+    private func mergeToolResults(in messages: [OpenClawChatMessage]) -> [OpenClawChatMessage] {
+        var result: [OpenClawChatMessage] = []
+        result.reserveCapacity(messages.count)
+
+        for message in messages {
+            guard self.isToolResultMessage(message) else {
+                result.append(message)
+                continue
+            }
+
+            guard let toolCallId = message.toolCallId,
+                  let last = result.last,
+                  toolCallIds(in: last).contains(toolCallId)
+            else {
+                result.append(message)
+                continue
+            }
+
+            let toolText = self.toolResultText(from: message)
+            if toolText.isEmpty {
+                continue
+            }
+
+            var content = last.content
+            content.append(
+                OpenClawChatMessageContent(
+                    type: "tool_result",
+                    text: toolText,
+                    thinking: nil,
+                    thinkingSignature: nil,
+                    mimeType: nil,
+                    fileName: nil,
+                    content: nil,
+                    id: toolCallId,
+                    name: message.toolName,
+                    arguments: nil))
+
+            let merged = OpenClawChatMessage(
+                id: last.id,
+                role: last.role,
+                content: content,
+                timestamp: last.timestamp,
+                idempotencyKey: last.idempotencyKey,
+                toolCallId: last.toolCallId,
+                toolName: last.toolName,
+                usage: last.usage,
+                stopReason: last.stopReason,
+                errorMessage: last.errorMessage)
+            result[result.count - 1] = merged
+        }
+
+        return result
+    }
+
+    private func isToolResultMessage(_ message: OpenClawChatMessage) -> Bool {
+        let role = message.role.lowercased()
+        return role == "toolresult" || role == "tool_result"
+    }
+
+    private func shouldDisplayMessage(_ message: OpenClawChatMessage) -> Bool {
+        if self.hasInlineAttachments(in: message) {
+            return true
+        }
+
+        let primaryText = self.primaryText(in: message)
+        if !primaryText.isEmpty {
+            if message.role.lowercased() == "user" {
+                return true
+            }
+            if AssistantTextParser.hasVisibleContent(in: primaryText, includeThinking: self.showsAssistantTrace) {
+                return true
+            }
+        }
+
+        guard self.showsAssistantTrace else {
+            return false
+        }
+
+        if self.isToolResultMessage(message) {
+            return !primaryText.isEmpty
+        }
+
+        return !self.toolCalls(in: message).isEmpty || !self.inlineToolResults(in: message).isEmpty
+    }
+
+    private func primaryText(in message: OpenClawChatMessage) -> String {
+        let parts = message.content.compactMap { content -> String? in
+            let kind = (content.type ?? "text").lowercased()
+            guard kind == "text" || kind.isEmpty else { return nil }
+            return content.text
+        }
+        return OpenClawChatMessage.displayText(
+            contentText: parts.joined(separator: "\n"),
+            role: message.role,
+            stopReason: message.stopReason,
+            errorMessage: message.errorMessage)
+    }
+
+    private func hasInlineAttachments(in message: OpenClawChatMessage) -> Bool {
+        message.content.contains { content in
+            switch content.type ?? "text" {
+            case "file", "attachment":
+                true
+            default:
+                false
+            }
+        }
+    }
+
+    private func toolCalls(in message: OpenClawChatMessage) -> [OpenClawChatMessageContent] {
+        message.content.filter { content in
+            let kind = (content.type ?? "").lowercased()
+            if ["toolcall", "tool_call", "tooluse", "tool_use"].contains(kind) {
+                return true
+            }
+            return content.name != nil && content.arguments != nil
+        }
+    }
+
+    private func inlineToolResults(in message: OpenClawChatMessage) -> [OpenClawChatMessageContent] {
+        message.content.filter { content in
+            let kind = (content.type ?? "").lowercased()
+            return kind == "toolresult" || kind == "tool_result"
+        }
+    }
+
+    private func toolCallIds(in message: OpenClawChatMessage) -> Set<String> {
+        var ids = Set<String>()
+        for content in self.toolCalls(in: message) {
+            if let id = content.id {
+                ids.insert(id)
+            }
+        }
+        if let toolCallId = message.toolCallId {
+            ids.insert(toolCallId)
+        }
+        return ids
+    }
+
+    private func toolResultText(from message: OpenClawChatMessage) -> String {
+        self.primaryText(in: message)
+    }
+
+    private func dismissKeyboardIfNeeded() {
+        #if canImport(UIKit)
+        UIApplication.shared.sendAction(
+            #selector(UIResponder.resignFirstResponder),
+            to: nil,
+            from: nil,
+            for: nil)
+        #endif
+    }
+}
+
+private struct ChatAssistantIntroCard: View {
+    let text: String
+    let prompts: [OpenClawChatView.StarterPrompt]
+    let onPrompt: (OpenClawChatView.StarterPrompt) -> Void
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            // Rendered as a grey assistant bubble so the greeting reads like the
+            // agent's first message, matching the in-conversation bubble style.
+            Text(self.text)
+                .font(OpenClawChatTypography.body)
+                .foregroundStyle(OpenClawChatTheme.assistantText)
+                .multilineTextAlignment(.leading)
+                .padding(.vertical, 10)
+                .padding(.horizontal, 14)
+                .background(
+                    RoundedRectangle(cornerRadius: 18, style: .continuous)
+                        .fill(OpenClawChatTheme.assistantBubble))
+
+            ForEach(self.prompts) { prompt in
+                Button {
+                    self.onPrompt(prompt)
+                } label: {
+                    HStack(spacing: 8) {
+                        Text(prompt.title)
+                            .font(OpenClawChatTypography.body(size: 15, weight: .semibold, relativeTo: .callout))
+                            .multilineTextAlignment(.leading)
+                        Spacer(minLength: 8)
+                        Image(systemName: "arrow.up.right")
+                            .font(OpenClawChatTypography.captionSemiBold)
+                            .foregroundStyle(.secondary)
+                    }
+                    .padding(.horizontal, 12)
+                    .padding(.vertical, 10)
+                    .background(
+                        RoundedRectangle(cornerRadius: 14, style: .continuous)
+                            .fill(OpenClawChatTheme.subtleCard))
+                }
+                .buttonStyle(.plain)
+                .accessibilityIdentifier("chat-starter-\(prompt.id)")
+            }
+        }
+        .frame(maxWidth: 340, alignment: .leading)
+        .padding(.top, 8)
+        .frame(maxWidth: .infinity, alignment: .leading)
+    }
+}
+
+private struct ChatLoadingBubble: View {
+    var body: some View {
+        HStack(spacing: 8) {
+            ProgressView()
+                .controlSize(.small)
+            Text("Loading chat")
+                .font(OpenClawChatTypography.captionSemiBold)
+                .foregroundStyle(.secondary)
+        }
+        .padding(.vertical, 9)
+        .padding(.horizontal, 12)
+        .background(
+            Capsule()
+                .fill(OpenClawChatTheme.subtleCard))
+        .padding(.leading, 10)
+    }
+}
+
+private struct ChatNoticeCard: View {
+    let systemImage: String
+    let title: String
+    let message: String
+    let actionTitle: String?
+    let action: (() -> Void)?
+
+    var body: some View {
+        // Native empty/error state: SwiftUI's standard ContentUnavailableView, not a custom card.
+        ContentUnavailableView {
+            Label(self.title, systemImage: self.systemImage)
+                .font(OpenClawChatTypography.headline)
+        } description: {
+            Text(self.message)
+                .font(OpenClawChatTypography.body)
+        } actions: {
+            if let actionTitle, let action {
+                Button(action: action) {
+                    Text(actionTitle)
+                        .font(OpenClawChatTypography.body(size: 15, weight: .semibold, relativeTo: .subheadline))
+                }
+                .buttonStyle(.borderedProminent)
+                .controlSize(.large)
+            }
+        }
+    }
+}
+
+private struct ChatNoticeBanner: View {
+    let systemImage: String
+    let title: String
+    let message: String
+    let tint: Color
+    let dismiss: () -> Void
+    let refresh: () -> Void
+
+    var body: some View {
+        HStack(alignment: .top, spacing: 10) {
+            Image(systemName: self.systemImage)
+                .font(OpenClawChatTypography.display(size: 15, weight: .semibold, relativeTo: .subheadline))
+                .foregroundStyle(self.tint)
+                .padding(.top, 1)
+
+            VStack(alignment: .leading, spacing: 3) {
+                Text(self.title)
+                    .font(OpenClawChatTypography.captionSemiBold)
+
+                Text(self.message)
+                    .font(OpenClawChatTypography.caption)
+                    .foregroundStyle(.secondary)
+                    .lineLimit(2)
+            }
+
+            Spacer(minLength: 0)
+
+            Button(action: self.refresh) {
+                Image(systemName: "arrow.clockwise")
+            }
+            .buttonStyle(.bordered)
+            .controlSize(.small)
+            .help("Refresh")
+
+            Button(action: self.dismiss) {
+                Image(systemName: "xmark")
+            }
+            .buttonStyle(.plain)
+            .foregroundStyle(.secondary)
+            .help("Dismiss")
+        }
+        .padding(.horizontal, 12)
+        .padding(.vertical, 10)
+        .background(
+            RoundedRectangle(cornerRadius: 14, style: .continuous)
+                .fill(OpenClawChatTheme.subtleCard)
+                .overlay(
+                    RoundedRectangle(cornerRadius: 14, style: .continuous)
+                        .strokeBorder(Color.white.opacity(0.12), lineWidth: 1)))
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+Attachments.swift

@@ -0,0 +1,84 @@
+import Foundation
+import OpenClawKit
+import UniformTypeIdentifiers
+
+#if canImport(AppKit)
+import AppKit
+#elseif canImport(UIKit)
+import UIKit
+#endif
+
+extension OpenClawChatViewModel {
+    func loadAttachments(urls: [URL]) async {
+        for url in urls {
+            do {
+                let data = try await Task.detached { try Data(contentsOf: url) }.value
+                await self.addImageAttachment(
+                    url: url,
+                    data: data,
+                    fileName: url.lastPathComponent,
+                    mimeType: Self.mimeType(for: url) ?? "application/octet-stream")
+            } catch {
+                await MainActor.run { self.errorText = error.localizedDescription }
+            }
+        }
+    }
+
+    static func mimeType(for url: URL) -> String? {
+        let ext = url.pathExtension
+        guard !ext.isEmpty else { return nil }
+        return (UTType(filenameExtension: ext) ?? .data).preferredMIMEType
+    }
+
+    func addImageAttachment(url: URL?, data: Data, fileName: String, mimeType: String) async {
+        let uti: UTType = {
+            if let url {
+                return UTType(filenameExtension: url.pathExtension) ?? .data
+            }
+            return UTType(mimeType: mimeType) ?? .data
+        }()
+        guard uti.conforms(to: .image) else {
+            self.errorText = "Only image attachments are supported right now"
+            return
+        }
+
+        let processed: Data
+        do {
+            processed = try await Task.detached(priority: .userInitiated) {
+                try ChatImageProcessor.processForUpload(data: data)
+            }.value
+        } catch {
+            self.errorText = "Could not process \(fileName): \(error.localizedDescription)"
+            return
+        }
+
+        if processed.count > Self.maxAttachmentBytes {
+            self.errorText = "Attachment \(fileName) exceeds 5 MB limit after resizing"
+            return
+        }
+
+        let outputFileName: String = {
+            let baseName = (fileName as NSString).deletingPathExtension
+            return baseName.isEmpty ? "image.jpg" : "\(baseName).jpg"
+        }()
+
+        let preview = Self.previewImage(data: processed)
+        self.attachments.append(
+            OpenClawPendingAttachment(
+                url: url,
+                data: processed,
+                fileName: outputFileName,
+                mimeType: "image/jpeg",
+                preview: preview))
+    }
+
+    static func previewImage(data: Data) -> OpenClawPlatformImage? {
+        #if canImport(AppKit)
+        NSImage(data: data)
+        #elseif canImport(UIKit)
+        UIImage(data: data)
+        #else
+        nil
+        #endif
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ChatViewModel+SessionKeys.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+extension OpenClawChatViewModel {
+    func matchesCurrentSessionKey(incoming: String, current: String) -> Bool {
+        Self.matchesCurrentSessionKey(
+            incoming: incoming,
+            current: current,
+            mainSessionKey: self.resolvedMainSessionKey)
+    }
+
+    func matchesCurrentSessionKey(incoming: String, agentId: String?, current: String) -> Bool {
+        Self.matchesCurrentSessionKey(
+            incoming: incoming,
+            agentId: agentId,
+            current: current,
+            mainSessionKey: self.resolvedMainSessionKey)
+    }
+
+    static func matchesCurrentSessionKey(
+        incoming: String,
+        agentId: String? = nil,
+        current: String,
+        mainSessionKey: String)
+        -> Bool
+    {
+        let incomingNormalized = incoming.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        let currentNormalized = current.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if incomingNormalized == currentNormalized {
+            return true
+        }
+
+        let mainNormalized = mainSessionKey.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if Self.matchesMainAlias(
+            incoming: incomingNormalized,
+            current: currentNormalized,
+            mainSessionKey: mainNormalized)
+        {
+            return true
+        }
+        if Self.matchesSelectedAgentGlobal(
+            incoming: incomingNormalized,
+            agentId: agentId,
+            current: currentNormalized)
+        {
+            return true
+        }
+        return false
+    }
+
+    private static func matchesMainAlias(incoming: String, current: String, mainSessionKey: String) -> Bool {
+        if current == "main", incoming == mainSessionKey, mainSessionKey != "main" {
+            return true
+        }
+        if incoming == "main", current == mainSessionKey, mainSessionKey != "main" {
+            return true
+        }
+        return (current == "main" && incoming == "agent:main:main") ||
+            (incoming == "main" && current == "agent:main:main")
+    }
+
+    private static func matchesSelectedAgentGlobal(incoming: String, agentId: String?, current: String) -> Bool {
+        guard incoming == "global",
+              let selectedAgentId = agentId?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased(),
+              !selectedAgentId.isEmpty
+        else {
+            return false
+        }
+        return current == "agent:\(selectedAgentId):global"
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/OpenClawMascotView.swift

@@ -0,0 +1,258 @@
+import SwiftUI
+
+/// Animated OpenClaw mascot. Redraws the canonical 120x120 vector from
+/// `ui/public/favicon.svg` so individual parts (claws, antennae, eyes) can
+/// animate like the openclaw.ai hero mark; the bundled PNG asset cannot.
+/// Styling (palette, glow colors, float depth) follows the openclaw.ai hero
+/// (`src/pages/index.astro` + `Layout.astro` theme variables).
+public struct OpenClawMascotView: View {
+    @Environment(\.accessibilityReduceMotion) private var reduceMotion
+    @Environment(\.colorScheme) private var colorScheme
+
+    public init() {}
+
+    public var body: some View {
+        let palette = OpenClawMascotPalette.forScheme(self.colorScheme)
+        if self.reduceMotion {
+            OpenClawMascotCanvas(pose: .still, palette: palette)
+        } else {
+            TimelineView(.animation(minimumInterval: 1.0 / 30.0)) { timeline in
+                let pose = OpenClawMascotPose.at(time: timeline.date.timeIntervalSinceReferenceDate)
+                // Float translates the whole canvas like the site floats the hero
+                // container; drawing the offset inside the canvas would clip the
+                // antennae (art starts at y~5 of 120) at the -9.6 float peak.
+                GeometryReader { proxy in
+                    OpenClawMascotCanvas(pose: pose, palette: palette)
+                        .offset(y: pose.floatOffset * min(proxy.size.width, proxy.size.height) / 120)
+                }
+            }
+        }
+    }
+
+    /// openclaw.ai hero drop-shadow color (`--logo-glow` / `--logo-glow-hover`).
+    /// Pair with a shadow radius of ~10% of the mascot size (15% while hovering)
+    /// to match the site's `drop-shadow(0 0 20px)` on a 100px mark.
+    public static func heroGlowColor(for colorScheme: ColorScheme, hovering: Bool = false) -> Color {
+        switch (colorScheme, hovering) {
+        case (.light, false): Color(red: 239 / 255, green: 75 / 255, blue: 88 / 255).opacity(0.2)
+        case (.light, true): Color(red: 0, green: 143 / 255, blue: 135 / 255).opacity(0.35)
+        case (_, false): Color(red: 1, green: 77 / 255, blue: 77 / 255).opacity(0.4)
+        case (_, true): Color(red: 0, green: 229 / 255, blue: 204 / 255).opacity(0.6)
+        }
+    }
+}
+
+/// Body/antenna colors from the openclaw.ai theme variables: `:root` (dark)
+/// and `html[data-theme='light']` in `Layout.astro`. Eye colors are fixed in
+/// the site markup and shared by both themes.
+struct OpenClawMascotPalette: Equatable {
+    let gradientTop: Color
+    let gradientBottom: Color
+    let antenna: Color
+
+    static let dark = OpenClawMascotPalette(
+        gradientTop: Color(red: 1, green: 77 / 255, blue: 77 / 255),
+        gradientBottom: Color(red: 153 / 255, green: 27 / 255, blue: 27 / 255),
+        antenna: Color(red: 1, green: 77 / 255, blue: 77 / 255))
+
+    static let light = OpenClawMascotPalette(
+        gradientTop: Color(red: 255 / 255, green: 112 / 255, blue: 121 / 255),
+        gradientBottom: Color(red: 234 / 255, green: 76 / 255, blue: 89 / 255),
+        antenna: Color(red: 239 / 255, green: 75 / 255, blue: 88 / 255))
+
+    static func forScheme(_ colorScheme: ColorScheme) -> OpenClawMascotPalette {
+        colorScheme == .light ? .light : .dark
+    }
+}
+
+/// Part transforms for one animation frame. Mirrors the openclaw.ai CSS
+/// keyframes: float 4s, antenna wiggle 2s, eye blink 3s, claw snap 4s with
+/// the right claw trailing by 0.2s.
+struct OpenClawMascotPose: Equatable {
+    var floatOffset: CGFloat = 0
+    var antennaDegrees: CGFloat = 0
+    var leftClawDegrees: CGFloat = 0
+    var rightClawDegrees: CGFloat = 0
+    var eyeGlowOpacity: CGFloat = 1
+
+    static let still = OpenClawMascotPose()
+
+    static func at(time: TimeInterval) -> OpenClawMascotPose {
+        // Float depth matches the hero: -8px on a 100px mark = 8% of the 120 box.
+        OpenClawMascotPose(
+            floatOffset: -4.8 * (1 - cos(2 * .pi * self.cyclePhase(time, period: 4))),
+            antennaDegrees: -3 * sin(2 * .pi * self.cyclePhase(time, period: 2)),
+            leftClawDegrees: self.clawSnapDegrees(phase: self.cyclePhase(time, period: 4)),
+            rightClawDegrees: self.clawSnapDegrees(phase: self.cyclePhase(time - 0.2, period: 4)),
+            eyeGlowOpacity: self.blinkOpacity(phase: self.cyclePhase(time, period: 3)))
+    }
+
+    private static func cyclePhase(_ time: TimeInterval, period: TimeInterval) -> CGFloat {
+        let normalized = (time / period).truncatingRemainder(dividingBy: 1)
+        return CGFloat(normalized < 0 ? normalized + 1 : normalized)
+    }
+
+    private static func clawSnapDegrees(phase: CGFloat) -> CGFloat {
+        // 0deg until 85%, snap to -8deg at 90%, back to 0deg at 95%, hold.
+        if phase < 0.85 || phase >= 0.95 {
+            return 0
+        }
+        if phase < 0.9 {
+            return -8 * self.easeInOut((phase - 0.85) / 0.05)
+        }
+        return -8 * (1 - self.easeInOut((phase - 0.9) / 0.05))
+    }
+
+    private static func blinkOpacity(phase: CGFloat) -> CGFloat {
+        // Full glow until 90%, dip to 0.3 at 95%, recover by 100%.
+        if phase < 0.9 {
+            return 1
+        }
+        let dip = phase < 0.95 ? self.easeInOut((phase - 0.9) / 0.05) : 1 - self.easeInOut((phase - 0.95) / 0.05)
+        return 1 - 0.7 * dip
+    }
+
+    private static func easeInOut(_ t: CGFloat) -> CGFloat {
+        let clamped = min(max(t, 0), 1)
+        return clamped * clamped * (3 - 2 * clamped)
+    }
+}
+
+private struct OpenClawMascotCanvas: View {
+    let pose: OpenClawMascotPose
+    let palette: OpenClawMascotPalette
+
+    var body: some View {
+        Canvas { context, size in
+            Self.draw(context: &context, size: size, pose: self.pose, palette: self.palette)
+        }
+        .accessibilityHidden(true)
+    }
+
+    // Geometry below is the favicon.svg path data in its native 120x120 space.
+    private static let eyeColor = Color(red: 5 / 255, green: 8 / 255, blue: 16 / 255)
+    private static let eyeGlowColor = Color(red: 0, green: 229 / 255, blue: 204 / 255)
+    // Rotation pivots: claws hinge on their body-facing edge, antennae on their own center.
+    private static let leftClawPivot = CGPoint(x: 26, y: 53)
+    private static let rightClawPivot = CGPoint(x: 94, y: 53)
+    private static let leftAntennaPivot = CGPoint(x: 37.5, y: 11)
+    private static let rightAntennaPivot = CGPoint(x: 82.5, y: 11)
+
+    private static let bodyPath: Path = {
+        var path = Path()
+        path.move(to: CGPoint(x: 60, y: 10))
+        path.addCurve(to: CGPoint(x: 15, y: 55), control1: CGPoint(x: 30, y: 10), control2: CGPoint(x: 15, y: 35))
+        path.addCurve(to: CGPoint(x: 45, y: 100), control1: CGPoint(x: 15, y: 75), control2: CGPoint(x: 30, y: 95))
+        path.addLine(to: CGPoint(x: 45, y: 110))
+        path.addLine(to: CGPoint(x: 55, y: 110))
+        path.addLine(to: CGPoint(x: 55, y: 100))
+        path.addCurve(to: CGPoint(x: 65, y: 100), control1: CGPoint(x: 55, y: 100), control2: CGPoint(x: 60, y: 102))
+        path.addLine(to: CGPoint(x: 65, y: 110))
+        path.addLine(to: CGPoint(x: 75, y: 110))
+        path.addLine(to: CGPoint(x: 75, y: 100))
+        path.addCurve(to: CGPoint(x: 105, y: 55), control1: CGPoint(x: 90, y: 95), control2: CGPoint(x: 105, y: 75))
+        path.addCurve(to: CGPoint(x: 60, y: 10), control1: CGPoint(x: 105, y: 35), control2: CGPoint(x: 90, y: 10))
+        path.closeSubpath()
+        return path
+    }()
+
+    private static let leftClawPath: Path = {
+        var path = Path()
+        path.move(to: CGPoint(x: 20, y: 45))
+        path.addCurve(to: CGPoint(x: 5, y: 60), control1: CGPoint(x: 5, y: 40), control2: CGPoint(x: 0, y: 50))
+        path.addCurve(to: CGPoint(x: 25, y: 55), control1: CGPoint(x: 10, y: 70), control2: CGPoint(x: 20, y: 65))
+        path.addCurve(to: CGPoint(x: 20, y: 45), control1: CGPoint(x: 28, y: 48), control2: CGPoint(x: 25, y: 45))
+        path.closeSubpath()
+        return path
+    }()
+
+    private static let rightClawPath: Path = {
+        var path = Path()
+        path.move(to: CGPoint(x: 100, y: 45))
+        path.addCurve(to: CGPoint(x: 115, y: 60), control1: CGPoint(x: 115, y: 40), control2: CGPoint(x: 120, y: 50))
+        path.addCurve(to: CGPoint(x: 95, y: 55), control1: CGPoint(x: 110, y: 70), control2: CGPoint(x: 100, y: 65))
+        path.addCurve(to: CGPoint(x: 100, y: 45), control1: CGPoint(x: 92, y: 48), control2: CGPoint(x: 95, y: 45))
+        path.closeSubpath()
+        return path
+    }()
+
+    private static let leftAntennaPath: Path = {
+        var path = Path()
+        path.move(to: CGPoint(x: 45, y: 15))
+        path.addQuadCurve(to: CGPoint(x: 30, y: 8), control: CGPoint(x: 35, y: 5))
+        return path
+    }()
+
+    private static let rightAntennaPath: Path = {
+        var path = Path()
+        path.move(to: CGPoint(x: 75, y: 15))
+        path.addQuadCurve(to: CGPoint(x: 90, y: 8), control: CGPoint(x: 85, y: 5))
+        return path
+    }()
+
+    private static func draw(
+        context: inout GraphicsContext,
+        size: CGSize,
+        pose: OpenClawMascotPose,
+        palette: OpenClawMascotPalette)
+    {
+        let scale = min(size.width, size.height) / 120
+        context.scaleBy(x: scale, y: scale)
+
+        // Site antennae: stroke-width 2, `--coral-bright`.
+        let antennaStroke = StrokeStyle(lineWidth: 2, lineCap: .round)
+
+        // Same paint order as favicon.svg: body, claws, antennae, eyes.
+        context.fill(self.bodyPath, with: self.gradient(for: self.bodyPath, palette: palette))
+        self.drawRotated(context: context, degrees: pose.leftClawDegrees, pivot: self.leftClawPivot) {
+            $0.fill(self.leftClawPath, with: self.gradient(for: self.leftClawPath, palette: palette))
+        }
+        self.drawRotated(context: context, degrees: pose.rightClawDegrees, pivot: self.rightClawPivot) {
+            $0.fill(self.rightClawPath, with: self.gradient(for: self.rightClawPath, palette: palette))
+        }
+        self.drawRotated(context: context, degrees: pose.antennaDegrees, pivot: self.leftAntennaPivot) {
+            $0.stroke(self.leftAntennaPath, with: .color(palette.antenna), style: antennaStroke)
+        }
+        self.drawRotated(context: context, degrees: pose.antennaDegrees, pivot: self.rightAntennaPivot) {
+            $0.stroke(self.rightAntennaPath, with: .color(palette.antenna), style: antennaStroke)
+        }
+
+        context.fill(Path(ellipseIn: CGRect(x: 39, y: 29, width: 12, height: 12)), with: .color(self.eyeColor))
+        context.fill(Path(ellipseIn: CGRect(x: 69, y: 29, width: 12, height: 12)), with: .color(self.eyeColor))
+        var glowContext = context
+        glowContext.opacity = pose.eyeGlowOpacity
+        glowContext.fill(
+            Path(ellipseIn: CGRect(x: 44, y: 32, width: 4, height: 4)),
+            with: .color(self.eyeGlowColor))
+        glowContext.fill(
+            Path(ellipseIn: CGRect(x: 74, y: 32, width: 4, height: 4)),
+            with: .color(self.eyeGlowColor))
+    }
+
+    /// SVG gradients default to objectBoundingBox units, so the body and each
+    /// claw span the full top-left -> bottom-right ramp across their own bounds;
+    /// one canvas-wide gradient would leave the claws nearly flat-colored.
+    private static func gradient(
+        for path: Path,
+        palette: OpenClawMascotPalette) -> GraphicsContext.Shading
+    {
+        let box = path.boundingRect
+        return .linearGradient(
+            Gradient(colors: [palette.gradientTop, palette.gradientBottom]),
+            startPoint: box.origin,
+            endPoint: CGPoint(x: box.maxX, y: box.maxY))
+    }
+
+    private static func drawRotated(
+        context: GraphicsContext,
+        degrees: CGFloat,
+        pivot: CGPoint,
+        draw: (inout GraphicsContext) -> Void)
+    {
+        var rotated = context
+        rotated.translateBy(x: pivot.x, y: pivot.y)
+        rotated.rotate(by: .degrees(degrees))
+        rotated.translateBy(x: -pivot.x, y: -pivot.y)
+        draw(&rotated)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawChatUI/ToolResultTextFormatter.swift

@@ -0,0 +1,157 @@
+import Foundation
+
+enum ToolResultTextFormatter {
+    static func format(text: String, toolName: String?) -> String {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return "" }
+
+        guard self.looksLikeJSON(trimmed),
+              let data = trimmed.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data)
+        else {
+            return trimmed
+        }
+
+        let normalizedTool = toolName?.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return self.renderJSON(json, toolName: normalizedTool)
+    }
+
+    private static func looksLikeJSON(_ value: String) -> Bool {
+        guard let first = value.first else { return false }
+        return first == "{" || first == "["
+    }
+
+    private static func renderJSON(_ json: Any, toolName: String?) -> String {
+        if let dict = json as? [String: Any] {
+            return self.renderDictionary(dict, toolName: toolName)
+        }
+        if let array = json as? [Any] {
+            if array.isEmpty { return "No items." }
+            return "\(array.count) item\(array.count == 1 ? "" : "s")."
+        }
+        return ""
+    }
+
+    private static func renderDictionary(_ dict: [String: Any], toolName: String?) -> String {
+        let status = (dict["status"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let errorText = self.firstString(in: dict, keys: ["error", "reason"])
+        let messageText = self.firstString(in: dict, keys: ["message", "result", "detail"])
+
+        if status?.lowercased() == "error" || errorText != nil {
+            if let errorText {
+                return "Error: \(self.sanitizeError(errorText))"
+            }
+            if let messageText {
+                return "Error: \(self.sanitizeError(messageText))"
+            }
+            return "Error"
+        }
+
+        if toolName == "nodes", let summary = self.renderNodesSummary(dict) {
+            return summary
+        }
+
+        if let message = messageText {
+            return message
+        }
+
+        if let status, !status.isEmpty {
+            return "Status: \(status)"
+        }
+
+        return ""
+    }
+
+    private static func renderNodesSummary(_ dict: [String: Any]) -> String? {
+        if let nodes = dict["nodes"] as? [[String: Any]] {
+            if nodes.isEmpty { return "No nodes found." }
+            var lines: [String] = []
+            lines.append("\(nodes.count) node\(nodes.count == 1 ? "" : "s") found.")
+
+            for node in nodes.prefix(3) {
+                let label = self.firstString(in: node, keys: ["displayName", "name", "nodeId"]) ?? "Node"
+                var details: [String] = []
+
+                if let connected = node["connected"] as? Bool {
+                    details.append(connected ? "connected" : "offline")
+                }
+                if let platform = self.firstString(in: node, keys: ["platform"]) {
+                    details.append(platform)
+                }
+                if let version = self.firstString(in: node, keys: ["osVersion", "appVersion", "version"]) {
+                    details.append(version)
+                }
+                if let pairing = self.pairingDetail(node) {
+                    details.append(pairing)
+                }
+
+                if details.isEmpty {
+                    lines.append("• \(label)")
+                } else {
+                    lines.append("• \(label) - \(details.joined(separator: ", "))")
+                }
+            }
+
+            let extra = nodes.count - 3
+            if extra > 0 {
+                lines.append("... +\(extra) more")
+            }
+            return lines.joined(separator: "\n")
+        }
+
+        if let pending = dict["pending"] as? [Any], let paired = dict["paired"] as? [Any] {
+            return "Pairing requests: \(pending.count) pending, \(paired.count) paired."
+        }
+
+        if let pending = dict["pending"] as? [Any] {
+            if pending.isEmpty { return "No pending pairing requests." }
+            return "\(pending.count) pending pairing request\(pending.count == 1 ? "" : "s")."
+        }
+
+        return nil
+    }
+
+    private static func pairingDetail(_ node: [String: Any]) -> String? {
+        if let paired = node["paired"] as? Bool, !paired {
+            return "pairing required"
+        }
+
+        for key in ["status", "state", "deviceStatus"] {
+            if let raw = node[key] as? String, raw.lowercased().contains("pairing required") {
+                return "pairing required"
+            }
+        }
+        return nil
+    }
+
+    private static func firstString(in dict: [String: Any], keys: [String]) -> String? {
+        for key in keys {
+            if let value = dict[key] as? String {
+                let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+                if !trimmed.isEmpty {
+                    return trimmed
+                }
+            }
+        }
+        return nil
+    }
+
+    private static func sanitizeError(_ raw: String) -> String {
+        var cleaned = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+        if cleaned.contains("agent="),
+           cleaned.contains("action="),
+           let marker = cleaned.range(of: ": ")
+        {
+            cleaned = String(cleaned[marker.upperBound...]).trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+
+        if let firstLine = cleaned.split(separator: "\n").first {
+            cleaned = String(firstLine).trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+
+        if cleaned.count > 220 {
+            cleaned = String(cleaned.prefix(217)) + "..."
+        }
+        return cleaned
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/AnyCodable+Helpers.swift

@@ -0,0 +1,88 @@
+import Foundation
+
+extension AnyCodable {
+    public var stringValue: String? {
+        self.value as? String
+    }
+
+    public var boolValue: Bool? {
+        if let value = self.value as? Bool {
+            return value
+        }
+        if let number = self.value as? NSNumber, CFGetTypeID(number) == CFBooleanGetTypeID() {
+            return number.boolValue
+        }
+        return nil
+    }
+
+    public var intValue: Int? {
+        if let value = self.value as? Int {
+            return value
+        }
+        if let number = self.value as? NSNumber, CFGetTypeID(number) != CFBooleanGetTypeID() {
+            let value = number.doubleValue
+            if value > 0, value.rounded(.towardZero) == value, value <= Double(Int.max) {
+                return Int(value)
+            }
+        }
+        return nil
+    }
+
+    public var doubleValue: Double? {
+        if let value = self.value as? Double {
+            return value
+        }
+        if let value = self.value as? Int {
+            return Double(value)
+        }
+        if let number = self.value as? NSNumber, CFGetTypeID(number) != CFBooleanGetTypeID() {
+            return number.doubleValue
+        }
+        return nil
+    }
+
+    public var dictionaryValue: [String: AnyCodable]? {
+        if let value = self.value as? [String: AnyCodable] {
+            return value
+        }
+        if let value = self.value as? [String: Any] {
+            return value.mapValues(AnyCodable.init)
+        }
+        if let value = self.value as? NSDictionary {
+            var converted: [String: AnyCodable] = [:]
+            for case let (key as String, raw) in value {
+                converted[key] = AnyCodable(raw)
+            }
+            return converted
+        }
+        return nil
+    }
+
+    public var arrayValue: [AnyCodable]? {
+        if let value = self.value as? [AnyCodable] {
+            return value
+        }
+        if let value = self.value as? [Any] {
+            return value.map(AnyCodable.init)
+        }
+        if let value = self.value as? NSArray {
+            return value.map(AnyCodable.init)
+        }
+        return nil
+    }
+
+    public var foundationValue: Any {
+        switch self.value {
+        case let dict as [String: AnyCodable]:
+            dict.mapValues(\.foundationValue)
+        case let array as [AnyCodable]:
+            array.map(\.foundationValue)
+        case let dict as [String: Any]:
+            dict.mapValues { AnyCodable($0).foundationValue }
+        case let array as [Any]:
+            array.map { AnyCodable($0).foundationValue }
+        default:
+            self.value
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/AnyCodable.swift

@@ -0,0 +1,3 @@
+import OpenClawProtocol
+
+public typealias AnyCodable = OpenClawProtocol.AnyCodable

apps/shared/OpenClawKit/Sources/OpenClawKit/AsyncTimeout.swift

@@ -0,0 +1,36 @@
+import Foundation
+
+public enum AsyncTimeout {
+    public static func withTimeout<T: Sendable>(
+        seconds: Double,
+        onTimeout: @escaping @Sendable () -> Error,
+        operation: @escaping @Sendable () async throws -> T) async throws -> T
+    {
+        let clamped = max(0, seconds)
+        if clamped == 0 {
+            return try await operation()
+        }
+
+        return try await withThrowingTaskGroup(of: T.self) { group in
+            group.addTask { try await operation() }
+            group.addTask {
+                try await Task.sleep(nanoseconds: UInt64(clamped * 1_000_000_000))
+                throw onTimeout()
+            }
+            let result = try await group.next()
+            group.cancelAll()
+            if let result { return result }
+            throw onTimeout()
+        }
+    }
+
+    public static func withTimeoutMs<T: Sendable>(
+        timeoutMs: Int,
+        onTimeout: @escaping @Sendable () -> Error,
+        operation: @escaping @Sendable () async throws -> T) async throws -> T
+    {
+        let clamped = max(0, timeoutMs)
+        let seconds = Double(clamped) / 1000.0
+        return try await self.withTimeout(seconds: seconds, onTimeout: onTimeout, operation: operation)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/AudioStreamingProtocols.swift

@@ -0,0 +1,18 @@
+#if Talk
+import Foundation
+
+@MainActor
+public protocol StreamingAudioPlaying {
+    func play(stream: AsyncThrowingStream<Data, Error>) async -> StreamingPlaybackResult
+    func stop() -> Double?
+}
+
+@MainActor
+public protocol PCMStreamingAudioPlaying {
+    func play(stream: AsyncThrowingStream<Data, Error>, sampleRate: Double) async -> StreamingPlaybackResult
+    func stop() -> Double?
+}
+
+extension StreamingAudioPlayer: StreamingAudioPlaying {}
+extension PCMStreamingAudioPlayer: PCMStreamingAudioPlaying {}
+#endif

apps/shared/OpenClawKit/Sources/OpenClawKit/BonjourEscapes.swift

@@ -0,0 +1,33 @@
+import Foundation
+
+public enum BonjourEscapes {
+    /// mDNS / DNS-SD commonly escapes bytes in instance names as `\DDD` (decimal-encoded),
+    /// e.g. spaces are `\032`.
+    public static func decode(_ input: String) -> String {
+        var out = ""
+        var i = input.startIndex
+        while i < input.endIndex {
+            if input[i] == "\\",
+               let d0 = input.index(i, offsetBy: 1, limitedBy: input.index(before: input.endIndex)),
+               let d1 = input.index(i, offsetBy: 2, limitedBy: input.index(before: input.endIndex)),
+               let d2 = input.index(i, offsetBy: 3, limitedBy: input.index(before: input.endIndex)),
+               input[d0].isNumber,
+               input[d1].isNumber,
+               input[d2].isNumber
+            {
+                let digits = String(input[d0...d2])
+                if let value = Int(digits),
+                   let scalar = UnicodeScalar(value)
+                {
+                    out.append(Character(scalar))
+                    i = input.index(i, offsetBy: 4)
+                    continue
+                }
+            }
+
+            out.append(input[i])
+            i = input.index(after: i)
+        }
+        return out
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/BonjourServiceResolverSupport.swift

@@ -0,0 +1,14 @@
+import Foundation
+
+public enum BonjourServiceResolverSupport {
+    public static func start(_ service: NetService, timeout: TimeInterval = 2.0) {
+        service.schedule(in: .main, forMode: .common)
+        service.resolve(withTimeout: timeout)
+    }
+
+    public static func normalizeHost(_ raw: String?) -> String? {
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty else { return nil }
+        return trimmed.hasSuffix(".") ? String(trimmed.dropLast()) : trimmed
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/BonjourTypes.swift

@@ -0,0 +1,40 @@
+import Foundation
+
+public enum OpenClawBonjour {
+    // v0: internal-only, subject to rename.
+    public static let gatewayServiceType = "_openclaw-gw._tcp"
+    public static let gatewayServiceDomain = "local."
+    public static var wideAreaGatewayServiceDomain: String? {
+        let env = ProcessInfo.processInfo.environment
+        return resolveWideAreaDomain(env["OPENCLAW_WIDE_AREA_DOMAIN"])
+    }
+
+    public static var gatewayServiceDomains: [String] {
+        var domains = [gatewayServiceDomain]
+        if let wideArea = wideAreaGatewayServiceDomain {
+            domains.append(wideArea)
+        }
+        return domains
+    }
+
+    private static func resolveWideAreaDomain(_ raw: String?) -> String? {
+        let trimmed = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty { return nil }
+        let normalized = self.normalizeServiceDomain(trimmed)
+        return normalized == self.gatewayServiceDomain ? nil : normalized
+    }
+
+    public static func normalizeServiceDomain(_ raw: String?) -> String {
+        let trimmed = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            return self.gatewayServiceDomain
+        }
+
+        let lower = trimmed.lowercased()
+        if lower == "local" || lower == "local." {
+            return self.gatewayServiceDomain
+        }
+
+        return lower.hasSuffix(".") ? lower : (lower + ".")
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/BridgeFrames.swift

@@ -0,0 +1,266 @@
+import Foundation
+
+public struct BridgeBaseFrame: Codable, Sendable {
+    public let type: String
+
+    public init(type: String) {
+        self.type = type
+    }
+}
+
+public struct BridgeInvokeRequest: Codable, Sendable {
+    public let type: String
+    public let id: String
+    public let command: String
+    public let paramsJSON: String?
+    public let nodeId: String?
+
+    public init(
+        type: String = "invoke",
+        id: String,
+        command: String,
+        paramsJSON: String? = nil,
+        nodeId: String? = nil)
+    {
+        self.type = type
+        self.id = id
+        self.command = command
+        self.paramsJSON = paramsJSON
+        self.nodeId = nodeId
+    }
+}
+
+public struct BridgeInvokeResponse: Codable, Sendable {
+    public let type: String
+    public let id: String
+    public let ok: Bool
+    public let payloadJSON: String?
+    public let error: OpenClawNodeError?
+
+    public init(
+        type: String = "invoke-res",
+        id: String,
+        ok: Bool,
+        payloadJSON: String? = nil,
+        error: OpenClawNodeError? = nil)
+    {
+        self.type = type
+        self.id = id
+        self.ok = ok
+        self.payloadJSON = payloadJSON
+        self.error = error
+    }
+}
+
+public struct BridgeEventFrame: Codable, Sendable {
+    public let type: String
+    public let event: String
+    public let payloadJSON: String?
+
+    public init(type: String = "event", event: String, payloadJSON: String? = nil) {
+        self.type = type
+        self.event = event
+        self.payloadJSON = payloadJSON
+    }
+}
+
+public struct BridgeHello: Codable, Sendable {
+    public let type: String
+    public let nodeId: String
+    public let displayName: String?
+    public let token: String?
+    public let platform: String?
+    public let version: String?
+    public let coreVersion: String?
+    public let uiVersion: String?
+    public let deviceFamily: String?
+    public let modelIdentifier: String?
+    public let caps: [String]?
+    public let commands: [String]?
+    public let permissions: [String: Bool]?
+
+    public init(
+        type: String = "hello",
+        nodeId: String,
+        displayName: String?,
+        token: String?,
+        platform: String?,
+        version: String?,
+        coreVersion: String? = nil,
+        uiVersion: String? = nil,
+        deviceFamily: String? = nil,
+        modelIdentifier: String? = nil,
+        caps: [String]? = nil,
+        commands: [String]? = nil,
+        permissions: [String: Bool]? = nil)
+    {
+        self.type = type
+        self.nodeId = nodeId
+        self.displayName = displayName
+        self.token = token
+        self.platform = platform
+        self.version = version
+        self.coreVersion = coreVersion
+        self.uiVersion = uiVersion
+        self.deviceFamily = deviceFamily
+        self.modelIdentifier = modelIdentifier
+        self.caps = caps
+        self.commands = commands
+        self.permissions = permissions
+    }
+}
+
+public struct BridgeHelloOk: Codable, Sendable {
+    public let type: String
+    public let serverName: String
+    public let mainSessionKey: String?
+
+    public init(
+        type: String = "hello-ok",
+        serverName: String,
+        mainSessionKey: String? = nil)
+    {
+        self.type = type
+        self.serverName = serverName
+        self.mainSessionKey = mainSessionKey
+    }
+}
+
+public struct BridgePairRequest: Codable, Sendable {
+    public let type: String
+    public let nodeId: String
+    public let displayName: String?
+    public let platform: String?
+    public let version: String?
+    public let coreVersion: String?
+    public let uiVersion: String?
+    public let deviceFamily: String?
+    public let modelIdentifier: String?
+    public let caps: [String]?
+    public let commands: [String]?
+    public let permissions: [String: Bool]?
+    public let remoteAddress: String?
+    public let silent: Bool?
+
+    public init(
+        type: String = "pair-request",
+        nodeId: String,
+        displayName: String?,
+        platform: String?,
+        version: String?,
+        coreVersion: String? = nil,
+        uiVersion: String? = nil,
+        deviceFamily: String? = nil,
+        modelIdentifier: String? = nil,
+        caps: [String]? = nil,
+        commands: [String]? = nil,
+        permissions: [String: Bool]? = nil,
+        remoteAddress: String? = nil,
+        silent: Bool? = nil)
+    {
+        self.type = type
+        self.nodeId = nodeId
+        self.displayName = displayName
+        self.platform = platform
+        self.version = version
+        self.coreVersion = coreVersion
+        self.uiVersion = uiVersion
+        self.deviceFamily = deviceFamily
+        self.modelIdentifier = modelIdentifier
+        self.caps = caps
+        self.commands = commands
+        self.permissions = permissions
+        self.remoteAddress = remoteAddress
+        self.silent = silent
+    }
+}
+
+public struct BridgePairOk: Codable, Sendable {
+    public let type: String
+    public let token: String
+
+    public init(type: String = "pair-ok", token: String) {
+        self.type = type
+        self.token = token
+    }
+}
+
+public struct BridgePing: Codable, Sendable {
+    public let type: String
+    public let id: String
+
+    public init(type: String = "ping", id: String) {
+        self.type = type
+        self.id = id
+    }
+}
+
+public struct BridgePong: Codable, Sendable {
+    public let type: String
+    public let id: String
+
+    public init(type: String = "pong", id: String) {
+        self.type = type
+        self.id = id
+    }
+}
+
+public struct BridgeErrorFrame: Codable, Sendable {
+    public let type: String
+    public let code: String
+    public let message: String
+
+    public init(type: String = "error", code: String, message: String) {
+        self.type = type
+        self.code = code
+        self.message = message
+    }
+}
+
+// MARK: - Optional RPC (node -> bridge)
+
+public struct BridgeRPCRequest: Codable, Sendable {
+    public let type: String
+    public let id: String
+    public let method: String
+    public let paramsJSON: String?
+
+    public init(type: String = "req", id: String, method: String, paramsJSON: String? = nil) {
+        self.type = type
+        self.id = id
+        self.method = method
+        self.paramsJSON = paramsJSON
+    }
+}
+
+public struct BridgeRPCError: Codable, Sendable, Equatable {
+    public let code: String
+    public let message: String
+
+    public init(code: String, message: String) {
+        self.code = code
+        self.message = message
+    }
+}
+
+public struct BridgeRPCResponse: Codable, Sendable {
+    public let type: String
+    public let id: String
+    public let ok: Bool
+    public let payloadJSON: String?
+    public let error: BridgeRPCError?
+
+    public init(
+        type: String = "res",
+        id: String,
+        ok: Bool,
+        payloadJSON: String? = nil,
+        error: BridgeRPCError? = nil)
+    {
+        self.type = type
+        self.id = id
+        self.ok = ok
+        self.payloadJSON = payloadJSON
+        self.error = error
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/BrowserCommands.swift

@@ -0,0 +1,5 @@
+import Foundation
+
+public enum OpenClawBrowserCommand: String, Codable, Sendable {
+    case proxy = "browser.proxy"
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CalendarCommands.swift

@@ -0,0 +1,83 @@
+import Foundation
+
+public enum OpenClawCalendarCommand: String, Codable, Sendable {
+    case events = "calendar.events"
+    case add = "calendar.add"
+}
+
+public typealias OpenClawCalendarEventsParams = OpenClawDateRangeLimitParams
+
+public struct OpenClawCalendarAddParams: Codable, Sendable, Equatable {
+    public var title: String
+    public var startISO: String
+    public var endISO: String
+    public var isAllDay: Bool?
+    public var location: String?
+    public var notes: String?
+    public var calendarId: String?
+    public var calendarTitle: String?
+
+    public init(
+        title: String,
+        startISO: String,
+        endISO: String,
+        isAllDay: Bool? = nil,
+        location: String? = nil,
+        notes: String? = nil,
+        calendarId: String? = nil,
+        calendarTitle: String? = nil)
+    {
+        self.title = title
+        self.startISO = startISO
+        self.endISO = endISO
+        self.isAllDay = isAllDay
+        self.location = location
+        self.notes = notes
+        self.calendarId = calendarId
+        self.calendarTitle = calendarTitle
+    }
+}
+
+public struct OpenClawCalendarEventPayload: Codable, Sendable, Equatable {
+    public var identifier: String
+    public var title: String
+    public var startISO: String
+    public var endISO: String
+    public var isAllDay: Bool
+    public var location: String?
+    public var calendarTitle: String?
+
+    public init(
+        identifier: String,
+        title: String,
+        startISO: String,
+        endISO: String,
+        isAllDay: Bool,
+        location: String? = nil,
+        calendarTitle: String? = nil)
+    {
+        self.identifier = identifier
+        self.title = title
+        self.startISO = startISO
+        self.endISO = endISO
+        self.isAllDay = isAllDay
+        self.location = location
+        self.calendarTitle = calendarTitle
+    }
+}
+
+public struct OpenClawCalendarEventsPayload: Codable, Sendable, Equatable {
+    public var events: [OpenClawCalendarEventPayload]
+
+    public init(events: [OpenClawCalendarEventPayload]) {
+        self.events = events
+    }
+}
+
+public struct OpenClawCalendarAddPayload: Codable, Sendable, Equatable {
+    public var event: OpenClawCalendarEventPayload
+
+    public init(event: OpenClawCalendarEventPayload) {
+        self.event = event
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CameraAuthorization.swift

@@ -0,0 +1,21 @@
+import AVFoundation
+
+public enum CameraAuthorization {
+    public static func isAuthorized(for mediaType: AVMediaType) async -> Bool {
+        let status = AVCaptureDevice.authorizationStatus(for: mediaType)
+        switch status {
+        case .authorized:
+            return true
+        case .notDetermined:
+            return await withCheckedContinuation(isolation: nil) { cont in
+                AVCaptureDevice.requestAccess(for: mediaType) { granted in
+                    cont.resume(returning: granted)
+                }
+            }
+        case .denied, .restricted:
+            return false
+        @unknown default:
+            return false
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CameraCapturePipelineSupport.swift

@@ -0,0 +1,151 @@
+import AVFoundation
+import Foundation
+
+public enum CameraCapturePipelineSupport {
+    public static func preparePhotoSession(
+        preferFrontCamera: Bool,
+        deviceId: String?,
+        pickCamera: (_ preferFrontCamera: Bool, _ deviceId: String?) -> AVCaptureDevice?,
+        cameraUnavailableError: @autoclosure () -> Error,
+        mapSetupError: (CameraSessionConfigurationError) -> Error) throws
+        -> (session: AVCaptureSession, device: AVCaptureDevice, output: AVCapturePhotoOutput)
+    {
+        let session = AVCaptureSession()
+        session.sessionPreset = .photo
+
+        guard let device = pickCamera(preferFrontCamera, deviceId) else {
+            throw cameraUnavailableError()
+        }
+
+        do {
+            try CameraSessionConfiguration.addCameraInput(session: session, camera: device)
+            let output = try CameraSessionConfiguration.addPhotoOutput(session: session)
+            return (session, device, output)
+        } catch let setupError as CameraSessionConfigurationError {
+            throw mapSetupError(setupError)
+        }
+    }
+
+    public static func prepareMovieSession(
+        preferFrontCamera: Bool,
+        deviceId: String?,
+        includeAudio: Bool,
+        durationMs: Int,
+        pickCamera: (_ preferFrontCamera: Bool, _ deviceId: String?) -> AVCaptureDevice?,
+        cameraUnavailableError: @autoclosure () -> Error,
+        mapSetupError: (CameraSessionConfigurationError) -> Error) throws
+        -> (session: AVCaptureSession, output: AVCaptureMovieFileOutput)
+    {
+        let session = AVCaptureSession()
+        session.sessionPreset = .high
+
+        guard let camera = pickCamera(preferFrontCamera, deviceId) else {
+            throw cameraUnavailableError()
+        }
+
+        do {
+            try CameraSessionConfiguration.addCameraInput(session: session, camera: camera)
+            let output = try CameraSessionConfiguration.addMovieOutput(
+                session: session,
+                includeAudio: includeAudio,
+                durationMs: durationMs)
+            return (session, output)
+        } catch let setupError as CameraSessionConfigurationError {
+            throw mapSetupError(setupError)
+        }
+    }
+
+    public static func prepareWarmMovieSession(
+        preferFrontCamera: Bool,
+        deviceId: String?,
+        includeAudio: Bool,
+        durationMs: Int,
+        pickCamera: (_ preferFrontCamera: Bool, _ deviceId: String?) -> AVCaptureDevice?,
+        cameraUnavailableError: @autoclosure () -> Error,
+        mapSetupError: (CameraSessionConfigurationError) -> Error) async throws
+        -> (session: AVCaptureSession, output: AVCaptureMovieFileOutput)
+    {
+        let prepared = try self.prepareMovieSession(
+            preferFrontCamera: preferFrontCamera,
+            deviceId: deviceId,
+            includeAudio: includeAudio,
+            durationMs: durationMs,
+            pickCamera: pickCamera,
+            cameraUnavailableError: cameraUnavailableError(),
+            mapSetupError: mapSetupError)
+        prepared.session.startRunning()
+        await self.warmUpCaptureSession()
+        return prepared
+    }
+
+    public static func withWarmMovieSession<T>(
+        preferFrontCamera: Bool,
+        deviceId: String?,
+        includeAudio: Bool,
+        durationMs: Int,
+        pickCamera: (_ preferFrontCamera: Bool, _ deviceId: String?) -> AVCaptureDevice?,
+        cameraUnavailableError: @autoclosure () -> Error,
+        mapSetupError: (CameraSessionConfigurationError) -> Error,
+        operation: (AVCaptureMovieFileOutput) async throws -> T) async throws -> T
+    {
+        let prepared = try await self.prepareWarmMovieSession(
+            preferFrontCamera: preferFrontCamera,
+            deviceId: deviceId,
+            includeAudio: includeAudio,
+            durationMs: durationMs,
+            pickCamera: pickCamera,
+            cameraUnavailableError: cameraUnavailableError(),
+            mapSetupError: mapSetupError)
+        defer { prepared.session.stopRunning() }
+        return try await operation(prepared.output)
+    }
+
+    public static func mapMovieSetupError<E: Error>(
+        _ setupError: CameraSessionConfigurationError,
+        microphoneUnavailableError: @autoclosure () -> E,
+        captureFailed: (String) -> E) -> E
+    {
+        if case .microphoneUnavailable = setupError {
+            return microphoneUnavailableError()
+        }
+        return captureFailed(setupError.localizedDescription)
+    }
+
+    public static func makePhotoSettings(output: AVCapturePhotoOutput) -> AVCapturePhotoSettings {
+        let settings: AVCapturePhotoSettings = {
+            if output.availablePhotoCodecTypes.contains(.jpeg) {
+                return AVCapturePhotoSettings(format: [AVVideoCodecKey: AVVideoCodecType.jpeg])
+            }
+            return AVCapturePhotoSettings()
+        }()
+        settings.photoQualityPrioritization = .quality
+        return settings
+    }
+
+    public static func capturePhotoData(
+        output: AVCapturePhotoOutput,
+        makeDelegate: (CheckedContinuation<Data, Error>) -> any AVCapturePhotoCaptureDelegate) async throws -> Data
+    {
+        var delegate: (any AVCapturePhotoCaptureDelegate)?
+        let rawData: Data = try await withCheckedThrowingContinuation { cont in
+            let captureDelegate = makeDelegate(cont)
+            delegate = captureDelegate
+            output.capturePhoto(with: self.makePhotoSettings(output: output), delegate: captureDelegate)
+        }
+        withExtendedLifetime(delegate) {}
+        return rawData
+    }
+
+    public static func warmUpCaptureSession() async {
+        // A short delay after `startRunning()` significantly reduces "blank first frame" captures on some devices.
+        try? await Task.sleep(nanoseconds: 150_000_000) // 150ms
+    }
+
+    public static func positionLabel(_ position: AVCaptureDevice.Position) -> String {
+        switch position {
+        case .front: "front"
+        case .back: "back"
+        default: "unspecified"
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CameraCommands.swift

@@ -0,0 +1,68 @@
+import Foundation
+
+public enum OpenClawCameraCommand: String, Codable, Sendable {
+    case list = "camera.list"
+    case snap = "camera.snap"
+    case clip = "camera.clip"
+}
+
+public enum OpenClawCameraFacing: String, Codable, Sendable {
+    case back
+    case front
+}
+
+public enum OpenClawCameraImageFormat: String, Codable, Sendable {
+    case jpg
+    case jpeg
+}
+
+public enum OpenClawCameraVideoFormat: String, Codable, Sendable {
+    case mp4
+}
+
+public struct OpenClawCameraSnapParams: Codable, Sendable, Equatable {
+    public var facing: OpenClawCameraFacing?
+    public var maxWidth: Int?
+    public var quality: Double?
+    public var format: OpenClawCameraImageFormat?
+    public var deviceId: String?
+    public var delayMs: Int?
+
+    public init(
+        facing: OpenClawCameraFacing? = nil,
+        maxWidth: Int? = nil,
+        quality: Double? = nil,
+        format: OpenClawCameraImageFormat? = nil,
+        deviceId: String? = nil,
+        delayMs: Int? = nil)
+    {
+        self.facing = facing
+        self.maxWidth = maxWidth
+        self.quality = quality
+        self.format = format
+        self.deviceId = deviceId
+        self.delayMs = delayMs
+    }
+}
+
+public struct OpenClawCameraClipParams: Codable, Sendable, Equatable {
+    public var facing: OpenClawCameraFacing?
+    public var durationMs: Int?
+    public var includeAudio: Bool?
+    public var format: OpenClawCameraVideoFormat?
+    public var deviceId: String?
+
+    public init(
+        facing: OpenClawCameraFacing? = nil,
+        durationMs: Int? = nil,
+        includeAudio: Bool? = nil,
+        format: OpenClawCameraVideoFormat? = nil,
+        deviceId: String? = nil)
+    {
+        self.facing = facing
+        self.durationMs = durationMs
+        self.includeAudio = includeAudio
+        self.format = format
+        self.deviceId = deviceId
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CameraSessionConfiguration.swift

@@ -0,0 +1,70 @@
+import AVFoundation
+import CoreMedia
+
+public enum CameraSessionConfigurationError: LocalizedError {
+    case addCameraInputFailed
+    case addPhotoOutputFailed
+    case microphoneUnavailable
+    case addMicrophoneInputFailed
+    case addMovieOutputFailed
+
+    public var errorDescription: String? {
+        switch self {
+        case .addCameraInputFailed:
+            "Failed to add camera input"
+        case .addPhotoOutputFailed:
+            "Failed to add photo output"
+        case .microphoneUnavailable:
+            "Microphone unavailable"
+        case .addMicrophoneInputFailed:
+            "Failed to add microphone input"
+        case .addMovieOutputFailed:
+            "Failed to add movie output"
+        }
+    }
+}
+
+public enum CameraSessionConfiguration {
+    public static func addCameraInput(session: AVCaptureSession, camera: AVCaptureDevice) throws {
+        let input = try AVCaptureDeviceInput(device: camera)
+        guard session.canAddInput(input) else {
+            throw CameraSessionConfigurationError.addCameraInputFailed
+        }
+        session.addInput(input)
+    }
+
+    public static func addPhotoOutput(session: AVCaptureSession) throws -> AVCapturePhotoOutput {
+        let output = AVCapturePhotoOutput()
+        guard session.canAddOutput(output) else {
+            throw CameraSessionConfigurationError.addPhotoOutputFailed
+        }
+        session.addOutput(output)
+        output.maxPhotoQualityPrioritization = .quality
+        return output
+    }
+
+    public static func addMovieOutput(
+        session: AVCaptureSession,
+        includeAudio: Bool,
+        durationMs: Int) throws -> AVCaptureMovieFileOutput
+    {
+        if includeAudio {
+            guard let mic = AVCaptureDevice.default(for: .audio) else {
+                throw CameraSessionConfigurationError.microphoneUnavailable
+            }
+            let micInput = try AVCaptureDeviceInput(device: mic)
+            guard session.canAddInput(micInput) else {
+                throw CameraSessionConfigurationError.addMicrophoneInputFailed
+            }
+            session.addInput(micInput)
+        }
+
+        let output = AVCaptureMovieFileOutput()
+        guard session.canAddOutput(output) else {
+            throw CameraSessionConfigurationError.addMovieOutputFailed
+        }
+        session.addOutput(output)
+        output.maxRecordedDuration = CMTime(value: Int64(durationMs), timescale: 1000)
+        return output
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CanvasA2UIAction.swift

@@ -0,0 +1,104 @@
+import Foundation
+
+public enum OpenClawCanvasA2UIAction: Sendable {
+    public struct AgentMessageContext: Sendable {
+        public struct Session: Sendable {
+            public var key: String
+            public var surfaceId: String
+
+            public init(key: String, surfaceId: String) {
+                self.key = key
+                self.surfaceId = surfaceId
+            }
+        }
+
+        public struct Component: Sendable {
+            public var id: String
+            public var host: String
+            public var instanceId: String
+
+            public init(id: String, host: String, instanceId: String) {
+                self.id = id
+                self.host = host
+                self.instanceId = instanceId
+            }
+        }
+
+        public var actionName: String
+        public var session: Session
+        public var component: Component
+        public var contextJSON: String?
+
+        public init(actionName: String, session: Session, component: Component, contextJSON: String?) {
+            self.actionName = actionName
+            self.session = session
+            self.component = component
+            self.contextJSON = contextJSON
+        }
+    }
+
+    public static func extractActionName(_ userAction: [String: Any]) -> String? {
+        let keys = ["name", "action"]
+        for key in keys {
+            if let raw = userAction[key] as? String {
+                let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+                if !trimmed.isEmpty { return trimmed }
+            }
+        }
+        return nil
+    }
+
+    public static func sanitizeTagValue(_ value: String) -> String {
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        let nonEmpty = trimmed.isEmpty ? "-" : trimmed
+        let normalized = nonEmpty.replacingOccurrences(of: " ", with: "_")
+        let allowed = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-.:")
+        let scalars = normalized.unicodeScalars.map { allowed.contains($0) ? Character($0) : "_" }
+        return String(scalars)
+    }
+
+    public static func compactJSON(_ obj: Any?) -> String? {
+        guard let obj else { return nil }
+        guard JSONSerialization.isValidJSONObject(obj) else { return nil }
+        guard let data = try? JSONSerialization.data(withJSONObject: obj, options: []),
+              let str = String(data: data, encoding: .utf8)
+        else { return nil }
+        return str
+    }
+
+    public static func formatAgentMessage(_ context: AgentMessageContext) -> String {
+        let ctxSuffix = context.contextJSON.flatMap { $0.isEmpty ? nil : " ctx=\($0)" } ?? ""
+        return [
+            "CANVAS_A2UI",
+            "action=\(self.sanitizeTagValue(context.actionName))",
+            "session=\(self.sanitizeTagValue(context.session.key))",
+            "surface=\(self.sanitizeTagValue(context.session.surfaceId))",
+            "component=\(self.sanitizeTagValue(context.component.id))",
+            "host=\(self.sanitizeTagValue(context.component.host))",
+            "instance=\(self.sanitizeTagValue(context.component.instanceId))\(ctxSuffix)",
+            "default=update_canvas",
+        ].joined(separator: " ")
+    }
+
+    public static func jsDispatchA2UIActionStatus(actionId: String, ok: Bool, error: String?) -> String {
+        let payload: [String: Any] = [
+            "id": actionId,
+            "ok": ok,
+            "error": error ?? "",
+        ]
+        let json: String = {
+            if let data = try? JSONSerialization.data(withJSONObject: payload, options: []),
+               let str = String(data: data, encoding: .utf8)
+            {
+                return str
+            }
+            return "{\"id\":\"\(actionId)\",\"ok\":\(ok ? "true" : "false"),\"error\":\"\"}"
+        }()
+        return """
+        (() => {
+          const detail = \(json);
+          window.dispatchEvent(new CustomEvent('openclaw:a2ui-action-status', { detail }));
+        })();
+        """
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CanvasA2UICommands.swift

@@ -0,0 +1,26 @@
+import Foundation
+
+public enum OpenClawCanvasA2UICommand: String, Codable, Sendable {
+    /// Render A2UI content on the device canvas.
+    case push = "canvas.a2ui.push"
+    /// Legacy alias for `push` when sending JSONL.
+    case pushJSONL = "canvas.a2ui.pushJSONL"
+    /// Reset the A2UI renderer state.
+    case reset = "canvas.a2ui.reset"
+}
+
+public struct OpenClawCanvasA2UIPushParams: Codable, Sendable, Equatable {
+    public var messages: [AnyCodable]
+
+    public init(messages: [AnyCodable]) {
+        self.messages = messages
+    }
+}
+
+public struct OpenClawCanvasA2UIPushJSONLParams: Codable, Sendable, Equatable {
+    public var jsonl: String
+
+    public init(jsonl: String) {
+        self.jsonl = jsonl
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CanvasA2UIJSONL.swift

@@ -0,0 +1,81 @@
+import Foundation
+
+public enum OpenClawCanvasA2UIJSONL: Sendable {
+    public struct ParsedItem: Sendable {
+        public var lineNumber: Int
+        public var message: AnyCodable
+
+        public init(lineNumber: Int, message: AnyCodable) {
+            self.lineNumber = lineNumber
+            self.message = message
+        }
+    }
+
+    public static func parse(_ text: String) throws -> [ParsedItem] {
+        var out: [ParsedItem] = []
+        var lineNumber = 0
+        for rawLine in text.split(omittingEmptySubsequences: false, whereSeparator: \.isNewline) {
+            lineNumber += 1
+            let line = String(rawLine).trimmingCharacters(in: .whitespacesAndNewlines)
+            if line.isEmpty { continue }
+            let data = Data(line.utf8)
+
+            let decoded = try JSONDecoder().decode(AnyCodable.self, from: data)
+            out.append(ParsedItem(lineNumber: lineNumber, message: decoded))
+        }
+        return out
+    }
+
+    public static func validateV0_8(_ items: [ParsedItem]) throws {
+        let allowed = Set([
+            "beginRendering",
+            "surfaceUpdate",
+            "dataModelUpdate",
+            "deleteSurface",
+        ])
+        for item in items {
+            guard let dict = item.message.value as? [String: AnyCodable] else {
+                throw NSError(domain: "A2UI", code: 1, userInfo: [
+                    NSLocalizedDescriptionKey: "A2UI JSONL line \(item.lineNumber): expected a JSON object",
+                ])
+            }
+
+            if dict.keys.contains("createSurface") {
+                throw NSError(domain: "A2UI", code: 2, userInfo: [
+                    NSLocalizedDescriptionKey: """
+                    A2UI JSONL line \(item.lineNumber): looks like A2UI v0.9 (`createSurface`).
+                    Canvas currently supports A2UI v0.8 server→client messages
+                    (`beginRendering`, `surfaceUpdate`, `dataModelUpdate`, `deleteSurface`).
+                    """,
+                ])
+            }
+
+            let matched = dict.keys.filter { allowed.contains($0) }
+            if matched.count != 1 {
+                let found = dict.keys.sorted().joined(separator: ", ")
+                throw NSError(domain: "A2UI", code: 3, userInfo: [
+                    NSLocalizedDescriptionKey: """
+                    A2UI JSONL line \(item.lineNumber): expected exactly one of \(allowed.sorted()
+                        .joined(separator: ", ")); found: \(found)
+                    """,
+                ])
+            }
+        }
+    }
+
+    public static func decodeMessagesFromJSONL(_ text: String) throws -> [AnyCodable] {
+        let items = try self.parse(text)
+        try self.validateV0_8(items)
+        return items.map(\.message)
+    }
+
+    public static func encodeMessagesJSONArray(_ messages: [AnyCodable]) throws -> String {
+        let data = try JSONEncoder().encode(messages)
+        guard let json = String(data: data, encoding: .utf8) else {
+            throw NSError(domain: "A2UI", code: 10, userInfo: [
+                NSLocalizedDescriptionKey: "Failed to encode messages payload as UTF-8",
+            ])
+        }
+        return json
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CanvasCommandParams.swift

@@ -0,0 +1,76 @@
+import Foundation
+
+public struct OpenClawCanvasNavigateParams: Codable, Sendable, Equatable {
+    public var url: String
+
+    public init(url: String) {
+        self.url = url
+    }
+}
+
+public struct OpenClawCanvasPlacement: Codable, Sendable, Equatable {
+    public var x: Double?
+    public var y: Double?
+    public var width: Double?
+    public var height: Double?
+
+    public init(x: Double? = nil, y: Double? = nil, width: Double? = nil, height: Double? = nil) {
+        self.x = x
+        self.y = y
+        self.width = width
+        self.height = height
+    }
+}
+
+public struct OpenClawCanvasPresentParams: Codable, Sendable, Equatable {
+    public var url: String?
+    public var placement: OpenClawCanvasPlacement?
+
+    public init(url: String? = nil, placement: OpenClawCanvasPlacement? = nil) {
+        self.url = url
+        self.placement = placement
+    }
+}
+
+public struct OpenClawCanvasEvalParams: Codable, Sendable, Equatable {
+    public var javaScript: String
+
+    public init(javaScript: String) {
+        self.javaScript = javaScript
+    }
+}
+
+public enum OpenClawCanvasSnapshotFormat: String, Codable, Sendable {
+    case png
+    case jpeg
+
+    public init(from decoder: Decoder) throws {
+        let c = try decoder.singleValueContainer()
+        let raw = try c.decode(String.self).trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        switch raw {
+        case "png":
+            self = .png
+        case "jpeg", "jpg":
+            self = .jpeg
+        default:
+            throw DecodingError.dataCorruptedError(in: c, debugDescription: "Invalid snapshot format: \(raw)")
+        }
+    }
+
+    public func encode(to encoder: Encoder) throws {
+        var c = encoder.singleValueContainer()
+        try c.encode(self.rawValue)
+    }
+}
+
+public struct OpenClawCanvasSnapshotParams: Codable, Sendable, Equatable {
+    public var maxWidth: Int?
+    public var quality: Double?
+    public var format: OpenClawCanvasSnapshotFormat?
+
+    public init(maxWidth: Int? = nil, quality: Double? = nil, format: OpenClawCanvasSnapshotFormat? = nil) {
+        self.maxWidth = maxWidth
+        self.quality = quality
+        self.format = format
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CanvasCommands.swift

@@ -0,0 +1,9 @@
+import Foundation
+
+public enum OpenClawCanvasCommand: String, Codable, Sendable {
+    case present = "canvas.present"
+    case hide = "canvas.hide"
+    case navigate = "canvas.navigate"
+    case evalJS = "canvas.eval"
+    case snapshot = "canvas.snapshot"
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/Capabilities.swift

@@ -0,0 +1,18 @@
+import Foundation
+
+public enum OpenClawCapability: String, Codable, Sendable {
+    case canvas
+    case browser
+    case camera
+    case screen
+    case voiceWake
+    case talk
+    case location
+    case device
+    case watch
+    case photos
+    case contacts
+    case calendar
+    case reminders
+    case motion
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/CaptureRateLimits.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+public enum CaptureRateLimits {
+    public static func clampDurationMs(
+        _ ms: Int?,
+        defaultMs: Int = 10000,
+        minMs: Int = 250,
+        maxMs: Int = 60000) -> Int
+    {
+        let value = ms ?? defaultMs
+        return min(maxMs, max(minMs, value))
+    }
+
+    public static func clampFps(
+        _ fps: Double?,
+        defaultFps: Double = 10,
+        minFps: Double = 1,
+        maxFps: Double) -> Double
+    {
+        let value = fps ?? defaultFps
+        guard value.isFinite else { return defaultFps }
+        return min(maxFps, max(minFps, value))
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ChatCommands.swift

@@ -0,0 +1,23 @@
+import Foundation
+
+public enum OpenClawChatCommand: String, Codable, Sendable {
+    case push = "chat.push"
+}
+
+public struct OpenClawChatPushParams: Codable, Sendable, Equatable {
+    public var text: String
+    public var speak: Bool?
+
+    public init(text: String, speak: Bool? = nil) {
+        self.text = text
+        self.speak = speak
+    }
+}
+
+public struct OpenClawChatPushPayload: Codable, Sendable, Equatable {
+    public var messageId: String?
+
+    public init(messageId: String? = nil) {
+        self.messageId = messageId
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ChatImageProcessor.swift

@@ -0,0 +1,44 @@
+import Foundation
+
+/// Chat-specific image upload policy built on the shared JPEG transcoder.
+public enum ChatImageProcessor {
+    public static let maxLongEdgePx = 1600
+    public static let jpegQuality = 0.8
+    public static let maxPayloadBytes = 3_500_000
+
+    public enum ProcessError: Error, LocalizedError, Sendable {
+        case notAnImage
+        case decodeFailed
+        case encodeFailed
+
+        public var errorDescription: String? {
+            switch self {
+            case .notAnImage:
+                "The data is not a recognizable image."
+            case .decodeFailed:
+                "The image could not be decoded."
+            case .encodeFailed:
+                "The image could not be resized to fit the chat upload limit."
+            }
+        }
+    }
+
+    public static func processForUpload(data: Data) throws -> Data {
+        do {
+            let result = try JPEGTranscoder.transcodeToJPEG(
+                imageData: data,
+                maxLongEdgePx: self.maxLongEdgePx,
+                quality: self.jpegQuality,
+                maxBytes: self.maxPayloadBytes)
+            return result.data
+        } catch JPEGTranscodeError.decodeFailed {
+            throw ProcessError.notAnImage
+        } catch JPEGTranscodeError.propertiesMissing {
+            throw ProcessError.decodeFailed
+        } catch JPEGTranscodeError.sizeLimitExceeded {
+            throw ProcessError.encodeFailed
+        } catch {
+            throw ProcessError.encodeFailed
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ContactsCommands.swift

@@ -0,0 +1,85 @@
+import Foundation
+
+public enum OpenClawContactsCommand: String, Codable, Sendable {
+    case search = "contacts.search"
+    case add = "contacts.add"
+}
+
+public struct OpenClawContactsSearchParams: Codable, Sendable, Equatable {
+    public var query: String?
+    public var limit: Int?
+
+    public init(query: String? = nil, limit: Int? = nil) {
+        self.query = query
+        self.limit = limit
+    }
+}
+
+public struct OpenClawContactsAddParams: Codable, Sendable, Equatable {
+    public var givenName: String?
+    public var familyName: String?
+    public var organizationName: String?
+    public var displayName: String?
+    public var phoneNumbers: [String]?
+    public var emails: [String]?
+
+    public init(
+        givenName: String? = nil,
+        familyName: String? = nil,
+        organizationName: String? = nil,
+        displayName: String? = nil,
+        phoneNumbers: [String]? = nil,
+        emails: [String]? = nil)
+    {
+        self.givenName = givenName
+        self.familyName = familyName
+        self.organizationName = organizationName
+        self.displayName = displayName
+        self.phoneNumbers = phoneNumbers
+        self.emails = emails
+    }
+}
+
+public struct OpenClawContactPayload: Codable, Sendable, Equatable {
+    public var identifier: String
+    public var displayName: String
+    public var givenName: String
+    public var familyName: String
+    public var organizationName: String
+    public var phoneNumbers: [String]
+    public var emails: [String]
+
+    public init(
+        identifier: String,
+        displayName: String,
+        givenName: String,
+        familyName: String,
+        organizationName: String,
+        phoneNumbers: [String],
+        emails: [String])
+    {
+        self.identifier = identifier
+        self.displayName = displayName
+        self.givenName = givenName
+        self.familyName = familyName
+        self.organizationName = organizationName
+        self.phoneNumbers = phoneNumbers
+        self.emails = emails
+    }
+}
+
+public struct OpenClawContactsSearchPayload: Codable, Sendable, Equatable {
+    public var contacts: [OpenClawContactPayload]
+
+    public init(contacts: [OpenClawContactPayload]) {
+        self.contacts = contacts
+    }
+}
+
+public struct OpenClawContactsAddPayload: Codable, Sendable, Equatable {
+    public var contact: OpenClawContactPayload
+
+    public init(contact: OpenClawContactPayload) {
+        self.contact = contact
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/DeepLinks.swift

@@ -0,0 +1,277 @@
+import Foundation
+
+public enum DeepLinkRoute: Sendable, Equatable {
+    case agent(AgentDeepLink)
+    case gateway(GatewayConnectDeepLink)
+    case dashboard
+}
+
+public struct GatewayConnectDeepLink: Codable, Sendable, Equatable {
+    private struct SetupPayload: Decodable {
+        let url: String?
+        let host: String?
+        let port: Int?
+        let tls: Bool?
+        let bootstrapToken: String?
+        let token: String?
+        let password: String?
+    }
+
+    public let host: String
+    public let port: Int
+    public let tls: Bool
+    public let bootstrapToken: String?
+    public let token: String?
+    public let password: String?
+
+    public init(host: String, port: Int, tls: Bool, bootstrapToken: String?, token: String?, password: String?) {
+        self.host = host
+        self.port = port
+        self.tls = tls
+        self.bootstrapToken = bootstrapToken
+        self.token = token
+        self.password = password
+    }
+
+    public var websocketURL: URL? {
+        let scheme = self.tls ? "wss" : "ws"
+        return URL(string: "\(scheme)://\(self.host):\(self.port)")
+    }
+
+    /// Parse a gateway setup input from the QR/scanner/manual entry surfaces.
+    ///
+    /// Accepted inputs are:
+    /// - device-pair setup code (base64url-encoded JSON)
+    /// - raw setup JSON
+    /// - a copied message containing a `Setup code:` line
+    /// - an `openclaw://gateway?...` deep link
+    /// - a raw `ws://` or `wss://` gateway URL
+    public static func fromSetupInput(_ input: String) -> GatewayConnectDeepLink? {
+        let trimmed = input.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if let link = fromSetupCode(trimmed) {
+            return link
+        }
+        if let url = URL(string: trimmed),
+           let route = DeepLinkParser.parse(url),
+           case let .gateway(link) = route
+        {
+            return link
+        }
+        return self.fromGatewayURLString(
+            trimmed,
+            bootstrapToken: nil,
+            token: nil,
+            password: nil)
+    }
+
+    /// Parse a gateway setup payload from a device-pair setup code or copied setup text.
+    ///
+    /// Accepted inputs are:
+    /// - base64url-encoded setup JSON
+    /// - raw setup JSON
+    /// - copied text/message content containing one or more extractable setup-code candidates
+    ///
+    /// Accepted payload shapes are:
+    /// - `{url, bootstrapToken?, token?, password?}`
+    /// - `{host, port?, tls?, bootstrapToken?, token?, password?}`
+    ///
+    /// URL-based payloads provide the gateway WebSocket URL via `url`. Host-based payloads
+    /// provide `host` plus optional `port` and `tls`. In both cases, the optional
+    /// `bootstrapToken`, `token`, and `password` fields are also supported.
+    public static func fromSetupCode(_ code: String) -> GatewayConnectDeepLink? {
+        let trimmed = code.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        if let link = decodeSetupPayload(from: Data(trimmed.utf8)) {
+            return link
+        }
+        if let data = decodeBase64Url(trimmed),
+           let link = decodeSetupPayload(from: data)
+        {
+            return link
+        }
+        for candidate in self.setupCodeCandidates(in: trimmed) where candidate != trimmed {
+            if let data = decodeBase64Url(candidate),
+               let link = decodeSetupPayload(from: data)
+            {
+                return link
+            }
+        }
+        return nil
+    }
+
+    private static func decodeSetupPayload(from data: Data) -> GatewayConnectDeepLink? {
+        guard let payload = try? JSONDecoder().decode(SetupPayload.self, from: data) else { return nil }
+        if let urlString = payload.url?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !urlString.isEmpty
+        {
+            return self.fromGatewayURLString(
+                urlString,
+                bootstrapToken: payload.bootstrapToken,
+                token: payload.token,
+                password: payload.password)
+        }
+        guard let host = payload.host?.trimmingCharacters(in: .whitespacesAndNewlines),
+              !host.isEmpty
+        else {
+            return nil
+        }
+        let tls = payload.tls ?? true
+        if !tls, !LoopbackHost.isLocalNetworkHost(host) {
+            return nil
+        }
+        return GatewayConnectDeepLink(
+            host: host,
+            port: payload.port ?? (tls ? 443 : 18789),
+            tls: tls,
+            bootstrapToken: payload.bootstrapToken,
+            token: payload.token,
+            password: payload.password)
+    }
+
+    private static func fromGatewayURLString(
+        _ urlString: String,
+        bootstrapToken: String?,
+        token: String?,
+        password: String?) -> GatewayConnectDeepLink?
+    {
+        guard let parsed = URLComponents(string: urlString),
+              let hostname = parsed.host, !hostname.isEmpty
+        else { return nil }
+
+        let scheme = (parsed.scheme ?? "ws").lowercased()
+        guard scheme == "ws" || scheme == "wss" || scheme == "http" || scheme == "https" else {
+            return nil
+        }
+        let tls = scheme == "wss" || scheme == "https"
+        if !tls, !LoopbackHost.isLocalNetworkHost(hostname) {
+            return nil
+        }
+        return GatewayConnectDeepLink(
+            host: hostname,
+            port: parsed.port ?? (tls ? 443 : 18789),
+            tls: tls,
+            bootstrapToken: bootstrapToken,
+            token: token,
+            password: password)
+    }
+
+    private static func decodeBase64Url(_ input: String) -> Data? {
+        var base64 = input
+            .replacingOccurrences(of: "-", with: "+")
+            .replacingOccurrences(of: "_", with: "/")
+        let remainder = base64.count % 4
+        if remainder > 0 {
+            base64.append(contentsOf: String(repeating: "=", count: 4 - remainder))
+        }
+        return Data(base64Encoded: base64)
+    }
+
+    private static func setupCodeCandidates(in input: String) -> [String] {
+        let surroundingPunctuation = CharacterSet(charactersIn: "`'\"“”‘’()[]{}<>.,;:")
+        return input
+            .components(separatedBy: .whitespacesAndNewlines)
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines.union(surroundingPunctuation)) }
+            .filter { candidate in
+                guard candidate.count >= 24 else { return false }
+                return candidate.allSatisfy { ch in
+                    ch.isLetter || ch.isNumber || ch == "-" || ch == "_" || ch == "="
+                }
+            }
+    }
+}
+
+public struct AgentDeepLink: Codable, Sendable, Equatable {
+    public let message: String
+    public let sessionKey: String?
+    public let thinking: String?
+    public let deliver: Bool
+    public let to: String?
+    public let channel: String?
+    public let timeoutSeconds: Int?
+    public let key: String?
+
+    public init(
+        message: String,
+        sessionKey: String?,
+        thinking: String?,
+        deliver: Bool,
+        to: String?,
+        channel: String?,
+        timeoutSeconds: Int?,
+        key: String?)
+    {
+        self.message = message
+        self.sessionKey = sessionKey
+        self.thinking = thinking
+        self.deliver = deliver
+        self.to = to
+        self.channel = channel
+        self.timeoutSeconds = timeoutSeconds
+        self.key = key
+    }
+}
+
+public enum DeepLinkParser {
+    public static func parse(_ url: URL) -> DeepLinkRoute? {
+        guard let scheme = url.scheme?.lowercased(),
+              scheme == "openclaw" || scheme == "openclaw-debug"
+        else {
+            return nil
+        }
+        guard let host = url.host?.lowercased(), !host.isEmpty else { return nil }
+        guard let comps = URLComponents(url: url, resolvingAgainstBaseURL: false) else { return nil }
+
+        let query = (comps.queryItems ?? []).reduce(into: [String: String]()) { dict, item in
+            guard let value = item.value else { return }
+            dict[item.name] = value
+        }
+
+        switch host {
+        case "agent":
+            guard let message = query["message"],
+                  !message.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            else {
+                return nil
+            }
+            let deliver = (query["deliver"] as NSString?)?.boolValue ?? false
+            let timeoutSeconds = query["timeoutSeconds"].flatMap { Int($0) }.flatMap { $0 >= 0 ? $0 : nil }
+            return .agent(
+                .init(
+                    message: message,
+                    sessionKey: query["sessionKey"],
+                    thinking: query["thinking"],
+                    deliver: deliver,
+                    to: query["to"],
+                    channel: query["channel"],
+                    timeoutSeconds: timeoutSeconds,
+                    key: query["key"]))
+
+        case "gateway":
+            guard let hostParam = query["host"],
+                  !hostParam.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+            else {
+                return nil
+            }
+            let port = query["port"].flatMap { Int($0) } ?? 18789
+            let tls = (query["tls"] as NSString?)?.boolValue ?? false
+            if !tls, !LoopbackHost.isLocalNetworkHost(hostParam) {
+                return nil
+            }
+            return .gateway(
+                .init(
+                    host: hostParam,
+                    port: port,
+                    tls: tls,
+                    bootstrapToken: nil,
+                    token: query["token"],
+                    password: query["password"]))
+
+        case "dashboard":
+            return .dashboard
+
+        default:
+            return nil
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/DeviceAuthPayload.swift

@@ -0,0 +1,76 @@
+import Foundation
+import OpenClawProtocol
+
+public enum GatewayDeviceAuthPayload {
+    public static func buildV3(
+        deviceId: String,
+        clientId: String,
+        clientMode: String,
+        role: String,
+        scopes: [String],
+        signedAtMs: Int,
+        token: String?,
+        nonce: String,
+        platform: String?,
+        deviceFamily: String?) -> String
+    {
+        let scopeString = scopes.joined(separator: ",")
+        let authToken = token ?? ""
+        let normalizedPlatform = self.normalizeMetadataField(platform)
+        let normalizedDeviceFamily = self.normalizeMetadataField(deviceFamily)
+        return [
+            "v3",
+            deviceId,
+            clientId,
+            clientMode,
+            role,
+            scopeString,
+            String(signedAtMs),
+            authToken,
+            nonce,
+            normalizedPlatform,
+            normalizedDeviceFamily,
+        ].joined(separator: "|")
+    }
+
+    static func normalizeMetadataField(_ value: String?) -> String {
+        guard let value else { return "" }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        if trimmed.isEmpty {
+            return ""
+        }
+        // Keep cross-runtime normalization deterministic (TS/Swift/Kotlin):
+        // lowercase ASCII A-Z only for auth payload metadata fields.
+        var output = String()
+        output.reserveCapacity(trimmed.count)
+        for scalar in trimmed.unicodeScalars {
+            let codePoint = scalar.value
+            if codePoint >= 65, codePoint <= 90, let lowered = UnicodeScalar(codePoint + 32) {
+                output.unicodeScalars.append(lowered)
+            } else {
+                output.unicodeScalars.append(scalar)
+            }
+        }
+        return output
+    }
+
+    public static func signedDeviceDictionary(
+        payload: String,
+        identity: DeviceIdentity,
+        signedAtMs: Int,
+        nonce: String) -> [String: OpenClawProtocol.AnyCodable]?
+    {
+        guard let signature = DeviceIdentityStore.signPayload(payload, identity: identity),
+              let publicKey = DeviceIdentityStore.publicKeyBase64Url(identity)
+        else {
+            return nil
+        }
+        return [
+            "id": OpenClawProtocol.AnyCodable(identity.deviceId),
+            "publicKey": OpenClawProtocol.AnyCodable(publicKey),
+            "signature": OpenClawProtocol.AnyCodable(signature),
+            "signedAt": OpenClawProtocol.AnyCodable(signedAtMs),
+            "nonce": OpenClawProtocol.AnyCodable(nonce),
+        ]
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/DeviceAuthStore.swift

@@ -0,0 +1,117 @@
+import Foundation
+
+public struct DeviceAuthEntry: Codable, Sendable {
+    public let token: String
+    public let role: String
+    public let scopes: [String]
+    public let updatedAtMs: Int
+
+    public init(token: String, role: String, scopes: [String], updatedAtMs: Int) {
+        self.token = token
+        self.role = role
+        self.scopes = scopes
+        self.updatedAtMs = updatedAtMs
+    }
+}
+
+private struct DeviceAuthStoreFile: Codable {
+    var version: Int
+    var deviceId: String
+    var tokens: [String: DeviceAuthEntry]
+}
+
+public enum DeviceAuthStore {
+    public static func loadToken(
+        deviceId: String,
+        role: String,
+        profile: GatewayDeviceIdentityProfile = .primary) -> DeviceAuthEntry?
+    {
+        guard let store = readStore(profile: profile), store.deviceId == deviceId else { return nil }
+        let role = self.normalizeRole(role)
+        return store.tokens[role]
+    }
+
+    public static func storeToken(
+        deviceId: String,
+        role: String,
+        token: String,
+        scopes: [String] = [],
+        profile: GatewayDeviceIdentityProfile = .primary) -> DeviceAuthEntry
+    {
+        let normalizedRole = self.normalizeRole(role)
+        var next = self.readStore(profile: profile)
+        if next?.deviceId != deviceId {
+            next = DeviceAuthStoreFile(version: 1, deviceId: deviceId, tokens: [:])
+        }
+        let entry = DeviceAuthEntry(
+            token: token,
+            role: normalizedRole,
+            scopes: normalizeScopes(scopes),
+            updatedAtMs: Int(Date().timeIntervalSince1970 * 1000))
+        if next == nil {
+            next = DeviceAuthStoreFile(version: 1, deviceId: deviceId, tokens: [:])
+        }
+        next?.tokens[normalizedRole] = entry
+        if let store = next {
+            self.writeStore(store, profile: profile)
+        }
+        return entry
+    }
+
+    public static func clearToken(
+        deviceId: String,
+        role: String,
+        profile: GatewayDeviceIdentityProfile = .primary)
+    {
+        guard var store = readStore(profile: profile), store.deviceId == deviceId else { return }
+        let normalizedRole = self.normalizeRole(role)
+        guard store.tokens[normalizedRole] != nil else { return }
+        store.tokens.removeValue(forKey: normalizedRole)
+        self.writeStore(store, profile: profile)
+    }
+
+    public static func clearAll(profile: GatewayDeviceIdentityProfile = .primary) {
+        try? FileManager.default.removeItem(at: self.fileURL(profile: profile))
+    }
+
+    private static func normalizeRole(_ role: String) -> String {
+        role.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private static func normalizeScopes(_ scopes: [String]) -> [String] {
+        let trimmed = scopes
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        return Array(Set(trimmed)).sorted()
+    }
+
+    private static func fileURL(profile: GatewayDeviceIdentityProfile) -> URL {
+        DeviceIdentityPaths.stateDirURL()
+            .appendingPathComponent("identity", isDirectory: true)
+            .appendingPathComponent(profile.authFileName, isDirectory: false)
+    }
+
+    private static func readStore(profile: GatewayDeviceIdentityProfile) -> DeviceAuthStoreFile? {
+        let url = self.fileURL(profile: profile)
+        guard let data = try? Data(contentsOf: url) else { return nil }
+        guard let decoded = try? JSONDecoder().decode(DeviceAuthStoreFile.self, from: data) else {
+            return nil
+        }
+        guard decoded.version == 1 else { return nil }
+        return decoded
+    }
+
+    private static func writeStore(_ store: DeviceAuthStoreFile, profile: GatewayDeviceIdentityProfile) {
+        let url = self.fileURL(profile: profile)
+        do {
+            try FileManager.default.createDirectory(
+                at: url.deletingLastPathComponent(),
+                withIntermediateDirectories: true)
+            let data = try JSONEncoder().encode(store)
+            try data.write(to: url, options: [.atomic])
+            try? FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: url.path)
+        } catch {
+            // best-effort only
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/DeviceCommands.swift

@@ -0,0 +1,134 @@
+import Foundation
+
+public enum OpenClawDeviceCommand: String, Codable, Sendable {
+    case status = "device.status"
+    case info = "device.info"
+}
+
+public enum OpenClawBatteryState: String, Codable, Sendable {
+    case unknown
+    case unplugged
+    case charging
+    case full
+}
+
+public enum OpenClawThermalState: String, Codable, Sendable {
+    case nominal
+    case fair
+    case serious
+    case critical
+}
+
+public enum OpenClawNetworkPathStatus: String, Codable, Sendable {
+    case satisfied
+    case unsatisfied
+    case requiresConnection
+}
+
+public enum OpenClawNetworkInterfaceType: String, Codable, Sendable {
+    case wifi
+    case cellular
+    case wired
+    case other
+}
+
+public struct OpenClawBatteryStatusPayload: Codable, Sendable, Equatable {
+    public var level: Double?
+    public var state: OpenClawBatteryState
+    public var lowPowerModeEnabled: Bool
+
+    public init(level: Double?, state: OpenClawBatteryState, lowPowerModeEnabled: Bool) {
+        self.level = level
+        self.state = state
+        self.lowPowerModeEnabled = lowPowerModeEnabled
+    }
+}
+
+public struct OpenClawThermalStatusPayload: Codable, Sendable, Equatable {
+    public var state: OpenClawThermalState
+
+    public init(state: OpenClawThermalState) {
+        self.state = state
+    }
+}
+
+public struct OpenClawStorageStatusPayload: Codable, Sendable, Equatable {
+    public var totalBytes: Int64
+    public var freeBytes: Int64
+    public var usedBytes: Int64
+
+    public init(totalBytes: Int64, freeBytes: Int64, usedBytes: Int64) {
+        self.totalBytes = totalBytes
+        self.freeBytes = freeBytes
+        self.usedBytes = usedBytes
+    }
+}
+
+public struct OpenClawNetworkStatusPayload: Codable, Sendable, Equatable {
+    public var status: OpenClawNetworkPathStatus
+    public var isExpensive: Bool
+    public var isConstrained: Bool
+    public var interfaces: [OpenClawNetworkInterfaceType]
+
+    public init(
+        status: OpenClawNetworkPathStatus,
+        isExpensive: Bool,
+        isConstrained: Bool,
+        interfaces: [OpenClawNetworkInterfaceType])
+    {
+        self.status = status
+        self.isExpensive = isExpensive
+        self.isConstrained = isConstrained
+        self.interfaces = interfaces
+    }
+}
+
+public struct OpenClawDeviceStatusPayload: Codable, Sendable, Equatable {
+    public var battery: OpenClawBatteryStatusPayload
+    public var thermal: OpenClawThermalStatusPayload
+    public var storage: OpenClawStorageStatusPayload
+    public var network: OpenClawNetworkStatusPayload
+    public var uptimeSeconds: Double
+
+    public init(
+        battery: OpenClawBatteryStatusPayload,
+        thermal: OpenClawThermalStatusPayload,
+        storage: OpenClawStorageStatusPayload,
+        network: OpenClawNetworkStatusPayload,
+        uptimeSeconds: Double)
+    {
+        self.battery = battery
+        self.thermal = thermal
+        self.storage = storage
+        self.network = network
+        self.uptimeSeconds = uptimeSeconds
+    }
+}
+
+public struct OpenClawDeviceInfoPayload: Codable, Sendable, Equatable {
+    public var deviceName: String
+    public var modelIdentifier: String
+    public var systemName: String
+    public var systemVersion: String
+    public var appVersion: String
+    public var appBuild: String
+    public var locale: String
+
+    public init(
+        deviceName: String,
+        modelIdentifier: String,
+        systemName: String,
+        systemVersion: String,
+        appVersion: String,
+        appBuild: String,
+        locale: String)
+    {
+        self.deviceName = deviceName
+        self.modelIdentifier = modelIdentifier
+        self.systemName = systemName
+        self.systemVersion = systemVersion
+        self.appVersion = appVersion
+        self.appBuild = appBuild
+        self.locale = locale
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/DeviceIdentity.swift

@@ -0,0 +1,297 @@
+import CryptoKit
+import Foundation
+
+public enum GatewayDeviceIdentityProfile: String, Sendable {
+    case primary
+    case node
+    case shareExtension
+
+    var identityFileName: String {
+        switch self {
+        case .primary:
+            "device.json"
+        case .node:
+            "node-device.json"
+        case .shareExtension:
+            "share-device.json"
+        }
+    }
+
+    var authFileName: String {
+        switch self {
+        case .primary:
+            "device-auth.json"
+        case .node:
+            "node-device-auth.json"
+        case .shareExtension:
+            "share-device-auth.json"
+        }
+    }
+}
+
+public struct DeviceIdentity: Codable, Sendable {
+    public var deviceId: String
+    public var publicKey: String
+    public var privateKey: String
+    public var createdAtMs: Int
+
+    public init(deviceId: String, publicKey: String, privateKey: String, createdAtMs: Int) {
+        self.deviceId = deviceId
+        self.publicKey = publicKey
+        self.privateKey = privateKey
+        self.createdAtMs = createdAtMs
+    }
+}
+
+enum DeviceIdentityPaths {
+    private static let stateDirEnv = ["OPENCLAW_STATE_DIR"]
+
+    static func stateDirURL() -> URL {
+        self.stateDirURL(
+            overrideURL: self.stateDirOverrideURL(),
+            legacyStateDirURL: self.legacyStateDirURL(),
+            appGroupStateDirURL: self.appGroupStateDirURL(),
+            temporaryDirectory: FileManager.default.temporaryDirectory)
+    }
+
+    static func stateDirURL(
+        overrideURL: URL?,
+        legacyStateDirURL: URL?,
+        appGroupStateDirURL: URL?,
+        temporaryDirectory: URL) -> URL
+    {
+        if let overrideURL {
+            return overrideURL
+        }
+        if let appGroupStateDirURL {
+            return appGroupStateDirURL
+        }
+        if let legacyStateDirURL {
+            return legacyStateDirURL
+        }
+        return temporaryDirectory.appendingPathComponent("openclaw", isDirectory: true)
+    }
+
+    private static func stateDirOverrideURL() -> URL? {
+        for key in self.stateDirEnv {
+            if let raw = getenv(key) {
+                let value = String(cString: raw).trimmingCharacters(in: .whitespacesAndNewlines)
+                if !value.isEmpty {
+                    return URL(fileURLWithPath: value, isDirectory: true)
+                }
+            }
+        }
+        return nil
+    }
+
+    private static func legacyStateDirURL() -> URL? {
+        if let appSupport = FileManager.default.urls(for: .applicationSupportDirectory, in: .userDomainMask).first {
+            return appSupport.appendingPathComponent("OpenClaw", isDirectory: true)
+        }
+        return nil
+    }
+
+    private static func appGroupStateDirURL() -> URL? {
+        guard
+            let containerURL = FileManager.default
+                .containerURL(forSecurityApplicationGroupIdentifier: OpenClawAppGroup.identifier)
+        else {
+            return nil
+        }
+        return containerURL.appendingPathComponent("OpenClaw", isDirectory: true)
+    }
+}
+
+public enum DeviceIdentityStore {
+    private static let ed25519SPKIPrefix = Data([
+        0x30, 0x2A, 0x30, 0x05, 0x06, 0x03, 0x2B, 0x65,
+        0x70, 0x03, 0x21, 0x00,
+    ])
+    private static let ed25519PKCS8PrivatePrefix = Data([
+        0x30, 0x2E, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06,
+        0x03, 0x2B, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+    ])
+
+    public static func loadOrCreate() -> DeviceIdentity {
+        self.loadOrCreate(profile: .primary)
+    }
+
+    public static func loadOrCreate(profile: GatewayDeviceIdentityProfile) -> DeviceIdentity {
+        self.loadOrCreate(fileURL: self.fileURL(profile: profile))
+    }
+
+    static func loadOrCreate(fileURL url: URL) -> DeviceIdentity {
+        if let data = try? Data(contentsOf: url) {
+            switch self.decodeStoredIdentity(data) {
+            case let .identity(decoded):
+                return decoded
+            case .recognizedInvalid:
+                return self.generate()
+            case .unknown:
+                break
+            }
+        }
+        let identity = self.generate()
+        self.save(identity, to: url)
+        return identity
+    }
+
+    private enum DecodeResult {
+        case identity(DeviceIdentity)
+        case recognizedInvalid
+        case unknown
+    }
+
+    private static func decodeStoredIdentity(_ data: Data) -> DecodeResult {
+        let decoder = JSONDecoder()
+        if let decoded = try? decoder.decode(DeviceIdentity.self, from: data) {
+            guard let identity = self.normalizedRawIdentity(decoded) else {
+                return .recognizedInvalid
+            }
+            return .identity(identity)
+        }
+
+        if let decoded = try? decoder.decode(PemDeviceIdentity.self, from: data) {
+            guard decoded.version == 1,
+                  let publicKeyData = self.rawPublicKey(fromPEM: decoded.publicKeyPem),
+                  let privateKeyData = self.rawPrivateKey(fromPEM: decoded.privateKeyPem),
+                  self.keyPairMatches(publicKeyData: publicKeyData, privateKeyData: privateKeyData)
+            else {
+                return .recognizedInvalid
+            }
+            return .identity(DeviceIdentity(
+                deviceId: self.deviceId(publicKeyData: publicKeyData),
+                publicKey: publicKeyData.base64EncodedString(),
+                privateKey: privateKeyData.base64EncodedString(),
+                createdAtMs: decoded.createdAtMs))
+        }
+
+        return self.hasRecognizedIdentityShape(data) ? .recognizedInvalid : .unknown
+    }
+
+    public 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 = self.deviceId(publicKeyData: publicKeyData)
+        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: "")
+    }
+
+    public static func publicKeyBase64Url(_ identity: DeviceIdentity) -> String? {
+        guard let data = Data(base64Encoded: identity.publicKey) else { return nil }
+        return self.base64UrlEncode(data)
+    }
+
+    private static func normalizedRawIdentity(_ identity: DeviceIdentity) -> DeviceIdentity? {
+        guard !identity.deviceId.isEmpty,
+              let publicKeyData = Data(base64Encoded: identity.publicKey),
+              let privateKeyData = Data(base64Encoded: identity.privateKey)
+        else { return nil }
+
+        guard publicKeyData.count == 32, privateKeyData.count == 32,
+              self.keyPairMatches(publicKeyData: publicKeyData, privateKeyData: privateKeyData)
+        else { return nil }
+        return DeviceIdentity(
+            deviceId: self.deviceId(publicKeyData: publicKeyData),
+            publicKey: identity.publicKey,
+            privateKey: identity.privateKey,
+            createdAtMs: identity.createdAtMs)
+    }
+
+    private static func rawPublicKey(fromPEM pem: String) -> Data? {
+        guard let der = self.derData(fromPEM: pem),
+              der.count == self.ed25519SPKIPrefix.count + 32,
+              der.prefix(self.ed25519SPKIPrefix.count) == self.ed25519SPKIPrefix
+        else { return nil }
+        return der.suffix(32)
+    }
+
+    private static func rawPrivateKey(fromPEM pem: String) -> Data? {
+        guard let der = self.derData(fromPEM: pem),
+              der.count == self.ed25519PKCS8PrivatePrefix.count + 32,
+              der.prefix(self.ed25519PKCS8PrivatePrefix.count) == self.ed25519PKCS8PrivatePrefix
+        else { return nil }
+        return der.suffix(32)
+    }
+
+    private static func keyPairMatches(publicKeyData: Data, privateKeyData: Data) -> Bool {
+        guard let privateKey = try? Curve25519.Signing.PrivateKey(rawRepresentation: privateKeyData)
+        else {
+            return false
+        }
+        return privateKey.publicKey.rawRepresentation == publicKeyData
+    }
+
+    private static func derData(fromPEM pem: String) -> Data? {
+        let body = pem
+            .split(whereSeparator: \.isNewline)
+            .filter { !$0.hasPrefix("-----") }
+            .joined()
+        return Data(base64Encoded: body)
+    }
+
+    private static func hasRecognizedIdentityShape(_ data: Data) -> Bool {
+        guard let object = try? JSONSerialization.jsonObject(with: data) as? [String: Any] else {
+            return false
+        }
+        return object.keys.contains("publicKeyPem")
+            || object.keys.contains("privateKeyPem")
+            || object.keys.contains("publicKey")
+            || object.keys.contains("privateKey")
+    }
+
+    private static func deviceId(publicKeyData: Data) -> String {
+        SHA256.hash(data: publicKeyData).compactMap { String(format: "%02x", $0) }.joined()
+    }
+
+    private static func save(_ identity: DeviceIdentity, to url: URL) {
+        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(profile: GatewayDeviceIdentityProfile) -> URL {
+        let base = DeviceIdentityPaths.stateDirURL()
+        return base
+            .appendingPathComponent("identity", isDirectory: true)
+            .appendingPathComponent(profile.identityFileName, isDirectory: false)
+    }
+}
+
+private struct PemDeviceIdentity: Codable {
+    var version: Int
+    var deviceId: String
+    var publicKeyPem: String
+    var privateKeyPem: String
+    var createdAtMs: Int
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ElevenLabsKitShim.swift

@@ -0,0 +1,11 @@
+#if Talk
+@_exported import ElevenLabsKit
+
+public typealias ElevenLabsVoice = ElevenLabsKit.ElevenLabsVoice
+public typealias ElevenLabsTTSRequest = ElevenLabsKit.ElevenLabsTTSRequest
+public typealias ElevenLabsTTSClient = ElevenLabsKit.ElevenLabsTTSClient
+public typealias TalkTTSValidation = ElevenLabsKit.TalkTTSValidation
+public typealias StreamingAudioPlayer = ElevenLabsKit.StreamingAudioPlayer
+public typealias PCMStreamingAudioPlayer = ElevenLabsKit.PCMStreamingAudioPlayer
+public typealias StreamingPlaybackResult = ElevenLabsKit.StreamingPlaybackResult
+#endif

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayConnectChallengeSupport.swift

@@ -0,0 +1,28 @@
+import Foundation
+import OpenClawProtocol
+
+public enum GatewayConnectChallengeSupport {
+    public static func nonce(from payload: [String: OpenClawProtocol.AnyCodable]?) -> String? {
+        guard let nonce = payload?["nonce"]?.value as? String else { return nil }
+        let trimmed = nonce.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return nil }
+        return trimmed
+    }
+
+    public static func waitForNonce(
+        timeoutSeconds: Double,
+        onTimeout: @escaping @Sendable () -> some Error,
+        receiveNonce: @escaping @Sendable () async throws -> String?) async throws -> String
+    {
+        try await AsyncTimeout.withTimeout(
+            seconds: timeoutSeconds,
+            onTimeout: onTimeout,
+            operation: {
+                while true {
+                    if let nonce = try await receiveNonce() {
+                        return nonce
+                    }
+                }
+            })
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayConnectionProblem.swift

@@ -0,0 +1,965 @@
+import Foundation
+
+public struct GatewayConnectionProblem: Equatable, Sendable {
+    public enum Kind: String, Equatable, Sendable {
+        case gatewayAuthTokenMissing
+        case gatewayAuthTokenMismatch
+        case gatewayAuthTokenNotConfigured
+        case gatewayAuthPasswordMissing
+        case gatewayAuthPasswordMismatch
+        case gatewayAuthPasswordNotConfigured
+        case bootstrapTokenInvalid
+        case deviceTokenMismatch
+        case deviceTokenScopeMismatch
+        case pairingRequired
+        case pairingRoleUpgradeRequired
+        case pairingScopeUpgradeRequired
+        case pairingMetadataUpgradeRequired
+        case protocolMismatch
+        case deviceIdentityRequired
+        case deviceSignatureExpired
+        case deviceNonceRequired
+        case deviceNonceMismatch
+        case deviceSignatureInvalid
+        case devicePublicKeyInvalid
+        case deviceIdMismatch
+        case tailscaleIdentityMissing
+        case tailscaleProxyMissing
+        case tailscaleWhoisFailed
+        case tailscaleIdentityMismatch
+        case authRateLimited
+        case timeout
+        case connectionRefused
+        case reachabilityFailed
+        case websocketCancelled
+        case tlsPinMismatch
+        case tlsCertificateUntrusted
+        case tlsCertificateUnavailable
+        case unknown
+    }
+
+    public enum Owner: String, Equatable, Sendable {
+        case gateway
+        case iphone
+        case both
+        case network
+        case unknown
+    }
+
+    public let kind: Kind
+    public let owner: Owner
+    public let title: String
+    public let message: String
+    public let actionLabel: String?
+    public let actionCommand: String?
+    public let docsURL: URL?
+    public let requestId: String?
+    public let retryable: Bool
+    public let pauseReconnect: Bool
+    public let technicalDetails: String?
+    public let tlsStoreKey: String?
+    public let tlsExpectedFingerprint: String?
+    public let tlsObservedFingerprint: String?
+    public let tlsSystemTrustOk: Bool
+
+    public init(
+        kind: Kind,
+        owner: Owner,
+        title: String,
+        message: String,
+        actionLabel: String? = nil,
+        actionCommand: String? = nil,
+        docsURL: URL? = nil,
+        requestId: String? = nil,
+        retryable: Bool,
+        pauseReconnect: Bool,
+        technicalDetails: String? = nil,
+        tlsStoreKey: String? = nil,
+        tlsExpectedFingerprint: String? = nil,
+        tlsObservedFingerprint: String? = nil,
+        tlsSystemTrustOk: Bool = false)
+    {
+        self.kind = kind
+        self.owner = owner
+        self.title = title
+        self.message = message
+        self.actionLabel = Self.trimmedOrNil(actionLabel)
+        self.actionCommand = Self.trimmedOrNil(actionCommand)
+        self.docsURL = docsURL
+        self.requestId = Self.trimmedOrNil(requestId)
+        self.retryable = retryable
+        self.pauseReconnect = pauseReconnect
+        self.technicalDetails = Self.trimmedOrNil(technicalDetails)
+        self.tlsStoreKey = Self.trimmedOrNil(tlsStoreKey)
+        self.tlsExpectedFingerprint = Self.trimmedOrNil(tlsExpectedFingerprint)
+        self.tlsObservedFingerprint = Self.trimmedOrNil(tlsObservedFingerprint)
+        self.tlsSystemTrustOk = tlsSystemTrustOk
+    }
+
+    public var needsPairingApproval: Bool {
+        switch self.kind {
+        case .pairingRequired, .pairingRoleUpgradeRequired, .pairingScopeUpgradeRequired,
+             .pairingMetadataUpgradeRequired, .deviceTokenScopeMismatch:
+            true
+        default:
+            false
+        }
+    }
+
+    public var needsCredentialUpdate: Bool {
+        switch self.kind {
+        case .gatewayAuthTokenMissing,
+             .gatewayAuthTokenMismatch,
+             .gatewayAuthTokenNotConfigured,
+             .gatewayAuthPasswordMissing,
+             .gatewayAuthPasswordMismatch,
+             .gatewayAuthPasswordNotConfigured,
+             .bootstrapTokenInvalid,
+             .deviceTokenMismatch:
+            true
+        default:
+            false
+        }
+    }
+
+    public var suggestsOnboardingReset: Bool {
+        self.kind == .gatewayAuthTokenMismatch
+    }
+
+    public var statusText: String {
+        switch self.kind {
+        case .pairingRequired, .pairingRoleUpgradeRequired, .pairingScopeUpgradeRequired,
+             .pairingMetadataUpgradeRequired, .protocolMismatch:
+            if let requestId {
+                return "\(self.title) (request ID: \(requestId))"
+            }
+            return self.title
+        default:
+            return self.title
+        }
+    }
+
+    public var canTrustRotatedCertificate: Bool {
+        self.kind == .tlsPinMismatch
+            && self.tlsSystemTrustOk
+            && self.tlsStoreKey != nil
+            && self.tlsObservedFingerprint != nil
+    }
+
+    private static func trimmedOrNil(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}
+
+public enum GatewayConnectionProblemMapper {
+    public static func map(
+        error: Error,
+        preserving previousProblem: GatewayConnectionProblem? = nil) -> GatewayConnectionProblem?
+    {
+        guard let nextProblem = self.rawMap(error) else {
+            return nil
+        }
+        guard let previousProblem else {
+            return nextProblem
+        }
+        if self.shouldPreserve(previousProblem: previousProblem, over: nextProblem) {
+            return previousProblem
+        }
+        return nextProblem
+    }
+
+    public static func shouldPreserve(
+        previousProblem: GatewayConnectionProblem,
+        over nextProblem: GatewayConnectionProblem) -> Bool
+    {
+        if nextProblem.kind == .websocketCancelled {
+            return previousProblem.pauseReconnect || previousProblem.requestId != nil
+        }
+        return false
+    }
+
+    public static func shouldPreserve(
+        previousProblem: GatewayConnectionProblem,
+        overDisconnectReason reason: String) -> Bool
+    {
+        let normalized = reason.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        guard !normalized.isEmpty else { return false }
+        if normalized.contains("cancelled") || normalized.contains("canceled") {
+            return previousProblem.pauseReconnect || previousProblem.requestId != nil
+        }
+        return false
+    }
+
+    private static func rawMap(_ error: Error) -> GatewayConnectionProblem? {
+        if let authError = error as? GatewayConnectAuthError {
+            return self.map(authError)
+        }
+        if let responseError = error as? GatewayResponseError {
+            return self.map(responseError)
+        }
+        if let tlsError = error as? GatewayTLSValidationError {
+            return self.map(tlsError)
+        }
+        return self.mapTransportError(error)
+    }
+
+    private static func map(_ authError: GatewayConnectAuthError) -> GatewayConnectionProblem {
+        let pairingCommand = self.approvalCommand(requestId: authError.requestId)
+
+        switch authError.detail {
+        case .authTokenMissing:
+            return self.problem(
+                kind: .gatewayAuthTokenMissing,
+                owner: .both,
+                title: authError.titleOverride ?? "Gateway token required",
+                message: authError.userMessageOverride
+                    ?? "This gateway requires an auth token, but this device did not send one.",
+                actionLabel: authError.actionLabel ?? "Open Settings",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/authentication"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authTokenMismatch:
+            return self.problem(
+                kind: .gatewayAuthTokenMismatch,
+                owner: .both,
+                title: authError.titleOverride ?? "Gateway token is out of date",
+                message: authError.userMessageOverride
+                    ?? "The token on this device does not match the gateway token.",
+                actionLabel: authError
+                    .actionLabel ?? (authError.canRetryWithDeviceToken ? "Retry once" : "Update gateway token"),
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/authentication"),
+                requestId: authError.requestId,
+                retryable: authError.retryableOverride ?? authError.canRetryWithDeviceToken,
+                pauseReconnect: authError.pauseReconnectOverride ?? !authError.canRetryWithDeviceToken,
+                authError: authError)
+        case .authTokenNotConfigured:
+            return self.problem(
+                kind: .gatewayAuthTokenNotConfigured,
+                owner: .gateway,
+                title: authError.titleOverride ?? "Gateway token is not configured",
+                message: authError.userMessageOverride
+                    ?? "This gateway is set to token auth, but no gateway token is configured on the gateway.",
+                actionLabel: authError.actionLabel ?? "Fix on gateway",
+                actionCommand: authError.actionCommand ?? "openclaw config set gateway.auth.token <new-token>",
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/authentication"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authPasswordMissing:
+            return self.problem(
+                kind: .gatewayAuthPasswordMissing,
+                owner: .both,
+                title: authError.titleOverride ?? "Gateway password required",
+                message: authError.userMessageOverride
+                    ?? "This gateway requires a password, but this device did not send one.",
+                actionLabel: authError.actionLabel ?? "Open Settings",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/authentication"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authPasswordMismatch:
+            return self.problem(
+                kind: .gatewayAuthPasswordMismatch,
+                owner: .both,
+                title: authError.titleOverride ?? "Gateway password is out of date",
+                message: authError.userMessageOverride
+                    ?? "The saved password on this device does not match the gateway password.",
+                actionLabel: authError.actionLabel ?? "Update password",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/authentication"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authPasswordNotConfigured:
+            return self.problem(
+                kind: .gatewayAuthPasswordNotConfigured,
+                owner: .gateway,
+                title: authError.titleOverride ?? "Gateway password is not configured",
+                message: authError.userMessageOverride
+                    ?? "This gateway is set to password auth, but no gateway password is configured on the gateway.",
+                actionLabel: authError.actionLabel ?? "Fix on gateway",
+                actionCommand: authError.actionCommand ?? "openclaw config set gateway.auth.password <new-password>",
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/authentication"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authBootstrapTokenInvalid:
+            return self.problem(
+                kind: .bootstrapTokenInvalid,
+                owner: .iphone,
+                title: authError.titleOverride ?? "Setup code expired",
+                message: authError.userMessageOverride
+                    ?? "The setup QR or bootstrap token is no longer valid.",
+                actionLabel: authError.actionLabel ?? "Scan QR again",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/platforms/ios"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authDeviceTokenMismatch:
+            return self.problem(
+                kind: .deviceTokenMismatch,
+                owner: .both,
+                title: authError.titleOverride ?? "This device's saved device token is no longer valid",
+                message: authError.userMessageOverride
+                    ?? "The gateway rejected the stored device token for this role.",
+                actionLabel: authError.actionLabel ?? "Repair pairing",
+                actionCommand: authError.actionCommand ?? pairingCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authScopeMismatch:
+            return self.problem(
+                kind: .deviceTokenScopeMismatch,
+                owner: .both,
+                title: authError.titleOverride ?? "Device permissions need approval",
+                message: authError.userMessageOverride
+                    ?? "The gateway accepted this device token but rejected the requested operator scopes.",
+                actionLabel: authError.actionLabel ?? "Review pairing",
+                actionCommand: authError.actionCommand ?? pairingCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .pairingRequired:
+            return self.pairingProblem(for: authError)
+        case .protocolMismatch:
+            return self.protocolMismatchProblem(for: authError)
+        case .controlUiDeviceIdentityRequired, .deviceIdentityRequired:
+            return self.problem(
+                kind: .deviceIdentityRequired,
+                owner: .iphone,
+                title: authError.titleOverride ?? "Secure device identity is required",
+                message: authError.userMessageOverride
+                    ??
+                    "This connection must include a signed device identity before the gateway can bind permissions to this device.",
+                actionLabel: authError.actionLabel ?? "Retry from the app",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/platforms/ios"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .deviceAuthSignatureExpired:
+            return self.problem(
+                kind: .deviceSignatureExpired,
+                owner: .iphone,
+                title: authError.titleOverride ?? "Secure handshake expired",
+                message: authError.userMessageOverride ?? "The device signature is too old to use.",
+                actionLabel: authError.actionLabel ?? "Check device time",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                requestId: authError.requestId,
+                retryable: true,
+                pauseReconnect: true,
+                authError: authError)
+        case .deviceAuthNonceRequired:
+            return self.problem(
+                kind: .deviceNonceRequired,
+                owner: .iphone,
+                title: authError.titleOverride ?? "Secure handshake is incomplete",
+                message: authError.userMessageOverride
+                    ?? "The gateway expected a one-time challenge response, but the nonce was missing.",
+                actionLabel: authError.actionLabel ?? "Retry",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                requestId: authError.requestId,
+                retryable: true,
+                pauseReconnect: true,
+                authError: authError)
+        case .deviceAuthNonceMismatch:
+            return self.problem(
+                kind: .deviceNonceMismatch,
+                owner: .iphone,
+                title: authError.titleOverride ?? "Secure handshake did not match",
+                message: authError.userMessageOverride ?? "The challenge response was stale or mismatched.",
+                actionLabel: authError.actionLabel ?? "Retry",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                requestId: authError.requestId,
+                retryable: true,
+                pauseReconnect: true,
+                authError: authError)
+        case .deviceAuthSignatureInvalid, .deviceAuthInvalid:
+            return self.problem(
+                kind: .deviceSignatureInvalid,
+                owner: .iphone,
+                title: authError.titleOverride ?? "This device identity could not be verified",
+                message: authError.userMessageOverride
+                    ?? "The gateway could not verify the identity this device presented.",
+                actionLabel: authError.actionLabel ?? "Re-pair this device",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .deviceAuthPublicKeyInvalid:
+            return self.problem(
+                kind: .devicePublicKeyInvalid,
+                owner: .iphone,
+                title: authError.titleOverride ?? "This device identity could not be verified",
+                message: authError.userMessageOverride
+                    ?? "The gateway could not verify the public key this device presented.",
+                actionLabel: authError.actionLabel ?? "Re-pair this device",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .deviceAuthDeviceIdMismatch:
+            return self.problem(
+                kind: .deviceIdMismatch,
+                owner: .iphone,
+                title: authError.titleOverride ?? "This device identity could not be verified",
+                message: authError.userMessageOverride
+                    ?? "The gateway rejected the device identity because the device ID did not match.",
+                actionLabel: authError.actionLabel ?? "Re-pair this device",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authTailscaleIdentityMissing:
+            return self.problem(
+                kind: .tailscaleIdentityMissing,
+                owner: .network,
+                title: authError.titleOverride ?? "Tailscale identity check failed",
+                message: authError.userMessageOverride
+                    ?? "This connection expected Tailscale identity headers, but they were not available.",
+                actionLabel: authError.actionLabel ?? "Turn on Tailscale",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/tailscale"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authTailscaleProxyMissing:
+            return self.problem(
+                kind: .tailscaleProxyMissing,
+                owner: .network,
+                title: authError.titleOverride ?? "Tailscale identity check failed",
+                message: authError.userMessageOverride
+                    ?? "The gateway expected a Tailscale auth proxy, but it was not configured.",
+                actionLabel: authError.actionLabel ?? "Review Tailscale setup",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/tailscale"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authTailscaleWhoisFailed:
+            return self.problem(
+                kind: .tailscaleWhoisFailed,
+                owner: .network,
+                title: authError.titleOverride ?? "Tailscale identity check failed",
+                message: authError.userMessageOverride
+                    ?? "The gateway could not verify this Tailscale client identity.",
+                actionLabel: authError.actionLabel ?? "Review Tailscale setup",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/tailscale"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authTailscaleIdentityMismatch:
+            return self.problem(
+                kind: .tailscaleIdentityMismatch,
+                owner: .network,
+                title: authError.titleOverride ?? "Tailscale identity check failed",
+                message: authError.userMessageOverride
+                    ?? "The forwarded Tailscale identity did not match the verified identity.",
+                actionLabel: authError.actionLabel ?? "Review Tailscale setup",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/tailscale"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authRateLimited:
+            return self.problem(
+                kind: .authRateLimited,
+                owner: .gateway,
+                title: authError.titleOverride ?? "Too many failed attempts",
+                message: authError.userMessageOverride
+                    ?? "The gateway is temporarily refusing new auth attempts after repeated failures.",
+                actionLabel: authError.actionLabel ?? "Wait and retry",
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(
+                    authError.docsURLString,
+                    fallback: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                requestId: authError.requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case .authRequired, .authUnauthorized, .none:
+            return self.problem(
+                kind: .unknown,
+                owner: authError.ownerRaw.flatMap { self.owner(from: $0) } ?? .unknown,
+                title: authError.titleOverride ?? "Gateway rejected the connection",
+                message: authError.userMessageOverride ?? authError.message,
+                actionLabel: authError.actionLabel,
+                actionCommand: authError.actionCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: nil),
+                requestId: authError.requestId,
+                retryable: authError.retryableOverride ?? false,
+                pauseReconnect: authError.pauseReconnectOverride ?? authError.isNonRecoverable,
+                authError: authError)
+        }
+    }
+
+    private static func map(_ responseError: GatewayResponseError) -> GatewayConnectionProblem? {
+        let code = responseError.code.trimmingCharacters(in: .whitespacesAndNewlines).uppercased()
+        if code == "NOT_PAIRED" || responseError.detailsReason == "not-paired" {
+            let authError = GatewayConnectAuthError(
+                message: responseError.message,
+                detailCodeRaw: GatewayConnectAuthDetailCode.pairingRequired.rawValue,
+                canRetryWithDeviceToken: false,
+                recommendedNextStepRaw: nil,
+                requestId: self.stringValue(responseError.details["requestId"]?.value),
+                detailsReason: responseError.detailsReason,
+                ownerRaw: nil,
+                titleOverride: nil,
+                userMessageOverride: nil,
+                actionLabel: nil,
+                actionCommand: nil,
+                docsURLString: nil,
+                retryableOverride: nil,
+                pauseReconnectOverride: nil)
+            return self.map(authError)
+        }
+        return nil
+    }
+
+    private static func map(_ tlsError: GatewayTLSValidationError) -> GatewayConnectionProblem {
+        let failure = tlsError.failure
+        switch failure.kind {
+        case .pinMismatch:
+            let trustedSuffix = failure.systemTrustOk
+                ? " The new certificate is trusted by this device; this is commonly caused by certificate rotation."
+                : " This device could not verify the new certificate."
+            return GatewayConnectionProblem(
+                kind: .tlsPinMismatch,
+                owner: failure.systemTrustOk ? .network : .unknown,
+                title: "Gateway certificate changed",
+                message: "The saved TLS certificate pin for \(failure.host) no longer matches the gateway certificate.\(trustedSuffix)",
+                actionLabel: "Review certificate",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: false,
+                pauseReconnect: true,
+                technicalDetails: tlsError.localizedDescription,
+                tlsStoreKey: failure.storeKey,
+                tlsExpectedFingerprint: failure.expectedFingerprint,
+                tlsObservedFingerprint: failure.observedFingerprint,
+                tlsSystemTrustOk: failure.systemTrustOk)
+        case .certificateUnavailable:
+            return GatewayConnectionProblem(
+                kind: .tlsCertificateUnavailable,
+                owner: .network,
+                title: "Gateway certificate unavailable",
+                message: "OpenClaw could not read the gateway certificate for \(failure.host).",
+                actionLabel: "Retry",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: true,
+                pauseReconnect: false,
+                technicalDetails: tlsError.localizedDescription)
+        case .untrustedCertificate:
+            return GatewayConnectionProblem(
+                kind: .tlsCertificateUntrusted,
+                owner: .network,
+                title: "Gateway certificate is not trusted",
+                message: "This device does not trust the TLS certificate presented by \(failure.host).",
+                actionLabel: "Check certificate",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: false,
+                pauseReconnect: true,
+                technicalDetails: tlsError.localizedDescription)
+        }
+    }
+
+    private static func mapTransportError(_ error: Error) -> GatewayConnectionProblem? {
+        let nsError = error as NSError
+        let rawMessage = nsError.userInfo[NSLocalizedDescriptionKey] as? String ?? nsError.localizedDescription
+        let lower = rawMessage.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        if lower.isEmpty {
+            return nil
+        }
+
+        let urlErrorCode = URLError.Code(rawValue: nsError.code)
+        if nsError.domain == URLError.errorDomain {
+            switch urlErrorCode {
+            case .timedOut:
+                return GatewayConnectionProblem(
+                    kind: .timeout,
+                    owner: .network,
+                    title: "Connection timed out",
+                    message: "The gateway did not respond before the connection timed out.",
+                    actionLabel: "Retry",
+                    actionCommand: nil,
+                    docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                    retryable: true,
+                    pauseReconnect: false,
+                    technicalDetails: rawMessage)
+            case .cannotConnectToHost:
+                return GatewayConnectionProblem(
+                    kind: .connectionRefused,
+                    owner: .network,
+                    title: "Gateway refused the connection",
+                    message: "The gateway host was reachable, but it refused the connection.",
+                    actionLabel: "Retry",
+                    actionCommand: nil,
+                    docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                    retryable: true,
+                    pauseReconnect: false,
+                    technicalDetails: rawMessage)
+            case .cannotFindHost, .dnsLookupFailed, .notConnectedToInternet, .networkConnectionLost,
+                 .internationalRoamingOff, .callIsActive, .dataNotAllowed:
+                return GatewayConnectionProblem(
+                    kind: .reachabilityFailed,
+                    owner: .network,
+                    title: "Gateway is not reachable",
+                    message: "OpenClaw could not reach the gateway over the current network.",
+                    actionLabel: "Check network",
+                    actionCommand: nil,
+                    docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                    retryable: true,
+                    pauseReconnect: false,
+                    technicalDetails: rawMessage)
+            case .cancelled:
+                return GatewayConnectionProblem(
+                    kind: .websocketCancelled,
+                    owner: .network,
+                    title: "Connection interrupted",
+                    message: "The connection to the gateway was interrupted before setup completed.",
+                    actionLabel: "Retry",
+                    actionCommand: nil,
+                    docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                    retryable: true,
+                    pauseReconnect: false,
+                    technicalDetails: rawMessage)
+            default:
+                break
+            }
+        }
+
+        if lower.contains("timed out") {
+            return GatewayConnectionProblem(
+                kind: .timeout,
+                owner: .network,
+                title: "Connection timed out",
+                message: "The gateway did not respond before the connection timed out.",
+                actionLabel: "Retry",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: true,
+                pauseReconnect: false,
+                technicalDetails: rawMessage)
+        }
+        if lower.contains("connection refused") || lower.contains("refused") {
+            return GatewayConnectionProblem(
+                kind: .connectionRefused,
+                owner: .network,
+                title: "Gateway refused the connection",
+                message: "The gateway host was reachable, but it refused the connection.",
+                actionLabel: "Retry",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: true,
+                pauseReconnect: false,
+                technicalDetails: rawMessage)
+        }
+        if lower.contains("cannot find host") || lower.contains("could not connect") || lower
+            .contains("network is unreachable")
+        {
+            return GatewayConnectionProblem(
+                kind: .reachabilityFailed,
+                owner: .network,
+                title: "Gateway is not reachable",
+                message: "OpenClaw could not reach the gateway over the current network.",
+                actionLabel: "Check network",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: true,
+                pauseReconnect: false,
+                technicalDetails: rawMessage)
+        }
+        if lower.contains("cancelled") || lower.contains("canceled") {
+            return GatewayConnectionProblem(
+                kind: .websocketCancelled,
+                owner: .network,
+                title: "Connection interrupted",
+                message: "The connection to the gateway was interrupted before setup completed.",
+                actionLabel: "Retry",
+                actionCommand: nil,
+                docsURL: URL(string: "https://docs.openclaw.ai/gateway/troubleshooting"),
+                retryable: true,
+                pauseReconnect: false,
+                technicalDetails: rawMessage)
+        }
+        return nil
+    }
+
+    private static func pairingProblem(for authError: GatewayConnectAuthError) -> GatewayConnectionProblem {
+        let requestId = authError.requestId
+        let pairingCommand = self.approvalCommand(requestId: requestId)
+
+        switch authError.detailsReason {
+        case "role-upgrade":
+            return self.problem(
+                kind: .pairingRoleUpgradeRequired,
+                owner: .gateway,
+                title: authError.titleOverride ?? "Additional approval required",
+                message: authError.userMessageOverride
+                    ??
+                    "This device is already paired, but it is requesting a new role that was not previously approved.",
+                actionLabel: authError.actionLabel ?? "Approve on gateway",
+                actionCommand: authError.actionCommand ?? pairingCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case "scope-upgrade":
+            return self.problem(
+                kind: .pairingScopeUpgradeRequired,
+                owner: .gateway,
+                title: authError.titleOverride ?? "Additional permissions required",
+                message: authError.userMessageOverride
+                    ?? "This device is already paired, but it is requesting new permissions that require approval.",
+                actionLabel: authError.actionLabel ?? "Approve on gateway",
+                actionCommand: authError.actionCommand ?? pairingCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        case "metadata-upgrade":
+            return self.problem(
+                kind: .pairingMetadataUpgradeRequired,
+                owner: .gateway,
+                title: authError.titleOverride ?? "Device approval needs refresh",
+                message: authError.userMessageOverride
+                    ??
+                    "The gateway detected a change in this device's approved identity metadata and requires re-approval.",
+                actionLabel: authError.actionLabel ?? "Approve on gateway",
+                actionCommand: authError.actionCommand ?? pairingCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        default:
+            return self.problem(
+                kind: .pairingRequired,
+                owner: .gateway,
+                title: authError.titleOverride ?? "This device is not approved yet",
+                message: authError.userMessageOverride
+                    ?? "The gateway received the connection request, but this device must be approved first.",
+                actionLabel: authError.actionLabel ?? "Approve on gateway",
+                actionCommand: authError.actionCommand ?? pairingCommand,
+                docsURL: self.docsURL(authError.docsURLString, fallback: "https://docs.openclaw.ai/gateway/pairing"),
+                requestId: requestId,
+                retryable: false,
+                pauseReconnect: true,
+                authError: authError)
+        }
+    }
+
+    private static func protocolMismatchProblem(for authError: GatewayConnectAuthError) -> GatewayConnectionProblem {
+        let title: String
+        let message: String
+        let owner: GatewayConnectionProblem.Owner
+        let actionLabel: String
+        if let clientMax = authError.clientMaxProtocol,
+           let expected = authError.expectedProtocol,
+           clientMax < expected
+        {
+            title = authError.titleOverride ?? "App update required"
+            message = authError.userMessageOverride
+                ?? "This app is older than the gateway. Update OpenClaw on this device, then retry."
+            owner = .iphone
+            actionLabel = authError.actionLabel ?? "Update app"
+        } else if let clientMin = authError.clientMinProtocol,
+                  let expected = authError.expectedProtocol,
+                  clientMin > expected
+        {
+            title = authError.titleOverride ?? "Gateway update required"
+            message = authError.userMessageOverride
+                ?? "The gateway is older than this app. Update OpenClaw on the gateway host, then retry."
+            owner = .gateway
+            actionLabel = authError.actionLabel ?? "Update gateway"
+        } else {
+            title = authError.titleOverride ?? "OpenClaw update required"
+            message = authError.userMessageOverride
+                ?? "The app and gateway use incompatible protocol versions. Update OpenClaw on both, then retry."
+            owner = .both
+            actionLabel = authError.actionLabel ?? "Update OpenClaw"
+        }
+        return self.problem(
+            kind: .protocolMismatch,
+            owner: owner,
+            title: title,
+            message: message,
+            actionLabel: actionLabel,
+            actionCommand: authError.actionCommand,
+            docsURL: self.docsURL(
+                authError.docsURLString,
+                fallback: "https://docs.openclaw.ai/gateway/troubleshooting"),
+            requestId: authError.requestId,
+            retryable: false,
+            pauseReconnect: true,
+            authError: authError)
+    }
+
+    private static func problem(
+        kind: GatewayConnectionProblem.Kind,
+        owner: GatewayConnectionProblem.Owner,
+        title: String,
+        message: String,
+        actionLabel: String?,
+        actionCommand: String?,
+        docsURL: URL?,
+        requestId: String?,
+        retryable: Bool,
+        pauseReconnect: Bool,
+        authError: GatewayConnectAuthError)
+        -> GatewayConnectionProblem
+    {
+        GatewayConnectionProblem(
+            kind: kind,
+            owner: authError.ownerRaw.flatMap(self.owner(from:)) ?? owner,
+            title: title,
+            message: message,
+            actionLabel: actionLabel,
+            actionCommand: actionCommand,
+            docsURL: docsURL,
+            requestId: requestId,
+            retryable: authError.retryableOverride ?? retryable,
+            pauseReconnect: authError.pauseReconnectOverride ?? pauseReconnect,
+            technicalDetails: self.technicalDetails(for: authError))
+    }
+
+    private static func approvalCommand(requestId: String?) -> String {
+        if let requestId = self.nonEmpty(requestId) {
+            return "openclaw devices approve \(requestId)"
+        }
+        return "openclaw devices list"
+    }
+
+    private static func technicalDetails(for authError: GatewayConnectAuthError) -> String? {
+        var parts: [String] = []
+        if let detail = self.nonEmpty(authError.detailCodeRaw) {
+            parts.append(detail)
+        }
+        if let reason = self.nonEmpty(authError.detailsReason) {
+            parts.append("reason=\(reason)")
+        }
+        if let requestId = self.nonEmpty(authError.requestId) {
+            parts.append("requestId=\(requestId)")
+        }
+        if let nextStep = self.nonEmpty(authError.recommendedNextStepRaw) {
+            parts.append("next=\(nextStep)")
+        }
+        if authError.canRetryWithDeviceToken {
+            parts.append("deviceTokenRetry=true")
+        }
+        if let clientRange = self.protocolRange(min: authError.clientMinProtocol, max: authError.clientMaxProtocol) {
+            parts.append("clientProtocol=\(clientRange)")
+        }
+        if let expected = authError.expectedProtocol {
+            parts.append("gatewayProtocol=\(expected)")
+        }
+        if let minimumProbe = authError.minimumProbeProtocol {
+            parts.append("probeMin=\(minimumProbe)")
+        }
+        return parts.isEmpty ? nil : parts.joined(separator: " · ")
+    }
+
+    private static func protocolRange(min: Int?, max: Int?) -> String? {
+        switch (min, max) {
+        case (nil, nil):
+            nil
+        case let (min?, max?) where min == max:
+            "\(min)"
+        case let (min?, max?):
+            "\(min)-\(max)"
+        case let (min?, nil):
+            "min \(min)"
+        case let (nil, max?):
+            "max \(max)"
+        }
+    }
+
+    private static func docsURL(_ preferred: String?, fallback: String?) -> URL? {
+        if let preferred = self.nonEmpty(preferred), let url = URL(string: preferred) {
+            return url
+        }
+        if let fallback = self.nonEmpty(fallback), let url = URL(string: fallback) {
+            return url
+        }
+        return nil
+    }
+
+    private static func owner(from raw: String) -> GatewayConnectionProblem.Owner? {
+        switch raw.trimmingCharacters(in: .whitespacesAndNewlines).lowercased() {
+        case "gateway":
+            .gateway
+        case "iphone", "ios", "device":
+            .iphone
+        case "both":
+            .both
+        case "network":
+            .network
+        case "unknown", "":
+            .unknown
+        default:
+            nil
+        }
+    }
+
+    private static func stringValue(_ value: Any?) -> String? {
+        self.nonEmpty(value as? String)
+    }
+
+    private static func nonEmpty(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayDiscoveryBrowserSupport.swift

@@ -0,0 +1,32 @@
+import Foundation
+import Network
+
+public enum GatewayDiscoveryBrowserSupport {
+    @MainActor
+    public static func makeBrowser(
+        serviceType: String,
+        domain: String,
+        queueLabelPrefix: String,
+        onState: @escaping @MainActor (NWBrowser.State) -> Void,
+        onResults: @escaping @MainActor (Set<NWBrowser.Result>) -> Void) -> NWBrowser
+    {
+        let params = NWParameters.tcp
+        params.includePeerToPeer = true
+        let browser = NWBrowser(
+            for: .bonjour(type: serviceType, domain: domain),
+            using: params)
+
+        browser.stateUpdateHandler = { state in
+            Task { @MainActor in
+                onState(state)
+            }
+        }
+        browser.browseResultsChangedHandler = { results, _ in
+            Task { @MainActor in
+                onResults(results)
+            }
+        }
+        browser.start(queue: DispatchQueue(label: "\(queueLabelPrefix).\(domain)"))
+        return browser
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayDiscoveryStatusText.swift

@@ -0,0 +1,38 @@
+import Foundation
+import Network
+
+public enum GatewayDiscoveryStatusText {
+    public static func make(states: [NWBrowser.State], hasBrowsers: Bool) -> String {
+        if states.isEmpty {
+            return hasBrowsers ? "Setup" : "Idle"
+        }
+
+        if let failed = states.first(where: { state in
+            if case .failed = state { return true }
+            return false
+        }) {
+            if case let .failed(err) = failed {
+                return "Failed: \(err)"
+            }
+        }
+
+        if let waiting = states.first(where: { state in
+            if case .waiting = state { return true }
+            return false
+        }) {
+            if case let .waiting(err) = waiting {
+                return "Waiting: \(err)"
+            }
+        }
+
+        if states.contains(where: { if case .ready = $0 { true } else { false } }) {
+            return "Searching…"
+        }
+
+        if states.contains(where: { if case .setup = $0 { true } else { false } }) {
+            return "Setup"
+        }
+
+        return "Searching…"
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/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/OpenClawKit/Sources/OpenClawKit/GatewayErrors.swift

@@ -0,0 +1,239 @@
+import Foundation
+import OpenClawProtocol
+
+public enum GatewayConnectAuthDetailCode: String, Sendable {
+    case authRequired = "AUTH_REQUIRED"
+    case authUnauthorized = "AUTH_UNAUTHORIZED"
+    case authTokenMismatch = "AUTH_TOKEN_MISMATCH"
+    case authBootstrapTokenInvalid = "AUTH_BOOTSTRAP_TOKEN_INVALID"
+    case authDeviceTokenMismatch = "AUTH_DEVICE_TOKEN_MISMATCH"
+    case authScopeMismatch = "AUTH_SCOPE_MISMATCH"
+    case authTokenMissing = "AUTH_TOKEN_MISSING"
+    case authTokenNotConfigured = "AUTH_TOKEN_NOT_CONFIGURED"
+    case authPasswordMissing = "AUTH_PASSWORD_MISSING"
+    case authPasswordMismatch = "AUTH_PASSWORD_MISMATCH"
+    case authPasswordNotConfigured = "AUTH_PASSWORD_NOT_CONFIGURED"
+    case authRateLimited = "AUTH_RATE_LIMITED"
+    case authTailscaleIdentityMissing = "AUTH_TAILSCALE_IDENTITY_MISSING"
+    case authTailscaleProxyMissing = "AUTH_TAILSCALE_PROXY_MISSING"
+    case authTailscaleWhoisFailed = "AUTH_TAILSCALE_WHOIS_FAILED"
+    case authTailscaleIdentityMismatch = "AUTH_TAILSCALE_IDENTITY_MISMATCH"
+    case pairingRequired = "PAIRING_REQUIRED"
+    case protocolMismatch = "PROTOCOL_MISMATCH"
+    case controlUiDeviceIdentityRequired = "CONTROL_UI_DEVICE_IDENTITY_REQUIRED"
+    case deviceIdentityRequired = "DEVICE_IDENTITY_REQUIRED"
+    case deviceAuthInvalid = "DEVICE_AUTH_INVALID"
+    case deviceAuthDeviceIdMismatch = "DEVICE_AUTH_DEVICE_ID_MISMATCH"
+    case deviceAuthSignatureExpired = "DEVICE_AUTH_SIGNATURE_EXPIRED"
+    case deviceAuthNonceRequired = "DEVICE_AUTH_NONCE_REQUIRED"
+    case deviceAuthNonceMismatch = "DEVICE_AUTH_NONCE_MISMATCH"
+    case deviceAuthSignatureInvalid = "DEVICE_AUTH_SIGNATURE_INVALID"
+    case deviceAuthPublicKeyInvalid = "DEVICE_AUTH_PUBLIC_KEY_INVALID"
+}
+
+public enum GatewayConnectRecoveryNextStep: String, Sendable {
+    case retryWithDeviceToken = "retry_with_device_token"
+    case updateAuthConfiguration = "update_auth_configuration"
+    case updateAuthCredentials = "update_auth_credentials"
+    case waitThenRetry = "wait_then_retry"
+    case reviewAuthConfiguration = "review_auth_configuration"
+}
+
+/// Structured websocket connect-auth rejection surfaced before the channel is usable.
+public struct GatewayConnectAuthError: LocalizedError, Sendable {
+    public let message: String
+    public let detailCodeRaw: String?
+    public let recommendedNextStepRaw: String?
+    public let canRetryWithDeviceToken: Bool
+    public let requestId: String?
+    public let detailsReason: String?
+    public let ownerRaw: String?
+    public let titleOverride: String?
+    public let userMessageOverride: String?
+    public let actionLabel: String?
+    public let actionCommand: String?
+    public let docsURLString: String?
+    public let retryableOverride: Bool?
+    public let pauseReconnectOverride: Bool?
+    public let clientMinProtocol: Int?
+    public let clientMaxProtocol: Int?
+    public let expectedProtocol: Int?
+    public let minimumProbeProtocol: Int?
+
+    public init(
+        message: String,
+        detailCodeRaw: String?,
+        canRetryWithDeviceToken: Bool,
+        recommendedNextStepRaw: String? = nil,
+        requestId: String? = nil,
+        detailsReason: String? = nil,
+        ownerRaw: String? = nil,
+        titleOverride: String? = nil,
+        userMessageOverride: String? = nil,
+        actionLabel: String? = nil,
+        actionCommand: String? = nil,
+        docsURLString: String? = nil,
+        retryableOverride: Bool? = nil,
+        pauseReconnectOverride: Bool? = nil,
+        clientMinProtocol: Int? = nil,
+        clientMaxProtocol: Int? = nil,
+        expectedProtocol: Int? = nil,
+        minimumProbeProtocol: Int? = nil)
+    {
+        let trimmedMessage = message.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedDetailCode = detailCodeRaw?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let trimmedRecommendedNextStep =
+            recommendedNextStepRaw?.trimmingCharacters(in: .whitespacesAndNewlines)
+        self.message = trimmedMessage.isEmpty ? "gateway connect failed" : trimmedMessage
+        self.detailCodeRaw = trimmedDetailCode?.isEmpty == false ? trimmedDetailCode : nil
+        self.canRetryWithDeviceToken = canRetryWithDeviceToken
+        self.recommendedNextStepRaw =
+            trimmedRecommendedNextStep?.isEmpty == false ? trimmedRecommendedNextStep : nil
+        self.requestId = Self.trimmedOrNil(requestId)
+        self.detailsReason = Self.trimmedOrNil(detailsReason)
+        self.ownerRaw = Self.trimmedOrNil(ownerRaw)
+        self.titleOverride = Self.trimmedOrNil(titleOverride)
+        self.userMessageOverride = Self.trimmedOrNil(userMessageOverride)
+        self.actionLabel = Self.trimmedOrNil(actionLabel)
+        self.actionCommand = Self.trimmedOrNil(actionCommand)
+        self.docsURLString = Self.trimmedOrNil(docsURLString)
+        self.retryableOverride = retryableOverride
+        self.pauseReconnectOverride = pauseReconnectOverride
+        self.clientMinProtocol = clientMinProtocol
+        self.clientMaxProtocol = clientMaxProtocol
+        self.expectedProtocol = expectedProtocol
+        self.minimumProbeProtocol = minimumProbeProtocol
+    }
+
+    public init(
+        message: String,
+        detailCode: String?,
+        canRetryWithDeviceToken: Bool,
+        recommendedNextStep: String? = nil,
+        requestId: String? = nil,
+        detailsReason: String? = nil,
+        ownerRaw: String? = nil,
+        titleOverride: String? = nil,
+        userMessageOverride: String? = nil,
+        actionLabel: String? = nil,
+        actionCommand: String? = nil,
+        docsURLString: String? = nil,
+        retryableOverride: Bool? = nil,
+        pauseReconnectOverride: Bool? = nil,
+        clientMinProtocol: Int? = nil,
+        clientMaxProtocol: Int? = nil,
+        expectedProtocol: Int? = nil,
+        minimumProbeProtocol: Int? = nil)
+    {
+        self.init(
+            message: message,
+            detailCodeRaw: detailCode,
+            canRetryWithDeviceToken: canRetryWithDeviceToken,
+            recommendedNextStepRaw: recommendedNextStep,
+            requestId: requestId,
+            detailsReason: detailsReason,
+            ownerRaw: ownerRaw,
+            titleOverride: titleOverride,
+            userMessageOverride: userMessageOverride,
+            actionLabel: actionLabel,
+            actionCommand: actionCommand,
+            docsURLString: docsURLString,
+            retryableOverride: retryableOverride,
+            pauseReconnectOverride: pauseReconnectOverride,
+            clientMinProtocol: clientMinProtocol,
+            clientMaxProtocol: clientMaxProtocol,
+            expectedProtocol: expectedProtocol,
+            minimumProbeProtocol: minimumProbeProtocol)
+    }
+
+    private static func trimmedOrNil(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    public var detailCode: String? {
+        self.detailCodeRaw
+    }
+
+    public var recommendedNextStepCode: String? {
+        self.recommendedNextStepRaw
+    }
+
+    public var detail: GatewayConnectAuthDetailCode? {
+        guard let detailCodeRaw else { return nil }
+        return GatewayConnectAuthDetailCode(rawValue: detailCodeRaw)
+    }
+
+    public var recommendedNextStep: GatewayConnectRecoveryNextStep? {
+        guard let recommendedNextStepRaw else { return nil }
+        return GatewayConnectRecoveryNextStep(rawValue: recommendedNextStepRaw)
+    }
+
+    public var errorDescription: String? {
+        self.message
+    }
+
+    public var isNonRecoverable: Bool {
+        switch self.detail {
+        case .authTokenMissing,
+             .authBootstrapTokenInvalid,
+             .authTokenNotConfigured,
+             .authPasswordMissing,
+             .authPasswordMismatch,
+             .authPasswordNotConfigured,
+             .authRateLimited,
+             .authScopeMismatch,
+             .pairingRequired,
+             .protocolMismatch,
+             .controlUiDeviceIdentityRequired,
+             .deviceIdentityRequired:
+            true
+        default:
+            false
+        }
+    }
+}
+
+/// 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 detailsReason: String? {
+        let raw = self.details["reason"]?.value as? String
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    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 init(method: String, message: String) {
+        self.method = method
+        self.message = message
+    }
+
+    public var errorDescription: String? {
+        "\(self.method): \(self.message)"
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayNodeSession.swift

@@ -0,0 +1,555 @@
+import Foundation
+import OpenClawProtocol
+import OSLog
+
+private struct NodeInvokeRequestPayload: Codable {
+    var id: String
+    var nodeId: String
+    var command: String
+    var paramsJSON: String?
+    var timeoutMs: Int?
+    var idempotencyKey: String?
+}
+
+func canonicalizeCanvasHostUrl(raw: String?, activeURL: URL?) -> String? {
+    let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    guard !trimmed.isEmpty else { return nil }
+    guard var parsed = URLComponents(string: trimmed) else { return trimmed }
+
+    let parsedHost = parsed.host?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+    let parsedIsLoopback = !parsedHost.isEmpty && LoopbackHost.isLoopback(parsedHost)
+
+    if !parsedHost.isEmpty, !parsedIsLoopback {
+        guard let activeURL else { return trimmed }
+        let isTLS = activeURL.scheme?.lowercased() == "wss"
+        guard isTLS else { return trimmed }
+        parsed.scheme = "https"
+        if parsed.port == nil {
+            let tlsPort = activeURL.port ?? 443
+            parsed.port = (tlsPort == 443) ? nil : tlsPort
+        }
+        return parsed.string ?? trimmed
+    }
+
+    guard let activeURL, let fallbackHost = activeURL.host, !LoopbackHost.isLoopback(fallbackHost) else {
+        return trimmed
+    }
+    let isTLS = activeURL.scheme?.lowercased() == "wss"
+    parsed.scheme = isTLS ? "https" : "http"
+    parsed.host = fallbackHost
+    let fallbackPort = activeURL.port ?? (isTLS ? 443 : 80)
+    parsed.port = ((isTLS && fallbackPort == 443) || (!isTLS && fallbackPort == 80)) ? nil : fallbackPort
+    return parsed.string ?? trimmed
+}
+
+public actor GatewayNodeSession {
+    private let logger = Logger(subsystem: "ai.openclaw", category: "node.gateway")
+    private let decoder = JSONDecoder()
+    private let encoder = JSONEncoder()
+    private static let defaultInvokeTimeoutMs = 30000
+    private var channel: GatewayChannelActor?
+    private var activeURL: URL?
+    private var activeToken: String?
+    private var activeBootstrapToken: String?
+    private var activePassword: String?
+    private var activeConnectOptionsKey: String?
+    private var activeSessionIdentity: ObjectIdentifier?
+    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 hasEverConnected = false
+    private var hasNotifiedConnected = false
+    private var snapshotReceived = false
+    private var snapshotWaiters: [CheckedContinuation<Bool, Never>] = []
+
+    static func invokeWithTimeout(
+        request: BridgeInvokeRequest,
+        timeoutMs: Int?,
+        onInvoke: @escaping @Sendable (BridgeInvokeRequest) async -> BridgeInvokeResponse) async -> BridgeInvokeResponse
+    {
+        let timeoutLogger = Logger(subsystem: "ai.openclaw", category: "node.gateway")
+        let timeout: Int = {
+            if let timeoutMs { return max(0, timeoutMs) }
+            return Self.defaultInvokeTimeoutMs
+        }()
+        guard timeout > 0 else {
+            return await onInvoke(request)
+        }
+
+        // Use an explicit latch so timeouts win even if onInvoke blocks (e.g., permission prompts).
+        final class InvokeLatch: @unchecked Sendable {
+            private let lock = NSLock()
+            private var continuation: CheckedContinuation<BridgeInvokeResponse, Never>?
+            private var resumed = false
+
+            func setContinuation(_ continuation: CheckedContinuation<BridgeInvokeResponse, Never>) {
+                self.lock.lock()
+                defer { self.lock.unlock() }
+                self.continuation = continuation
+            }
+
+            func resume(_ response: BridgeInvokeResponse) {
+                let cont: CheckedContinuation<BridgeInvokeResponse, Never>?
+                self.lock.lock()
+                if self.resumed {
+                    self.lock.unlock()
+                    return
+                }
+                self.resumed = true
+                cont = self.continuation
+                self.continuation = nil
+                self.lock.unlock()
+                cont?.resume(returning: response)
+            }
+        }
+
+        let latch = InvokeLatch()
+        var onInvokeTask: Task<Void, Never>?
+        var timeoutTask: Task<Void, Never>?
+        defer {
+            onInvokeTask?.cancel()
+            timeoutTask?.cancel()
+        }
+        let response = await withCheckedContinuation { (cont: CheckedContinuation<BridgeInvokeResponse, Never>) in
+            latch.setContinuation(cont)
+            onInvokeTask = Task.detached {
+                let result = await onInvoke(request)
+                latch.resume(result)
+            }
+            timeoutTask = Task.detached {
+                do {
+                    try await Task.sleep(nanoseconds: UInt64(timeout) * 1_000_000)
+                } catch {
+                    // Expected when invoke finishes first and cancels the timeout task.
+                    return
+                }
+                guard !Task.isCancelled else { return }
+                timeoutLogger.info("node invoke timeout fired id=\(request.id, privacy: .public)")
+                latch.resume(BridgeInvokeResponse(
+                    id: request.id,
+                    ok: false,
+                    error: OpenClawNodeError(
+                        code: .unavailable,
+                        message: "node invoke timed out")))
+            }
+        }
+        timeoutLogger
+            .info("node invoke race resolved id=\(request.id, privacy: .public) ok=\(response.ok, privacy: .public)")
+        return response
+    }
+
+    private var serverEventSubscribers: [UUID: AsyncStream<EventFrame>.Continuation] = [:]
+    private var pluginSurfaceUrls: [String: String] = [:]
+
+    private struct PluginSurfaceRefreshResponse: Decodable {
+        let pluginSurfaceUrls: [String: AnyCodable]?
+    }
+
+    public init() {}
+
+    private func connectOptionsKey(_ options: GatewayConnectOptions) -> String {
+        func sorted(_ values: [String]) -> String {
+            values.map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+                .filter { !$0.isEmpty }
+                .sorted()
+                .joined(separator: ",")
+        }
+        let role = options.role.trimmingCharacters(in: .whitespacesAndNewlines)
+        let scopes = sorted(options.scopes)
+        let caps = sorted(options.caps)
+        let commands = sorted(options.commands)
+        let clientId = options.clientId.trimmingCharacters(in: .whitespacesAndNewlines)
+        let clientMode = options.clientMode.trimmingCharacters(in: .whitespacesAndNewlines)
+        let clientDisplayName = (options.clientDisplayName ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        let deviceIdentityProfile = options.deviceIdentityProfile.rawValue
+        let includeDeviceIdentity = options.includeDeviceIdentity ? "1" : "0"
+        let permissions = options.permissions
+            .map { key, value in
+                let trimmed = key.trimmingCharacters(in: .whitespacesAndNewlines)
+                return "\(trimmed)=\(value ? "1" : "0")"
+            }
+            .sorted()
+            .joined(separator: ",")
+
+        return [
+            role,
+            scopes,
+            caps,
+            commands,
+            clientId,
+            clientMode,
+            clientDisplayName,
+            deviceIdentityProfile,
+            includeDeviceIdentity,
+            permissions,
+        ].joined(separator: "|")
+    }
+
+    public func connect(
+        url: URL,
+        token: String?,
+        bootstrapToken: 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 nextOptionsKey = self.connectOptionsKey(connectOptions)
+        let nextSessionIdentity = sessionBox.map { ObjectIdentifier($0.session) }
+        let shouldReconnect = self.activeURL != url ||
+            self.activeToken != token ||
+            self.activeBootstrapToken != bootstrapToken ||
+            self.activePassword != password ||
+            self.activeConnectOptionsKey != nextOptionsKey ||
+            self.activeSessionIdentity != nextSessionIdentity ||
+            self.channel == nil
+
+        self.connectOptions = connectOptions
+        self.onConnected = onConnected
+        self.onDisconnected = onDisconnected
+        self.onInvoke = onInvoke
+
+        if shouldReconnect {
+            self.resetConnectionState()
+            if let existing = self.channel {
+                await existing.shutdown()
+            }
+            let channel = GatewayChannelActor(
+                url: url,
+                token: token,
+                bootstrapToken: bootstrapToken,
+                password: password,
+                session: sessionBox,
+                pushHandler: { [weak self] push in
+                    await self?.handlePush(push)
+                },
+                connectOptions: connectOptions,
+                disconnectHandler: { [weak self] reason in
+                    await self?.handleChannelDisconnected(reason)
+                })
+            self.channel = channel
+            self.activeURL = url
+            self.activeToken = token
+            self.activeBootstrapToken = bootstrapToken
+            self.activePassword = password
+            self.activeConnectOptionsKey = nextOptionsKey
+            self.activeSessionIdentity = nextSessionIdentity
+        }
+
+        guard let channel = self.channel else {
+            throw NSError(domain: "Gateway", code: 0, userInfo: [
+                NSLocalizedDescriptionKey: "gateway channel unavailable",
+            ])
+        }
+
+        do {
+            try await channel.connect()
+            _ = await self.waitForSnapshot(timeoutMs: 500)
+            await self.notifyConnectedIfNeeded()
+        } catch {
+            throw error
+        }
+    }
+
+    public func disconnect() async {
+        await self.channel?.shutdown()
+        self.channel = nil
+        self.activeURL = nil
+        self.activeToken = nil
+        self.activeBootstrapToken = nil
+        self.activePassword = nil
+        self.activeConnectOptionsKey = nil
+        self.activeSessionIdentity = nil
+        self.hasEverConnected = false
+        self.resetConnectionState()
+    }
+
+    public func currentCanvasHostUrl() -> String? {
+        self.pluginSurfaceUrls["canvas"]
+    }
+
+    @discardableResult
+    public func refreshPluginSurfaceUrl(surface: String, timeoutSeconds: Int = 8) async -> String? {
+        guard let channel = self.channel else { return nil }
+        let trimmedSurface = surface.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmedSurface.isEmpty else { return nil }
+
+        return await self.requestPluginSurfaceRefresh(
+            channel: channel,
+            method: "node.pluginSurface.refresh",
+            params: ["surface": AnyCodable(trimmedSurface)],
+            surface: trimmedSurface,
+            timeoutSeconds: timeoutSeconds)
+    }
+
+    @discardableResult
+    public func refreshCanvasHostUrl(timeoutSeconds: Int = 8) async -> String? {
+        await self.refreshPluginSurfaceUrl(surface: "canvas", timeoutSeconds: timeoutSeconds)
+    }
+
+    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: AnyCodable] = [
+            "event": AnyCodable(event),
+            "payloadJSON": AnyCodable(payloadJSON ?? NSNull()),
+        ]
+        do {
+            try await channel.send(method: "node.event", params: params)
+        } catch {
+            self.logger.error("node event failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    public func send(method: String, paramsJSON: String?) async throws {
+        guard let channel = self.channel else {
+            throw NSError(domain: "Gateway", code: 11, userInfo: [
+                NSLocalizedDescriptionKey: "not connected",
+            ])
+        }
+
+        let params = try self.decodeParamsJSON(paramsJSON)
+        try await channel.send(method: method, params: params)
+    }
+
+    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):
+            self.pluginSurfaceUrls = self.normalizePluginSurfaceUrls(ok.pluginsurfaceurls)
+            if self.hasEverConnected {
+                self.broadcastServerEvent(
+                    EventFrame(type: "event", event: "seqGap", payload: nil, seq: nil, stateversion: nil))
+            }
+            self.hasEverConnected = true
+            self.markSnapshotReceived()
+            await self.notifyConnectedIfNeeded()
+        case let .event(evt):
+            await self.handleEvent(evt)
+        default:
+            break
+        }
+    }
+
+    private func resetConnectionState() {
+        self.hasNotifiedConnected = false
+        self.snapshotReceived = false
+        self.drainSnapshotWaiters(returning: false)
+    }
+
+    private func handleChannelDisconnected(_ reason: String) async {
+        // The underlying channel can auto-reconnect; resetting state here ensures we surface a fresh
+        // onConnected callback once a new snapshot arrives after reconnect.
+        self.resetConnectionState()
+        await self.onDisconnected?(reason)
+    }
+
+    private func markSnapshotReceived() {
+        self.snapshotReceived = true
+        self.drainSnapshotWaiters(returning: true)
+    }
+
+    private func waitForSnapshot(timeoutMs: Int) async -> Bool {
+        if self.snapshotReceived { return true }
+        let clamped = max(0, timeoutMs)
+        return await withCheckedContinuation { cont in
+            self.snapshotWaiters.append(cont)
+            Task { [weak self] in
+                guard let self else { return }
+                try? await Task.sleep(nanoseconds: UInt64(clamped) * 1_000_000)
+                await self.timeoutSnapshotWaiters()
+            }
+        }
+    }
+
+    private func timeoutSnapshotWaiters() {
+        guard !self.snapshotReceived else { return }
+        self.drainSnapshotWaiters(returning: false)
+    }
+
+    private func drainSnapshotWaiters(returning value: Bool) {
+        if !self.snapshotWaiters.isEmpty {
+            let waiters = self.snapshotWaiters
+            self.snapshotWaiters.removeAll()
+            for waiter in waiters {
+                waiter.resume(returning: value)
+            }
+        }
+    }
+
+    private func notifyConnectedIfNeeded() async {
+        guard !self.hasNotifiedConnected else { return }
+        self.hasNotifiedConnected = true
+        await self.onConnected?()
+    }
+
+    private func normalizeCanvasHostUrl(_ raw: String?) -> String? {
+        canonicalizeCanvasHostUrl(raw: raw, activeURL: self.activeURL)
+    }
+
+    private func normalizePluginSurfaceUrls(_ raw: [String: AnyCodable]?) -> [String: String] {
+        var normalized: [String: String] = [:]
+        if let raw {
+            normalized = raw.compactMapValues { value in
+                self.normalizeCanvasHostUrl(value.value as? String)
+            }
+        }
+        return normalized
+    }
+
+    private func requestPluginSurfaceRefresh(
+        channel: GatewayChannelActor,
+        method: String,
+        params: [String: AnyCodable]?,
+        surface: String,
+        timeoutSeconds: Int) async -> String?
+    {
+        do {
+            let data = try await channel.request(
+                method: method,
+                params: params,
+                timeoutMs: Double(timeoutSeconds * 1000))
+            let decoded = try self.decoder.decode(PluginSurfaceRefreshResponse.self, from: data)
+            let urls = self.normalizePluginSurfaceUrls(decoded.pluginSurfaceUrls)
+            guard let refreshed = urls[surface] else { return nil }
+            self.pluginSurfaceUrls[surface] = refreshed
+            return refreshed
+        } catch {
+            self.logger.debug("\(method, privacy: .public) failed: \(error.localizedDescription, privacy: .public)")
+            return nil
+        }
+    }
+
+    private func handleEvent(_ evt: EventFrame) async {
+        self.broadcastServerEvent(evt)
+        guard evt.event == "node.invoke.request" else { return }
+        self.logger.info("node invoke request received")
+        guard let payload = evt.payload else { return }
+        do {
+            let request = try self.decodeInvokeRequest(from: payload)
+            let timeoutLabel = request.timeoutMs.map(String.init) ?? "none"
+            self.logger.info(
+                "node invoke request decoded id=\(request.id, privacy: .public) command=\(request.command, privacy: .public) timeoutMs=\(timeoutLabel, privacy: .public)")
+            guard let onInvoke else { return }
+            let req = BridgeInvokeRequest(
+                id: request.id,
+                command: request.command,
+                paramsJSON: request.paramsJSON,
+                nodeId: request.nodeId)
+            self.logger.info("node invoke executing id=\(request.id, privacy: .public)")
+            let response = await Self.invokeWithTimeout(
+                request: req,
+                timeoutMs: request.timeoutMs,
+                onInvoke: onInvoke)
+            self.logger.info(
+                "node invoke completed id=\(request.id, privacy: .public) ok=\(response.ok, privacy: .public)")
+            await self.sendInvokeResult(request: request, response: response)
+        } catch {
+            self.logger.error("node invoke decode failed: \(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func decodeInvokeRequest(from payload: OpenClawProtocol.AnyCodable) throws -> NodeInvokeRequestPayload {
+        do {
+            let data = try self.encoder.encode(payload)
+            return try self.decoder.decode(NodeInvokeRequestPayload.self, from: data)
+        } catch {
+            if let raw = payload.value as? String, let data = raw.data(using: .utf8) {
+                return try self.decoder.decode(NodeInvokeRequestPayload.self, from: data)
+            }
+            throw error
+        }
+    }
+
+    private func sendInvokeResult(request: NodeInvokeRequestPayload, response: BridgeInvokeResponse) async {
+        guard let channel = self.channel else { return }
+        self.logger.info(
+            "node invoke result sending id=\(request.id, privacy: .public) ok=\(response.ok, privacy: .public)")
+        var params: [String: AnyCodable] = [
+            "id": AnyCodable(request.id),
+            "nodeId": AnyCodable(request.nodeId),
+            "ok": AnyCodable(response.ok),
+        ]
+        if let payloadJSON = response.payloadJSON {
+            params["payloadJSON"] = AnyCodable(payloadJSON)
+        }
+        if let error = response.error {
+            params["error"] = AnyCodable([
+                "code": error.code.rawValue,
+                "message": error.message,
+            ])
+        }
+        do {
+            try await channel.send(method: "node.invoke.result", params: params)
+        } catch {
+            self.logger.error(
+                "node invoke result failed id=\(request.id, privacy: .public) error=\(error.localizedDescription, privacy: .public)")
+        }
+    }
+
+    private func decodeParamsJSON(
+        _ paramsJSON: String?) throws -> [String: 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] = AnyCodable(entry.value)
+        }
+    }
+
+    private func broadcastServerEvent(_ evt: EventFrame) {
+        for (id, continuation) in self.serverEventSubscribers {
+            if case .terminated = continuation.yield(evt) {
+                self.serverEventSubscribers.removeValue(forKey: id)
+            }
+        }
+    }
+
+    private func removeServerEventSubscriber(_ id: UUID) {
+        self.serverEventSubscribers.removeValue(forKey: id)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayPayloadDecoding.swift

@@ -0,0 +1,20 @@
+import Foundation
+import OpenClawProtocol
+
+public enum GatewayPayloadDecoding {
+    public static func decode<T: Decodable>(
+        _ payload: 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: AnyCodable?,
+        as _: T.Type = T.self) throws -> T?
+    {
+        guard let payload else { return nil }
+        return try self.decode(payload, as: T.self)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/GatewayPush.swift

@@ -0,0 +1,13 @@
+import OpenClawProtocol
+
+/// 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/OpenClawKit/Sources/OpenClawKit/GatewayTLSPinning.swift

@@ -0,0 +1,295 @@
+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 GatewayTLSValidationFailureKind: String, Sendable {
+    case pinMismatch
+    case certificateUnavailable
+    case untrustedCertificate
+}
+
+public struct GatewayTLSValidationFailure: Equatable, Sendable {
+    public let kind: GatewayTLSValidationFailureKind
+    public let host: String
+    public let storeKey: String?
+    public let expectedFingerprint: String?
+    public let observedFingerprint: String?
+    public let systemTrustOk: Bool
+
+    public init(
+        kind: GatewayTLSValidationFailureKind,
+        host: String,
+        storeKey: String?,
+        expectedFingerprint: String?,
+        observedFingerprint: String?,
+        systemTrustOk: Bool)
+    {
+        self.kind = kind
+        self.host = host
+        self.storeKey = storeKey
+        self.expectedFingerprint = expectedFingerprint
+        self.observedFingerprint = observedFingerprint
+        self.systemTrustOk = systemTrustOk
+    }
+}
+
+public struct GatewayTLSValidationError: LocalizedError, Sendable {
+    public let failure: GatewayTLSValidationFailure
+    public let context: String
+
+    public init(failure: GatewayTLSValidationFailure, context: String) {
+        self.failure = failure
+        self.context = context
+    }
+
+    public var errorDescription: String? {
+        let prefix = self.context.trimmingCharacters(in: .whitespacesAndNewlines)
+        switch self.failure.kind {
+        case .pinMismatch:
+            let expected = self.failure.expectedFingerprint ?? "unknown"
+            let observed = self.failure.observedFingerprint ?? "unknown"
+            return "\(prefix): TLS certificate pin mismatch for \(self.failure.host) (expected \(expected), observed \(observed))"
+        case .certificateUnavailable:
+            return "\(prefix): TLS certificate unavailable for \(self.failure.host)"
+        case .untrustedCertificate:
+            return "\(prefix): TLS certificate is not trusted for \(self.failure.host)"
+        }
+    }
+}
+
+public protocol GatewayTLSFailureProviding: AnyObject {
+    func consumeLastTLSFailure() -> GatewayTLSValidationFailure?
+}
+
+public protocol GatewayDeviceTokenRetryTrustProviding: AnyObject {
+    var allowsDeviceTokenRetryAuth: Bool { get }
+}
+
+enum GatewayTLSFirstUsePolicy {
+    static func allowsFirstUsePin(systemTrustOk: Bool) -> Bool {
+        systemTrustOk
+    }
+}
+
+public enum GatewayTLSStore {
+    private static let keychainService = "ai.openclaw.tls-pinning"
+
+    // Legacy UserDefaults location used before Keychain migration.
+    private static let legacySuiteName = "ai.openclaw.shared"
+    private static let legacyKeyPrefix = "gateway.tls."
+
+    public static func loadFingerprint(stableID: String) -> String? {
+        self.migrateFromUserDefaultsIfNeeded(stableID: stableID)
+        let raw = GenericPasswordKeychainStore.loadString(service: self.keychainService, account: stableID)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if raw?.isEmpty == false { return raw }
+        return nil
+    }
+
+    public static func saveFingerprint(_ value: String, stableID: String) {
+        _ = GenericPasswordKeychainStore.saveString(value, service: self.keychainService, account: stableID)
+    }
+
+    @discardableResult
+    public static func replaceFingerprint(_ value: String, stableID: String) -> Bool {
+        guard GenericPasswordKeychainStore.saveString(value, service: self.keychainService, account: stableID) else {
+            return false
+        }
+        self.clearLegacyFingerprint(stableID: stableID)
+        return true
+    }
+
+    @discardableResult
+    public static func clearFingerprint(stableID: String) -> Bool {
+        let removedKeychain = GenericPasswordKeychainStore.delete(
+            service: self.keychainService,
+            account: stableID)
+        self.clearLegacyFingerprint(stableID: stableID)
+        return removedKeychain
+    }
+
+    @discardableResult
+    public static func clearAllFingerprints() -> Bool {
+        let removedKeychain = SecItemDelete([
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: self.keychainService,
+        ] as CFDictionary)
+        self.clearAllLegacyFingerprints()
+        return removedKeychain == errSecSuccess || removedKeychain == errSecItemNotFound
+    }
+
+    // MARK: - Migration
+
+    /// On first Keychain read for a given stableID, move any legacy UserDefaults
+    /// fingerprint into Keychain and remove the old entry.
+    private static func migrateFromUserDefaultsIfNeeded(stableID: String) {
+        guard let defaults = UserDefaults(suiteName: self.legacySuiteName) else { return }
+        let legacyKey = self.legacyKeyPrefix + stableID
+        guard let existing = defaults.string(forKey: legacyKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines),
+            !existing.isEmpty
+        else { return }
+        if GenericPasswordKeychainStore.loadString(service: self.keychainService, account: stableID) == nil {
+            guard GenericPasswordKeychainStore.saveString(existing, service: self.keychainService, account: stableID)
+            else {
+                return
+            }
+        }
+        defaults.removeObject(forKey: legacyKey)
+    }
+
+    private static func clearLegacyFingerprint(stableID: String) {
+        guard let defaults = UserDefaults(suiteName: self.legacySuiteName) else { return }
+        defaults.removeObject(forKey: self.legacyKeyPrefix + stableID)
+    }
+
+    private static func clearAllLegacyFingerprints() {
+        guard let defaults = UserDefaults(suiteName: self.legacySuiteName) else { return }
+        for key in defaults.dictionaryRepresentation().keys where key.hasPrefix(self.legacyKeyPrefix) {
+            defaults.removeObject(forKey: key)
+        }
+    }
+}
+
+public final class GatewayTLSPinningSession: NSObject, WebSocketSessioning, URLSessionDelegate,
+GatewayTLSFailureProviding, GatewayDeviceTokenRetryTrustProviding, @unchecked Sendable {
+    private let params: GatewayTLSParams
+    private let failureLock = NSLock()
+    private var lastTLSFailure: GatewayTLSValidationFailure?
+    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 var allowsDeviceTokenRetryAuth: Bool {
+        self.params.expectedFingerprint?.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty == false
+    }
+
+    public func consumeLastTLSFailure() -> GatewayTLSValidationFailure? {
+        self.failureLock.lock()
+        defer { self.failureLock.unlock() }
+        let failure = self.lastTLSFailure
+        self.lastTLSFailure = nil
+        return failure
+    }
+
+    private func recordTLSFailure(_ failure: GatewayTLSValidationFailure) {
+        self.failureLock.lock()
+        self.lastTLSFailure = failure
+        self.failureLock.unlock()
+    }
+
+    private func clearTLSFailure() {
+        self.failureLock.lock()
+        self.lastTLSFailure = nil
+        self.failureLock.unlock()
+    }
+
+    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 host = challenge.protectionSpace.host
+        let systemTrustOk = SecTrustEvaluateWithError(trust, nil)
+        let expected = self.params.expectedFingerprint.map(normalizeFingerprint)
+        let fingerprint = certificateFingerprint(trust)
+        if let fingerprint {
+            if let expected {
+                if fingerprint == expected {
+                    self.clearTLSFailure()
+                    completionHandler(.useCredential, URLCredential(trust: trust))
+                } else {
+                    self.recordTLSFailure(GatewayTLSValidationFailure(
+                        kind: .pinMismatch,
+                        host: host,
+                        storeKey: self.params.storeKey,
+                        expectedFingerprint: expected,
+                        observedFingerprint: fingerprint,
+                        systemTrustOk: systemTrustOk))
+                    completionHandler(.cancelAuthenticationChallenge, nil)
+                }
+                return
+            }
+            if self.params.allowTOFU {
+                if GatewayTLSFirstUsePolicy.allowsFirstUsePin(systemTrustOk: systemTrustOk) {
+                    if let storeKey = params.storeKey {
+                        GatewayTLSStore.saveFingerprint(fingerprint, stableID: storeKey)
+                    }
+                    self.clearTLSFailure()
+                    completionHandler(.useCredential, URLCredential(trust: trust))
+                    return
+                }
+            }
+        }
+
+        if systemTrustOk || !self.params.required {
+            self.clearTLSFailure()
+            completionHandler(.useCredential, URLCredential(trust: trust))
+        } else {
+            self.recordTLSFailure(GatewayTLSValidationFailure(
+                kind: fingerprint == nil ? .certificateUnavailable : .untrustedCertificate,
+                host: host,
+                storeKey: self.params.storeKey,
+                expectedFingerprint: expected,
+                observedFingerprint: fingerprint,
+                systemTrustOk: false))
+            completionHandler(.cancelAuthenticationChallenge, nil)
+        }
+    }
+}
+
+private func certificateFingerprint(_ trust: SecTrust) -> String? {
+    guard let chain = SecTrustCopyCertificateChain(trust) as? [SecCertificate],
+          let cert = chain.first
+    else {
+        return nil
+    }
+    return sha256Hex(SecCertificateCopyData(cert) as 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 {
+    let stripped = raw.replacingOccurrences(
+        of: #"(?i)^sha-?256\s*:?\s*"#,
+        with: "",
+        options: .regularExpression)
+    return stripped.lowercased().filter(\.isHexDigit)
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/GenericPasswordKeychainStore.swift

@@ -0,0 +1,77 @@
+import Foundation
+import Security
+
+public enum GenericPasswordKeychainStore {
+    public static func loadString(service: String, account: String) -> String? {
+        guard let data = self.loadData(service: service, account: account) else { return nil }
+        return String(data: data, encoding: .utf8)
+    }
+
+    @discardableResult
+    public static func saveString(
+        _ value: String,
+        service: String,
+        account: String,
+        accessible: CFString = kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly) -> Bool
+    {
+        self.saveData(Data(value.utf8), service: service, account: account, accessible: accessible)
+    }
+
+    @discardableResult
+    public static func delete(service: String, account: String) -> Bool {
+        let query = self.baseQuery(service: service, account: account)
+        let status = SecItemDelete(query as CFDictionary)
+        return status == errSecSuccess || status == errSecItemNotFound
+    }
+
+    private static func loadData(service: String, account: String) -> Data? {
+        var query = self.baseQuery(service: service, account: account)
+        query[kSecReturnData as String] = true
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+
+        var item: CFTypeRef?
+        let status = SecItemCopyMatching(query as CFDictionary, &item)
+        guard status == errSecSuccess, let data = item as? Data else { return nil }
+        return data
+    }
+
+    @discardableResult
+    private static func saveData(
+        _ data: Data,
+        service: String,
+        account: String,
+        accessible: CFString) -> Bool
+    {
+        let query = self.baseQuery(service: service, account: account)
+        let previousData = self.loadData(service: service, account: account)
+
+        let deleteStatus = SecItemDelete(query as CFDictionary)
+        guard deleteStatus == errSecSuccess || deleteStatus == errSecItemNotFound else {
+            return false
+        }
+
+        var insert = query
+        insert[kSecValueData as String] = data
+        insert[kSecAttrAccessible as String] = accessible
+        if SecItemAdd(insert as CFDictionary, nil) == errSecSuccess {
+            return true
+        }
+
+        // Best-effort rollback: preserve prior value if replacement fails.
+        guard let previousData else { return false }
+        var rollback = query
+        rollback[kSecValueData as String] = previousData
+        rollback[kSecAttrAccessible as String] = accessible
+        _ = SecItemDelete(query as CFDictionary)
+        _ = SecItemAdd(rollback as CFDictionary, nil)
+        return false
+    }
+
+    private static func baseQuery(service: String, account: String) -> [String: Any] {
+        [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: service,
+            kSecAttrAccount as String: account,
+        ]
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/InstanceIdentity.swift

@@ -0,0 +1,108 @@
+import Foundation
+
+#if canImport(UIKit)
+import UIKit
+#endif
+
+public enum InstanceIdentity {
+    private static let suiteName = "ai.openclaw.shared"
+    private static let instanceIdKey = "instanceId"
+
+    private static var defaults: UserDefaults {
+        UserDefaults(suiteName: suiteName) ?? .standard
+    }
+
+    #if canImport(UIKit)
+    private static func readMainActor<T: Sendable>(_ body: @MainActor () -> T) -> T {
+        if Thread.isMainThread {
+            return MainActor.assumeIsolated { body() }
+        }
+        return DispatchQueue.main.sync {
+            MainActor.assumeIsolated { body() }
+        }
+    }
+    #endif
+
+    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 = Self.readMainActor {
+            UIDevice.current.name.trimmingCharacters(in: .whitespacesAndNewlines)
+        }
+        return name.isEmpty ? "openclaw" : name
+        #else
+        if let name = Host.current().localizedName?.trimmingCharacters(in: .whitespacesAndNewlines),
+           !name.isEmpty
+        {
+            return name
+        }
+        return "openclaw"
+        #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)
+        return Self.readMainActor {
+            switch UIDevice.current.userInterfaceIdiom {
+            case .pad: "iPad"
+            case .phone: "iPhone"
+            default: "iOS"
+            }
+        }
+        #else
+        return "Mac"
+        #endif
+    }()
+
+    public static let platformString: String = {
+        let v = ProcessInfo.processInfo.operatingSystemVersion
+        #if canImport(UIKit)
+        let name = Self.readMainActor {
+            switch UIDevice.current.userInterfaceIdiom {
+            case .pad: "iPadOS"
+            case .phone: "iOS"
+            default: "iOS"
+            }
+        }
+        return "\(name) \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
+        #else
+        return "macOS \(v.majorVersion).\(v.minorVersion).\(v.patchVersion)"
+        #endif
+    }()
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/JPEGTranscoder.swift

@@ -0,0 +1,190 @@
+import CoreGraphics
+import Foundation
+import ImageIO
+import UniformTypeIdentifiers
+
+public enum JPEGTranscodeError: LocalizedError, Sendable {
+    case decodeFailed
+    case propertiesMissing
+    case encodeFailed
+    case sizeLimitExceeded(maxBytes: Int, actualBytes: Int)
+
+    public var errorDescription: String? {
+        switch self {
+        case .decodeFailed:
+            "Failed to decode image data"
+        case .propertiesMissing:
+            "Failed to read image properties"
+        case .encodeFailed:
+            "Failed to encode JPEG"
+        case let .sizeLimitExceeded(maxBytes, actualBytes):
+            "JPEG exceeds size limit (\(actualBytes) bytes > \(maxBytes) bytes)"
+        }
+    }
+}
+
+public struct JPEGTranscoder: Sendable {
+    public static func clampQuality(_ quality: Double) -> Double {
+        min(1.0, max(0.05, quality))
+    }
+
+    /// Re-encodes image data to JPEG, optionally downscaling so that the *oriented* pixel width is <= `maxWidthPx`.
+    ///
+    /// - Important: This normalizes EXIF orientation (the output pixels are rotated if needed; orientation tag is not
+    ///   relied on).
+    public static func transcodeToJPEG(
+        imageData: Data,
+        maxWidthPx: Int?,
+        quality: Double,
+        maxBytes: Int? = nil) throws -> (data: Data, widthPx: Int, heightPx: Int)
+    {
+        try self.transcodeToJPEG(
+            imageData: imageData,
+            maxWidthPx: maxWidthPx,
+            maxLongEdgePx: nil,
+            quality: quality,
+            maxBytes: maxBytes)
+    }
+
+    /// Re-encodes image data to JPEG, optionally downscaling so the *oriented* longest edge is <= `maxLongEdgePx`.
+    ///
+    /// When `maxLongEdgePx` is provided it takes precedence over `maxWidthPx`.
+    /// - Important: This normalizes EXIF orientation (the output pixels are rotated if needed; orientation tag is not
+    ///   relied on).
+    public static func transcodeToJPEG(
+        imageData: Data,
+        maxWidthPx: Int? = nil,
+        maxLongEdgePx: Int?,
+        quality: Double,
+        maxBytes: Int? = nil) throws -> (data: Data, widthPx: Int, heightPx: Int)
+    {
+        guard let src = CGImageSourceCreateWithData(imageData as CFData, nil) else {
+            throw JPEGTranscodeError.decodeFailed
+        }
+        guard
+            let props = CGImageSourceCopyPropertiesAtIndex(src, 0, nil) as? [CFString: Any],
+            let rawWidth = props[kCGImagePropertyPixelWidth] as? NSNumber,
+            let rawHeight = props[kCGImagePropertyPixelHeight] as? NSNumber
+        else {
+            throw JPEGTranscodeError.propertiesMissing
+        }
+
+        let pixelWidth = rawWidth.intValue
+        let pixelHeight = rawHeight.intValue
+        let orientation = (props[kCGImagePropertyOrientation] as? NSNumber)?.intValue ?? 1
+
+        guard pixelWidth > 0, pixelHeight > 0 else {
+            throw JPEGTranscodeError.propertiesMissing
+        }
+
+        let rotates90 = orientation == 5 || orientation == 6 || orientation == 7 || orientation == 8
+        let orientedWidth = rotates90 ? pixelHeight : pixelWidth
+        let orientedHeight = rotates90 ? pixelWidth : pixelHeight
+
+        let maxDim = max(orientedWidth, orientedHeight)
+        var targetMaxPixelSize: Int = {
+            if let maxLongEdgePx, maxLongEdgePx > 0 {
+                guard maxDim > maxLongEdgePx else { return maxDim } // never upscale
+                return maxLongEdgePx
+            }
+            guard let maxWidthPx, maxWidthPx > 0 else { return maxDim }
+            guard orientedWidth > maxWidthPx else { return maxDim } // never upscale
+
+            let scale = Double(maxWidthPx) / Double(orientedWidth)
+            return max(1, Int((Double(maxDim) * scale).rounded(.toNearestOrAwayFromZero)))
+        }()
+
+        func encode(maxPixelSize: Int, quality: Double) throws -> (data: Data, widthPx: Int, heightPx: Int) {
+            let thumbOpts: [CFString: Any] = [
+                kCGImageSourceCreateThumbnailFromImageAlways: true,
+                kCGImageSourceCreateThumbnailWithTransform: true,
+                kCGImageSourceThumbnailMaxPixelSize: maxPixelSize,
+                kCGImageSourceShouldCacheImmediately: true,
+            ]
+
+            guard let img = CGImageSourceCreateThumbnailAtIndex(src, 0, thumbOpts as CFDictionary) else {
+                throw JPEGTranscodeError.decodeFailed
+            }
+            let opaqueImage = Self.flattenAlphaIfNeeded(img)
+
+            let out = NSMutableData()
+            guard let dest = CGImageDestinationCreateWithData(out, UTType.jpeg.identifier as CFString, 1, nil) else {
+                throw JPEGTranscodeError.encodeFailed
+            }
+            let q = self.clampQuality(quality)
+            let encodeProps = [kCGImageDestinationLossyCompressionQuality: q] as CFDictionary
+            CGImageDestinationAddImage(dest, opaqueImage, encodeProps)
+            guard CGImageDestinationFinalize(dest) else {
+                throw JPEGTranscodeError.encodeFailed
+            }
+
+            return (out as Data, opaqueImage.width, opaqueImage.height)
+        }
+
+        guard let maxBytes, maxBytes > 0 else {
+            return try encode(maxPixelSize: targetMaxPixelSize, quality: quality)
+        }
+
+        let minQuality = max(0.2, self.clampQuality(quality) * 0.35)
+        let minPixelSize = 256
+        var best = try encode(maxPixelSize: targetMaxPixelSize, quality: quality)
+        if best.data.count <= maxBytes {
+            return best
+        }
+
+        for _ in 0..<6 {
+            var q = self.clampQuality(quality)
+            for _ in 0..<6 {
+                let candidate = try encode(maxPixelSize: targetMaxPixelSize, quality: q)
+                best = candidate
+                if candidate.data.count <= maxBytes {
+                    return candidate
+                }
+                if q <= minQuality { break }
+                q = max(minQuality, q * 0.75)
+            }
+
+            let nextPixelSize = max(Int(Double(targetMaxPixelSize) * 0.85), minPixelSize)
+            if nextPixelSize == targetMaxPixelSize {
+                break
+            }
+            targetMaxPixelSize = nextPixelSize
+        }
+
+        if best.data.count > maxBytes {
+            throw JPEGTranscodeError.sizeLimitExceeded(maxBytes: maxBytes, actualBytes: best.data.count)
+        }
+
+        return best
+    }
+
+    /// JPEG cannot store alpha. Flatten transparent sources over white before encoding so ImageIO does not composite
+    /// transparent pixels onto black by default.
+    private static func flattenAlphaIfNeeded(_ image: CGImage) -> CGImage {
+        switch image.alphaInfo {
+        case .none, .noneSkipFirst, .noneSkipLast:
+            return image
+        default:
+            break
+        }
+
+        guard
+            let context = CGContext(
+                data: nil,
+                width: image.width,
+                height: image.height,
+                bitsPerComponent: 8,
+                bytesPerRow: 0,
+                space: CGColorSpaceCreateDeviceRGB(),
+                bitmapInfo: CGImageAlphaInfo.noneSkipLast.rawValue)
+        else {
+            return image
+        }
+
+        let rect = CGRect(x: 0, y: 0, width: image.width, height: image.height)
+        context.setFillColor(CGColor(red: 1, green: 1, blue: 1, alpha: 1))
+        context.fill(rect)
+        context.draw(image, in: rect)
+        return context.makeImage() ?? image
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/LocalNetworkURLSupport.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+public enum LocalNetworkURLSupport {
+    public static func isLocalNetworkHTTPURL(_ url: URL) -> Bool {
+        guard let scheme = url.scheme?.lowercased(), scheme == "http" || scheme == "https" else {
+            return false
+        }
+        guard let host = url.host?.trimmingCharacters(in: .whitespacesAndNewlines), !host.isEmpty else {
+            return false
+        }
+        return LoopbackHost.isLocalNetworkHost(host)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/LocationCommands.swift

@@ -0,0 +1,57 @@
+import Foundation
+
+public enum OpenClawLocationCommand: String, Codable, Sendable {
+    case get = "location.get"
+}
+
+public enum OpenClawLocationAccuracy: String, Codable, Sendable {
+    case coarse
+    case balanced
+    case precise
+}
+
+public struct OpenClawLocationGetParams: Codable, Sendable, Equatable {
+    public var timeoutMs: Int?
+    public var maxAgeMs: Int?
+    public var desiredAccuracy: OpenClawLocationAccuracy?
+
+    public init(timeoutMs: Int? = nil, maxAgeMs: Int? = nil, desiredAccuracy: OpenClawLocationAccuracy? = nil) {
+        self.timeoutMs = timeoutMs
+        self.maxAgeMs = maxAgeMs
+        self.desiredAccuracy = desiredAccuracy
+    }
+}
+
+public struct OpenClawLocationPayload: Codable, Sendable, Equatable {
+    public var lat: Double
+    public var lon: Double
+    public var accuracyMeters: Double
+    public var altitudeMeters: Double?
+    public var speedMps: Double?
+    public var headingDeg: Double?
+    public var timestamp: String
+    public var isPrecise: Bool
+    public var source: String?
+
+    public init(
+        lat: Double,
+        lon: Double,
+        accuracyMeters: Double,
+        altitudeMeters: Double? = nil,
+        speedMps: Double? = nil,
+        headingDeg: Double? = nil,
+        timestamp: String,
+        isPrecise: Bool,
+        source: String? = nil)
+    {
+        self.lat = lat
+        self.lon = lon
+        self.accuracyMeters = accuracyMeters
+        self.altitudeMeters = altitudeMeters
+        self.speedMps = speedMps
+        self.headingDeg = headingDeg
+        self.timestamp = timestamp
+        self.isPrecise = isPrecise
+        self.source = source
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/LocationCurrentRequest.swift

@@ -0,0 +1,43 @@
+import CoreLocation
+import Foundation
+
+public enum LocationCurrentRequest {
+    public typealias TimeoutRunner = @Sendable (
+        _ timeoutMs: Int,
+        _ operation: @escaping @Sendable () async throws -> CLLocation) async throws -> CLLocation
+
+    @MainActor
+    public static func resolve(
+        manager: CLLocationManager,
+        desiredAccuracy: OpenClawLocationAccuracy,
+        maxAgeMs: Int?,
+        timeoutMs: Int?,
+        request: @escaping @Sendable () async throws -> CLLocation,
+        withTimeout: TimeoutRunner) async throws -> CLLocation
+    {
+        let now = Date()
+        if let maxAgeMs,
+           let cached = manager.location,
+           now.timeIntervalSince(cached.timestamp) * 1000 <= Double(maxAgeMs)
+        {
+            return cached
+        }
+
+        manager.desiredAccuracy = self.accuracyValue(desiredAccuracy)
+        let timeout = max(0, timeoutMs ?? 10000)
+        return try await withTimeout(timeout) {
+            try await request()
+        }
+    }
+
+    public static func accuracyValue(_ accuracy: OpenClawLocationAccuracy) -> CLLocationAccuracy {
+        switch accuracy {
+        case .coarse:
+            kCLLocationAccuracyKilometer
+        case .balanced:
+            kCLLocationAccuracyHundredMeters
+        case .precise:
+            kCLLocationAccuracyBest
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/LocationServiceSupport.swift

@@ -0,0 +1,49 @@
+import CoreLocation
+import Foundation
+
+@MainActor
+public protocol LocationServiceCommon: AnyObject, CLLocationManagerDelegate {
+    var locationManager: CLLocationManager { get }
+    var locationRequestContinuation: CheckedContinuation<CLLocation, Error>? { get set }
+}
+
+extension LocationServiceCommon {
+    public func configureLocationManager() {
+        self.locationManager.delegate = self
+        self.locationManager.desiredAccuracy = kCLLocationAccuracyBest
+    }
+
+    public func authorizationStatus() -> CLAuthorizationStatus {
+        self.locationManager.authorizationStatus
+    }
+
+    public func accuracyAuthorization() -> CLAccuracyAuthorization {
+        LocationServiceSupport.accuracyAuthorization(manager: self.locationManager)
+    }
+
+    public func requestLocationOnce() async throws -> CLLocation {
+        try await LocationServiceSupport.requestLocation(manager: self.locationManager) { continuation in
+            self.locationRequestContinuation = continuation
+        }
+    }
+}
+
+public enum LocationServiceSupport {
+    public static func accuracyAuthorization(manager: CLLocationManager) -> CLAccuracyAuthorization {
+        if #available(iOS 14.0, macOS 11.0, *) {
+            return manager.accuracyAuthorization
+        }
+        return .fullAccuracy
+    }
+
+    @MainActor
+    public static func requestLocation(
+        manager: CLLocationManager,
+        setContinuation: @escaping (CheckedContinuation<CLLocation, Error>) -> Void) async throws -> CLLocation
+    {
+        try await withCheckedThrowingContinuation { continuation in
+            setContinuation(continuation)
+            manager.requestLocation()
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/LocationSettings.swift

@@ -0,0 +1,7 @@
+import Foundation
+
+public enum OpenClawLocationMode: String, Codable, Sendable, CaseIterable {
+    case off
+    case whileUsing
+    case always
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/LoopbackHost.swift

@@ -0,0 +1,94 @@
+import Foundation
+import Network
+
+public enum LoopbackHost {
+    public static func isLoopback(_ rawHost: String) -> Bool {
+        self.isLoopbackHost(rawHost)
+    }
+
+    public static func isLoopbackHost(_ rawHost: String) -> Bool {
+        var host = rawHost
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+            .trimmingCharacters(in: CharacterSet(charactersIn: "[]"))
+        if host.hasSuffix(".") {
+            host.removeLast()
+        }
+        if let zoneIndex = host.firstIndex(of: "%") {
+            host = String(host[..<zoneIndex])
+        }
+        if host.isEmpty {
+            return false
+        }
+        if host == "localhost" || host == "0.0.0.0" || host == "::" {
+            return true
+        }
+
+        if let ipv4 = IPv4Address(host) {
+            return ipv4.rawValue.first == 127
+        }
+        if let ipv6 = IPv6Address(host) {
+            let bytes = Array(ipv6.rawValue)
+            let isV6Loopback = bytes[0..<15].allSatisfy { $0 == 0 } && bytes[15] == 1
+            if isV6Loopback {
+                return true
+            }
+            let isMappedV4 = bytes[0..<10].allSatisfy { $0 == 0 } && bytes[10] == 0xFF && bytes[11] == 0xFF
+            return isMappedV4 && bytes[12] == 127
+        }
+
+        return false
+    }
+
+    public static func isLocalNetworkHost(_ rawHost: String) -> Bool {
+        let host = self.normalizedHost(rawHost)
+        guard !host.isEmpty else { return false }
+        if self.isLoopbackHost(host) { return true }
+        if host.hasSuffix(".local") { return true }
+        if let ipv4 = self.parseIPv4(host) {
+            return self.isLocalNetworkIPv4(ipv4)
+        }
+        guard let ipv6 = IPv6Address(host) else { return false }
+        let bytes = Array(ipv6.rawValue)
+        let isUniqueLocal = (bytes[0] & 0xFE) == 0xFC
+        let isLinkLocal = bytes[0] == 0xFE && (bytes[1] & 0xC0) == 0x80
+        return isUniqueLocal || isLinkLocal
+    }
+
+    static func normalizedHost(_ rawHost: String) -> String {
+        var host = rawHost
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+            .trimmingCharacters(in: CharacterSet(charactersIn: "[]"))
+        if host.hasSuffix(".") {
+            host.removeLast()
+        }
+        if let zoneIndex = host.firstIndex(of: "%") {
+            host = String(host[..<zoneIndex])
+        }
+        return host
+    }
+
+    static func parseIPv4(_ host: String) -> (UInt8, UInt8, UInt8, UInt8)? {
+        let parts = host.split(separator: ".", omittingEmptySubsequences: false)
+        guard parts.count == 4 else { return nil }
+        let bytes: [UInt8] = parts.compactMap { UInt8($0) }
+        guard bytes.count == 4 else { return nil }
+        return (bytes[0], bytes[1], bytes[2], bytes[3])
+    }
+
+    static func isLocalNetworkIPv4(_ ip: (UInt8, UInt8, UInt8, UInt8)) -> Bool {
+        let (a, b, _, _) = ip
+        // 10.0.0.0/8
+        if a == 10 { return true }
+        // 172.16.0.0/12
+        if a == 172, (16...31).contains(Int(b)) { return true }
+        // 192.168.0.0/16
+        if a == 192, b == 168 { return true }
+        // 127.0.0.0/8
+        if a == 127 { return true }
+        // 169.254.0.0/16 (link-local)
+        if a == 169, b == 254 { return true }
+        return false
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/MotionCommands.swift

@@ -0,0 +1,85 @@
+import Foundation
+
+public enum OpenClawMotionCommand: String, Codable, Sendable {
+    case activity = "motion.activity"
+    case pedometer = "motion.pedometer"
+}
+
+public typealias OpenClawMotionActivityParams = OpenClawDateRangeLimitParams
+
+public struct OpenClawMotionActivityEntry: Codable, Sendable, Equatable {
+    public var startISO: String
+    public var endISO: String
+    public var confidence: String
+    public var isWalking: Bool
+    public var isRunning: Bool
+    public var isCycling: Bool
+    public var isAutomotive: Bool
+    public var isStationary: Bool
+    public var isUnknown: Bool
+
+    public init(
+        startISO: String,
+        endISO: String,
+        confidence: String,
+        isWalking: Bool,
+        isRunning: Bool,
+        isCycling: Bool,
+        isAutomotive: Bool,
+        isStationary: Bool,
+        isUnknown: Bool)
+    {
+        self.startISO = startISO
+        self.endISO = endISO
+        self.confidence = confidence
+        self.isWalking = isWalking
+        self.isRunning = isRunning
+        self.isCycling = isCycling
+        self.isAutomotive = isAutomotive
+        self.isStationary = isStationary
+        self.isUnknown = isUnknown
+    }
+}
+
+public struct OpenClawMotionActivityPayload: Codable, Sendable, Equatable {
+    public var activities: [OpenClawMotionActivityEntry]
+
+    public init(activities: [OpenClawMotionActivityEntry]) {
+        self.activities = activities
+    }
+}
+
+public struct OpenClawPedometerParams: Codable, Sendable, Equatable {
+    public var startISO: String?
+    public var endISO: String?
+
+    public init(startISO: String? = nil, endISO: String? = nil) {
+        self.startISO = startISO
+        self.endISO = endISO
+    }
+}
+
+public struct OpenClawPedometerPayload: Codable, Sendable, Equatable {
+    public var startISO: String
+    public var endISO: String
+    public var steps: Int?
+    public var distanceMeters: Double?
+    public var floorsAscended: Int?
+    public var floorsDescended: Int?
+
+    public init(
+        startISO: String,
+        endISO: String,
+        steps: Int?,
+        distanceMeters: Double?,
+        floorsAscended: Int?,
+        floorsDescended: Int?)
+    {
+        self.startISO = startISO
+        self.endISO = endISO
+        self.steps = steps
+        self.distanceMeters = distanceMeters
+        self.floorsAscended = floorsAscended
+        self.floorsDescended = floorsDescended
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/NetworkInterfaceIPv4.swift

@@ -0,0 +1,43 @@
+import Darwin
+import Foundation
+
+public enum NetworkInterfaceIPv4 {
+    public struct AddressEntry: Sendable {
+        public let name: String
+        public let ip: String
+    }
+
+    public static func addresses() -> [AddressEntry] {
+        var addrList: UnsafeMutablePointer<ifaddrs>?
+        guard getifaddrs(&addrList) == 0, let first = addrList else { return [] }
+        defer { freeifaddrs(addrList) }
+
+        var entries: [AddressEntry] = []
+        for ptr in sequence(first: first, next: { $0.pointee.ifa_next }) {
+            let flags = Int32(ptr.pointee.ifa_flags)
+            let isUp = (flags & IFF_UP) != 0
+            let isLoopback = (flags & IFF_LOOPBACK) != 0
+            let family = ptr.pointee.ifa_addr.pointee.sa_family
+            if !isUp || isLoopback || family != UInt8(AF_INET) { continue }
+
+            var addr = ptr.pointee.ifa_addr.pointee
+            var buffer = [CChar](repeating: 0, count: Int(NI_MAXHOST))
+            let result = getnameinfo(
+                &addr,
+                socklen_t(ptr.pointee.ifa_addr.pointee.sa_len),
+                &buffer,
+                socklen_t(buffer.count),
+                nil,
+                0,
+                NI_NUMERICHOST)
+            guard result == 0 else { continue }
+
+            let len = buffer.prefix { $0 != 0 }
+            let bytes = len.map { UInt8(bitPattern: $0) }
+            guard let ip = String(bytes: bytes, encoding: .utf8) else { continue }
+            let name = String(cString: ptr.pointee.ifa_name)
+            entries.append(AddressEntry(name: name, ip: ip))
+        }
+        return entries
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/NetworkInterfaces.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+public enum NetworkInterfaces {
+    public static func primaryIPv4Address() -> String? {
+        var fallback: String?
+        var en0: String?
+        for entry in NetworkInterfaceIPv4.addresses() {
+            if entry.name == "en0" {
+                en0 = entry.ip
+                break
+            }
+            if fallback == nil { fallback = entry.ip }
+        }
+
+        return en0 ?? fallback
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/NodeError.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+public enum OpenClawNodeErrorCode: String, Codable, Sendable {
+    case notPaired = "NOT_PAIRED"
+    case unauthorized = "UNAUTHORIZED"
+    case backgroundUnavailable = "NODE_BACKGROUND_UNAVAILABLE"
+    case invalidRequest = "INVALID_REQUEST"
+    case unavailable = "UNAVAILABLE"
+}
+
+public struct OpenClawNodeError: Error, Codable, Sendable, Equatable {
+    public var code: OpenClawNodeErrorCode
+    public var message: String
+    public var retryable: Bool?
+    public var retryAfterMs: Int?
+
+    public init(
+        code: OpenClawNodeErrorCode,
+        message: String,
+        retryable: Bool? = nil,
+        retryAfterMs: Int? = nil)
+    {
+        self.code = code
+        self.message = message
+        self.retryable = retryable
+        self.retryAfterMs = retryAfterMs
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/OpenClawAppGroup.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+public enum OpenClawAppGroup {
+    public static let canonicalIdentifier = "group.ai.openclawfoundation.app.shared"
+
+    public static var identifier: String {
+        let raw = Bundle.main.object(forInfoDictionaryKey: "OpenClawAppGroupIdentifier") as? String
+        let trimmed = raw?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return trimmed.isEmpty ? self.canonicalIdentifier : trimmed
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/OpenClawDateRangeLimitParams.swift

@@ -0,0 +1,13 @@
+import Foundation
+
+public struct OpenClawDateRangeLimitParams: Codable, Sendable, Equatable {
+    public var startISO: String?
+    public var endISO: String?
+    public var limit: Int?
+
+    public init(startISO: String? = nil, endISO: String? = nil, limit: Int? = nil) {
+        self.startISO = startISO
+        self.endISO = endISO
+        self.limit = limit
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/OpenClawKitResources.swift

@@ -0,0 +1,83 @@
+import Foundation
+
+public enum OpenClawKitResources {
+    /// Resource bundle for OpenClawKit.
+    ///
+    /// Locates the SwiftPM-generated resource bundle, checking multiple locations:
+    /// 1. Inside Bundle.main (packaged apps)
+    /// 2. Bundle.module (SwiftPM development/tests)
+    /// 3. Falls back to Bundle.main if not found (resource lookups will return nil)
+    ///
+    /// This avoids a fatal crash when Bundle.module can't locate its resources
+    /// in packaged .app bundles where the resource bundle path differs from
+    /// SwiftPM's expectations.
+    public static let bundle: Bundle = locateBundle()
+
+    private static let bundleName = "OpenClawKit_OpenClawKit"
+
+    private static func locateBundle() -> Bundle {
+        // 1. Check inside Bundle.main (packaged apps copy resources here)
+        if let mainResourceURL = Bundle.main.resourceURL {
+            let bundleURL = mainResourceURL.appendingPathComponent("\(self.bundleName).bundle")
+            if let bundle = Bundle(url: bundleURL) {
+                return bundle
+            }
+        }
+
+        // 2. Check Bundle.main directly for embedded resources
+        if Bundle.main.url(forResource: "tool-display", withExtension: "json") != nil {
+            return Bundle.main
+        }
+
+        // 3. Try Bundle.module (works in SwiftPM development/tests)
+        // Wrap in a function to defer the fatalError until actually called
+        if let moduleBundle = loadModuleBundleSafely() {
+            return moduleBundle
+        }
+
+        // 4. Fallback: return Bundle.main (resource lookups will return nil gracefully)
+        return Bundle.main
+    }
+
+    private static func loadModuleBundleSafely() -> Bundle? {
+        // Bundle.module is generated by SwiftPM and will fatalError if not found.
+        // We check likely locations manually to avoid the crash.
+        let candidates: [URL?] = [
+            Bundle.main.resourceURL,
+            Bundle.main.bundleURL,
+            Bundle(for: BundleLocator.self).resourceURL,
+            Bundle(for: BundleLocator.self).bundleURL,
+        ]
+
+        for candidate in candidates {
+            guard let baseURL = candidate else { continue }
+
+            // SwiftPM often places the resource bundle next to (or near) the test runner bundle,
+            // not inside it. Walk up a few levels and check common container paths.
+            var roots: [URL] = []
+            roots.append(baseURL)
+            roots.append(baseURL.appendingPathComponent("Resources"))
+            roots.append(baseURL.appendingPathComponent("Contents/Resources"))
+
+            var current = baseURL
+            for _ in 0..<5 {
+                current = current.deletingLastPathComponent()
+                roots.append(current)
+                roots.append(current.appendingPathComponent("Resources"))
+                roots.append(current.appendingPathComponent("Contents/Resources"))
+            }
+
+            for root in roots {
+                let bundleURL = root.appendingPathComponent("\(self.bundleName).bundle")
+                if let bundle = Bundle(url: bundleURL) {
+                    return bundle
+                }
+            }
+        }
+
+        return nil
+    }
+}
+
+/// Helper class for bundle lookup via Bundle(for:)
+private final class BundleLocator {}

apps/shared/OpenClawKit/Sources/OpenClawKit/PhotoCapture.swift

@@ -0,0 +1,18 @@
+import Foundation
+
+public enum PhotoCapture {
+    public static func transcodeJPEGForGateway(
+        rawData: Data,
+        maxWidthPx: Int,
+        quality: Double,
+        maxPayloadBytes: Int = 5 * 1024 * 1024) throws -> (data: Data, widthPx: Int, heightPx: Int)
+    {
+        // Base64 inflates payloads by ~4/3; cap encoded bytes so the payload stays under maxPayloadBytes (API limit).
+        let maxEncodedBytes = (maxPayloadBytes / 4) * 3
+        return try JPEGTranscoder.transcodeToJPEG(
+            imageData: rawData,
+            maxWidthPx: maxWidthPx,
+            quality: quality,
+            maxBytes: maxEncodedBytes)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/PhotosCommands.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+public enum OpenClawPhotosCommand: String, Codable, Sendable {
+    case latest = "photos.latest"
+}
+
+public struct OpenClawPhotosLatestParams: Codable, Sendable, Equatable {
+    public var limit: Int?
+    public var maxWidth: Int?
+    public var quality: Double?
+
+    public init(limit: Int? = nil, maxWidth: Int? = nil, quality: Double? = nil) {
+        self.limit = limit
+        self.maxWidth = maxWidth
+        self.quality = quality
+    }
+}
+
+public struct OpenClawPhotoPayload: Codable, Sendable, Equatable {
+    public var format: String
+    public var base64: String
+    public var width: Int
+    public var height: Int
+    public var createdAt: String?
+
+    public init(format: String, base64: String, width: Int, height: Int, createdAt: String? = nil) {
+        self.format = format
+        self.base64 = base64
+        self.width = width
+        self.height = height
+        self.createdAt = createdAt
+    }
+}
+
+public struct OpenClawPhotosLatestPayload: Codable, Sendable, Equatable {
+    public var photos: [OpenClawPhotoPayload]
+
+    public init(photos: [OpenClawPhotoPayload]) {
+        self.photos = photos
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/RemindersCommands.swift

@@ -0,0 +1,82 @@
+import Foundation
+
+public enum OpenClawRemindersCommand: String, Codable, Sendable {
+    case list = "reminders.list"
+    case add = "reminders.add"
+}
+
+public enum OpenClawReminderStatusFilter: String, Codable, Sendable {
+    case incomplete
+    case completed
+    case all
+}
+
+public struct OpenClawRemindersListParams: Codable, Sendable, Equatable {
+    public var status: OpenClawReminderStatusFilter?
+    public var limit: Int?
+
+    public init(status: OpenClawReminderStatusFilter? = nil, limit: Int? = nil) {
+        self.status = status
+        self.limit = limit
+    }
+}
+
+public struct OpenClawRemindersAddParams: Codable, Sendable, Equatable {
+    public var title: String
+    public var dueISO: String?
+    public var notes: String?
+    public var listId: String?
+    public var listName: String?
+
+    public init(
+        title: String,
+        dueISO: String? = nil,
+        notes: String? = nil,
+        listId: String? = nil,
+        listName: String? = nil)
+    {
+        self.title = title
+        self.dueISO = dueISO
+        self.notes = notes
+        self.listId = listId
+        self.listName = listName
+    }
+}
+
+public struct OpenClawReminderPayload: Codable, Sendable, Equatable {
+    public var identifier: String
+    public var title: String
+    public var dueISO: String?
+    public var completed: Bool
+    public var listName: String?
+
+    public init(
+        identifier: String,
+        title: String,
+        dueISO: String? = nil,
+        completed: Bool,
+        listName: String? = nil)
+    {
+        self.identifier = identifier
+        self.title = title
+        self.dueISO = dueISO
+        self.completed = completed
+        self.listName = listName
+    }
+}
+
+public struct OpenClawRemindersListPayload: Codable, Sendable, Equatable {
+    public var reminders: [OpenClawReminderPayload]
+
+    public init(reminders: [OpenClawReminderPayload]) {
+        self.reminders = reminders
+    }
+}
+
+public struct OpenClawRemindersAddPayload: Codable, Sendable, Equatable {
+    public var reminder: OpenClawReminderPayload
+
+    public init(reminder: OpenClawReminderPayload) {
+        self.reminder = reminder
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/Resources/CanvasA2UI/index.html

@@ -0,0 +1,311 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>OpenClaw Canvas</title>
+    <script>
+      (() => {
+        const normalizeLower = (value) => {
+          const trimmed = String(value || "").trim();
+          return trimmed.toLocaleLowerCase();
+        };
+        try {
+          const params = new URLSearchParams(window.location.search);
+          const platform = normalizeLower(params.get("platform"));
+          if (platform) {
+            document.documentElement.dataset.platform = platform;
+            return;
+          }
+          if (/android/i.test(navigator.userAgent || "")) {
+            document.documentElement.dataset.platform = "android";
+          }
+        } catch (_) {}
+      })();
+    </script>
+    <style>
+      :root {
+        color-scheme: dark;
+      }
+      @media (prefers-reduced-motion: reduce) {
+        body::before,
+        body::after {
+          animation: none !important;
+        }
+      }
+      html,
+      body {
+        height: 100%;
+        margin: 0;
+      }
+      body {
+        font:
+          14px system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          "Roboto",
+          sans-serif;
+        background:
+          radial-gradient(1200px 900px at 15% 20%, rgba(42, 113, 255, 0.18), rgba(0, 0, 0, 0) 55%),
+          radial-gradient(900px 700px at 85% 30%, rgba(255, 0, 138, 0.14), rgba(0, 0, 0, 0) 60%),
+          radial-gradient(1000px 900px at 60% 90%, rgba(0, 209, 255, 0.1), rgba(0, 0, 0, 0) 60%),
+          #000;
+        color: #e5e7eb;
+        overflow: hidden;
+      }
+      :root[data-platform="android"] body {
+        background:
+          radial-gradient(1200px 900px at 15% 20%, rgba(42, 113, 255, 0.62), rgba(0, 0, 0, 0) 55%),
+          radial-gradient(900px 700px at 85% 30%, rgba(255, 0, 138, 0.52), rgba(0, 0, 0, 0) 60%),
+          radial-gradient(1000px 900px at 60% 90%, rgba(0, 209, 255, 0.48), rgba(0, 0, 0, 0) 60%),
+          #0b1328;
+      }
+      body::before {
+        content: "";
+        position: fixed;
+        inset: -20%;
+        background:
+          repeating-linear-gradient(
+            0deg,
+            rgba(255, 255, 255, 0.03) 0,
+            rgba(255, 255, 255, 0.03) 1px,
+            transparent 1px,
+            transparent 48px
+          ),
+          repeating-linear-gradient(
+            90deg,
+            rgba(255, 255, 255, 0.03) 0,
+            rgba(255, 255, 255, 0.03) 1px,
+            transparent 1px,
+            transparent 48px
+          );
+        transform: translate3d(0, 0, 0) rotate(-7deg);
+        will-change: transform, opacity;
+        -webkit-backface-visibility: hidden;
+        backface-visibility: hidden;
+        opacity: 0.45;
+        pointer-events: none;
+        animation: openclaw-grid-drift 140s ease-in-out infinite alternate;
+      }
+      :root[data-platform="android"] body::before {
+        opacity: 0.8;
+      }
+      body::after {
+        content: "";
+        position: fixed;
+        inset: -35%;
+        background:
+          radial-gradient(900px 700px at 30% 30%, rgba(42, 113, 255, 0.16), rgba(0, 0, 0, 0) 60%),
+          radial-gradient(800px 650px at 70% 35%, rgba(255, 0, 138, 0.12), rgba(0, 0, 0, 0) 62%),
+          radial-gradient(900px 800px at 55% 75%, rgba(0, 209, 255, 0.1), rgba(0, 0, 0, 0) 62%);
+        filter: blur(28px);
+        opacity: 0.52;
+        will-change: transform, opacity;
+        -webkit-backface-visibility: hidden;
+        backface-visibility: hidden;
+        transform: translate3d(0, 0, 0);
+        pointer-events: none;
+        animation: openclaw-glow-drift 110s ease-in-out infinite alternate;
+      }
+      :root[data-platform="android"] body::after {
+        opacity: 0.85;
+      }
+      @supports (mix-blend-mode: screen) {
+        body::after {
+          mix-blend-mode: screen;
+        }
+      }
+      @supports not (mix-blend-mode: screen) {
+        body::after {
+          opacity: 0.7;
+        }
+      }
+      @keyframes openclaw-grid-drift {
+        0% {
+          transform: translate3d(-12px, 8px, 0) rotate(-7deg);
+          opacity: 0.4;
+        }
+        50% {
+          transform: translate3d(10px, -7px, 0) rotate(-6.6deg);
+          opacity: 0.56;
+        }
+        100% {
+          transform: translate3d(-8px, 6px, 0) rotate(-7.2deg);
+          opacity: 0.42;
+        }
+      }
+      @keyframes openclaw-glow-drift {
+        0% {
+          transform: translate3d(-18px, 12px, 0) scale(1.02);
+          opacity: 0.4;
+        }
+        50% {
+          transform: translate3d(14px, -10px, 0) scale(1.05);
+          opacity: 0.52;
+        }
+        100% {
+          transform: translate3d(-10px, 8px, 0) scale(1.03);
+          opacity: 0.43;
+        }
+      }
+      canvas {
+        position: fixed;
+        inset: 0;
+        display: block;
+        width: 100vw;
+        height: 100vh;
+        touch-action: none;
+        z-index: 1;
+      }
+      :root[data-platform="android"] #openclaw-canvas {
+        background:
+          radial-gradient(1100px 800px at 20% 15%, rgba(42, 113, 255, 0.78), rgba(0, 0, 0, 0) 58%),
+          radial-gradient(900px 650px at 82% 28%, rgba(255, 0, 138, 0.66), rgba(0, 0, 0, 0) 62%),
+          radial-gradient(1000px 900px at 60% 88%, rgba(0, 209, 255, 0.58), rgba(0, 0, 0, 0) 62%),
+          #141c33;
+      }
+      #openclaw-status {
+        position: fixed;
+        inset: 0;
+        display: none;
+        align-items: center;
+        justify-content: center;
+        flex-direction: column;
+        padding: 24px;
+        box-sizing: border-box;
+        pointer-events: none;
+        z-index: 3;
+      }
+      #openclaw-status .card {
+        width: min(560px, 88vw);
+        text-align: left;
+        padding: 14px 16px 12px;
+        border-radius: 16px;
+        background: linear-gradient(140deg, rgba(23, 24, 35, 0.78), rgba(18, 19, 28, 0.55));
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        box-shadow:
+          0 16px 46px rgba(0, 0, 0, 0.52),
+          inset 0 1px 0 rgba(255, 255, 255, 0.06);
+        -webkit-backdrop-filter: blur(18px) saturate(140%);
+        backdrop-filter: blur(18px) saturate(140%);
+      }
+      #openclaw-status .title {
+        font:
+          600 12px/1.2 -apple-system,
+          BlinkMacSystemFont,
+          "SF Pro Text",
+          system-ui,
+          sans-serif;
+        letter-spacing: 0.45px;
+        text-transform: uppercase;
+        color: rgba(255, 255, 255, 0.7);
+      }
+      #openclaw-status .subtitle {
+        margin-top: 8px;
+        font:
+          500 13px/1.45 -apple-system,
+          BlinkMacSystemFont,
+          "SF Pro Text",
+          system-ui,
+          sans-serif;
+        color: rgba(255, 255, 255, 0.9);
+        white-space: pre-wrap;
+        overflow-wrap: anywhere;
+      }
+      openclaw-a2ui-host {
+        display: block;
+        height: 100%;
+        position: fixed;
+        inset: 0;
+        z-index: 4;
+        --openclaw-a2ui-inset-top: 28px;
+        --openclaw-a2ui-inset-right: 0px;
+        --openclaw-a2ui-inset-bottom: 0px;
+        --openclaw-a2ui-inset-left: 0px;
+        --openclaw-a2ui-scroll-pad-bottom: 0px;
+        --openclaw-a2ui-status-top: calc(50% - 18px);
+        --openclaw-a2ui-empty-top: 18px;
+      }
+    </style>
+  </head>
+  <body>
+    <canvas id="openclaw-canvas"></canvas>
+    <div id="openclaw-status" role="status" aria-live="polite">
+      <section class="card">
+        <div class="title" id="openclaw-status-title">Ready</div>
+        <div class="subtitle" id="openclaw-status-subtitle">Waiting for agent</div>
+      </section>
+    </div>
+    <openclaw-a2ui-host></openclaw-a2ui-host>
+    <script src="a2ui.bundle.js"></script>
+    <script>
+      (() => {
+        const canvas = document.getElementById("openclaw-canvas");
+        const ctx = canvas.getContext("2d");
+        const statusEl = document.getElementById("openclaw-status");
+        const titleEl = document.getElementById("openclaw-status-title");
+        const subtitleEl = document.getElementById("openclaw-status-subtitle");
+        const debugStatusEnabledByQuery = (() => {
+          try {
+            const params = new URLSearchParams(window.location.search);
+            const raw = params.get("debugStatus") ?? params.get("debug");
+            if (!raw) return false;
+            const normalized = normalizeLower(raw);
+            return normalized === "1" || normalized === "true" || normalized === "yes";
+          } catch (_) {
+            return false;
+          }
+        })();
+        let debugStatusEnabled = debugStatusEnabledByQuery;
+
+        function resize() {
+          const dpr = window.devicePixelRatio || 1;
+          const w = Math.max(1, Math.floor(window.innerWidth * dpr));
+          const h = Math.max(1, Math.floor(window.innerHeight * dpr));
+          canvas.width = w;
+          canvas.height = h;
+          ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        }
+
+        window.addEventListener("resize", resize);
+        resize();
+
+        const setDebugStatusEnabled = (enabled) => {
+          debugStatusEnabled = !!enabled;
+          if (!statusEl) return;
+          if (!debugStatusEnabled) {
+            statusEl.style.display = "none";
+          }
+        };
+
+        if (statusEl && !debugStatusEnabled) {
+          statusEl.style.display = "none";
+        }
+
+        window.__openclaw = {
+          canvas,
+          ctx,
+          setDebugStatusEnabled,
+          setStatus: (title, subtitle) => {
+            if (!statusEl || !debugStatusEnabled) return;
+            if (!title && !subtitle) {
+              statusEl.style.display = "none";
+              return;
+            }
+            statusEl.style.display = "flex";
+            if (titleEl && typeof title === "string") titleEl.textContent = title;
+            if (subtitleEl && typeof subtitle === "string") subtitleEl.textContent = subtitle;
+            if (!debugStatusEnabled) {
+              clearTimeout(window.__statusTimeout);
+              window.__statusTimeout = setTimeout(() => {
+                statusEl.style.display = "none";
+              }, 3000);
+            } else {
+              clearTimeout(window.__statusTimeout);
+            }
+          },
+        };
+      })();
+    </script>
+  </body>
+</html>

apps/shared/OpenClawKit/Sources/OpenClawKit/Resources/CanvasScaffold/scaffold.html

@@ -0,0 +1,672 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+    <title>OpenClaw</title>
+    <script>
+      (() => {
+        try {
+          const params = new URLSearchParams(window.location.search);
+          const platform = (params.get('platform') || '').trim().toLowerCase();
+          if (platform) {
+            document.documentElement.dataset.platform = platform;
+            return;
+          }
+          if (/android/i.test(navigator.userAgent || '')) {
+            document.documentElement.dataset.platform = 'android';
+          } else {
+            document.documentElement.dataset.platform = 'ios';
+          }
+        } catch (_) {}
+      })();
+    </script>
+    <style>
+      :root {
+        color-scheme: dark;
+        --bg: #08080a;
+        --panel: rgba(18, 19, 23, 0.76);
+        --panel-strong: rgba(28, 30, 35, 0.88);
+        --line: rgba(255, 255, 255, 0.11);
+        --line-strong: rgba(255, 255, 255, 0.2);
+        --text: rgba(250, 250, 250, 0.96);
+        --muted: rgba(224, 224, 226, 0.72);
+        --soft: rgba(224, 224, 226, 0.5);
+        --accent: #c6312a;
+        --accent-strong: #ef3e52;
+        --accent-warm: #f59e0b;
+        --state: #7d8ca3;
+        --safe-top: env(safe-area-inset-top, 0px);
+        --safe-bottom: env(safe-area-inset-bottom, 0px);
+      }
+
+      html, body {
+        height: 100%;
+        margin: 0;
+      }
+
+      body {
+        font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", system-ui, sans-serif;
+        background:
+          linear-gradient(135deg, rgba(198, 49, 42, 0.2), rgba(198, 49, 42, 0) 34%),
+          linear-gradient(180deg, #14161a 0%, #08080a 42%, #050506 100%);
+        color: var(--text);
+        overflow: hidden;
+      }
+
+      body::before {
+        content: "";
+        position: fixed;
+        inset: -10%;
+        pointer-events: none;
+        background:
+          repeating-linear-gradient(
+            90deg,
+            rgba(255, 255, 255, 0.018) 0,
+            rgba(255, 255, 255, 0.018) 1px,
+            transparent 1px,
+            transparent 44px
+          ),
+          repeating-linear-gradient(
+            0deg,
+            rgba(255, 255, 255, 0.018) 0,
+            rgba(255, 255, 255, 0.018) 1px,
+            transparent 1px,
+            transparent 44px
+          );
+        opacity: 0.5;
+      }
+
+      body[data-state="connected"] { --state: #61d58b; }
+      body[data-state="connecting"] { --state: #ffd05f; }
+      body[data-state="error"] { --state: #ff6d6d; }
+      body[data-state="offline"] { --state: #95a3b9; }
+
+      canvas {
+        position: fixed;
+        inset: 0;
+        width: 100vw;
+        height: 100vh;
+        display: block;
+        z-index: 1;
+      }
+
+      #openclaw-home {
+        position: fixed;
+        inset: 0;
+        z-index: 2;
+        display: flex;
+        align-items: flex-start;
+        justify-content: center;
+        padding: calc(var(--safe-top) + 18px) 16px calc(var(--safe-bottom) + 18px);
+        box-sizing: border-box;
+        overflow-y: auto;
+        overflow-x: hidden;
+        -webkit-overflow-scrolling: touch;
+      }
+
+      .shell {
+        width: min(100%, 760px);
+        display: flex;
+        flex-direction: column;
+        justify-content: flex-start;
+        gap: 16px;
+        min-height: 100%;
+        box-sizing: border-box;
+      }
+
+      .hero {
+        position: relative;
+        overflow: hidden;
+        border-radius: 24px;
+        background: linear-gradient(180deg, rgba(31, 33, 38, 0.86), rgba(13, 14, 17, 0.94));
+        border: 1px solid var(--line);
+        box-shadow: 0 28px 90px rgba(0, 0, 0, 0.42);
+        padding: 22px 22px 18px;
+      }
+
+      .hero::before {
+        content: "";
+        position: absolute;
+        inset: 0 auto 0 0;
+        width: 3px;
+        background: linear-gradient(180deg, var(--accent-strong), rgba(198, 49, 42, 0.08));
+        pointer-events: none;
+      }
+
+      .eyebrow {
+        display: inline-flex;
+        align-items: center;
+        gap: 9px;
+        padding: 8px 12px;
+        border-radius: 999px;
+        background: rgba(255, 255, 255, 0.04);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 700;
+        letter-spacing: 0.06em;
+        text-transform: uppercase;
+        max-width: 100%;
+        box-sizing: border-box;
+      }
+
+      .eyebrow-dot {
+        flex: 0 0 auto;
+        width: 9px;
+        height: 9px;
+        border-radius: 999px;
+        background: var(--state);
+        box-shadow: 0 0 18px color-mix(in srgb, var(--state) 68%, transparent);
+      }
+
+      #openclaw-home-eyebrow {
+        min-width: 0;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+      }
+
+      .hero h1 {
+        margin: 18px 0 0;
+        font-size: clamp(34px, 7vw, 54px);
+        line-height: 1;
+        letter-spacing: -0.03em;
+      }
+
+      .hero p {
+        margin: 14px 0 0;
+        font-size: 16px;
+        line-height: 1.5;
+        color: var(--muted);
+        max-width: 32rem;
+      }
+
+      .hero-grid {
+        display: grid;
+        grid-template-columns: 1.2fr 1fr;
+        gap: 12px;
+        margin-top: 22px;
+      }
+
+      .meta-card,
+      .agent-card {
+        border-radius: 22px;
+        background: var(--panel);
+        border: 1px solid var(--line);
+        backdrop-filter: blur(18px);
+        -webkit-backdrop-filter: blur(18px);
+      }
+
+      .meta-card {
+        padding: 16px 16px 15px;
+      }
+
+      .meta-label {
+        font-size: 11px;
+        letter-spacing: 0.08em;
+        text-transform: uppercase;
+        color: var(--soft);
+      }
+
+      .meta-value {
+        margin-top: 8px;
+        font-size: 24px;
+        font-weight: 700;
+        letter-spacing: -0.03em;
+        overflow-wrap: anywhere;
+      }
+
+      .meta-subtitle {
+        margin-top: 6px;
+        color: var(--muted);
+        font-size: 13px;
+        line-height: 1.4;
+      }
+
+      .agent-focus {
+        display: flex;
+        align-items: flex-start;
+        gap: 14px;
+        margin-top: 8px;
+      }
+
+      .agent-badge {
+        width: 56px;
+        height: 56px;
+        border-radius: 18px;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        background:
+          linear-gradient(135deg, rgba(198, 49, 42, 0.28), rgba(239, 62, 82, 0.1)),
+          rgba(255, 255, 255, 0.04);
+        border: 1px solid rgba(255, 255, 255, 0.12);
+        font-size: 24px;
+        font-weight: 700;
+      }
+
+      .agent-focus .name {
+        font-size: 22px;
+        font-weight: 700;
+        letter-spacing: -0.03em;
+        overflow-wrap: anywhere;
+      }
+
+      .agent-focus .caption {
+        margin-top: 4px;
+        font-size: 13px;
+        color: var(--muted);
+      }
+
+      .section {
+        padding: 16px 16px 14px;
+      }
+
+      .section-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 12px;
+        margin-bottom: 12px;
+      }
+
+      .section-title {
+        font-size: 14px;
+        font-weight: 700;
+        color: var(--muted);
+      }
+
+      .section-count {
+        font-size: 12px;
+        font-weight: 700;
+        color: var(--soft);
+      }
+
+      .agent-grid {
+        display: grid;
+        grid-template-columns: repeat(2, minmax(0, 1fr));
+        gap: 10px;
+      }
+
+      .agent-card {
+        padding: 13px 13px 12px;
+      }
+
+      .agent-card.active {
+        background: var(--panel-strong);
+        border-color: var(--line-strong);
+        box-shadow: inset 0 0 0 1px rgba(198, 49, 42, 0.18);
+      }
+
+      .agent-row {
+        display: flex;
+        align-items: center;
+        gap: 10px;
+      }
+
+      .agent-row .badge {
+        width: 38px;
+        height: 38px;
+        border-radius: 14px;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        background: rgba(255, 255, 255, 0.05);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        font-size: 16px;
+        font-weight: 700;
+      }
+
+      .agent-row .name {
+        font-size: 15px;
+        font-weight: 700;
+        line-height: 1.2;
+        overflow-wrap: anywhere;
+      }
+
+      .agent-row .caption {
+        margin-top: 3px;
+        font-size: 12px;
+        color: var(--muted);
+      }
+
+      .empty-state {
+        padding: 18px;
+        border-radius: 18px;
+        background: rgba(255, 255, 255, 0.03);
+        border: 1px dashed rgba(255, 255, 255, 0.12);
+        color: var(--muted);
+        font-size: 14px;
+        line-height: 1.45;
+      }
+
+      .footer-note {
+        margin-top: 12px;
+        color: var(--soft);
+        font-size: 12px;
+        line-height: 1.45;
+      }
+
+      #openclaw-status {
+        position: fixed;
+        inset: 0;
+        display: none;
+        align-items: center;
+        justify-content: flex-start;
+        flex-direction: column;
+        padding-top: calc(var(--safe-top) + 18px);
+        pointer-events: none;
+        z-index: 3;
+      }
+
+      #openclaw-status .card {
+        text-align: center;
+        padding: 16px 18px;
+        border-radius: 14px;
+        background: rgba(18, 18, 22, 0.46);
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        box-shadow: 0 18px 60px rgba(0, 0, 0, 0.55);
+        -webkit-backdrop-filter: blur(14px);
+        backdrop-filter: blur(14px);
+      }
+
+      #openclaw-status .title {
+        font: 600 20px -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", system-ui, sans-serif;
+        color: rgba(255, 255, 255, 0.92);
+      }
+
+      #openclaw-status .subtitle {
+        margin-top: 6px;
+        font: 500 12px -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
+        color: rgba(255, 255, 255, 0.58);
+      }
+
+      @media (max-width: 640px) {
+        #openclaw-home {
+          padding-left: 12px;
+          padding-right: 12px;
+        }
+
+        .hero {
+          border-radius: 24px;
+          padding: 18px 16px 16px;
+        }
+
+        .hero-grid,
+        .agent-grid {
+          grid-template-columns: 1fr;
+        }
+
+        .hero h1 {
+          font-size: 34px;
+        }
+      }
+
+      @media (max-height: 760px) {
+        #openclaw-home {
+          padding-top: calc(var(--safe-top) + 14px);
+          padding-bottom: calc(var(--safe-bottom) + 12px);
+        }
+
+        .shell {
+          gap: 12px;
+        }
+
+        .hero {
+          border-radius: 24px;
+          padding: 16px 15px 15px;
+        }
+
+        .hero h1 {
+          margin-top: 14px;
+          font-size: clamp(28px, 8vw, 38px);
+        }
+
+        .hero p {
+          margin-top: 10px;
+          font-size: 15px;
+          line-height: 1.42;
+        }
+
+        .hero-grid {
+          margin-top: 18px;
+        }
+
+        .meta-card {
+          padding: 14px 14px 13px;
+        }
+
+        .meta-value {
+          font-size: 22px;
+        }
+
+        .agent-badge {
+          width: 50px;
+          height: 50px;
+          border-radius: 16px;
+          font-size: 22px;
+        }
+
+        .agent-focus .name {
+          font-size: 20px;
+        }
+
+        .section {
+          padding: 14px 14px 12px;
+        }
+
+        .section-header {
+          margin-bottom: 10px;
+        }
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        body::before,
+        body::after {
+          animation: none !important;
+        }
+      }
+    </style>
+  </head>
+  <body data-state="offline">
+    <canvas id="openclaw-canvas"></canvas>
+    <div id="openclaw-home">
+      <div class="shell">
+        <div class="hero">
+          <div class="eyebrow">
+            <span class="eyebrow-dot"></span>
+            <span id="openclaw-home-eyebrow">Welcome to OpenClaw</span>
+          </div>
+          <h1 id="openclaw-home-title">Your phone stays quiet until it is needed</h1>
+          <p id="openclaw-home-subtitle">
+            Pair this device to your gateway to wake it only for real work, keep a live agent overview handy, and avoid battery-draining background loops.
+          </p>
+
+          <div class="hero-grid">
+            <div class="meta-card">
+              <div class="meta-label">Gateway</div>
+              <div class="meta-value" id="openclaw-home-gateway">Gateway</div>
+              <div class="meta-subtitle" id="openclaw-home-gateway-caption">Connect to load your agents</div>
+            </div>
+
+            <div class="meta-card">
+              <div class="meta-label">Active Agent</div>
+              <div class="agent-focus">
+                <div class="agent-badge" id="openclaw-home-active-badge">OC</div>
+                <div>
+                  <div class="name" id="openclaw-home-active-name">Main</div>
+                  <div class="caption" id="openclaw-home-active-caption">Connect to load your agents</div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <div class="meta-card section">
+          <div class="section-header">
+            <div class="section-title">Live agents</div>
+            <div class="section-count" id="openclaw-home-agent-count">0 agents</div>
+          </div>
+          <div class="agent-grid" id="openclaw-home-agent-grid"></div>
+          <div class="footer-note" id="openclaw-home-footer">
+            When connected, the gateway can wake the phone with a silent push instead of holding an always-on session.
+          </div>
+        </div>
+      </div>
+    </div>
+
+    <div id="openclaw-status">
+      <div class="card">
+        <div class="title" id="openclaw-status-title">Ready</div>
+        <div class="subtitle" id="openclaw-status-subtitle">Waiting for agent</div>
+      </div>
+    </div>
+
+    <script>
+      (() => {
+        const canvas = document.getElementById('openclaw-canvas');
+        const ctx = canvas.getContext('2d');
+        const statusEl = document.getElementById('openclaw-status');
+        const titleEl = document.getElementById('openclaw-status-title');
+        const subtitleEl = document.getElementById('openclaw-status-subtitle');
+        const home = {
+          root: document.getElementById('openclaw-home'),
+          eyebrow: document.getElementById('openclaw-home-eyebrow'),
+          title: document.getElementById('openclaw-home-title'),
+          subtitle: document.getElementById('openclaw-home-subtitle'),
+          gateway: document.getElementById('openclaw-home-gateway'),
+          gatewayCaption: document.getElementById('openclaw-home-gateway-caption'),
+          activeBadge: document.getElementById('openclaw-home-active-badge'),
+          activeName: document.getElementById('openclaw-home-active-name'),
+          activeCaption: document.getElementById('openclaw-home-active-caption'),
+          agentCount: document.getElementById('openclaw-home-agent-count'),
+          agentGrid: document.getElementById('openclaw-home-agent-grid'),
+          footer: document.getElementById('openclaw-home-footer')
+        };
+        const debugStatusEnabledByQuery = (() => {
+          try {
+            const params = new URLSearchParams(window.location.search);
+            const raw = params.get('debugStatus') ?? params.get('debug');
+            if (!raw) return false;
+            const normalized = String(raw).trim().toLowerCase();
+            return normalized === '1' || normalized === 'true' || normalized === 'yes';
+          } catch (_) {
+            return false;
+          }
+        })();
+        let debugStatusEnabled = debugStatusEnabledByQuery;
+
+        function resize() {
+          const dpr = window.devicePixelRatio || 1;
+          const width = Math.max(1, Math.floor(window.innerWidth * dpr));
+          const height = Math.max(1, Math.floor(window.innerHeight * dpr));
+          canvas.width = width;
+          canvas.height = height;
+          ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        }
+
+        function setDebugStatusEnabled(enabled) {
+          debugStatusEnabled = !!enabled;
+          if (!debugStatusEnabled) {
+            statusEl.style.display = 'none';
+          }
+        }
+
+        function setStatus(title, subtitle) {
+          if (!debugStatusEnabled) return;
+          if (!title && !subtitle) {
+            statusEl.style.display = 'none';
+            return;
+          }
+          statusEl.style.display = 'flex';
+          if (typeof title === 'string') titleEl.textContent = title;
+          if (typeof subtitle === 'string') subtitleEl.textContent = subtitle;
+        }
+
+        function clearChildren(node) {
+          while (node.firstChild) node.removeChild(node.firstChild);
+        }
+
+        function createAgentCard(agent) {
+          const card = document.createElement('div');
+          card.className = `agent-card${agent.isActive ? ' active' : ''}`;
+
+          const row = document.createElement('div');
+          row.className = 'agent-row';
+
+          const badge = document.createElement('div');
+          badge.className = 'badge';
+          badge.textContent = agent.badge || 'OC';
+
+          const text = document.createElement('div');
+
+          const name = document.createElement('div');
+          name.className = 'name';
+          name.textContent = agent.name || agent.id || 'Agent';
+
+          const caption = document.createElement('div');
+          caption.className = 'caption';
+          caption.textContent = agent.caption || 'Ready';
+
+          text.appendChild(name);
+          text.appendChild(caption);
+          row.appendChild(badge);
+          row.appendChild(text);
+          card.appendChild(row);
+          return card;
+        }
+
+        function renderHome(state) {
+          if (!state || typeof state !== 'object') return;
+
+          document.body.dataset.state = state.gatewayState || 'offline';
+          home.root.style.display = 'flex';
+          home.eyebrow.textContent = state.eyebrow || 'Welcome to OpenClaw';
+          home.title.textContent = state.title || 'OpenClaw';
+          home.subtitle.textContent = state.subtitle || '';
+          home.gateway.textContent = state.gatewayLabel || 'Gateway';
+          home.gatewayCaption.textContent = state.gatewayState === 'connected'
+            ? `${state.agentCount || 0} agent${state.agentCount === 1 ? '' : 's'} available`
+            : (state.activeAgentCaption || 'Connect to load your agents');
+          home.activeBadge.textContent = state.activeAgentBadge || 'OC';
+          home.activeName.textContent = state.activeAgentName || 'Main';
+          home.activeCaption.textContent = state.activeAgentCaption || '';
+          home.agentCount.textContent = `${state.agentCount || 0} agent${state.agentCount === 1 ? '' : 's'}`;
+          home.footer.textContent = state.footer || '';
+
+          clearChildren(home.agentGrid);
+          const agents = Array.isArray(state.agents) ? state.agents : [];
+          if (!agents.length) {
+            const empty = document.createElement('div');
+            empty.className = 'empty-state';
+            empty.textContent = state.gatewayState === 'connected'
+              ? 'Your gateway is online. Agents will appear here as soon as the current scope reports them.'
+              : 'Connect this phone to your gateway and the live agent overview will appear here.';
+            home.agentGrid.appendChild(empty);
+            return;
+          }
+
+          agents.forEach((agent) => {
+            home.agentGrid.appendChild(createAgentCard(agent));
+          });
+        }
+
+        window.addEventListener('resize', resize);
+        resize();
+
+        if (!debugStatusEnabled) {
+          statusEl.style.display = 'none';
+        }
+
+        window.__openclaw = {
+          canvas,
+          ctx,
+          setDebugStatusEnabled,
+          setStatus,
+          renderHome
+        };
+      })();
+    </script>
+  </body>
+</html>

apps/shared/OpenClawKit/Sources/OpenClawKit/Resources/tool-display.json

@@ -0,0 +1,999 @@
+{
+  "version": 1,
+  "fallback": {
+    "emoji": "🧩",
+    "detailKeys": [
+      "command",
+      "path",
+      "url",
+      "targetUrl",
+      "targetId",
+      "ref",
+      "element",
+      "node",
+      "nodeId",
+      "id",
+      "requestId",
+      "to",
+      "channelId",
+      "guildId",
+      "userId",
+      "name",
+      "query",
+      "pattern",
+      "messageId"
+    ]
+  },
+  "tools": {
+    "bash": {
+      "emoji": "🛠️",
+      "title": "Bash",
+      "detailKeys": [
+        "command"
+      ]
+    },
+    "process": {
+      "emoji": "🧰",
+      "title": "Process",
+      "detailKeys": [
+        "sessionId"
+      ]
+    },
+    "read": {
+      "emoji": "📖",
+      "title": "Read",
+      "detailKeys": [
+        "path"
+      ]
+    },
+    "write": {
+      "emoji": "✍️",
+      "title": "Write",
+      "detailKeys": [
+        "path"
+      ]
+    },
+    "edit": {
+      "emoji": "📝",
+      "title": "Edit",
+      "detailKeys": [
+        "path"
+      ]
+    },
+    "attach": {
+      "emoji": "📎",
+      "title": "Attach",
+      "detailKeys": [
+        "path",
+        "url",
+        "fileName"
+      ]
+    },
+    "api": {
+      "emoji": "🌐",
+      "title": "API",
+      "detailKeys": [
+        "url",
+        "endpoint",
+        "path",
+        "method",
+        "name"
+      ]
+    },
+    "browser": {
+      "emoji": "🌐",
+      "title": "Browser",
+      "actions": {
+        "status": {
+          "label": "status"
+        },
+        "start": {
+          "label": "start"
+        },
+        "stop": {
+          "label": "stop"
+        },
+        "tabs": {
+          "label": "tabs"
+        },
+        "open": {
+          "label": "open",
+          "detailKeys": [
+            "targetUrl"
+          ]
+        },
+        "focus": {
+          "label": "focus",
+          "detailKeys": [
+            "targetId"
+          ]
+        },
+        "close": {
+          "label": "close",
+          "detailKeys": [
+            "targetId"
+          ]
+        },
+        "snapshot": {
+          "label": "snapshot",
+          "detailKeys": [
+            "targetUrl",
+            "targetId",
+            "ref",
+            "element",
+            "format"
+          ]
+        },
+        "screenshot": {
+          "label": "screenshot",
+          "detailKeys": [
+            "targetUrl",
+            "targetId",
+            "ref",
+            "element"
+          ]
+        },
+        "navigate": {
+          "label": "navigate",
+          "detailKeys": [
+            "targetUrl",
+            "targetId"
+          ]
+        },
+        "console": {
+          "label": "console",
+          "detailKeys": [
+            "level",
+            "targetId"
+          ]
+        },
+        "pdf": {
+          "label": "pdf",
+          "detailKeys": [
+            "targetId"
+          ]
+        },
+        "upload": {
+          "label": "upload",
+          "detailKeys": [
+            "paths",
+            "ref",
+            "inputRef",
+            "element",
+            "targetId"
+          ]
+        },
+        "dialog": {
+          "label": "dialog",
+          "detailKeys": [
+            "accept",
+            "promptText",
+            "targetId"
+          ]
+        },
+        "act": {
+          "label": "act",
+          "detailKeys": [
+            "request.kind",
+            "request.ref",
+            "request.selector",
+            "request.text",
+            "request.value"
+          ]
+        }
+      }
+    },
+    "canvas": {
+      "emoji": "🖼️",
+      "title": "Canvas",
+      "actions": {
+        "present": {
+          "label": "present",
+          "detailKeys": [
+            "target",
+            "node",
+            "nodeId"
+          ]
+        },
+        "hide": {
+          "label": "hide",
+          "detailKeys": [
+            "node",
+            "nodeId"
+          ]
+        },
+        "navigate": {
+          "label": "navigate",
+          "detailKeys": [
+            "url",
+            "node",
+            "nodeId"
+          ]
+        },
+        "eval": {
+          "label": "eval",
+          "detailKeys": [
+            "javaScript",
+            "node",
+            "nodeId"
+          ]
+        },
+        "snapshot": {
+          "label": "snapshot",
+          "detailKeys": [
+            "format",
+            "node",
+            "nodeId"
+          ]
+        },
+        "a2ui_push": {
+          "label": "A2UI push",
+          "detailKeys": [
+            "jsonlPath",
+            "node",
+            "nodeId"
+          ]
+        },
+        "a2ui_reset": {
+          "label": "A2UI reset",
+          "detailKeys": [
+            "node",
+            "nodeId"
+          ]
+        }
+      }
+    },
+    "nodes": {
+      "emoji": "📱",
+      "title": "Nodes",
+      "actions": {
+        "status": {
+          "label": "status"
+        },
+        "describe": {
+          "label": "describe",
+          "detailKeys": [
+            "node",
+            "nodeId"
+          ]
+        },
+        "pending": {
+          "label": "pending"
+        },
+        "approve": {
+          "label": "approve",
+          "detailKeys": [
+            "requestId"
+          ]
+        },
+        "reject": {
+          "label": "reject",
+          "detailKeys": [
+            "requestId"
+          ]
+        },
+        "notify": {
+          "label": "notify",
+          "detailKeys": [
+            "node",
+            "nodeId",
+            "title",
+            "body"
+          ]
+        },
+        "camera_snap": {
+          "label": "camera snap",
+          "detailKeys": [
+            "node",
+            "nodeId",
+            "facing",
+            "deviceId"
+          ]
+        },
+        "camera_list": {
+          "label": "camera list",
+          "detailKeys": [
+            "node",
+            "nodeId"
+          ]
+        },
+        "camera_clip": {
+          "label": "camera clip",
+          "detailKeys": [
+            "node",
+            "nodeId",
+            "facing",
+            "duration",
+            "durationMs"
+          ]
+        },
+        "screen_record": {
+          "label": "screen record",
+          "detailKeys": [
+            "node",
+            "nodeId",
+            "duration",
+            "durationMs",
+            "fps",
+            "screenIndex"
+          ]
+        },
+        "screen_snapshot": {
+          "label": "screen snapshot",
+          "detailKeys": [
+            "node",
+            "nodeId",
+            "screenIndex",
+            "maxWidth"
+          ]
+        }
+      }
+    },
+    "cron": {
+      "emoji": "⏰",
+      "title": "Cron",
+      "actions": {
+        "status": {
+          "label": "status"
+        },
+        "list": {
+          "label": "list"
+        },
+        "add": {
+          "label": "add",
+          "detailKeys": [
+            "job.name",
+            "job.id",
+            "job.schedule",
+            "job.cron"
+          ]
+        },
+        "update": {
+          "label": "update",
+          "detailKeys": [
+            "id"
+          ]
+        },
+        "remove": {
+          "label": "remove",
+          "detailKeys": [
+            "id"
+          ]
+        },
+        "run": {
+          "label": "run",
+          "detailKeys": [
+            "id"
+          ]
+        },
+        "runs": {
+          "label": "runs",
+          "detailKeys": [
+            "id"
+          ]
+        },
+        "wake": {
+          "label": "wake",
+          "detailKeys": [
+            "text",
+            "mode"
+          ]
+        }
+      }
+    },
+    "get_goal": {
+      "emoji": "🎯",
+      "title": "Get Goal",
+      "detailKeys": []
+    },
+    "create_goal": {
+      "emoji": "🎯",
+      "title": "Create Goal",
+      "detailKeys": [
+        "objective",
+        "token_budget"
+      ]
+    },
+    "update_goal": {
+      "emoji": "🎯",
+      "title": "Update Goal",
+      "detailKeys": [
+        "status"
+      ]
+    },
+    "update_plan": {
+      "emoji": "🗺️",
+      "title": "Update Plan",
+      "detailKeys": [
+        "explanation",
+        "plan.0.step"
+      ]
+    },
+    "skill_workshop": {
+      "emoji": "🧰",
+      "title": "Skill Workshop",
+      "detailKeys": [
+        "action",
+        "name",
+        "proposal_id"
+      ]
+    },
+    "crestodian": {
+      "emoji": "🦀",
+      "title": "Crestodian",
+      "detailKeys": [
+        "action",
+        "path",
+        "model"
+      ]
+    },
+    "gateway": {
+      "emoji": "🔌",
+      "title": "Gateway",
+      "actions": {
+        "restart": {
+          "label": "restart",
+          "detailKeys": [
+            "reason",
+            "delayMs"
+          ]
+        }
+      }
+    },
+    "exec": {
+      "emoji": "🛠️",
+      "title": "Exec",
+      "detailKeys": [
+        "command"
+      ]
+    },
+    "tool_call": {
+      "emoji": "🧰",
+      "title": "Tool Call",
+      "detailKeys": []
+    },
+    "tool_call_update": {
+      "emoji": "🧰",
+      "title": "Tool Call",
+      "detailKeys": []
+    },
+    "session_status": {
+      "emoji": "📊",
+      "title": "Session Status",
+      "detailKeys": [
+        "sessionKey",
+        "model"
+      ]
+    },
+    "sessions_list": {
+      "emoji": "🗂️",
+      "title": "Sessions",
+      "detailKeys": [
+        "kinds",
+        "label",
+        "agentId",
+        "search",
+        "limit",
+        "activeMinutes",
+        "includeDerivedTitles",
+        "includeLastMessage",
+        "messageLimit"
+      ]
+    },
+    "sessions_send": {
+      "emoji": "📨",
+      "title": "Session Send",
+      "detailKeys": [
+        "label",
+        "sessionKey",
+        "agentId",
+        "timeoutSeconds"
+      ]
+    },
+    "sessions_history": {
+      "emoji": "🧾",
+      "title": "Session History",
+      "detailKeys": [
+        "sessionKey",
+        "limit",
+        "includeTools"
+      ]
+    },
+    "transcripts": {
+      "emoji": "🎙️",
+      "title": "Transcripts",
+      "actions": {
+        "start": {
+          "label": "start",
+          "detailKeys": [
+            "sessionId",
+            "title",
+            "providerId",
+            "accountId",
+            "guildId",
+            "channelId",
+            "meetingUrl"
+          ]
+        },
+        "stop": {
+          "label": "stop",
+          "detailKeys": [
+            "sessionId"
+          ]
+        },
+        "status": {
+          "label": "status"
+        },
+        "import": {
+          "label": "import",
+          "detailKeys": [
+            "sessionId",
+            "title",
+            "providerId",
+            "meetingUrl",
+            "speakerLabel"
+          ]
+        },
+        "summarize": {
+          "label": "summarize",
+          "detailKeys": [
+            "sessionId"
+          ]
+        }
+      }
+    },
+    "sessions_spawn": {
+      "emoji": "🧑‍🔧",
+      "title": "Sub-agent",
+      "detailKeys": [
+        "label",
+        "task",
+        "agentId",
+        "model",
+        "thinking",
+        "runTimeoutSeconds",
+        "cleanup"
+      ]
+    },
+    "subagents": {
+      "emoji": "🤖",
+      "title": "Subagents",
+      "actions": {
+        "list": {
+          "label": "list",
+          "detailKeys": [
+            "recentMinutes"
+          ]
+        },
+        "kill": {
+          "label": "kill",
+          "detailKeys": [
+            "target"
+          ]
+        },
+        "steer": {
+          "label": "steer",
+          "detailKeys": [
+            "target"
+          ]
+        }
+      }
+    },
+    "agents_list": {
+      "emoji": "🧭",
+      "title": "Agents",
+      "detailKeys": []
+    },
+    "memory_search": {
+      "emoji": "🧠",
+      "title": "Memory Search",
+      "detailKeys": [
+        "query"
+      ]
+    },
+    "memory_get": {
+      "emoji": "📓",
+      "title": "Memory Get",
+      "detailKeys": [
+        "path",
+        "from",
+        "lines"
+      ]
+    },
+    "web_search": {
+      "emoji": "🔎",
+      "title": "Web Search",
+      "detailKeys": [
+        "query",
+        "count"
+      ]
+    },
+    "web_fetch": {
+      "emoji": "📄",
+      "title": "Web Fetch",
+      "detailKeys": [
+        "url",
+        "extractMode",
+        "maxChars"
+      ]
+    },
+    "code_execution": {
+      "emoji": "🧮",
+      "title": "Code Execution",
+      "detailKeys": [
+        "task"
+      ]
+    },
+    "message": {
+      "emoji": "✉️",
+      "title": "Message",
+      "actions": {
+        "send": {
+          "label": "send",
+          "detailKeys": [
+            "provider",
+            "to",
+            "media",
+            "replyTo",
+            "threadId"
+          ]
+        },
+        "poll": {
+          "label": "poll",
+          "detailKeys": [
+            "provider",
+            "to",
+            "pollQuestion"
+          ]
+        },
+        "react": {
+          "label": "react",
+          "detailKeys": [
+            "provider",
+            "to",
+            "messageId",
+            "emoji",
+            "remove"
+          ]
+        },
+        "reactions": {
+          "label": "reactions",
+          "detailKeys": [
+            "provider",
+            "to",
+            "messageId",
+            "limit"
+          ]
+        },
+        "read": {
+          "label": "read",
+          "detailKeys": [
+            "provider",
+            "to",
+            "limit"
+          ]
+        },
+        "edit": {
+          "label": "edit",
+          "detailKeys": [
+            "provider",
+            "to",
+            "messageId"
+          ]
+        },
+        "delete": {
+          "label": "delete",
+          "detailKeys": [
+            "provider",
+            "to",
+            "messageId"
+          ]
+        },
+        "pin": {
+          "label": "pin",
+          "detailKeys": [
+            "provider",
+            "to",
+            "messageId"
+          ]
+        },
+        "unpin": {
+          "label": "unpin",
+          "detailKeys": [
+            "provider",
+            "to",
+            "messageId"
+          ]
+        },
+        "list-pins": {
+          "label": "list pins",
+          "detailKeys": [
+            "provider",
+            "to"
+          ]
+        },
+        "permissions": {
+          "label": "permissions",
+          "detailKeys": [
+            "provider",
+            "channelId",
+            "to"
+          ]
+        },
+        "thread-create": {
+          "label": "thread create",
+          "detailKeys": [
+            "provider",
+            "channelId",
+            "threadName"
+          ]
+        },
+        "thread-list": {
+          "label": "thread list",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "channelId"
+          ]
+        },
+        "thread-reply": {
+          "label": "thread reply",
+          "detailKeys": [
+            "provider",
+            "channelId",
+            "messageId"
+          ]
+        },
+        "search": {
+          "label": "search",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "query"
+          ]
+        },
+        "sticker": {
+          "label": "sticker",
+          "detailKeys": [
+            "provider",
+            "to",
+            "stickerId"
+          ]
+        },
+        "member-info": {
+          "label": "member",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "userId"
+          ]
+        },
+        "role-info": {
+          "label": "roles",
+          "detailKeys": [
+            "provider",
+            "guildId"
+          ]
+        },
+        "emoji-list": {
+          "label": "emoji list",
+          "detailKeys": [
+            "provider",
+            "guildId"
+          ]
+        },
+        "emoji-upload": {
+          "label": "emoji upload",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "emojiName"
+          ]
+        },
+        "sticker-upload": {
+          "label": "sticker upload",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "stickerName"
+          ]
+        },
+        "role-add": {
+          "label": "role add",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "userId",
+            "roleId"
+          ]
+        },
+        "role-remove": {
+          "label": "role remove",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "userId",
+            "roleId"
+          ]
+        },
+        "channel-info": {
+          "label": "channel",
+          "detailKeys": [
+            "provider",
+            "channelId"
+          ]
+        },
+        "channel-list": {
+          "label": "channels",
+          "detailKeys": [
+            "provider",
+            "guildId"
+          ]
+        },
+        "voice-status": {
+          "label": "voice",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "userId"
+          ]
+        },
+        "event-list": {
+          "label": "events",
+          "detailKeys": [
+            "provider",
+            "guildId"
+          ]
+        },
+        "event-create": {
+          "label": "event create",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "eventName"
+          ]
+        },
+        "timeout": {
+          "label": "timeout",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "userId"
+          ]
+        },
+        "kick": {
+          "label": "kick",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "userId"
+          ]
+        },
+        "ban": {
+          "label": "ban",
+          "detailKeys": [
+            "provider",
+            "guildId",
+            "userId"
+          ]
+        }
+      }
+    },
+    "apply_patch": {
+      "emoji": "🩹",
+      "title": "Apply Patch",
+      "detailKeys": []
+    },
+    "image": {
+      "emoji": "🖼️",
+      "title": "Image",
+      "detailKeys": [
+        "path",
+        "paths",
+        "url",
+        "urls",
+        "prompt",
+        "model"
+      ]
+    },
+    "image_generate": {
+      "emoji": "🎨",
+      "title": "Image Generation",
+      "actions": {
+        "generate": {
+          "label": "generate",
+          "detailKeys": [
+            "prompt",
+            "model",
+            "count",
+            "resolution",
+            "aspectRatio"
+          ]
+        },
+        "list": {
+          "label": "list",
+          "detailKeys": [
+            "provider",
+            "model"
+          ]
+        }
+      }
+    },
+    "music_generate": {
+      "emoji": "🎵",
+      "title": "Music Generation",
+      "actions": {
+        "generate": {
+          "label": "generate",
+          "detailKeys": [
+            "prompt",
+            "model",
+            "durationSeconds",
+            "format",
+            "instrumental"
+          ]
+        },
+        "list": {
+          "label": "list",
+          "detailKeys": [
+            "provider",
+            "model"
+          ]
+        }
+      }
+    },
+    "video_generate": {
+      "emoji": "🎬",
+      "title": "Video Generation",
+      "actions": {
+        "generate": {
+          "label": "generate",
+          "detailKeys": [
+            "prompt",
+            "model",
+            "durationSeconds",
+            "resolution",
+            "aspectRatio",
+            "audio",
+            "watermark"
+          ]
+        },
+        "list": {
+          "label": "list",
+          "detailKeys": [
+            "provider",
+            "model"
+          ]
+        }
+      }
+    },
+    "pdf": {
+      "emoji": "📑",
+      "title": "PDF",
+      "detailKeys": [
+        "path",
+        "paths",
+        "url",
+        "urls",
+        "prompt",
+        "pageRange",
+        "model"
+      ]
+    },
+    "sessions_yield": {
+      "emoji": "⏸️",
+      "title": "Yield",
+      "detailKeys": [
+        "message"
+      ]
+    },
+    "tts": {
+      "emoji": "🔊",
+      "title": "TTS",
+      "detailKeys": [
+        "text",
+        "channel"
+      ]
+    }
+  }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ScreenCommands.swift

@@ -0,0 +1,52 @@
+import Foundation
+
+public enum OpenClawScreenCommand: String, Codable, Sendable {
+    case snapshot = "screen.snapshot"
+    case record = "screen.record"
+}
+
+public enum OpenClawScreenSnapshotFormat: String, Codable, Sendable {
+    case jpeg
+    case png
+}
+
+public struct OpenClawScreenSnapshotParams: Codable, Sendable, Equatable {
+    public var screenIndex: Int?
+    public var maxWidth: Int?
+    public var quality: Double?
+    public var format: OpenClawScreenSnapshotFormat?
+
+    public init(
+        screenIndex: Int? = nil,
+        maxWidth: Int? = nil,
+        quality: Double? = nil,
+        format: OpenClawScreenSnapshotFormat? = nil)
+    {
+        self.screenIndex = screenIndex
+        self.maxWidth = maxWidth
+        self.quality = quality
+        self.format = format
+    }
+}
+
+public struct OpenClawScreenRecordParams: Codable, Sendable, Equatable {
+    public var screenIndex: Int?
+    public var durationMs: Int?
+    public var fps: Double?
+    public var format: String?
+    public var includeAudio: Bool?
+
+    public init(
+        screenIndex: Int? = nil,
+        durationMs: Int? = nil,
+        fps: Double? = nil,
+        format: String? = nil,
+        includeAudio: Bool? = nil)
+    {
+        self.screenIndex = screenIndex
+        self.durationMs = durationMs
+        self.fps = fps
+        self.format = format
+        self.includeAudio = includeAudio
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/SessionMutationResponses.swift

@@ -0,0 +1,26 @@
+import Foundation
+
+public struct OpenClawSessionsCompactResponse: Decodable, Sendable {
+    public let ok: Bool
+    public let reason: String?
+
+    public static func requireSuccess(from data: Data) throws {
+        let response = try JSONDecoder().decode(Self.self, from: data)
+        guard response.ok else {
+            throw OpenClawSessionsCompactError(reason: response.reason)
+        }
+    }
+}
+
+public struct OpenClawSessionsCompactError: Error, LocalizedError, Sendable {
+    public let reason: String?
+
+    public var errorDescription: String? {
+        let detail = self.reason?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return detail?.isEmpty == false ? detail : "Session compaction failed"
+    }
+
+    public init(reason: String?) {
+        self.reason = reason
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ShareGatewayRelaySettings.swift

@@ -0,0 +1,62 @@
+import Foundation
+
+public struct ShareGatewayRelayConfig: Codable, Sendable, Equatable {
+    public let gatewayURLString: String
+    public let token: String?
+    public let password: String?
+    public let sessionKey: String
+    public let deliveryChannel: String?
+    public let deliveryTo: String?
+
+    public init(
+        gatewayURLString: String,
+        token: String?,
+        password: String?,
+        sessionKey: String,
+        deliveryChannel: String? = nil,
+        deliveryTo: String? = nil)
+    {
+        self.gatewayURLString = gatewayURLString
+        self.token = token
+        self.password = password
+        self.sessionKey = sessionKey
+        self.deliveryChannel = deliveryChannel
+        self.deliveryTo = deliveryTo
+    }
+}
+
+public enum ShareGatewayRelaySettings {
+    private static var suiteName: String { OpenClawAppGroup.identifier }
+    private static let relayConfigKey = "share.gatewayRelay.config.v1"
+    private static let lastEventKey = "share.gatewayRelay.event.v1"
+
+    private static var defaults: UserDefaults {
+        UserDefaults(suiteName: self.suiteName) ?? .standard
+    }
+
+    public static func loadConfig() -> ShareGatewayRelayConfig? {
+        guard let data = self.defaults.data(forKey: self.relayConfigKey) else { return nil }
+        return try? JSONDecoder().decode(ShareGatewayRelayConfig.self, from: data)
+    }
+
+    public static func saveConfig(_ config: ShareGatewayRelayConfig) {
+        guard let data = try? JSONEncoder().encode(config) else { return }
+        self.defaults.set(data, forKey: self.relayConfigKey)
+    }
+
+    public static func clearConfig() {
+        self.defaults.removeObject(forKey: self.relayConfigKey)
+    }
+
+    public static func saveLastEvent(_ message: String) {
+        let timestamp = ISO8601DateFormatter().string(from: Date())
+        let payload = "[\(timestamp)] \(message)"
+        self.defaults.set(payload, forKey: self.lastEventKey)
+    }
+
+    public static func loadLastEvent() -> String? {
+        let value = self.defaults.string(forKey: self.lastEventKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        return value.isEmpty ? nil : value
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ShareToAgentDeepLink.swift

@@ -0,0 +1,70 @@
+import Foundation
+
+public struct SharedContentPayload: Sendable, Equatable {
+    public let title: String?
+    public let url: URL?
+    public let text: String?
+
+    public init(title: String?, url: URL?, text: String?) {
+        self.title = title
+        self.url = url
+        self.text = text
+    }
+}
+
+public enum ShareToAgentDeepLink {
+    public static func buildURL(from payload: SharedContentPayload, instruction: String? = nil) -> URL? {
+        let message = self.buildMessage(from: payload, instruction: instruction)
+        guard !message.isEmpty else { return nil }
+
+        var components = URLComponents()
+        components.scheme = "openclaw"
+        components.host = "agent"
+        components.queryItems = [
+            URLQueryItem(name: "message", value: message),
+            URLQueryItem(name: "thinking", value: "low"),
+        ]
+        return components.url
+    }
+
+    public static func buildMessage(from payload: SharedContentPayload, instruction: String? = nil) -> String {
+        let title = self.clean(payload.title)
+        let text = self.clean(payload.text)
+        let urlText = payload.url?.absoluteString.trimmingCharacters(in: .whitespacesAndNewlines)
+        let resolvedInstruction = self.clean(instruction) ?? self.clean(ShareToAgentSettings.loadDefaultInstruction())
+        let hasSharedContent = title != nil || text != nil || self.clean(urlText) != nil
+
+        guard hasSharedContent || resolvedInstruction != nil else { return "" }
+
+        var lines: [String] = []
+        if hasSharedContent {
+            lines.append("Shared from iOS.")
+        }
+        if let title, !title.isEmpty {
+            lines.append("Title: \(title)")
+        }
+        if let urlText, !urlText.isEmpty {
+            lines.append("URL: \(urlText)")
+        }
+        if let text, !text.isEmpty {
+            lines.append("Text:\n\(text)")
+        }
+        if let resolvedInstruction {
+            lines.append(resolvedInstruction)
+        }
+
+        let message = lines.joined(separator: "\n\n")
+        return self.limit(message, maxCharacters: 2400)
+    }
+
+    private static func clean(_ value: String?) -> String? {
+        guard let value else { return nil }
+        let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func limit(_ value: String, maxCharacters: Int) -> String {
+        guard value.count > maxCharacters else { return value }
+        return String(value.prefix(maxCharacters))
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ShareToAgentSettings.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+public enum ShareToAgentSettings {
+    private static var suiteName: String { OpenClawAppGroup.identifier }
+    private static let defaultInstructionKey = "share.defaultInstruction"
+
+    private static var defaults: UserDefaults {
+        UserDefaults(suiteName: suiteName) ?? .standard
+    }
+
+    public static func loadDefaultInstruction() -> String {
+        let raw = self.defaults.string(forKey: self.defaultInstructionKey)?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        if let raw, !raw.isEmpty {
+            return raw
+        }
+        return ""
+    }
+
+    public static func saveDefaultInstruction(_ value: String?) {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        if trimmed.isEmpty {
+            self.defaults.removeObject(forKey: self.defaultInstructionKey)
+            return
+        }
+        self.defaults.set(trimmed, forKey: self.defaultInstructionKey)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/StoragePaths.swift

@@ -0,0 +1,37 @@
+import Foundation
+
+public enum OpenClawNodeStorage {
+    public static func appSupportDir() throws -> URL {
+        let base = FileManager().urls(for: .applicationSupportDirectory, in: .userDomainMask).first
+        guard let base else {
+            throw NSError(domain: "OpenClawNodeStorage", code: 1, userInfo: [
+                NSLocalizedDescriptionKey: "Application Support directory unavailable",
+            ])
+        }
+        return base.appendingPathComponent("OpenClaw", isDirectory: true)
+    }
+
+    public static func canvasRoot(sessionKey: String) throws -> URL {
+        let root = try appSupportDir().appendingPathComponent("canvas", isDirectory: true)
+        let safe = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        let session = safe.isEmpty ? "main" : safe
+        return root.appendingPathComponent(session, isDirectory: true)
+    }
+
+    public static func cachesDir() throws -> URL {
+        let base = FileManager().urls(for: .cachesDirectory, in: .userDomainMask).first
+        guard let base else {
+            throw NSError(domain: "OpenClawNodeStorage", code: 2, userInfo: [
+                NSLocalizedDescriptionKey: "Caches directory unavailable",
+            ])
+        }
+        return base.appendingPathComponent("OpenClaw", isDirectory: true)
+    }
+
+    public static func canvasSnapshotsRoot(sessionKey: String) throws -> URL {
+        let root = try cachesDir().appendingPathComponent("canvas-snapshots", isDirectory: true)
+        let safe = sessionKey.trimmingCharacters(in: .whitespacesAndNewlines)
+        let session = safe.isEmpty ? "main" : safe
+        return root.appendingPathComponent(session, isDirectory: true)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/SystemCommands.swift

@@ -0,0 +1,91 @@
+import Foundation
+
+public enum OpenClawSystemCommand: String, Codable, Sendable {
+    case run = "system.run"
+    case which = "system.which"
+    case notify = "system.notify"
+    case execApprovalsGet = "system.execApprovals.get"
+    case execApprovalsSet = "system.execApprovals.set"
+}
+
+public enum OpenClawNotificationPriority: String, Codable, Sendable {
+    case passive
+    case active
+    case timeSensitive
+}
+
+public enum OpenClawNotificationDelivery: String, Codable, Sendable {
+    case system
+    case overlay
+    case auto
+}
+
+public struct OpenClawSystemRunParams: Codable, Sendable, Equatable {
+    public var command: [String]
+    public var rawCommand: String?
+    public var cwd: String?
+    public var env: [String: String]?
+    public var timeoutMs: Int?
+    public var needsScreenRecording: Bool?
+    public var agentId: String?
+    public var sessionKey: String?
+    public var runId: String?
+    public var approved: Bool?
+    public var approvalDecision: String?
+
+    public init(
+        command: [String],
+        rawCommand: String? = nil,
+        cwd: String? = nil,
+        env: [String: String]? = nil,
+        timeoutMs: Int? = nil,
+        needsScreenRecording: Bool? = nil,
+        agentId: String? = nil,
+        sessionKey: String? = nil,
+        runId: String? = nil,
+        approved: Bool? = nil,
+        approvalDecision: String? = nil)
+    {
+        self.command = command
+        self.rawCommand = rawCommand
+        self.cwd = cwd
+        self.env = env
+        self.timeoutMs = timeoutMs
+        self.needsScreenRecording = needsScreenRecording
+        self.agentId = agentId
+        self.sessionKey = sessionKey
+        self.runId = runId
+        self.approved = approved
+        self.approvalDecision = approvalDecision
+    }
+}
+
+public struct OpenClawSystemWhichParams: Codable, Sendable, Equatable {
+    public var bins: [String]
+
+    public init(bins: [String]) {
+        self.bins = bins
+    }
+}
+
+public struct OpenClawSystemNotifyParams: Codable, Sendable, Equatable {
+    public var title: String
+    public var body: String
+    public var sound: String?
+    public var priority: OpenClawNotificationPriority?
+    public var delivery: OpenClawNotificationDelivery?
+
+    public init(
+        title: String,
+        body: String,
+        sound: String? = nil,
+        priority: OpenClawNotificationPriority? = nil,
+        delivery: OpenClawNotificationDelivery? = nil)
+    {
+        self.title = title
+        self.body = body
+        self.sound = sound
+        self.priority = priority
+        self.delivery = delivery
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/TalkCommands.swift

@@ -0,0 +1,28 @@
+import Foundation
+
+public enum OpenClawTalkCommand: String, Codable, Sendable {
+    case pttStart = "talk.ptt.start"
+    case pttStop = "talk.ptt.stop"
+    case pttCancel = "talk.ptt.cancel"
+    case pttOnce = "talk.ptt.once"
+}
+
+public struct OpenClawTalkPTTStartPayload: Codable, Sendable, Equatable {
+    public var captureId: String
+
+    public init(captureId: String) {
+        self.captureId = captureId
+    }
+}
+
+public struct OpenClawTalkPTTStopPayload: Codable, Sendable, Equatable {
+    public var captureId: String
+    public var transcript: String?
+    public var status: String
+
+    public init(captureId: String, transcript: String?, status: String) {
+        self.captureId = captureId
+        self.transcript = transcript
+        self.status = status
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/TalkConfigParsing.swift

@@ -0,0 +1,116 @@
+import Foundation
+
+public struct TalkProviderConfigSelection: Sendable {
+    public let provider: String
+    public let config: [String: AnyCodable]
+    public let normalizedPayload: Bool
+
+    public init(provider: String, config: [String: AnyCodable], normalizedPayload: Bool) {
+        self.provider = provider
+        self.config = config
+        self.normalizedPayload = normalizedPayload
+    }
+}
+
+public enum TalkConfigParsing {
+    public static func bridgeFoundationDictionary(_ raw: [String: Any]?) -> [String: AnyCodable]? {
+        raw?.mapValues(AnyCodable.init)
+    }
+
+    public static func selectProviderConfig(
+        _ talk: [String: AnyCodable]?,
+        defaultProvider: String,
+        allowLegacyFallback: Bool = true) -> TalkProviderConfigSelection?
+    {
+        guard let talk else { return nil }
+        if let resolvedSelection = self.resolvedProviderConfig(talk) {
+            return resolvedSelection
+        }
+        let hasNormalizedPayload = talk["provider"] != nil || talk["providers"] != nil
+        if hasNormalizedPayload {
+            return nil
+        }
+        guard allowLegacyFallback else { return nil }
+        return TalkProviderConfigSelection(
+            provider: defaultProvider,
+            config: talk,
+            normalizedPayload: false)
+    }
+
+    public static func resolvedPositiveInt(_ value: AnyCodable?, fallback: Int) -> Int {
+        if let timeout = value?.intValue, timeout > 0 {
+            return timeout
+        }
+        if
+            let timeout = value?.doubleValue,
+            timeout > 0,
+            timeout.rounded(.towardZero) == timeout,
+            timeout <= Double(Int.max)
+        {
+            return Int(timeout)
+        }
+        return fallback
+    }
+
+    public static func resolvedSilenceTimeoutMs(_ talk: [String: AnyCodable]?, fallback: Int) -> Int {
+        self.resolvedPositiveInt(talk?["silenceTimeoutMs"], fallback: fallback)
+    }
+
+    public static func normalizedSpeechLocaleID(_ value: String?) -> String? {
+        let trimmed = (value ?? "").trimmingCharacters(in: .whitespacesAndNewlines)
+        return trimmed.isEmpty ? nil : trimmed.replacingOccurrences(of: "_", with: "-")
+    }
+
+    public static func resolvedSpeechLocaleID(
+        _ talk: [String: AnyCodable]?,
+        fallback: String? = nil) -> String?
+    {
+        self.normalizedSpeechLocaleID(talk?["speechLocale"]?.stringValue)
+            ?? self.normalizedSpeechLocaleID(fallback)
+    }
+
+    public static func normalizedExplicitSpeechLocaleID(
+        _ value: String?,
+        automaticID: String = "auto") -> String?
+    {
+        let normalized = self.normalizedSpeechLocaleID(value)
+        return normalized == automaticID ? nil : normalized
+    }
+
+    public static func resolvedSpeechRecognitionLocaleID(
+        preferredLocaleIDs: [String?],
+        fallbackLocaleID: String = "en-US",
+        supportedLocaleIDs: Set<String>) -> String?
+    {
+        let supported = Set(supportedLocaleIDs.compactMap(self.normalizedSpeechLocaleID))
+        var seen = Set<String>()
+        let candidates = (preferredLocaleIDs + [fallbackLocaleID])
+            .compactMap(self.normalizedSpeechLocaleID)
+
+        for candidate in candidates {
+            guard seen.insert(candidate).inserted else { continue }
+            if supported.isEmpty || supported.contains(candidate) {
+                return candidate
+            }
+        }
+        return nil
+    }
+
+    private static func normalizedTalkProviderID(_ raw: String?) -> String? {
+        let trimmed = (raw ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+        return trimmed.isEmpty ? nil : trimmed
+    }
+
+    private static func resolvedProviderConfig(
+        _ talk: [String: AnyCodable]) -> TalkProviderConfigSelection?
+    {
+        guard
+            let resolved = talk["resolved"]?.dictionaryValue,
+            let providerID = self.normalizedTalkProviderID(resolved["provider"]?.stringValue)
+        else { return nil }
+        return TalkProviderConfigSelection(
+            provider: providerID,
+            config: resolved["config"]?.dictionaryValue ?? [:],
+            normalizedPayload: true)
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/TalkDirective.swift

@@ -0,0 +1,201 @@
+import Foundation
+
+public struct TalkDirective: Equatable, Sendable {
+    public var voiceId: String?
+    public var modelId: String?
+    public var speed: Double?
+    public var rateWPM: Int?
+    public var stability: Double?
+    public var similarity: Double?
+    public var style: Double?
+    public var speakerBoost: Bool?
+    public var seed: Int?
+    public var normalize: String?
+    public var language: String?
+    public var outputFormat: String?
+    public var latencyTier: Int?
+    public var once: Bool?
+
+    public init(
+        voiceId: String? = nil,
+        modelId: String? = nil,
+        speed: Double? = nil,
+        rateWPM: Int? = nil,
+        stability: Double? = nil,
+        similarity: Double? = nil,
+        style: Double? = nil,
+        speakerBoost: Bool? = nil,
+        seed: Int? = nil,
+        normalize: String? = nil,
+        language: String? = nil,
+        outputFormat: String? = nil,
+        latencyTier: Int? = nil,
+        once: Bool? = nil)
+    {
+        self.voiceId = voiceId
+        self.modelId = modelId
+        self.speed = speed
+        self.rateWPM = rateWPM
+        self.stability = stability
+        self.similarity = similarity
+        self.style = style
+        self.speakerBoost = speakerBoost
+        self.seed = seed
+        self.normalize = normalize
+        self.language = language
+        self.outputFormat = outputFormat
+        self.latencyTier = latencyTier
+        self.once = once
+    }
+}
+
+public struct TalkDirectiveParseResult: Equatable, Sendable {
+    public let directive: TalkDirective?
+    public let stripped: String
+    public let unknownKeys: [String]
+
+    public init(directive: TalkDirective?, stripped: String, unknownKeys: [String]) {
+        self.directive = directive
+        self.stripped = stripped
+        self.unknownKeys = unknownKeys
+    }
+}
+
+public enum TalkDirectiveParser {
+    public static func parse(_ text: String) -> TalkDirectiveParseResult {
+        let normalized = text.replacingOccurrences(of: "\r\n", with: "\n")
+        var lines = normalized.split(separator: "\n", omittingEmptySubsequences: false)
+        guard !lines.isEmpty else { return TalkDirectiveParseResult(directive: nil, stripped: text, unknownKeys: []) }
+
+        guard let firstNonEmptyIndex =
+            lines.firstIndex(where: { !$0.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty })
+        else {
+            return TalkDirectiveParseResult(directive: nil, stripped: text, unknownKeys: [])
+        }
+
+        var firstNonEmpty = firstNonEmptyIndex
+        if firstNonEmpty > 0 {
+            lines.removeSubrange(0..<firstNonEmpty)
+            firstNonEmpty = 0
+        }
+
+        let head = lines[firstNonEmpty].trimmingCharacters(in: .whitespacesAndNewlines)
+        guard head.hasPrefix("{"), head.hasSuffix("}") else {
+            return TalkDirectiveParseResult(directive: nil, stripped: text, unknownKeys: [])
+        }
+
+        guard let data = head.data(using: .utf8),
+              let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any]
+        else {
+            return TalkDirectiveParseResult(directive: nil, stripped: text, unknownKeys: [])
+        }
+
+        let speakerBoost = self.boolValue(json, keys: ["speaker_boost", "speakerBoost"])
+            ?? self.boolValue(json, keys: ["no_speaker_boost", "noSpeakerBoost"]).map { !$0 }
+
+        let directive = TalkDirective(
+            voiceId: stringValue(json, keys: ["voice", "voice_id", "voiceId"]),
+            modelId: stringValue(json, keys: ["model", "model_id", "modelId"]),
+            speed: doubleValue(json, keys: ["speed"]),
+            rateWPM: intValue(json, keys: ["rate", "wpm"]),
+            stability: doubleValue(json, keys: ["stability"]),
+            similarity: doubleValue(json, keys: ["similarity", "similarity_boost", "similarityBoost"]),
+            style: doubleValue(json, keys: ["style"]),
+            speakerBoost: speakerBoost,
+            seed: intValue(json, keys: ["seed"]),
+            normalize: stringValue(json, keys: ["normalize", "apply_text_normalization"]),
+            language: stringValue(json, keys: ["lang", "language_code", "language"]),
+            outputFormat: stringValue(json, keys: ["output_format", "format"]),
+            latencyTier: intValue(json, keys: ["latency", "latency_tier", "latencyTier"]),
+            once: boolValue(json, keys: ["once"]))
+
+        let hasDirective = [
+            directive.voiceId,
+            directive.modelId,
+            directive.speed.map { "\($0)" },
+            directive.rateWPM.map { "\($0)" },
+            directive.stability.map { "\($0)" },
+            directive.similarity.map { "\($0)" },
+            directive.style.map { "\($0)" },
+            directive.speakerBoost.map { "\($0)" },
+            directive.seed.map { "\($0)" },
+            directive.normalize,
+            directive.language,
+            directive.outputFormat,
+            directive.latencyTier.map { "\($0)" },
+            directive.once.map { "\($0)" },
+        ].contains { $0 != nil }
+
+        guard hasDirective else {
+            return TalkDirectiveParseResult(directive: nil, stripped: text, unknownKeys: [])
+        }
+
+        let knownKeys = Set([
+            "voice", "voice_id", "voiceid",
+            "model", "model_id", "modelid",
+            "speed", "rate", "wpm",
+            "stability", "similarity", "similarity_boost", "similarityboost",
+            "style",
+            "speaker_boost", "speakerboost",
+            "no_speaker_boost", "nospeakerboost",
+            "seed",
+            "normalize", "apply_text_normalization",
+            "lang", "language_code", "language",
+            "output_format", "format",
+            "latency", "latency_tier", "latencytier",
+            "once",
+        ])
+        let unknownKeys = json.keys.filter { !knownKeys.contains($0.lowercased()) }.sorted()
+
+        lines.remove(at: firstNonEmpty)
+        if firstNonEmpty < lines.count {
+            let next = lines[firstNonEmpty].trimmingCharacters(in: .whitespacesAndNewlines)
+            if next.isEmpty {
+                lines.remove(at: firstNonEmpty)
+            }
+        }
+
+        let stripped = lines.joined(separator: "\n")
+        return TalkDirectiveParseResult(directive: directive, stripped: stripped, unknownKeys: unknownKeys)
+    }
+
+    private static func stringValue(_ dict: [String: Any], keys: [String]) -> String? {
+        for key in keys {
+            if let value = dict[key] as? String {
+                let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
+                if !trimmed.isEmpty { return trimmed }
+            }
+        }
+        return nil
+    }
+
+    private static func doubleValue(_ dict: [String: Any], keys: [String]) -> Double? {
+        for key in keys {
+            if let value = dict[key] as? Double { return value }
+            if let value = dict[key] as? Int { return Double(value) }
+            if let value = dict[key] as? String, let parsed = Double(value) { return parsed }
+        }
+        return nil
+    }
+
+    private static func intValue(_ dict: [String: Any], keys: [String]) -> Int? {
+        for key in keys {
+            if let value = dict[key] as? Int { return value }
+            if let value = dict[key] as? Double { return Int(value) }
+            if let value = dict[key] as? String, let parsed = Int(value) { return parsed }
+        }
+        return nil
+    }
+
+    private static func boolValue(_ dict: [String: Any], keys: [String]) -> Bool? {
+        for key in keys {
+            if let value = dict[key] as? Bool { return value }
+            if let value = dict[key] as? String {
+                let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+                if ["true", "yes", "1"].contains(trimmed) { return true }
+                if ["false", "no", "0"].contains(trimmed) { return false }
+            }
+        }
+        return nil
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/TalkHistoryTimestamp.swift

@@ -0,0 +1,12 @@
+public enum TalkHistoryTimestamp: Sendable {
+    /// Gateway history timestamps have historically been emitted as either seconds (Double, epoch seconds)
+    /// or milliseconds (Double, epoch ms). This helper accepts either.
+    public static func isAfter(_ timestamp: Double, sinceSeconds: Double) -> Bool {
+        let sinceMs = sinceSeconds * 1000
+        // ~2286-11-20 in epoch seconds. Anything bigger is almost certainly epoch milliseconds.
+        if timestamp > 10_000_000_000 {
+            return timestamp >= sinceMs - 500
+        }
+        return timestamp >= sinceSeconds - 0.5
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/TalkPromptBuilder.swift

@@ -0,0 +1,25 @@
+public enum TalkPromptBuilder: Sendable {
+    public static func build(
+        transcript: String,
+        interruptedAtSeconds: Double?,
+        includeVoiceDirectiveHint: Bool = true) -> String
+    {
+        var lines: [String] = [
+            "Talk Mode active. Reply in a concise, spoken tone.",
+        ]
+
+        if includeVoiceDirectiveHint {
+            lines.append(
+                "You may optionally prefix the response with JSON (first line) to set ElevenLabs voice (id or alias), e.g. {\"voice\":\"<id>\",\"once\":true}.")
+        }
+
+        if let interruptedAtSeconds {
+            let formatted = String(format: "%.1f", interruptedAtSeconds)
+            lines.append("Assistant speech interrupted at \(formatted)s.")
+        }
+
+        lines.append("")
+        lines.append(transcript)
+        return lines.joined(separator: "\n")
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/TalkSystemSpeechSynthesizer.swift

@@ -0,0 +1,179 @@
+import AVFoundation
+import Foundation
+
+@MainActor
+public final class TalkSystemSpeechSynthesizer: NSObject {
+    public enum SpeakError: Error {
+        case canceled
+    }
+
+    public static let shared = TalkSystemSpeechSynthesizer()
+
+    private let synth = AVSpeechSynthesizer()
+    private var speakContinuation: CheckedContinuation<Void, Error>?
+    private var currentUtterance: AVSpeechUtterance?
+    private var didStartCallback: (() -> Void)?
+    private var currentToken = UUID()
+    private var watchdog: Task<Void, Never>?
+
+    public var isSpeaking: Bool {
+        self.synth.isSpeaking
+    }
+
+    override private init() {
+        super.init()
+        self.synth.delegate = self
+    }
+
+    public func stop() {
+        self.currentToken = UUID()
+        self.watchdog?.cancel()
+        self.watchdog = nil
+        self.didStartCallback = nil
+        self.synth.stopSpeaking(at: .immediate)
+        self.finishCurrent(with: SpeakError.canceled)
+    }
+
+    public func speak(
+        text: String,
+        language: String? = nil,
+        onStart: (() -> Void)? = nil) async throws
+    {
+        let trimmed = text.trimmingCharacters(in: .whitespacesAndNewlines)
+        guard !trimmed.isEmpty else { return }
+
+        self.stop()
+        let token = UUID()
+        self.currentToken = token
+        self.didStartCallback = onStart
+
+        let utterance = AVSpeechUtterance(string: trimmed)
+        if let language, let voice = AVSpeechSynthesisVoice(language: language) {
+            utterance.voice = voice
+        }
+        self.currentUtterance = utterance
+
+        let watchdogTimeout = Self.watchdogTimeoutSeconds(
+            text: trimmed,
+            language: language ?? utterance.voice?.language)
+        self.watchdog?.cancel()
+        self.watchdog = Task { @MainActor [weak self] in
+            guard let self else { return }
+            try? await Task.sleep(nanoseconds: UInt64(watchdogTimeout * 1_000_000_000))
+            if Task.isCancelled { return }
+            guard self.currentToken == token else { return }
+            if self.synth.isSpeaking {
+                self.synth.stopSpeaking(at: .immediate)
+            }
+            self.finishCurrent(
+                with: NSError(domain: "TalkSystemSpeechSynthesizer", code: 408, userInfo: [
+                    NSLocalizedDescriptionKey: "system TTS timed out after \(watchdogTimeout)s",
+                ]))
+        }
+
+        try await withTaskCancellationHandler(operation: {
+            try await withCheckedThrowingContinuation { cont in
+                self.speakContinuation = cont
+                self.synth.speak(utterance)
+            }
+        }, onCancel: {
+            Task { @MainActor in
+                self.stop()
+            }
+        })
+
+        if self.currentToken != token {
+            throw SpeakError.canceled
+        }
+    }
+
+    static func watchdogTimeoutSeconds(text: String, language: String?) -> Double {
+        // Estimate speech duration per language, then apply 3x safety margin.
+        // The watchdog is a hang guard — normal completion relies on didFinish.
+        //
+        // Speech rates based on Pellegrino et al. (2019) syllable-per-second data,
+        // adjusted for TTS synthesis (slower than natural speech):
+        // https://www.science.org/doi/10.1126/sciadv.aaw2594
+        //   Japanese: 7.84 SPS -> ~0.20s/char (mixed kana/kanji avg ~1.5 mora/char)
+        //   Korean:   5.96 SPS -> ~0.25s/char (1 char = 1 syllable)
+        //   Chinese:  5.18 SPS -> ~0.28s/char (1 char = 1 syllable)
+        //   English:  6.19 SPS -> ~0.08s/char (avg ~5 chars/syllable)
+        let normalizedLanguage = language?.lowercased() ?? "en"
+        let perCharSeconds: Double
+        let minSeconds: Double
+        if normalizedLanguage.hasPrefix("ko") {
+            perCharSeconds = 0.25
+            minSeconds = 10.0
+        } else if normalizedLanguage.hasPrefix("zh") {
+            perCharSeconds = 0.28
+            minSeconds = 10.0
+        } else if normalizedLanguage.hasPrefix("ja") {
+            perCharSeconds = 0.20
+            minSeconds = 10.0
+        } else {
+            perCharSeconds = 0.08
+            minSeconds = 3.0
+        }
+        let estimatedSeconds = max(minSeconds, min(300.0, Double(text.count) * perCharSeconds))
+        return estimatedSeconds * 3.0
+    }
+
+    private func matchesCurrentUtterance(_ utteranceID: ObjectIdentifier) -> Bool {
+        guard let currentUtterance = self.currentUtterance else { return false }
+        return ObjectIdentifier(currentUtterance) == utteranceID
+    }
+
+    private func handleFinish(utteranceID: ObjectIdentifier, error: Error?) {
+        guard self.matchesCurrentUtterance(utteranceID) else { return }
+        self.watchdog?.cancel()
+        self.watchdog = nil
+        self.finishCurrent(with: error)
+    }
+
+    private func finishCurrent(with error: Error?) {
+        self.currentUtterance = nil
+        self.didStartCallback = nil
+        let cont = self.speakContinuation
+        self.speakContinuation = nil
+        if let error {
+            cont?.resume(throwing: error)
+        } else {
+            cont?.resume(returning: ())
+        }
+    }
+}
+
+extension TalkSystemSpeechSynthesizer: AVSpeechSynthesizerDelegate {
+    public nonisolated func speechSynthesizer(
+        _ synthesizer: AVSpeechSynthesizer,
+        didStart utterance: AVSpeechUtterance)
+    {
+        let utteranceID = ObjectIdentifier(utterance)
+        Task { @MainActor in
+            guard self.matchesCurrentUtterance(utteranceID) else { return }
+            let callback = self.didStartCallback
+            self.didStartCallback = nil
+            callback?()
+        }
+    }
+
+    public nonisolated func speechSynthesizer(
+        _ synthesizer: AVSpeechSynthesizer,
+        didFinish utterance: AVSpeechUtterance)
+    {
+        let utteranceID = ObjectIdentifier(utterance)
+        Task { @MainActor in
+            self.handleFinish(utteranceID: utteranceID, error: nil)
+        }
+    }
+
+    public nonisolated func speechSynthesizer(
+        _ synthesizer: AVSpeechSynthesizer,
+        didCancel utterance: AVSpeechUtterance)
+    {
+        let utteranceID = ObjectIdentifier(utterance)
+        Task { @MainActor in
+            self.handleFinish(utteranceID: utteranceID, error: SpeakError.canceled)
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ThrowingContinuationSupport.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+public enum ThrowingContinuationSupport {
+    public static func resumeVoid(_ continuation: CheckedContinuation<Void, Error>, error: Error?) {
+        if let error {
+            continuation.resume(throwing: error)
+        } else {
+            continuation.resume(returning: ())
+        }
+    }
+}

apps/shared/OpenClawKit/Sources/OpenClawKit/ToolDisplay.swift

@@ -0,0 +1,228 @@
+import Foundation
+
+public struct ToolDisplaySummary: Sendable, Equatable {
+    public let name: String
+    public let emoji: String
+    public let title: String
+    public let label: String
+    public let verb: String?
+    public let detail: String?
+
+    public var detailLine: String? {
+        var parts: [String] = []
+        if let verb, !verb.isEmpty { parts.append(verb) }
+        if let detail, !detail.isEmpty { parts.append(detail) }
+        return parts.isEmpty ? nil : parts.joined(separator: " · ")
+    }
+
+    public var summaryLine: String {
+        if let detailLine {
+            return "\(self.emoji) \(self.label): \(detailLine)"
+        }
+        return "\(self.emoji) \(self.label)"
+    }
+}
+
+public enum ToolDisplayRegistry {
+    private struct ToolDisplayActionSpec: Decodable {
+        let label: String?
+        let detailKeys: [String]?
+    }
+
+    private struct ToolDisplaySpec: Decodable {
+        let emoji: String?
+        let title: String?
+        let label: String?
+        let detailKeys: [String]?
+        let actions: [String: ToolDisplayActionSpec]?
+    }
+
+    private struct ToolDisplayConfig: Decodable {
+        let version: Int?
+        let fallback: ToolDisplaySpec?
+        let tools: [String: ToolDisplaySpec]?
+    }
+
+    private static let config: ToolDisplayConfig = loadConfig()
+
+    public static func resolve(name: String?, args: AnyCodable?, meta: String? = nil) -> ToolDisplaySummary {
+        let trimmedName = name?.trimmingCharacters(in: .whitespacesAndNewlines) ?? "tool"
+        let key = trimmedName.lowercased()
+        let spec = self.config.tools?[key]
+        let fallback = self.config.fallback
+
+        let emoji = spec?.emoji ?? fallback?.emoji ?? "🧩"
+        let title = spec?.title ?? self.titleFromName(trimmedName)
+        let label = spec?.label ?? trimmedName
+
+        let actionRaw = self.valueForKeyPath(args, path: "action") as? String
+        let action = actionRaw?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let actionSpec = action.flatMap { spec?.actions?[$0] }
+        let verb = self.normalizeVerb(actionSpec?.label ?? action)
+
+        var detail: String?
+        if key == "read" {
+            detail = self.readDetail(args)
+        } else if key == "write" || key == "edit" || key == "attach" {
+            detail = self.pathDetail(args)
+        }
+
+        let detailKeys = actionSpec?.detailKeys ?? spec?.detailKeys ?? fallback?.detailKeys ?? []
+        if detail == nil {
+            detail = self.firstValue(args, keys: detailKeys)
+        }
+
+        if detail == nil {
+            detail = meta
+        }
+
+        if let detailValue = detail {
+            detail = self.shortenHomeInString(detailValue)
+        }
+
+        return ToolDisplaySummary(
+            name: trimmedName,
+            emoji: emoji,
+            title: title,
+            label: label,
+            verb: verb,
+            detail: detail)
+    }
+
+    private static func loadConfig() -> ToolDisplayConfig {
+        guard let url = OpenClawKitResources.bundle.url(forResource: "tool-display", withExtension: "json") else {
+            return self.defaultConfig()
+        }
+        do {
+            let data = try Data(contentsOf: url)
+            return try JSONDecoder().decode(ToolDisplayConfig.self, from: data)
+        } catch {
+            return self.defaultConfig()
+        }
+    }
+
+    private static func defaultConfig() -> ToolDisplayConfig {
+        ToolDisplayConfig(
+            version: 1,
+            fallback: ToolDisplaySpec(
+                emoji: "🧩",
+                title: nil,
+                label: nil,
+                detailKeys: [
+                    "command",
+                    "path",
+                    "url",
+                    "targetUrl",
+                    "targetId",
+                    "ref",
+                    "element",
+                    "node",
+                    "nodeId",
+                    "id",
+                    "requestId",
+                    "to",
+                    "channelId",
+                    "guildId",
+                    "userId",
+                    "name",
+                    "query",
+                    "pattern",
+                    "messageId",
+                ],
+                actions: nil),
+            tools: nil)
+    }
+
+    private static func titleFromName(_ name: String) -> String {
+        let cleaned = name.replacingOccurrences(of: "_", with: " ").trimmingCharacters(in: .whitespaces)
+        guard !cleaned.isEmpty else { return "Tool" }
+        return cleaned
+            .split(separator: " ")
+            .map { part in
+                let upper = part.uppercased()
+                if part.count <= 2, part == upper { return String(part) }
+                return String(upper.prefix(1)) + String(part.lowercased().dropFirst())
+            }
+            .joined(separator: " ")
+    }
+
+    private static func normalizeVerb(_ value: String?) -> String? {
+        let trimmed = value?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
+        guard !trimmed.isEmpty else { return nil }
+        return trimmed.replacingOccurrences(of: "_", with: " ")
+    }
+
+    private static func readDetail(_ args: AnyCodable?) -> String? {
+        guard let path = valueForKeyPath(args, path: "path") as? String else { return nil }
+        let offsetAny = self.valueForKeyPath(args, path: "offset")
+        let limitAny = self.valueForKeyPath(args, path: "limit")
+        let offset = (offsetAny as? Double) ?? (offsetAny as? Int).map(Double.init)
+        let limit = (limitAny as? Double) ?? (limitAny as? Int).map(Double.init)
+        if let offset, let limit {
+            let end = offset + limit
+            return "\(path):\(Int(offset))-\(Int(end))"
+        }
+        return path
+    }
+
+    private static func pathDetail(_ args: AnyCodable?) -> String? {
+        self.valueForKeyPath(args, path: "path") as? String
+    }
+
+    private static func firstValue(_ args: AnyCodable?, keys: [String]) -> String? {
+        for key in keys {
+            if let value = valueForKeyPath(args, path: key),
+               let rendered = renderValue(value)
+            {
+                return rendered
+            }
+        }
+        return nil
+    }
+
+    private static func renderValue(_ value: Any) -> String? {
+        if let str = value as? String {
+            let trimmed = str.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return nil }
+            let first = trimmed.split(whereSeparator: \.isNewline).first.map(String.init) ?? trimmed
+            if first.count > 160 { return String(first.prefix(157)) + "…" }
+            return first
+        }
+        if let num = value as? Int { return String(num) }
+        if let num = value as? Double { return String(num) }
+        if let bool = value as? Bool { return bool ? "true" : "false" }
+        if let array = value as? [Any] {
+            let items = array.compactMap { self.renderValue($0) }
+            guard !items.isEmpty else { return nil }
+            let preview = items.prefix(3).joined(separator: ", ")
+            return items.count > 3 ? "\(preview)…" : preview
+        }
+        if let dict = value as? [String: Any] {
+            if let label = dict["name"].flatMap({ renderValue($0) }) { return label }
+            if let label = dict["id"].flatMap({ renderValue($0) }) { return label }
+        }
+        return nil
+    }
+
+    private static func valueForKeyPath(_ args: AnyCodable?, path: String) -> Any? {
+        guard let args else { return nil }
+        let parts = path.split(separator: ".").map(String.init)
+        var current: Any? = args.value
+        for part in parts {
+            if let dict = current as? [String: AnyCodable] {
+                current = dict[part]?.value
+            } else if let dict = current as? [String: Any] {
+                current = dict[part]
+            } else {
+                return nil
+            }
+        }
+        return current
+    }
+
+    private static func shortenHomeInString(_ value: String) -> String {
+        let home = NSHomeDirectory()
+        guard !home.isEmpty else { return value }
+        return value.replacingOccurrences(of: home, with: "~")
+    }
+}