Skip to content

A tiny friend in your Mac's notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.

27.2 KB
Raw Blame
import CloudKit
import Observation
import UIKit
import UserNotifications
import WidgetKit

/// A Ping written by the Mac, as seen by the iPhone.
struct PingItem: Identifiable {
    let id: CKRecord.ID
    let macName: String
    let app: String
    let message: String
    let sentAt: Date
    /// When this iPhone first saw it. nil for pings that were already there at launch.
    let receivedAt: Date?
    var delay: TimeInterval? { receivedAt.map { $0.timeIntervalSince(sentAt) } }
}

/// An agent session published by the Mac (SessionPublisher), as seen by the iPhone.
struct SessionItem: Identifiable {
    let id: String          // pill ID
    let name: String
    let color: String
    let state: BotState
    let stepIndex: Int
    let steps: [String]
    let needsApproval: Bool
    let approvalCommand: String
    let approvalFingerprint: String
    /// The Mac runs instructions sent from here for this session (GitHub build, switch on).
    let acceptsInstructions: Bool
    let question: String
    /// The question's choices, when it can be answered from here.
    let questionPayload: QuestionPayload?
    let questionFingerprint: String
    let finalLine: String
    let cwd: String
    let updatedAt: Date
    let macName: String

    init(record: CKRecord) {
        id = record["pillId"] as? String ?? record.recordID.recordName
        name = record.encryptedValues["name"] as? String ?? ""
        color = record["color"] as? String ?? "#C0C4CC"
        state = BotState(rawValue: record["state"] as? String ?? "") ?? .idle
        stepIndex = record["stepIndex"] as? Int ?? 0
        steps = record.encryptedValues["steps"] as? [String] ?? []
        needsApproval = record["needsApproval"] as? Bool ?? false
        approvalCommand = record.encryptedValues["approvalCommand"] as? String ?? ""
        approvalFingerprint = record["approvalFingerprint"] as? String ?? ""
        acceptsInstructions = record["acceptsInstructions"] as? Bool ?? false
        question = record.encryptedValues["question"] as? String ?? ""
        questionPayload = QuestionPayload.decode(record.encryptedValues["questionPayload"] as? String ?? "")
        questionFingerprint = record["questionFingerprint"] as? String ?? ""
        finalLine = record.encryptedValues["finalLine"] as? String ?? ""
        cwd = record.encryptedValues["cwd"] as? String ?? ""
        updatedAt = record["updatedAt"] as? Date ?? record.modificationDate ?? .now
        macName = record["macName"] as? String ?? ""
    }

    var pillName: String { PillCatalog.definition(for: id)?.name ?? id }
    var currentStep: String? { steps.indices.contains(stepIndex) ? steps[stepIndex] : steps.last }
}

@MainActor
@Observable
final class PhoneLink {
    static let shared = PhoneLink()

    enum Status: Equatable {
        case starting
        case noAccount(String)
        case zoneMissing
        case ready
        case failed(String)
    }

    static let containerID = "iCloud.fr.louisraille.Coucou"
    static let zoneID = CKRecordZone.ID(zoneName: "Coucou", ownerName: CKCurrentUserDefaultName)
    private static let subscriptionID = "coucou-zone-phone-silent"
    /// Step 1's subscription showed a "Ping from your Mac" banner. A saved
    /// subscription keeps its notification settings, so it is deleted rather than reused.
    private static let oldSubscriptionID = "coucou-zone-phone"

    var status: Status = .starting
    /// The first look at iCloud is over (whatever came of it): the intro can end.
    var firstSyncDone = false
    var pings: [PingItem] = []
    var sessions: [SessionItem] = []
    /// Service Mochi (GitHub, Stripe…) the Mac publishes, by pill ID.
    var services: [String: ServiceSnapshot] = [:]
    /// A service up close (figures, lists, actions), fetched by the Mac when its screen opens.
    var serviceDetails: [String: ServiceDetail] = [:]
    /// The last turn of each session (prompt, actions, diffs, answer), by pill ID.
    var turns: [String: TurnSnapshot] = [:]
    /// Turns seen before the latest one, and today's tally (this iPhone only).
    var archive = TurnArchive.load()
    var lastPong: String?
    var pushError: String?
    var notificationsAllowed: Bool?
    /// A session to open, from a notification, a shortcut or the Control Center.
    var openPillId: String?

    @ObservationIgnored private let container = CKContainer(identifier: PhoneLink.containerID)
    @ObservationIgnored private var database: CKDatabase { container.privateCloudDatabase }
    @ObservationIgnored private var changeToken: CKServerChangeToken?
    @ObservationIgnored private var firstFetchDone = false
    @ObservationIgnored private var subscribed = false
    @ObservationIgnored private var approvalsSubscribed = false
    @ObservationIgnored private var fetching = false
    /// Things to notify once the fetch is done (finished, failed, questions).
    @ObservationIgnored private var events: [AgentNotifier.Event] = []

    func start() async {
        // The fetch starts right away, not after the notification prompt: the
        // intro hides it and should end as soon as everything is there.
        let authorization = Task {
            (try? await UNUserNotificationCenter.current().requestAuthorization(options: [.alert, .sound, .badge])) ?? false
        }
        await refresh()
        notificationsAllowed = await authorization.value
    }

    /// Checks the account, makes sure the subscription exists, then fetches new records.
    func refresh() async {
        do {
            let accountStatus = try await container.accountStatus()
            guard accountStatus == .available else {
                status = .noAccount(describe(accountStatus))
                firstSyncDone = true
                return
            }
        } catch {
            status = .noAccount(error.localizedDescription)
            firstSyncDone = true
            return
        }
        if !subscribed { await subscribe() }
        if subscribed && !approvalsSubscribed { await subscribeToApprovals() }
        _ = await fetchChanges()
        await notifyNewApprovals()
        await postEvents()
    }

    /// Called on a CloudKit push. Returns true when new records arrived.
    func handlePush() async -> Bool {
        let gotNew = await fetchChanges()
        await notifyNewApprovals()
        await postEvents()
        return gotNew
    }

    private func subscribe() async {
        let sub = CKDatabaseSubscription(subscriptionID: Self.subscriptionID)
        // Silent: the Mac writes on every session change, a banner each time
        // would be noise. Approvals have their own subscription below.
        let info = CKSubscription.NotificationInfo()
        info.shouldSendContentAvailable = true
        sub.notificationInfo = info
        do {
            _ = try await database.modifySubscriptions(saving: [sub], deleting: [Self.oldSubscriptionID])
            subscribed = true
        } catch {
            status = .failed("Subscription: \(error.localizedDescription)")
        }
    }

    /// A visible notification for each approval request the Mac sends
    /// (ApprovalRelay), with Review and Deny actions. Kept apart from the
    /// silent subscription so a failure here never stops the sessions.
    private func subscribeToApprovals() async {
        // A saved subscription keeps its sound: one ID per sound, the other one is deleted.
        let mochi = PhoneSettings.mochiSounds
        let approvals = CKQuerySubscription(recordType: "ApprovalRequest", predicate: NSPredicate(value: true),
                                            subscriptionID: mochi ? "coucou-approvals-mochi" : "coucou-approvals",
                                            options: [.firesOnRecordCreation])
        approvals.zoneID = Self.zoneID
        let alert = CKSubscription.NotificationInfo()
        alert.title = "Coucou"
        alert.alertBody = "An agent is waiting for your OK"
        alert.soundName = mochi ? "approval.wav" : "default"
        alert.category = NotificationActions.approvalCategory
        alert.shouldSendContentAvailable = true
        alert.desiredKeys = ["fingerprint", "pillId"]
        approvals.notificationInfo = alert
        do {
            _ = try await database.modifySubscriptions(saving: [approvals], deleting: [])
            _ = try? await database.modifySubscriptions(saving: [], deleting: [mochi ? "coucou-approvals" : "coucou-approvals-mochi"])
            approvalsSubscribed = true
            approvalsStatus = "On"
        } catch {
            // In the Development environment a query subscription needs the
            // record type to exist: create it once with a throwaway record.
            let seed = CKRecord(recordType: "ApprovalRequest",
                                recordID: CKRecord.ID(recordName: "approval-schema", zoneID: Self.zoneID))
            seed["pillId"] = ""
            seed["fingerprint"] = ""
            seed["createdAt"] = Date()
            seed.encryptedValues["tool"] = ""
            seed.encryptedValues["command"] = ""
            do {
                _ = try await database.modifyRecords(saving: [seed], deleting: [], savePolicy: .allKeys)
                _ = try await database.modifyRecords(saving: [], deleting: [seed.recordID])
                _ = try await database.modifySubscriptions(saving: [approvals], deleting: [])
                approvalsSubscribed = true
                approvalsStatus = "On (record type created)"
            } catch {
                approvalsStatus = "Failed: \(error.localizedDescription)"
            }
        }
    }

    @discardableResult
    private func fetchChanges() async -> Bool {
        guard !fetching else { return false }
        fetching = true
        defer { fetching = false }
        var gotNew = false
        do {
            var more = true
            while more {
                let changes = try await database.recordZoneChanges(inZoneWith: Self.zoneID, since: changeToken)
                for (_, result) in changes.modificationResultsByID {
                    if case .success(let mod) = result, add(mod.record) { gotNew = true }
                }
                for deletion in changes.deletions where deletion.recordType == "Session" {
                    sessions.removeAll { "session-\($0.id)" == deletion.recordID.recordName }
                    gotNew = true
                }
                for deletion in changes.deletions where deletion.recordType == TurnSnapshot.recordType {
                    if let id = TurnSnapshot.pillId(fromRecordName: deletion.recordID.recordName) { turns[id] = nil }
                }
                for deletion in changes.deletions where deletion.recordType == ServiceDetail.recordType {
                    if let id = ServiceDetail.pillId(fromRecordName: deletion.recordID.recordName) { serviceDetails[id] = nil }
                }
                for deletion in changes.deletions where deletion.recordType == ServiceSnapshot.recordType {
                    if let id = ServiceSnapshot.pillId(fromRecordName: deletion.recordID.recordName) {
                        services[id] = nil
                        gotNew = true
                    }
                }
                changeToken = changes.changeToken
                more = changes.moreComing
            }
            firstFetchDone = true
            status = .ready
            if gotNew { updateWidgets() }
        } catch let error as CKError where error.code == .zoneNotFound || error.code == .userDeletedZone {
            status = .zoneMissing
        } catch let error as CKError where error.code == .changeTokenExpired {
            changeToken = nil
        } catch let error as CKError where error.code == .notAuthenticated {
            status = .noAccount(error.localizedDescription)
        } catch {
            status = .failed(error.localizedDescription)
        }
        pings.sort { $0.sentAt > $1.sentAt }
        firstSyncDone = true
        return gotNew
    }

    private func add(_ record: CKRecord) -> Bool {
        if record.recordType == TurnSnapshot.recordType {
            guard let payload = record.encryptedValues["payload"] as? String,
                  let turn = try? JSONDecoder().decode(TurnSnapshot.self, from: Data(payload.utf8)) else { return false }
            let before = archive
            archive.update(from: turns[turn.pillId], to: turn)
            if archive.past != before.past || archive.today != before.today { archive.save() }
            turns[turn.pillId] = turn
            SpotlightIndex.index(turn)
            return false   // nothing for the widgets
        }
        if record.recordType == ServiceDetail.recordType {
            guard let payload = record.encryptedValues["payload"] as? String,
                  let detail = try? JSONDecoder().decode(ServiceDetail.self, from: Data(payload.utf8)) else { return false }
            serviceDetails[detail.pillId] = detail
            return false
        }
        if record.recordType == ServiceSnapshot.recordType {
            guard let payload = record.encryptedValues["payload"] as? String,
                  let snapshot = try? JSONDecoder().decode(ServiceSnapshot.self, from: Data(payload.utf8)) else { return false }
            services[snapshot.pillId] = snapshot
            return true
        }
        if record.recordType == "Session" {
            let item = SessionItem(record: record)
            // Services used to come as sessions; they have their own records now.
            guard PillCatalog.isSession(item.id) else { return false }
            if let event = AgentNotifier.event(for: item) { events.append(event) }
            sessions.removeAll { $0.id == item.id }
            sessions.append(item)
            sessions.sort { $0.updatedAt > $1.updatedAt }
            return true
        }
        guard record.recordType == "Ping",
              !pings.contains(where: { $0.id == record.recordID }) else { return false }
        pings.append(PingItem(
            id: record.recordID,
            macName: record["macName"] as? String ?? "Mac",
            app: record["app"] as? String ?? "",
            message: record.encryptedValues["message"] as? String ?? "",
            sentAt: record["sentAt"] as? Date ?? record.creationDate ?? .now,
            receivedAt: firstFetchDone ? .now : nil
        ))
        return true
    }

    // MARK: Approval notifications (step 7)

    /// State of the "coucou-approvals" subscription, shown on the link test screen.
    var approvalsStatus = "Not set up yet"
    @ObservationIgnored private var notifiedFingerprints: Set<String> = []

    nonisolated static func approvalNotificationID(_ fingerprint: String) -> String { "approval-\(fingerprint)" }

    /// The iCloud alert for an approval doesn't always come. The silent push
    /// that updates the sessions does, so a new approval also gets a local
    /// notification, unless the iCloud one came, or the app is open.
    /// Notifications for requests no longer pending are removed.
    private func notifyNewApprovals() async {
        await removeAnsweredNotifications()
        let fresh = sessions.filter {
            $0.needsApproval && !$0.approvalFingerprint.isEmpty && !notifiedFingerprints.contains($0.approvalFingerprint)
        }
        guard !fresh.isEmpty else { return }
        fresh.forEach { notifiedFingerprints.insert($0.approvalFingerprint) }
        // The app is open: the request is on screen.
        guard UIApplication.shared.applicationState != .active else { return }
        // Give the iCloud alert a moment to land first, then check the request still waits.
        try? await Task.sleep(for: .seconds(3))
        _ = await fetchChanges()
        let shown = await Self.shownApprovals().map { $0.fingerprint }
        for session in fresh where !shown.contains(session.approvalFingerprint) {
            guard pendingFingerprints.contains(session.approvalFingerprint),
                  !iCloudAlerted.contains(session.approvalFingerprint) else { continue }
            let content = UNMutableNotificationContent()
            content.title = "\(session.pillName) · \(session.title)"
            content.body = session.approvalCommand.isEmpty
                ? "An agent is waiting for your OK"
                : "Waiting for your OK: \(session.approvalCommand.prefix(140))"
            content.sound = PhoneSettings.sound("approval")
            content.categoryIdentifier = NotificationActions.approvalCategory
            content.userInfo = ["fingerprint": session.approvalFingerprint, "pillId": session.id]
            let request = UNNotificationRequest(identifier: Self.approvalNotificationID(session.approvalFingerprint),
                                                content: content, trigger: nil)
            try? await UNUserNotificationCenter.current().add(request)
        }
    }

    /// Fingerprints of the requests the Mac is still waiting on.
    private var pendingFingerprints: Set<String> {
        Set(sessions.filter(\.needsApproval).map(\.approvalFingerprint).filter { !$0.isEmpty })
    }

    /// Fingerprints whose iCloud alert reached this iPhone (shown or tapped).
    @ObservationIgnored private var iCloudAlerted: Set<String> = []

    func noteICloudAlert(_ fingerprint: String) {
        iCloudAlerted.insert(fingerprint)
        notifiedFingerprints.insert(fingerprint)
    }

    /// Clears the banners of requests answered on the Mac, on the iPhone or expired.
    private func removeAnsweredNotifications() async {
        let pending = pendingFingerprints
        let stale = await Self.shownApprovals().filter { !pending.contains($0.fingerprint) }.map { $0.id }
        if !stale.isEmpty { UNUserNotificationCenter.current().removeDeliveredNotifications(withIdentifiers: stale) }
    }

    /// Approval notifications in Notification Center, local or from iCloud.
    nonisolated static func shownApprovals() async -> [(id: String, fingerprint: String)] {
        let delivered = await UNUserNotificationCenter.current().deliveredNotifications()
        return delivered.compactMap { notification in
            let request = notification.request
            return approvalFingerprint(in: request).map { (request.identifier, $0) }
        }
    }

    /// The approval fingerprint carried by a notification, local or from iCloud.
    nonisolated static func approvalFingerprint(in request: UNNotificationRequest) -> String? {
        let userInfo = request.content.userInfo
        // Finished and question notifications carry a "kind"; approvals don't.
        guard userInfo["kind"] == nil else { return nil }
        if let fingerprint = userInfo["fingerprint"] as? String { return fingerprint }
        let note = CKNotification(fromRemoteNotificationDictionary: userInfo) as? CKQueryNotification
        return note?.recordFields?["fingerprint"] as? String
    }

    /// Finished, failed and question notifications, after a fetch (in the
    /// background only; the app open shows it all already).
    private func postEvents() async {
        let pending = events
        events = []
        for event in pending {
            let pillId: String
            switch event {
            case .finished(let session), .failed(let session), .question(let session, _): pillId = session.id
            }
            await AgentNotifier.post(event, turn: turns[pillId])
        }
    }

    /// The approval subscription is made again with the new sound.
    func soundsChanged() {
        approvalsSubscribed = false
        Task { await refresh() }
    }

    // MARK: Questions

    /// Answers the question a session waits on. The Mac takes it within ~2 s,
    /// only if it is still the same question and the picks are among its choices.
    func answer(fingerprint: String, pillId: String, selections: [[String]]) async -> Bool {
        let record = CKRecord(recordType: "Answer",
                              recordID: CKRecord.ID(recordName: "answer-\(UUID().uuidString)", zoneID: Self.zoneID))
        record["fingerprint"] = fingerprint
        record["pillId"] = pillId
        record["answeredAt"] = Date()
        record["deviceName"] = UIDevice.current.name
        record.encryptedValues["selections"] = QuestionPayload.encodeSelections(selections)
        do {
            _ = try await database.save(record)
            return true
        } catch {
            lastPong = "Answer failed: \(error.localizedDescription)"
            return false
        }
    }

    // MARK: Services up close

    /// Asks the Mac to read this service's API now (it answers within ~10 s).
    /// False when no new detail came back in time (Mac asleep, sync off, older build).
    @discardableResult
    func requestServiceDetail(_ pillId: String) async -> Bool {
        let previous = serviceDetails[pillId]?.fetchedAt
        guard await sendServiceRequest(kind: ServiceDetail.refreshKind, target: "", pillId: pillId) else { return false }
        // The new detail usually comes with a push; fetch anyway in case it doesn't.
        for _ in 0..<3 {
            // Screen left (task cancelled): stop rather than fetch back to back.
            do { try await Task.sleep(for: .seconds(6)) } catch { return false }
            _ = await fetchChanges()
            // Only the Mac's answer to this request counts, not an older detail.
            if let detail = serviceDetails[pillId], detail.fetchedAt != previous { return true }
        }
        return false
    }

    /// Asks the Mac to run an action it offered on this service. Face ID first.
    /// True only when the Mac's result for this request came back and it worked.
    func runServiceAction(_ action: ServiceActionDef, pillId: String) async -> Bool {
        guard await OwnerCheck.confirm(reason: "\(action.title) from your Mac") else { return false }
        // The result already shown (from an earlier action) doesn't count for this one.
        let previous = serviceDetails[pillId]?.lastAction
        guard await sendServiceRequest(kind: action.kind, target: action.target, pillId: pillId) else { return false }
        for _ in 0..<6 {
            try? await Task.sleep(for: .seconds(5))
            _ = await fetchChanges()
            if let result = serviceDetails[pillId]?.lastAction, result != previous { return result.ok }
        }
        return false
    }

    private func sendServiceRequest(kind: String, target: String, pillId: String) async -> Bool {
        let record = CKRecord(recordType: ServiceDetail.requestType,
                              recordID: CKRecord.ID(recordName: "service-request-\(UUID().uuidString)", zoneID: Self.zoneID))
        record["pillId"] = pillId
        record["kind"] = kind
        record["requestedAt"] = Date()
        record.encryptedValues["target"] = target
        do {
            _ = try await database.save(record)
            return true
        } catch {
            lastPong = "Request failed: \(error.localizedDescription)"
            return false
        }
    }

    // MARK: Instructions (step B)

    /// Sends an instruction to continue a session on the Mac. The Mac takes it
    /// within ~15 s and deletes it; it never runs twice.
    func sendInstruction(_ text: String, pillId: String) async -> Bool {
        let record = CKRecord(recordType: "Instruction",
                              recordID: CKRecord.ID(recordName: "instruction-\(UUID().uuidString)", zoneID: Self.zoneID))
        record["pillId"] = pillId
        record["createdAt"] = Date()
        record["deviceName"] = UIDevice.current.name
        record.encryptedValues["text"] = text
        do {
            _ = try await database.save(record)
            return true
        } catch {
            lastPong = "Instruction failed: \(error.localizedDescription)"
            return false
        }
    }

    // MARK: Decisions (step 7)

    /// Decisions taken on this iPhone, newest first.
    var history: [DecisionLog] = DecisionLog.load()

    /// Set when the user taps "Review" on an approval notification.
    var reviewFingerprint: String?
    /// When the notification of the request under review arrived: a request older than the
    /// Mac's 2-minute wait has expired rather than been answered.
    var reviewSince: Date?

    /// Sends allow / deny for one exact request. The Mac applies it only if the
    /// fingerprint still matches the request it is waiting on.
    func decide(_ decision: Decision, fingerprint: String, pillId: String, summary: String) async -> Bool {
        let record = CKRecord(recordType: "Decision",
                              recordID: CKRecord.ID(recordName: "decision-\(UUID().uuidString)", zoneID: Self.zoneID))
        record["fingerprint"] = fingerprint
        record["pillId"] = pillId
        record["decision"] = decision.rawValue
        record["decidedAt"] = Date()
        record["deviceName"] = UIDevice.current.name
        do {
            _ = try await database.save(record)
            history.insert(DecisionLog(decision: decision, pillId: pillId, summary: summary, date: .now), at: 0)
            history = Array(history.prefix(50))
            DecisionLog.save(history)
            return true
        } catch {
            lastPong = "Decision failed: \(error.localizedDescription)"
            return false
        }
    }

    /// Allow from the Live Activity or a notification, without opening the app
    /// (the iPhone was unlocked by its owner: iOS asks for it first).
    func allowFromOutside(fingerprint: String, pillId: String, from place: String) async -> Bool {
        noteICloudAlert(fingerprint)
        let command = sessions.first { $0.approvalFingerprint == fingerprint }?.approvalCommand ?? ""
        let summary = command.isEmpty ? "Allowed from \(place)" : String(command.prefix(200))
        let sent = await decide(.allow, fingerprint: fingerprint, pillId: pillId, summary: summary)
        if sent { UNUserNotificationCenter.current().removeDeliveredNotifications(withIdentifiers: [Self.approvalNotificationID(fingerprint)]) }
        return sent
    }

    /// Hands the sessions to the widgets and asks them to redraw.
    private func updateWidgets() {
        SharedSessions.save(sessions.map(\.shared) + services.values.map(\.shared))
        WidgetCenter.shared.reloadAllTimelines()
        ControlCenter.shared.reloadAllControls()
    }

    /// Writes a Pong linked to the latest Ping.
    func sendPong() async {
        guard let ping = pings.first else { return }
        let record = CKRecord(recordType: "Pong",
                              recordID: CKRecord.ID(recordName: UUID().uuidString, zoneID: Self.zoneID))
        let repliedAt = Date()
        record["ping"] = CKRecord.Reference(recordID: ping.id, action: .none)
        record["pingSentAt"] = ping.sentAt
        record["repliedAt"] = repliedAt
        record["deviceName"] = UIDevice.current.name
        record.encryptedValues["message"] = "pong for \"\(ping.message)\""
        do {
            _ = try await database.save(record)
            lastPong = String(format: "Pong saved in %.1f s", Date().timeIntervalSince(repliedAt))
        } catch let error as CKError where error.code == .zoneNotFound {
            status = .zoneMissing
        } catch {
            lastPong = "Pong failed: \(error.localizedDescription)"
        }
    }

    private func describe(_ status: CKAccountStatus) -> String {
        switch status {
        case .available: "available"
        case .noAccount: "No iCloud account on this iPhone."
        case .restricted: "iCloud is restricted on this iPhone."
        case .couldNotDetermine: "Couldn't check the iCloud account."
        case .temporarilyUnavailable: "iCloud is temporarily unavailable."
        @unknown default: "Unknown iCloud status."
        }
    }
}