@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/permissionkit/references/permissionkit-patterns.md

@@ -1,475 +1,362 @@
-# PermissionKit Extended Patterns
+# PermissionKit patterns
 
-Overflow reference for the `permissionkit` skill. Contains advanced patterns
-that exceed the main skill file's scope.
+Longer examples that back the main `permissionkit` skill. They assume the iOS
+26.2 SDK (macOS 26.2 for the AppKit section) unless marked otherwise; the
+26.0 pieces (`CommunicationLimits`, the topic and question types) work
+earlier. Check signatures against the SDK you build with.
+
+One rule runs through every example: a child who cancels the iMessage send
+sheet produces no response at all. Pending state therefore has to be explicit
+and has to be able to expire.
 
 ## Contents
 
-- [Full UIKit Integration](#full-uikit-integration)
-- [Response Observer Manager](#response-observer-manager)
-- [Multi-Contact Permission Flow](#multi-contact-permission-flow)
-- [Communication Limits Checking Pattern](#communication-limits-checking-pattern)
-- [SwiftUI Full-Screen Permission Flow](#swiftui-full-screen-permission-flow)
-- [macOS Integration](#macos-integration)
-- [Error Recovery Patterns](#error-recovery-patterns)
+- [UIKit view controller](#uikit-view-controller)
+- [Response manager](#response-manager)
+- [Several contacts in one question](#several-contacts-in-one-question)
+- [Limits-check view model](#limits-check-view-model)
+- [SwiftUI full flow](#swiftui-full-flow)
+- [macOS](#macos)
+- [Error recovery](#error-recovery)
 
-## Full UIKit Integration
+## UIKit view controller
 
-Complete UIKit view controller with permission request and response handling.
-Keep the pending state explicit: if the child cancels the iMessage send flow,
-PermissionKit does not deliver a `PermissionResponse` for that question.
+The controller owns one long-lived observer task, started when the view loads
+and cancelled when the controller goes away.
 
 ```swift
 import UIKit
-import PermissionKit
+@preconcurrency import PermissionKit
 
-class ContactViewController: UIViewController {
-    private var responseTask: Task<Void, Never>?
+@available(iOS 26.2, *)
+final class TeammateViewController: UIViewController {
+    private var answerTask: Task<Void, Never>?
+    private let teammate: Teammate
 
-    override func viewDidLoad() {
-        super.viewDidLoad()
-        startObservingResponses()
+    init(teammate: Teammate) {
+        self.teammate = teammate
+        super.init(nibName: nil, bundle: nil)
     }
+    required init?(coder: NSCoder) { nil }
 
-    deinit {
-        responseTask?.cancel()
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        answerTask = Task { [weak self] in
+            let answers = AskCenter.shared.responses(for: CommunicationTopic.self)
+            for await answer in answers {
+                await MainActor.run { self?.apply(answer) }
+            }
+        }
     }
 
-    func requestPermissionToMessage(_ contact: Contact) {
-        let personInfo = CommunicationTopic.PersonInformation(
-            handle: CommunicationHandle(
-                value: contact.phoneNumber,
-                kind: .phoneNumber
-            ),
-            nameComponents: contact.nameComponents,
-            avatarImage: contact.avatarCGImage
-        )
-
-        let topic = CommunicationTopic(
-            personInformation: [personInfo],
-            actions: [.message]
-        )
+    deinit { answerTask?.cancel() }
 
-        let question = PermissionQuestion<CommunicationTopic>(
-            communicationTopic: topic
+    func askToMessage() {
+        let person = CommunicationTopic.PersonInformation(
+            handle: CommunicationHandle(value: teammate.phone, kind: .phoneNumber),
+            nameComponents: teammate.name,
+            avatarImage: teammate.avatarCGImage
         )
+        let topic = CommunicationTopic(personInformation: [person], actions: [.message])
+        let request = PermissionQuestion<CommunicationTopic>(communicationTopic: topic)
 
         Task {
             do {
-                try await AskCenter.shared.ask(question, in: self)
-                showPendingState(for: contact)
-                schedulePendingExpiration(for: question.id)
+                try await AskCenter.shared.ask(request, in: self as UIViewController)
+                showWaitingBadge()
+                scheduleExpiry(for: request.id)
             } catch AskError.communicationLimitsNotEnabled {
-                enableMessaging(for: contact)
+                enableMessaging(for: person.handle)
             } catch AskError.notAvailable {
-                showFeatureUnavailable()
+                showUnavailableBanner()
             } catch {
                 showError(error)
             }
         }
     }
 
-    private func startObservingResponses() {
-        responseTask = Task { [weak self] in
-            let responses = AskCenter.shared.responses(
-                for: CommunicationTopic.self
-            )
-            for await response in responses {
-                await MainActor.run {
-                    self?.handleResponse(response)
-                }
-            }
-        }
-    }
-
     @MainActor
-    private func handleResponse(_ response: PermissionResponse<CommunicationTopic>) {
-        switch response.choice.answer {
-        case .approval:
-            let handles = response.question.topic.personInformation
-                .map(\.handle)
-            for handle in handles {
-                enableCommunication(for: handle)
+    private func apply(_ answer: PermissionResponse<CommunicationTopic>) {
+        let people = answer.question.topic.personInformation
+        for handle in people.map(\.handle) {
+            switch answer.choice.answer {
+            case .approval: enableMessaging(for: handle)
+            case .denial: showDenied(for: handle)
+            @unknown default: showDenied(for: handle)
             }
-        case .denial:
-            let handles = response.question.topic.personInformation
-                .map(\.handle)
-            for handle in handles {
-                showDeniedState(for: handle)
-            }
-        @unknown default:
-            break
         }
     }
-
-    private func showPendingState(for contact: Contact) { }
-    private func schedulePendingExpiration(for id: UUID) { }
-    private func enableMessaging(for contact: Contact) { }
-    private func enableCommunication(for handle: CommunicationHandle) { }
-    private func showDeniedState(for handle: CommunicationHandle) { }
-    private func showFeatureUnavailable() { }
-    private func showError(_ error: Error) { }
 }
 ```
 
-## Response Observer Manager
+`avatarImage` takes a `CGImage`, so convert from `UIImage` with `.cgImage`
+before building the person.
 
-Centralize response observation for apps with multiple permission flows.
+## Response manager
 
-```swift
-import PermissionKit
+A single observable object keeps approval state for the whole app, keyed by
+handle value, plus the ids of questions still waiting.
 
-@Observable
-@MainActor
-final class PermissionManager {
-    static let shared = PermissionManager()
-
-    var approvedHandles: Set<String> = []
-    var deniedHandles: Set<String> = []
-    var pendingHandleValues: Set<String> = []
-    var pendingQuestionIDs: Set<UUID> = []
-
-    private var observerTask: Task<Void, Never>?
-
-    private init() {
-        startObserving()
-    }
-
-    deinit {
-        observerTask?.cancel()
-    }
+```swift
+import Observation
+@preconcurrency import PermissionKit
+import UIKit
 
-    func askPermission(
-        for handles: [CommunicationHandle],
-        actions: Set<CommunicationTopic.Action>,
-        in viewController: UIViewController
-    ) async throws {
-        let personInfo = handles.map { handle in
-            CommunicationTopic.PersonInformation(
-                handle: handle,
-                nameComponents: nil,
-                avatarImage: nil
-            )
+@available(iOS 26.2, *)
+@Observable @MainActor
+final class ContactApprovals {
+    static let shared = ContactApprovals()
+
+    private(set) var approved: Set<String> = []
+    private(set) var denied: Set<String> = []
+    private(set) var waitingValues: Set<String> = []
+    private(set) var waitingQuestions: Set<UUID> = []
+
+    func request(_ handles: [CommunicationHandle],
+                 actions: Set<CommunicationTopic.Action>,
+                 in host: UIViewController) async throws {
+        let people = handles.map {
+            CommunicationTopic.PersonInformation(handle: $0, nameComponents: nil, avatarImage: nil)
         }
-
-        let topic = CommunicationTopic(
-            personInformation: personInfo,
-            actions: actions
-        )
-
         let question = PermissionQuestion<CommunicationTopic>(
-            communicationTopic: topic
+            communicationTopic: CommunicationTopic(personInformation: people, actions: actions)
         )
-
-        try await AskCenter.shared.ask(question, in: viewController)
-        let handleValues = handles.map(\.value)
-        pendingQuestionIDs.insert(question.id)
-        pendingHandleValues.formUnion(handleValues)
-        schedulePendingExpiration(
-            for: question.id,
-            handleValues: handleValues
-        )
-    }
-
-    func isApproved(_ handleValue: String) -> Bool {
-        approvedHandles.contains(handleValue)
+        try await AskCenter.shared.ask(question, in: host as UIViewController)
+        waitingQuestions.insert(question.id)
+        waitingValues.formUnion(handles.map(\.value))
+        scheduleExpiry(question.id, values: handles.map(\.value))
     }
 
-    func isDenied(_ handleValue: String) -> Bool {
-        deniedHandles.contains(handleValue)
-    }
-
-    func isPending(_ handleValue: String) -> Bool {
-        pendingHandleValues.contains(handleValue)
-    }
-
-    private func startObserving() {
-        observerTask = Task { [weak self] in
-            let responses = AskCenter.shared.responses(
-                for: CommunicationTopic.self
-            )
-            for await response in responses {
-                await MainActor.run {
-                    self?.processResponse(response)
-                }
-            }
-        }
-    }
-
-    private func processResponse(
-        _ response: PermissionResponse<CommunicationTopic>
-    ) {
-        pendingQuestionIDs.remove(response.question.id)
-
-        let handleValues = response.question.topic.personInformation
-            .map(\.handle.value)
-        for value in handleValues {
-            pendingHandleValues.remove(value)
-        }
+    func isApproved(_ value: String) -> Bool { approved.contains(value) }
+    func isDenied(_ value: String) -> Bool { denied.contains(value) }
+    func isWaiting(_ value: String) -> Bool { waitingValues.contains(value) }
 
+    func consume(_ response: PermissionResponse<CommunicationTopic>) {
+        let people = response.question.topic.personInformation
+        let values = people.map { $0.handle.value }
+        waitingQuestions.remove(response.question.id)
+        waitingValues.subtract(values)
         switch response.choice.answer {
         case .approval:
-            for value in handleValues {
-                approvedHandles.insert(value)
-                deniedHandles.remove(value)
-            }
+            approved.formUnion(values)
+            denied.subtract(values)
         case .denial:
-            for value in handleValues {
-                deniedHandles.insert(value)
-            }
+            denied.formUnion(values)
         @unknown default:
-            break
+            denied.formUnion(values)
         }
     }
 
-    private func schedulePendingExpiration(
-        for id: UUID,
-        handleValues: [String]
-    ) {
-        // Expire or offer retry if no response arrives after your product's
-        // chosen pending window. Child cancellation produces no response.
+    private func scheduleExpiry(_ id: UUID, values: [String]) {
+        // Product decision: how long a request may stay open before the
+        // child can ask again.
+        Task {
+            try? await ContinuousClock().sleep(until: .now + .seconds(172_800))
+            guard waitingQuestions.remove(id) != nil else { return }
+            waitingValues.subtract(values)
+        }
     }
 }
 ```
 
-## Multi-Contact Permission Flow
-
-Request permission for multiple contacts in a single question.
-
-```swift
-func requestGroupPermission(
-    contacts: [Contact],
-    in viewController: UIViewController
-) async throws {
-    let personInfoList = contacts.map { contact in
-        CommunicationTopic.PersonInformation(
-            handle: CommunicationHandle(
-                value: contact.identifier,
-                kind: .custom
-            ),
-            nameComponents: contact.nameComponents,
-            avatarImage: contact.avatarCGImage
-        )
-    }
+The pending window is a product choice. Pick one, then either expire the
+request or offer a retry when it runs out.
 
-    let topic = CommunicationTopic(
-        personInformation: personInfoList,
-        actions: [.message, .audioCall, .videoCall]
-    )
+## Several contacts in one question
 
-    let question = PermissionQuestion<CommunicationTopic>(
-        communicationTopic: topic
-    )
+One question can cover a whole group. Here the handles are `.custom` values
+built from contact identifiers, and the question allows three kinds of
+contact:
 
-    // Check question properties
-    print("Question ID: \(question.id)")
-    print("Choices: \(question.choices.map(\.title))")
-    print("Default choice: \(question.defaultChoice.title)")
-
-    if let expiration = question.expirationDate {
-        print("Expires: \(expiration)")
+```swift
+func groupQuestion(for memberIDs: [String]) -> PermissionQuestion<CommunicationTopic> {
+    let people = memberIDs.map {
+        CommunicationTopic.PersonInformation(handle: CommunicationHandle(value: $0, kind: .custom))
     }
-
-    try await AskCenter.shared.ask(question, in: viewController)
+    let topic = CommunicationTopic(personInformation: people,
+                                   actions: [.message, .audioCall, .videoCall])
+    return PermissionQuestion(communicationTopic: topic)
 }
+
+let q = groupQuestion(for: ["member-8", "member-9"])
+print(q.id)                              // UUID for tracking
+print(q.choices.map(\.title))            // the options the parent sees
+print(q.defaultChoice.title)
+print(q.expirationDate as Any)           // nil unless set
 ```
 
-## Communication Limits Checking Pattern
+A question exposes `id`, `choices` (each with a `title`), `defaultChoice` and
+an optional `expirationDate`.
 
-Check which handles are already known to the system before building the
-permission UI. This does not prove communication limits are enabled; still
-handle `AskError.communicationLimitsNotEnabled` when asking. `knownHandles(in:)`
-requires a non-nil, nonempty app bundle identifier.
+## Limits-check view model
 
-```swift
-@Observable
-@MainActor
-final class ContactListViewModel {
-    var contacts: [ContactItem] = []
-
-    struct ContactItem: Identifiable {
-        let id: String
-        let name: String
-        let handle: CommunicationHandle
-        var isKnownBySystem: Bool = false
-        var needsPermissionPrompt: Bool = false
-    }
-
-    func refreshContactStatus() async {
-        guard Bundle.main.bundleIdentifier?.isEmpty == false else { return }
+This view model sorts a contact list into "the system already knows this
+handle" and "we will need to ask". It says nothing about whether limits are
+enabled; that only shows up as `AskError.communicationLimitsNotEnabled` when
+you ask.
 
-        let limits = CommunicationLimits.current
-        let allHandles = Set(contacts.map(\.handle))
-        let knownHandles = await limits.knownHandles(in: allHandles)
+```swift
+import Observation
+@preconcurrency import PermissionKit
+
+struct RosterEntry: Identifiable {
+    let id: String
+    let handle: CommunicationHandle
+    var isKnownBySystem = false
+    var needsPermissionPrompt = true
+}
 
-        for i in contacts.indices {
-            contacts[i].isKnownBySystem = knownHandles.contains(
-                contacts[i].handle
-            )
-            contacts[i].needsPermissionPrompt = !contacts[i].isKnownBySystem
+@Observable @MainActor
+final class RosterModel {
+    var entries: [RosterEntry] = []
+
+    func classify() async {
+        let appID = Bundle.main.bundleIdentifier ?? ""
+        if appID.isEmpty { return }
+        let known = await CommunicationLimits.current.knownHandles(in: Set(entries.map(\.handle)))
+        for index in entries.indices {
+            let isKnown = known.contains(entries[index].handle)
+            entries[index].isKnownBySystem = isKnown
+            entries[index].needsPermissionPrompt = !isKnown
         }
     }
 }
 ```
 
-## SwiftUI Full-Screen Permission Flow
+## SwiftUI full flow
 
-Build a complete permission flow in SwiftUI.
+A screen that works out its state on appear, then shows either a
+`PermissionButton`, a waiting label or the final result. The manager is the
+`ContactApprovals` type above, injected through the environment.
 
 ```swift
 import SwiftUI
-import PermissionKit
-
-struct ContactDetailView: View {
-    let contact: Contact
-    @State private var permissionState: PermissionState = .unknown
-    @Environment(PermissionManager.self) private var permissionManager
+@preconcurrency import PermissionKit
 
-    enum PermissionState {
-        case unknown, checking, needsPermission, approved, denied
-        case pending, error(String)
+@available(iOS 26.2, *)
+struct TeammateAccessView: View {
+    enum Phase: Equatable {
+        case unknown, checking, needsPermission, pending, approved, denied
+        case error(String)
     }
 
-    var body: some View {
-        VStack {
-            Text(contact.name)
-                .font(.title)
+    @Environment(ContactApprovals.self) private var approvals
+    let handle: CommunicationHandle
+    let displayName: PersonNameComponents
+    @State private var phase: Phase = .unknown
 
-            switch permissionState {
+    var body: some View {
+        Group {
+            switch phase {
             case .unknown, .checking:
-                ProgressView("Checking permissions...")
-
+                ProgressView()
             case .needsPermission:
-                let handle = CommunicationHandle(
-                    value: contact.phoneNumber,
-                    kind: .phoneNumber
-                )
-                let question = PermissionQuestion<CommunicationTopic>(
-                    handle: handle
-                )
-
-                VStack {
-                    Text("Permission needed to message this contact.")
-                        .foregroundStyle(.secondary)
+                VStack(spacing: 12) {
+                    Text("A parent or guardian needs to allow chatting with this teammate.")
+                        .multilineTextAlignment(.center)
                     PermissionButton(question: question) {
-                        Label("Ask to Message", systemImage: "message.badge.clock")
+                        Label("Ask a parent", systemImage: "figure.and.child.holdinghands")
                     }
                     .buttonStyle(.borderedProminent)
                 }
-
             case .pending:
-                Label("Waiting for parent response", systemImage: "clock")
-                    .foregroundStyle(.secondary)
-
+                Label("Waiting for a parent", systemImage: "hourglass")
             case .approved:
-                Label("Messaging enabled", systemImage: "checkmark.circle.fill")
-                    .foregroundStyle(.green)
-
+                Label("Chat allowed", systemImage: "checkmark.circle")
             case .denied:
-                Label("Permission denied", systemImage: "xmark.circle.fill")
-                    .foregroundStyle(.red)
-
+                Label("Chat not allowed", systemImage: "xmark.circle")
             case .error(let message):
                 Label(message, systemImage: "exclamationmark.triangle")
-                    .foregroundStyle(.orange)
             }
         }
-        .task {
-            await checkPermission()
-        }
+        .task { await resolvePhase() }
     }
 
-    private func checkPermission() async {
-        permissionState = .checking
-        let handle = CommunicationHandle(
-            value: contact.phoneNumber,
-            kind: .phoneNumber
-        )
-        let limits = CommunicationLimits.current
-        let isKnown = await limits.isKnownHandle(handle)
-
-        if isKnown {
-            permissionState = .approved
-        } else if permissionManager.isApproved(contact.phoneNumber) {
-            permissionState = .approved
-        } else if permissionManager.isDenied(contact.phoneNumber) {
-            permissionState = .denied
-        } else if permissionManager.isPending(contact.phoneNumber) {
-            permissionState = .pending
+    private var question: PermissionQuestion<CommunicationTopic> {
+        let person = CommunicationTopic.PersonInformation(handle: handle, nameComponents: displayName)
+        return PermissionQuestion(communicationTopic: CommunicationTopic(personInformation: [person],
+                                                                         actions: [.chat]))
+    }
+
+    private func resolvePhase() async {
+        phase = .checking
+        if await CommunicationLimits.current.isKnownHandle(handle) {
+            phase = .approved
+        } else if approvals.isApproved(handle.value) {
+            phase = .approved
+        } else if approvals.isDenied(handle.value) {
+            phase = .denied
+        } else if approvals.isWaiting(handle.value) {
+            phase = .pending
         } else {
-            permissionState = .needsPermission
+            phase = .needsPermission
         }
     }
 }
 ```
 
-## macOS Integration
+## macOS
 
-On macOS 26.2+, pass an `NSWindow` instead of `UIViewController`.
+On macOS 26.2 and later the ask call takes an `NSWindow` rather than a view
+controller:
 
 ```swift
 #if os(macOS)
 import AppKit
-import PermissionKit
+@preconcurrency import PermissionKit
 
-func requestPermission(
-    for question: PermissionQuestion<CommunicationTopic>,
-    in window: NSWindow
-) async throws {
-    try await AskCenter.shared.ask(question, in: window)
+@available(macOS 26.2, *)
+@MainActor
+func ask(_ question: PermissionQuestion<CommunicationTopic>, from window: NSWindow) async throws {
+    try await AskCenter.shared.ask(question, in: window as NSWindow)
 }
 #endif
 ```
 
-## Error Recovery Patterns
+## Error recovery
 
-Provide actionable recovery for each error type.
+Map every `AskError` case to something the user can read and, where it makes
+sense, act on.
 
 ```swift
-func handleAskError(_ error: AskError) -> (title: String, message: String, action: (() -> Void)?) {
+@preconcurrency import PermissionKit
+
+struct RecoveryAdvice {
+    let title: String
+    let message: String
+    let action: Action?
+    enum Action { case openSettings, retry }
+}
+
+@available(iOS 26.2, *)
+func advice(for error: AskError) -> RecoveryAdvice {
     switch error {
     case .communicationLimitsNotEnabled:
-        return (
-            "No Restrictions",
-            "Communication limits are not enabled. You can communicate freely.",
-            nil
-        )
+        RecoveryAdvice(title: "No approval needed",
+                       message: "You can start chatting right away.", action: nil)
     case .contactSyncNotSetup:
-        return (
-            "Contact Sync Required",
-            "Please enable contact sync in Settings to use this feature.",
-            { openContactSyncSettings() }
-        )
+        RecoveryAdvice(title: "Contacts not synced",
+                       message: "Turn on contact sync so a parent can review this request.",
+                       action: .openSettings)
     case .invalidQuestion:
-        return (
-            "Invalid Request",
-            "The permission request could not be created. Please try again.",
-            nil
-        )
+        RecoveryAdvice(title: "Request could not be built",
+                       message: "Please try again.", action: .retry)
     case .notAvailable:
-        return (
-            "Not Available",
-            "This feature is not available on this device.",
-            nil
-        )
+        RecoveryAdvice(title: "Not available here",
+                       message: "This device cannot send approval requests.", action: nil)
     case .systemError(let underlying):
-        return (
-            "System Error",
-            underlying.localizedDescription,
-            nil
-        )
+        RecoveryAdvice(title: "Something went wrong",
+                       message: underlying.localizedDescription, action: .retry)
     case .unknown:
-        return (
-            "Unknown Error",
-            "An unexpected error occurred. Please try again later.",
-            nil
-        )
+        RecoveryAdvice(title: "Request failed",
+                       message: "Please try again later.", action: .retry)
     @unknown default:
-        return (
-            "Error",
-            "An error occurred.",
-            nil
-        )
+        RecoveryAdvice(title: "Request failed",
+                       message: "Please try again later.", action: .retry)
     }
 }
 ```
+
+`.systemError` is deprecated in the 26.2 SDK (the underlying error is now
+thrown on its own), so pair this mapping with a plain `catch` for non-`AskError`
+failures.