@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.0

package/pipeline/skills/shared/external/callkit-voip/references/callkit-patterns.md

@@ -1,444 +1,276 @@
-# CallKit + PushKit Extended Patterns
+# CallKit Patterns
 
-Overflow reference for the `callkit` skill. Contains advanced patterns that exceed the main skill file's scope.
+Longer examples that back the `callkit-voip` skill. Read its SKILL.md first;
+this file assumes the provider setup, push rules and audio rules described
+there.
 
-## Contents
+## An observable call manager
 
-- [Full Call Manager](#full-call-manager)
-- [Hold and Mute Actions](#hold-and-mute-actions)
-- [Multiple Concurrent Calls](#multiple-concurrent-calls)
-- [Call State Tracking](#call-state-tracking)
-- [Encrypted VoIP Push Filtering](#encrypted-voip-push-filtering)
-- [Call Directory Incremental Updates](#call-directory-incremental-updates)
-- [Testing VoIP Locally](#testing-voip-locally)
-
-## Full Call Manager
+A `@MainActor` model that SwiftUI can watch. It owns the provider and the
+controller and keeps a table of live calls.
 
 ```swift
 import CallKit
-import AVFoundation
-import PushKit
-
-@Observable
-@MainActor
-final class VoIPCallManager: NSObject {
-    let provider: CXProvider
-    let callController = CXCallController()
-
-    private(set) var activeCalls: [UUID: CallInfo] = [:]
-
-    struct CallInfo {
-        let uuid: UUID
-        let handle: String
-        let isOutgoing: Bool
-        var isOnHold: Bool = false
-        var isMuted: Bool = false
-        var isConnected: Bool = false
-    }
+import Observation
+
+struct LiveCall: Identifiable, Sendable {
+    let id: UUID
+    let address: String
+    let outgoing: Bool
+    var held = false
+    var muted = false
+    var connected = false
+}
+
+@Observable @MainActor
+final class Switchboard: NSObject {
+    @ObservationIgnored let provider: CXProvider
+    @ObservationIgnored let controller = CXCallController()
+    private(set) var calls: [UUID: LiveCall] = [:]
 
     override init() {
-        let config = CXProviderConfiguration()
-        config.localizedName = "My VoIP"
-        config.supportsVideo = true
-        config.maximumCallGroups = 2
-        config.maximumCallsPerCallGroup = 1
-        config.supportedHandleTypes = [.phoneNumber]
-        config.includesCallsInRecents = true
-
-        provider = CXProvider(configuration: config)
+        let setup = CXProviderConfiguration()
+        setup.supportedHandleTypes = [.phoneNumber]
+        setup.includesCallsInRecents = true
+        setup.maximumCallsPerCallGroup = 1
+        setup.maximumCallGroups = 2
+        setup.supportsVideo = true
+        provider = CXProvider(configuration: setup)
         super.init()
         provider.setDelegate(self, queue: nil)
     }
 
-    // MARK: - Incoming
-
-    func reportIncoming(
-        uuid: UUID,
-        handle: String,
-        callerName: String,
-        hasVideo: Bool
-    ) async throws {
-        let update = CXCallUpdate()
-        update.remoteHandle = CXHandle(type: .phoneNumber, value: handle)
-        update.localizedCallerName = callerName
-        update.hasVideo = hasVideo
-        update.supportsHolding = true
-        update.supportsDTMF = true
-        update.supportsGrouping = false
-        update.supportsUngrouping = false
-
-        try await withCheckedThrowingContinuation {
-            (continuation: CheckedContinuation<Void, Error>) in
-            provider.reportNewIncomingCall(
-                with: uuid, update: update
-            ) { error in
-                if let error {
-                    continuation.resume(throwing: error)
-                } else {
-                    continuation.resume()
-                }
-            }
-        }
-
-        activeCalls[uuid] = CallInfo(
-            uuid: uuid, handle: handle, isOutgoing: false
-        )
+    func reportIncoming(id: UUID, address: String, name: String) async throws {
+        let info = CXCallUpdate()
+        info.localizedCallerName = name
+        info.remoteHandle = CXHandle(type: .generic, value: address)
+        info.supportsDTMF = true
+        info.supportsHolding = true
+        info.supportsUngrouping = false
+        info.supportsGrouping = false
+        try await provider.reportNewIncomingCall(with: id, update: info)
+        calls[id] = LiveCall(id: id, address: address, outgoing: false)
     }
 
-    // MARK: - Outgoing
-
-    func startCall(handle: String, hasVideo: Bool) {
-        let uuid = UUID()
-        let cxHandle = CXHandle(type: .phoneNumber, value: handle)
-        let action = CXStartCallAction(call: uuid, handle: cxHandle)
-        action.isVideo = hasVideo
-
-        callController.request(
-            CXTransaction(action: action)
-        ) { error in
-            if let error {
-                print("Start call failed: \(error)")
-            }
-        }
-
-        activeCalls[uuid] = CallInfo(
-            uuid: uuid, handle: handle, isOutgoing: true
-        )
+    func startCall(to address: String) async throws {
+        let id = UUID()
+        let action = CXStartCallAction(call: id, handle: CXHandle(type: .phoneNumber, value: address))
+        try await controller.request(CXTransaction(action: action))
+        calls[id] = LiveCall(id: id, address: address, outgoing: true)
     }
 
-    // MARK: - Actions
-
-    func endCall(uuid: UUID) {
-        let action = CXEndCallAction(call: uuid)
-        callController.request(CXTransaction(action: action)) { error in
-            if let error { print("End call failed: \(error)") }
-        }
+    func hangUp(_ id: UUID) async throws {
+        try await controller.request(CXTransaction(action: CXEndCallAction(call: id)))
     }
 
-    func setHeld(uuid: UUID, onHold: Bool) {
-        let action = CXSetHeldCallAction(call: uuid, onHold: onHold)
-        callController.request(CXTransaction(action: action)) { error in
-            if let error { print("Hold failed: \(error)") }
-        }
+    func setHeld(_ id: UUID, _ held: Bool) async throws {
+        try await controller.request(CXTransaction(action: CXSetHeldCallAction(call: id, onHold: held)))
     }
 
-    func setMuted(uuid: UUID, muted: Bool) {
-        let action = CXSetMutedCallAction(call: uuid, muted: muted)
-        callController.request(CXTransaction(action: action)) { error in
-            if let error { print("Mute failed: \(error)") }
-        }
+    func setMuted(_ id: UUID, _ muted: Bool) async throws {
+        try await controller.request(CXTransaction(action: CXSetMutedCallAction(call: id, muted: muted)))
     }
 }
 ```
 
-## Hold and Mute Actions
+A call enters `calls` only after its incoming report succeeds; an outgoing call
+enters after the start transaction was accepted. Hanging up, holding and muting
+all follow the same shape: build the action, wrap it in a `CXTransaction`, send
+it with `request`.
 
-```swift
-extension VoIPCallManager: CXProviderDelegate {
-    nonisolated func providerDidReset(_ provider: CXProvider) {
-        Task { @MainActor in
-            for uuid in activeCalls.keys {
-                disconnectCall(uuid)
-            }
-            activeCalls.removeAll()
-        }
-    }
-
-    nonisolated func provider(
-        _ provider: CXProvider,
-        perform action: CXSetHeldCallAction
-    ) {
-        Task { @MainActor in
-            activeCalls[action.callUUID]?.isOnHold = action.isOnHold
-            if action.isOnHold {
-                pauseAudio(for: action.callUUID)
-            } else {
-                resumeAudio(for: action.callUUID)
-            }
-            action.fulfill()
-        }
-    }
+## Hold and mute in the delegate
 
-    nonisolated func provider(
-        _ provider: CXProvider,
-        perform action: CXSetMutedCallAction
-    ) {
-        Task { @MainActor in
-            activeCalls[action.callUUID]?.isMuted = action.isMuted
-            // If call translation is active, mute app input without deactivating
-            // upstream audio that translated audio may need.
-            setMicrophoneMuted(action.isMuted)
-            action.fulfill()
-        }
-    }
+The provider calls its delegate on the main queue here (`queue: nil`), so the
+conformance is `@preconcurrency`: the methods stay main-actor isolated and
+touch `calls` directly. Marking them `nonisolated` and hopping back with
+`Task { @MainActor in ... }` does not compile under Swift 6, because the task
+would carry the non-`Sendable` `CXAction` off the delegate call ("sending
+'hold' risks causing data races").
 
-    nonisolated func provider(
-        _ provider: CXProvider,
-        perform action: CXAnswerCallAction
-    ) {
-        Task { @MainActor in
-            configureAudioSession()
-            connectToServer(callUUID: action.callUUID) { success in
-                if success {
-                    activeCalls[action.callUUID]?.isConnected = true
-                    action.fulfill()
-                } else {
-                    provider.reportCall(
-                        with: action.callUUID,
-                        endedAt: Date(),
-                        reason: .failed
-                    )
-                    action.fail()
-                }
-            }
-        }
-    }
-
-    nonisolated func provider(
-        _ provider: CXProvider,
-        perform action: CXStartCallAction
-    ) {
-        Task { @MainActor in
-            configureAudioSession()
-            provider.reportOutgoingCall(
-                with: action.callUUID,
-                startedConnectingAt: Date()
-            )
-            connectToServer(callUUID: action.callUUID)
-            provider.reportOutgoingCall(
-                with: action.callUUID,
-                connectedAt: Date()
-            )
-            activeCalls[action.callUUID]?.isConnected = true
-            action.fulfill()
-        }
-    }
-
-    nonisolated func provider(
-        _ provider: CXProvider,
-        perform action: CXEndCallAction
-    ) {
-        Task { @MainActor in
-            disconnectCall(action.callUUID)
-            activeCalls.removeValue(forKey: action.callUUID)
-            action.fulfill()
+```swift
+extension Switchboard: @preconcurrency CXProviderDelegate {
+    func providerDidReset(_ cx: CXProvider) {
+        Task {
+            for id in calls.keys { await CallMedia.shared.disconnect(id) }
+            calls.removeAll()
         }
     }
 
-    nonisolated func provider(
-        _ provider: CXProvider,
-        didActivate audioSession: AVAudioSession
-    ) {
-        Task { @MainActor in
-            startAudioEngine()
-        }
+    func provider(_ cx: CXProvider, perform hold: CXSetHeldCallAction) {
+        let id = hold.callUUID
+        calls[id]?.held = hold.isOnHold
+        if hold.isOnHold { CallMedia.shared.pause(id) } else { CallMedia.shared.resume(id) }
+        hold.fulfill()
     }
 
-    nonisolated func provider(
-        _ provider: CXProvider,
-        didDeactivate audioSession: AVAudioSession
-    ) {
-        Task { @MainActor in
-            stopAudioEngine()
-        }
+    func provider(_ cx: CXProvider, perform mute: CXSetMutedCallAction) {
+        calls[mute.callUUID]?.muted = mute.isMuted
+        CallMedia.shared.setMicrophoneMuted(mute.isMuted)
+        mute.fulfill()
     }
 }
 ```
 
-## Multiple Concurrent Calls
+Muting only silences the microphone input. Upstream audio keeps flowing,
+because iOS 26 call translation depends on it.
 
-When a second call arrives while one is active, CallKit automatically puts
-the first call on hold. Handle the hold action to pause your audio stream:
+The answer, start, end, `didActivate` and `didDeactivate` handlers are the same
+as in SKILL.md, with bookkeeping added: set `connected = true` once media
+connects, and remove the entry when the call ends.
 
-```swift
-nonisolated func provider(
-    _ provider: CXProvider,
-    perform action: CXSetHeldCallAction
-) {
-    Task { @MainActor in
-        if action.isOnHold {
-            // Pause the RTP stream for this call
-            pauseMediaStream(for: action.callUUID)
-        } else {
-            // Resume the RTP stream
-            resumeMediaStream(for: action.callUUID)
-        }
-        activeCalls[action.callUUID]?.isOnHold = action.isOnHold
-        action.fulfill()
-    }
-}
-```
+## Several calls at once
 
-Configure `maximumCallGroups` and `maximumCallsPerCallGroup` in
-`CXProviderConfiguration` to control how many concurrent calls your app
-supports.
+When a second call rings while one is active and the user accepts it, CallKit
+holds the first call on its own. The app sees a `CXSetHeldCallAction` for the
+first call and must pause or resume its media stream (for example the RTP
+session) in response. How many calls may coexist is set by
+`maximumCallGroups` and `maximumCallsPerCallGroup` in the configuration.
 
-## Call State Tracking
+## Watching call state
 
-Use `CXCallObserver` to monitor call state changes from outside the provider
-delegate:
+`CXCallObserver` reports every call on the device, which is useful outside the
+provider delegate, for example in a status view.
 
 ```swift
 import CallKit
 
-final class CallStateObserver: NSObject, CXCallObserverDelegate {
-    let observer = CXCallObserver()
+final class CallWatcher: NSObject, CXCallObserverDelegate {
+    private let monitor = CXCallObserver()
 
     override init() {
         super.init()
-        observer.setDelegate(self, queue: nil)
+        monitor.setDelegate(self, queue: .main)
     }
 
-    func callObserver(
-        _ callObserver: CXCallObserver,
-        callChanged call: CXCall
-    ) {
+    func callObserver(_ watcher: CXCallObserver, callChanged call: CXCall) {
+        let phase: String
         if call.hasEnded {
-            print("Call \(call.uuid) ended")
+            phase = "ended"
         } else if call.hasConnected {
-            print("Call \(call.uuid) connected")
+            phase = "connected"
         } else if call.isOutgoing {
-            print("Outgoing call \(call.uuid) ringing")
+            phase = "dialing"
         } else {
-            print("Incoming call \(call.uuid) ringing")
+            phase = "ringing"
         }
+        Log.calls.info("\(call.uuid) is \(phase)")
     }
 }
 ```
 
-## Encrypted VoIP Push Filtering
+## Filtering encrypted VoIP pushes
 
-Use a notification service extension with
-`CXProvider.reportNewIncomingVoIPPushPayload` only when server-side metadata
-encryption means the server cannot determine whether the outgoing notification
-is a VoIP call request or some other data. If the server knows the content is
-a VoIP call, send a normal PushKit VoIP push instead.
+When the server sends end-to-end encrypted content and cannot tell whether it
+is a call, a notification service extension decrypts it and hands call
+payloads to CallKit.
 
 ```swift
-import UserNotifications
 import CallKit
+import UserNotifications
 
-final class NotificationService: UNNotificationServiceExtension {
-    override func didReceive(
-        _ request: UNNotificationRequest,
-        withContentHandler contentHandler:
-            @escaping (UNNotificationContent) -> Void
-    ) {
-        guard let encryptedPayload = request.content
-            .userInfo["encrypted"] as? [AnyHashable: Any] else {
-            contentHandler(request.content)
+final class PushFilter: UNNotificationServiceExtension {
+    override func didReceive(_ incoming: UNNotificationRequest,
+                             withContentHandler deliver: @escaping (UNNotificationContent) -> Void) {
+        guard let sealed = incoming.content.userInfo["sealed"] as? String,
+              let opened = Envelope.open(sealed) else {
+            deliver(incoming.content)
             return
         }
-
-        let decryptedPayload = decryptPayload(encryptedPayload)
-
-        CXProvider.reportNewIncomingVoIPPushPayload(
-            decryptedPayload
-        ) { error in
-            if let error {
-                // Show a missed-call notification instead
-                let content = UNMutableNotificationContent()
-                content.title = "Missed Call"
-                content.body = decryptedPayload["callerName"] as? String ?? ""
-                contentHandler(content)
-            } else {
-                // Call was reported; suppress the notification
-                contentHandler(UNNotificationContent())
+        nonisolated(unsafe) let deliver = deliver
+        CXProvider.reportNewIncomingVoIPPushPayload(opened) { failure in
+            guard failure != nil else {
+                deliver(UNNotificationContent())
+                return
             }
+            let missed = UNMutableNotificationContent()
+            missed.title = String(localized: "Missed call")
+            deliver(missed)
         }
     }
 }
 ```
 
-This requires the `com.apple.developer.usernotifications.filtering` entitlement.
+Content that was not encrypted passes through untouched. The content handler
+is not `Sendable`, and both forms of `reportNewIncomingVoIPPushPayload` need it
+somewhere concurrent: the completion form runs its callback as `@Sendable`, and
+the async form needs a `Task` whose closure Swift 6 rejects for capturing the
+handler. The `nonisolated(unsafe)` copy lets the `@Sendable` callback hold it. A failed report turns
+into a missed-call notification; a successful one is suppressed with empty
+content. If the server does know the push is a call, skip all of this and use
+an ordinary PushKit VoIP push. Entitlement required for the extension:
+`com.apple.developer.usernotifications.filtering`.
 
-## Call Directory Incremental Updates
+## Incremental Call Directory updates
 
-After the first full load, use incremental updates to add or remove entries
-without reloading the entire dataset:
+Once the initial complete load has run, the extension can add and remove individual numbers
+instead of rebuilding everything.
 
 ```swift
-private func addOrRemoveIncrementalEntries(
-    to context: CXCallDirectoryExtensionContext
-) {
-    let removedNumbers: [CXCallDirectoryPhoneNumber] = fetchRemovedNumbers()
-    for number in removedNumbers {
-        context.removeBlockingEntry(withPhoneNumber: number)
-        context.removeIdentificationEntry(withPhoneNumber: number)
-    }
-
-    let newBlocked: [CXCallDirectoryPhoneNumber] = fetchNewBlockedNumbers()
-    for number in newBlocked.sorted() {
-        context.addBlockingEntry(withNextSequentialPhoneNumber: number)
-    }
-
-    let newIdentified: [(CXCallDirectoryPhoneNumber, String)] = fetchNewIdentified()
-    for (number, label) in newIdentified.sorted(by: { $0.0 < $1.0 }) {
-        context.addIdentificationEntry(
-            withNextSequentialPhoneNumber: number,
-            label: label
-        )
+extension SpamListProvider {
+    func applyChanges(to context: CXCallDirectoryExtensionContext) {
+        let delta = SharedStore.pendingDelta()
+        for number in delta.unblocked {
+            context.removeBlockingEntry(withPhoneNumber: number)
+        }
+        for number in delta.unlabeled {
+            context.removeIdentificationEntry(withPhoneNumber: number)
+        }
+        for number in delta.blocked.sorted() {
+            context.addBlockingEntry(withNextSequentialPhoneNumber: number)
+        }
+        for pair in delta.labeled.sorted(by: { $0.key < $1.key }) {
+            context.addIdentificationEntry(withNextSequentialPhoneNumber: pair.key, label: pair.value)
+        }
+        SharedStore.clearDelta()
     }
 }
 ```
 
-Call Directory data is bulk data. The system calls `beginRequest(with:)` when
-loading the extension, not for each individual incoming call, so keep web
-lookups and dataset sync in the containing app before reloading the extension.
-
-## Testing VoIP Locally
+Additions are sorted before they are added. The system runs
+`beginRequest(with:)` when it loads the extension, never per incoming call, so
+any web lookup and dataset sync happens in the containing app before it calls
+`reloadExtension(withIdentifier:)`.
 
-### Simulating VoIP Pushes
+## Testing VoIP locally
 
-Use the Push Notifications Console or a command-line tool to send test pushes.
-The payload must target the VoIP topic (`<bundle-id>.voip`):
+- Fire test pushes with the Push Notifications Console, or with any APNs
+  client you run from a terminal. The topic is the bundle identifier with `.voip` appended, for example
+  `com.example.dialer.voip`.
+- A test payload needs only an empty `aps` plus your own keys:
 
 ```json
 {
-    "aps": {},
-    "handle": "+15551234567",
-    "callerName": "Test Caller",
-    "hasVideo": false
+  "aps": {},
+  "from": "+14155550123",
+  "display": "Test Caller",
+  "video": false
 }
 ```
 
-### Testing Without a Server
-
-For development, you can bypass PushKit and directly call the incoming call
-reporting method:
+- Without a server, a debug-only helper can call the incoming report directly:
 
 ```swift
 #if DEBUG
-func simulateIncomingCall() {
-    let uuid = UUID()
-    Task {
-        try? await CallManager.shared.reportIncomingCall(
-            uuid: uuid,
-            handle: "+15551234567",
-            hasVideo: false
-        )
+extension Switchboard {
+    func simulateIncomingCall() async {
+        try? await reportIncoming(id: UUID(), address: "+14155550123", name: "Test Caller")
     }
 }
 #endif
 ```
 
-### Checking Extension Status
-
-Verify that the Call Directory extension is enabled:
+- Check the Call Directory extension state from the app:
 
 ```swift
-CXCallDirectoryManager.sharedInstance.getEnabledStatusForExtension(
-    withIdentifier: "com.example.app.CallDirectory"
-) { status, error in
-    switch status {
-    case .enabled:
-        print("Extension is enabled")
-    case .disabled:
-        print("Extension is disabled -- prompt user to enable in Settings")
-    case .unknown:
-        print("Status unknown")
-    @unknown default:
-        break
+func checkBlockerStatus() {
+    let manager = CXCallDirectoryManager.sharedInstance
+    manager.getEnabledStatusForExtension(withIdentifier: "org.sample.dialer.blocker") { state, failure in
+        switch state {
+        case .enabled: Log.calls.info("blocker active")
+        case .disabled: Log.calls.info("ask the user to enable it in Settings")
+        case .unknown: Log.calls.info("status unknown: \(String(describing: failure))")
+        @unknown default: break
+        }
     }
 }
 ```