native macOS codings agent orchestrator prowl.onev.cat
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616import Foundation
nonisolated struct MirrorPaneDescriptor: Codable, Equatable, Identifiable, Sendable { let id: UUID let title: String let directory: String let busy: Bool var projectName: String? var subtitle: String? var role: String?}
nonisolated struct MirrorFrame: Codable, Equatable, Sendable { let columns: UInt32 let rows: UInt32 let bytes: Data var viewportText: String? var scrollBounds: MirrorScrollBounds? var styledScrollback: MirrorStyledScrollback?}
nonisolated struct MirrorStyledScrollback: Codable, Equatable, Sendable { static let maximumBytes = 2 * 1024 * 1024 let bytes: Data let rowOffset: Int
var isValid: Bool { !bytes.isEmpty && bytes.count <= Self.maximumBytes && (0...5000).contains(rowOffset) }}
nonisolated struct MirrorScrollBounds: Codable, Equatable, Sendable { var atTop: Bool? var atBottom: Bool?}
nonisolated enum MirrorMessage: Codable, Sendable { enum Representation: String, Codable, Sendable { case terminal = "vt-v1" case text = "text-v1" } enum Intent: String, Codable, Sendable { case takeover, ifFree } enum ScrollDirection: String, Codable, Sendable { case upward = "up" case downward = "down" } enum EndReason: String, Codable, Sendable { case takenOver, hostStopped, paneClosed } case challenge(Challenge) case authenticate(Authentication) case pair(PairRequest) case paired(MirrorDeviceCredential) case authenticated(UUID) struct Challenge: Codable, Sendable { let hostID: UUID let nonce: Data } struct Authentication: Codable, Sendable { let deviceID: UUID let proof: Data } struct PairRequest: Codable, Sendable { let name: String let proof: Data } enum Kind: String, Codable { case challenge, authenticate, pair, paired, authenticated, list, panes, subscribe, subscribed, frame, textFrame, viewport, acknowledge, input, history, historyPage, failure, ping, pong, ended, refresh, scroll, scrollResult, scrollState, command, commandResult, commandReceipt } case list case panes(PanesPayload) struct PanesPayload: Codable, Sendable { var panes: [MirrorPaneDescriptor] var capabilities: [String] var hostRunID: UUID } case subscribe(SubscribePayload) struct SubscribePayload: Codable, Sendable { var paneID: UUID var representation: Representation var intent: Intent var includeViewportText: Bool? var includeScrollState: Bool? var includeStyledScrollback: Bool? } case subscribed(SubscribedPayload) struct SubscribedPayload: Codable, Sendable { var paneID: UUID var subscriptionID: UUID var hostRunID: UUID } case frame(FramePayload) struct FramePayload: Codable, Sendable { var frame: MirrorFrame var sequence: UInt64 var subscriptionID: UUID } case textFrame(TextFramePayload) struct TextFramePayload: Codable, Sendable { var columns: UInt32 = 0 var rows: UInt32 = 0 var truncated: Bool = false var sequence: UInt64 var text: String var subscriptionID: UUID var scrollBounds: MirrorScrollBounds? } case viewport(ViewportPayload) struct ViewportPayload: Codable, Sendable { var styledScrollback: MirrorStyledScrollback? var text: String? var sequence: UInt64 var subscriptionID: UUID } case acknowledge(AcknowledgePayload) struct AcknowledgePayload: Codable, Sendable { var sequence: UInt64 var subscriptionID: UUID } case input(InputPayload) struct InputPayload: Codable, Sendable { var bytes: Data var subscriptionID: UUID } case scroll(ScrollPayload) struct ScrollPayload: Codable, Sendable { var requestID: UUID var direction: ScrollDirection var subscriptionID: UUID } case scrollResult(ScrollResultPayload) struct ScrollResultPayload: Codable, Sendable { var requestID: UUID var sequence: UInt64 var subscriptionID: UUID } case scrollState(ScrollStatePayload) struct ScrollStatePayload: Codable, Sendable { var atTop: Bool? var atBottom: Bool? var sequence: UInt64 var subscriptionID: UUID } case history(HistoryPayload) struct HistoryPayload: Codable, Sendable { var historyID: UUID? var offset: Int? var subscriptionID: UUID } case historyPage(HistoryPagePayload) struct HistoryPagePayload: Codable, Sendable { var historyID: UUID var offset: Int var lines: [String] var total: Int var subscriptionID: UUID var capturedAt: TimeInterval var truncated: Bool } case failure(FailurePayload) struct FailurePayload: Codable, Sendable { var error: String var subscriptionID: UUID? var requestID: UUID? } case ping case pong case ended(EndedPayload) struct EndedPayload: Codable, Sendable { var reason: EndReason } case refresh(RefreshPayload) struct RefreshPayload: Codable, Sendable { var subscriptionID: UUID } case command(CommandPayload) struct CommandPayload: Codable, Sendable { var subscriptionID: UUID? var commandRequest: MirrorCommandRequest } case commandResult(CommandResultPayload) struct CommandResultPayload: Codable, Sendable { var commandResponse: MirrorCommandResponse } case commandReceipt(CommandReceiptPayload) struct CommandReceiptPayload: Codable, Sendable { var subscriptionID: UUID var commandReceiptID: UUID } var kind: Kind { switch self { case .challenge: .challenge case .authenticate: .authenticate case .pair: .pair case .paired: .paired case .authenticated: .authenticated case .list: .list case .panes: .panes case .subscribe: .subscribe case .subscribed: .subscribed case .frame: .frame case .textFrame: .textFrame case .viewport: .viewport case .acknowledge: .acknowledge case .input: .input case .scroll: .scroll case .scrollResult: .scrollResult case .scrollState: .scrollState case .history: .history case .historyPage: .historyPage case .failure: .failure case .ping: .ping case .pong: .pong case .ended: .ended case .refresh: .refresh case .command: .command case .commandResult: .commandResult case .commandReceipt: .commandReceipt } } var panes: [MirrorPaneDescriptor]? { switch self { case .panes(let payload): payload.panes default: nil } } var capabilities: [String]? { switch self { case .panes(let payload): payload.capabilities default: nil } } var hostRunID: UUID? { switch self { case .panes(let payload): payload.hostRunID case .subscribed(let payload): payload.hostRunID default: nil } } var paneID: UUID? { switch self { case .subscribe(let payload): payload.paneID case .subscribed(let payload): payload.paneID default: nil } } var representation: Representation? { switch self { case .subscribe(let payload): payload.representation default: nil } } var intent: Intent? { switch self { case .subscribe(let payload): payload.intent default: nil } } var subscriptionID: UUID? { switch self { case .subscribed(let payload): payload.subscriptionID case .frame(let payload): payload.subscriptionID case .textFrame(let payload): payload.subscriptionID case .viewport(let payload): payload.subscriptionID case .acknowledge(let payload): payload.subscriptionID case .input(let payload): payload.subscriptionID case .scroll(let payload): payload.subscriptionID case .scrollResult(let payload): payload.subscriptionID case .scrollState(let payload): payload.subscriptionID case .history(let payload): payload.subscriptionID case .historyPage(let payload): payload.subscriptionID case .failure(let payload): payload.subscriptionID case .refresh(let payload): payload.subscriptionID case .command(let payload): payload.subscriptionID case .commandReceipt(let payload): payload.subscriptionID default: nil } } var frame: MirrorFrame? { switch self { case .frame(let payload): payload.frame default: nil } } var sequence: UInt64? { switch self { case .frame(let payload): payload.sequence case .textFrame(let payload): payload.sequence case .viewport(let payload): payload.sequence case .acknowledge(let payload): payload.sequence case .scrollResult(let payload): payload.sequence case .scrollState(let payload): payload.sequence default: nil } } var text: String? { switch self { case .textFrame(let payload): payload.text default: nil } } var viewportText: String? { switch self { case .viewport(let payload): payload.text default: nil } } var includeStyledScrollback: Bool? { if case .subscribe(let payload) = self { return payload.includeStyledScrollback } return nil } var includeViewportText: Bool? { switch self { case .subscribe(let payload): payload.includeViewportText default: nil } } var includeScrollState: Bool? { switch self { case .subscribe(let payload): payload.includeScrollState default: nil } } var scrollBounds: MirrorScrollBounds? { switch self { case .scrollState(let payload): .init(atTop: payload.atTop, atBottom: payload.atBottom) default: nil } } var bytes: Data? { switch self { case .input(let payload): payload.bytes default: nil } } var scrollDirection: ScrollDirection? { switch self { case .scroll(let payload): payload.direction default: nil } } var scrollRequestID: UUID? { switch self { case .scroll(let payload): payload.requestID case .scrollResult(let payload): payload.requestID case .failure(let payload): payload.requestID default: nil } } var historyID: UUID? { switch self { case .history(let payload): payload.historyID case .historyPage(let payload): payload.historyID default: nil } } var offset: Int? { switch self { case .history(let payload): payload.offset case .historyPage(let payload): payload.offset default: nil } } var lines: [String]? { switch self { case .historyPage(let payload): payload.lines default: nil } } var total: Int? { switch self { case .historyPage(let payload): payload.total default: nil } } var capturedAt: TimeInterval? { switch self { case .historyPage(let payload): payload.capturedAt default: nil } } var truncated: Bool? { switch self { case .historyPage(let payload): payload.truncated default: nil } } var error: String? { switch self { case .failure(let payload): payload.error default: nil } } var reason: EndReason? { switch self { case .ended(let payload): payload.reason default: nil } } var commandRequest: MirrorCommandRequest? { switch self { case .command(let payload): payload.commandRequest default: nil } } var commandResponse: MirrorCommandResponse? { switch self { case .commandResult(let payload): payload.commandResponse default: nil } } var commandReceiptID: UUID? { switch self { case .commandReceipt(let payload): payload.commandReceiptID default: nil } }}
nonisolated enum MirrorProtocolError: Error, LocalizedError { case invalidMessage, messageTooLarge, invalidPairingKey var errorDescription: String? { switch self { case .invalidMessage: String(localized: "Invalid remote mirror message.") case .messageTooLarge: String(localized: "Remote mirror message exceeds the size limit.") case .invalidPairingKey: String(localized: "Enter the current 8-character pairing code shown on Host.") } }}
nonisolated enum MirrorWire { static let maximumPayload = 8 * 1024 * 1024 static let maximumInput = 64 * 1024
static func encode(_ message: MirrorMessage) throws -> Data { let payload: Data switch message { case .frame(let value): guard value.sequence > 0, (1...1000).contains(value.frame.columns), (1...1000).contains(value.frame.rows) else { throw MirrorProtocolError.invalidMessage } var bytes = Data([1]) bytes.append(uuidBytes(value.subscriptionID)) append(value.sequence, to: &bytes) append(value.frame.columns, to: &bytes) append(value.frame.rows, to: &bytes) bytes.append(value.frame.bytes) payload = bytes case .textFrame(let value): guard value.sequence > 0, value.columns <= 1000, value.rows <= 1000 else { throw MirrorProtocolError.invalidMessage } var bytes = Data([2]) bytes.append(uuidBytes(value.subscriptionID)) append(value.sequence, to: &bytes) append(value.columns, to: &bytes) append(value.rows, to: &bytes) bytes.append(value.truncated ? 1 : 0) bytes.append(Data(value.text.utf8)) payload = bytes default: payload = Data([0]) + (try JSONEncoder().encode(message)) } return try frame(payload) }
private static func uuidBytes(_ id: UUID) -> Data { var value = id.uuid return withUnsafeBytes(of: &value) { Data($0) } }
private static func append<T: FixedWidthInteger>(_ value: T, to data: inout Data) { var value = value.bigEndian withUnsafeBytes(of: &value) { data.append(contentsOf: $0) } }
static func frame(_ payload: Data) throws -> Data { guard !payload.isEmpty, payload.count <= maximumPayload else { throw MirrorProtocolError.messageTooLarge } var length = UInt32(payload.count).bigEndian var result = withUnsafeBytes(of: &length) { Data($0) } result.append(payload) return result }
static func length(_ header: Data) throws -> Int { guard header.count == 4 else { throw MirrorProtocolError.invalidMessage } let length = header.reduce(0) { ($0 << 8) | Int($1) } guard length > 0, length <= maximumPayload else { throw MirrorProtocolError.messageTooLarge } return length }
static func decode(_ data: Data) throws -> MirrorMessage { guard data.count <= maximumPayload else { throw MirrorProtocolError.messageTooLarge } guard let kind = data.first else { throw MirrorProtocolError.invalidMessage } if kind == 0 { let message = try JSONDecoder().decode(MirrorMessage.self, from: data.dropFirst()) guard message.kind != .frame, message.kind != .textFrame else { throw MirrorProtocolError.invalidMessage } return message } guard kind == 1 || kind == 2, data.count >= (kind == 1 ? 33 : 34) else { throw MirrorProtocolError.invalidMessage } let raw = Array(data) let id = UUID( uuid: ( raw[1], raw[2], raw[3], raw[4], raw[5], raw[6], raw[7], raw[8], raw[9], raw[10], raw[11], raw[12], raw[13], raw[14], raw[15], raw[16] )) let sequence = raw[17..<25].reduce(UInt64(0)) { ($0 << 8) | UInt64($1) } guard sequence > 0 else { throw MirrorProtocolError.invalidMessage } if kind == 2 { let columns = raw[25..<29].reduce(UInt32(0)) { ($0 << 8) | UInt32($1) } let rows = raw[29..<33].reduce(UInt32(0)) { ($0 << 8) | UInt32($1) } guard columns <= 1000, rows <= 1000, raw[33] <= 1, let text = String(bytes: raw.dropFirst(34), encoding: .utf8) else { throw MirrorProtocolError.invalidMessage } return .textFrame( .init( columns: columns, rows: rows, truncated: raw[33] == 1, sequence: sequence, text: text, subscriptionID: id)) } let columns = raw[25..<29].reduce(UInt32(0)) { ($0 << 8) | UInt32($1) } let rows = raw[29..<33].reduce(UInt32(0)) { ($0 << 8) | UInt32($1) } guard (1...1000).contains(columns), (1...1000).contains(rows) else { throw MirrorProtocolError.invalidMessage } return .frame( .init( frame: .init(columns: columns, rows: rows, bytes: Data(raw.dropFirst(33))), sequence: sequence, subscriptionID: id)) }
}
/// Empty text is a replacement frame, distinct from a subscription with no baseline.nonisolated struct MirrorTextFrameGate { private var gate = MirrorFrameGate() var outstanding: UInt64? { gate.outstanding }
mutating func offer( _ text: String, columns: UInt32 = 0, rows: UInt32 = 0, truncated: Bool = false, scrollBounds: MirrorScrollBounds? = nil ) -> UInt64? { gate.offer( MirrorFrame( columns: columns, rows: rows, bytes: Data([truncated ? 1 : 0]) + Data(text.utf8), scrollBounds: scrollBounds)) }
mutating func acknowledge(_ sequence: UInt64) throws { try gate.acknowledge(sequence) }
mutating func requestRefresh() { gate.requestRefresh() }}
/// One unacknowledged frame per subscriber bounds memory even on a stalled link.nonisolated struct MirrorFrameGate { private(set) var sequence: UInt64 = 0 private(set) var outstanding: UInt64? private var previous: MirrorFrame?
mutating func requestRefresh() { previous = nil }
mutating func offer(_ frame: MirrorFrame) -> UInt64? { guard outstanding == nil, previous != frame else { return nil } sequence += 1 outstanding = sequence previous = frame return sequence }
mutating func acknowledge(_ sequence: UInt64) throws { guard outstanding == sequence else { throw MirrorProtocolError.invalidMessage } outstanding = nil }}
/// Pages refer to one retained-text snapshot, never moving offsets in a live PTY.nonisolated struct MirrorRetainedText { let text: String let truncated: Bool}
nonisolated struct MirrorHistory { let id = UUID() let lines: [String] let capturedAt = Date().timeIntervalSince1970 let truncated: Bool static let pageSize = 200 static let maximumBytes = 2 * 1024 * 1024
init(text: String, truncated: Bool = false) { self.truncated = truncated || text.utf8.count > Self.maximumBytes // A byte limit can split a scalar; discard only its leading continuation bytes. let bytes = text.utf8.suffix(Self.maximumBytes).drop(while: { $0 & 0xC0 == 0x80 }) guard let bounded = String(bytes: bytes, encoding: .utf8) else { preconditionFailure("A scalar-aligned suffix of a Swift String must be valid UTF-8") } lines = bounded.components(separatedBy: "\n") }
func page(before offset: Int) throws -> (start: Int, lines: [String]) { guard (0...lines.count).contains(offset) else { throw MirrorProtocolError.invalidMessage } let start = max(0, offset - Self.pageSize) return (start, Array(lines[start..<offset])) }}