@mmerterden/multi-agent-pipeline 20.36.0 → 20.37.1

package/pipeline/skills/shared/external/apple-on-device-ai/references/foundation-models-code.md

@@ -0,0 +1,186 @@
+# Foundation Models and multi-backend code
+
+<!-- toc -->
+- [Check availability first](#check-availability-first)
+- [Structured output](#structured-output)
+- [Tools](#tools)
+- [Errors](#errors)
+- [Running several backends](#running-several-backends)
+<!-- /toc -->
+
+Code for availability checks, structured output, tools, error handling and routing between several backends. SKILL.md keeps stack choice, rules and review guidance.
+
+## Check availability first
+
+Every entry point checks availability and falls back without crashing.
+
+```swift
+import Foundation
+import FoundationModels
+import os
+
+private let aiLog = Logger(subsystem: "StudyApp", category: "AI")
+
+enum SummaryState { case ready, openSettings, downloading, unsupported }
+
+func summaryState() -> SummaryState {
+    let model = SystemLanguageModel.default
+    switch model.availability {
+    case .available:
+        return model.supportsLocale(Locale.current) ? .ready : .unsupported
+    case .unavailable(.appleIntelligenceNotEnabled):
+        return .openSettings          // point the user to Settings
+    case .unavailable(.modelNotReady):
+        return .downloading           // assets still arriving; show progress
+    case .unavailable(.deviceNotEligible):
+        return .unsupported           // hardware cannot run it; use a fallback
+    case .unavailable(let other):
+        aiLog.notice("Model unavailable: \(String(describing: other))")
+        return .unsupported
+    }
+}
+```
+
+## Structured output
+
+`@Generable` builds the output schema at compile time, and the response comes
+back as your type.
+
+```swift
+@Generable
+struct StudyCard {
+    @Guide(description: "The term being studied, two to four words")
+    var term: String
+    @Guide(description: "Plain-language definitions", .count(2))
+    var definitions: [String]
+    @Guide(.range(1...5))
+    var difficulty: Int
+}
+
+let reply = try await tutor.respond(to: "Make a card for osmosis",
+                                    generating: StudyCard.self)
+let card = reply.content
+```
+
+`@Guide` options:
+
+| Guide | Effect |
+|---|---|
+| `description:` | Natural-language hint for the field |
+| `.anyOf([...])` | String must be one of the listed values |
+| `.count(n)` | Array has exactly `n` elements |
+| `.range(a...b)` | Number within a closed range |
+| `.minimum(n)` / `.maximum(n)` | Lower or upper limit on a number |
+| `.minimumCount(n)` / `.maximumCount(n)` | Limits on how many elements an array has |
+| `.constant(value)` | Field is always exactly this |
+| `.pattern(regex)` | String matches a pattern |
+| `.element(guide)` | Applies a guide to every array element |
+
+Fields are generated in declaration order. Put the fields that others depend on
+first.
+
+Streaming gives partial values as they form; each property of
+`StudyCard.PartiallyGenerated` is optional:
+
+```swift
+let cardStream = tutor.streamResponse(to: "Card for diffusion", generating: StudyCard.self)
+for try await partial in cardStream {
+    draft.term = partial.content.term ?? draft.term
+    draft.definitions = partial.content.definitions ?? draft.definitions
+}
+```
+
+## Tools
+
+```swift
+struct GlossaryTool: Tool {
+    let name = "lookUpTerm"
+    let description = "Returns the course glossary entry for a biology term."
+
+    @Generable
+    struct Arguments {
+        @Guide(description: "Singular form of the term to look up")
+        var term: String
+        @Guide(.range(1...3))
+        var gradeLevel: Int
+    }
+
+    func call(arguments: Arguments) async throws -> String {
+        await Glossary.shared.entry(for: arguments.term, level: arguments.gradeLevel)
+            ?? "No entry found."
+    }
+}
+```
+
+- Register tools when creating the session, and only the ones the task needs.
+- `Tool` is `Sendable`; captured state must be safe to share.
+- Tool names, descriptions and argument schemas, like `@Generable` schemas,
+  use up part of the context budget.
+- Whether a tool runs is the model's decision. Data the answer always needs
+  should be fetched beforehand and put in the prompt; keep tools for lookups
+  that depend on the conversation.
+
+## Errors
+
+```swift
+do {
+    let answer = try await tutor.respond(to: question)
+    show(answer.content)
+} catch let failure as LanguageModelSession.GenerationError {
+    switch failure {
+    case .exceededContextWindowSize:   restartWithSummary()         // too many tokens
+    case .guardrailViolation:          showRephraseHint()           // safety filter hit
+    case .concurrentRequests:          queueUntilIdle()             // session already busy
+    case .unsupportedLanguageOrLocale: showLanguageNotice()
+    case .unsupportedGuide:            logSchemaProblem()           // a @Guide the model cannot honour
+    case .assetsUnavailable:           showDownloadingState()
+    case .refusal(let refusal, _):     explain(refusal)             // stream refusal.explanation
+    case .rateLimited:                 retryLater()                 // back off
+    case .decodingFailure:             logSchemaProblem()           // output did not fit the type
+    default:                           showGenericFailure()
+    }
+}
+```
+
+## Running several backends
+
+Try the system model first, then a local open model, and fail clearly when
+neither is there:
+
+```swift
+func pickBackend() async throws -> Backend {
+    let systemModel = SystemLanguageModel.default
+    if systemModel.isAvailable { return .foundationModels }
+    if await mlxModelCanLoad() { return .mlx }
+    throw AIError.noBackendAvailable
+}
+```
+
+Send every model call through one actor so requests never compete for the same
+hardware. Actors are reentrant: a method that awaits lets the next caller in,
+so an actor that only forwards the call does not serialise anything. Chain the
+work instead:
+
+```swift
+actor InferenceGate {
+    private var last: Task<Void, Never>?
+
+    func exclusive<Value: Sendable>(
+        _ work: @escaping @Sendable () async throws -> Value
+    ) async throws -> Value {
+        let previous = last
+        let current = Task { () async throws -> Value in
+            await previous?.value
+            return try await work()
+        }
+        last = Task { _ = try? await current.value }
+        return try await current.value
+    }
+}
+```
+
+- For a custom Core ML model, this skill stops at conversion and
+  optimisation. Swift integration, loading, Vision hookup and running
+  predictions are for `coreml`.
+- Private material such as journals or health notes stays on the device unless
+  the product has deliberately chosen a non-local fallback.

package/pipeline/skills/shared/external/authentication/SKILL.md

@@ -51,32 +51,7 @@ extension WelcomeViewController: ASAuthorizationControllerPresentationContextPro
 
 ### Delegate callbacks
 
-```swift
-extension WelcomeViewController: ASAuthorizationControllerDelegate {
-    func authorizationController(controller: ASAuthorizationController,
-                                 didCompleteWithAuthorization authorization: ASAuthorization) {
-        let credential = authorization.credential
-        guard let apple = credential as? ASAuthorizationAppleIDCredential else { return }
-        AccountVault.shared.rememberAppleUser(apple.user)          // stable per-team ID
-        if let name = apple.fullName { ProfileDraft.shared.name = name }  // first time only
-        if let mail = apple.email { ProfileDraft.shared.email = mail }    // first time only
-        Task { try await SessionAPI.exchange(token: apple.identityToken, code: apple.authorizationCode) }
-    }
-
-    func authorizationController(controller: ASAuthorizationController,
-                                 didCompleteWithError error: Error) {
-        guard let authError = error as? ASAuthorizationError else { return }
-        switch authError.code {
-        case .canceled:        break                       // user closed the sheet
-        case .notInteractive:  break                       // silent check found nothing
-        case .failed, .invalidResponse, .notHandled:
-            showSignInProblem(authError)
-        default:
-            showSignInProblem(authError)
-        }
-    }
-}
-```
+Code: [Delegate callbacks](references/code-examples.md#delegate-callbacks).
 
 `user` is a stable identifier scoped to your team; save it in the Keychain so
 you can check credential state later. `identityToken` is a JWT for the server
@@ -138,30 +113,7 @@ user out as soon as it fires.
 Never accept the identity token on the device alone. Hand both values to your
 backend and keep only what it returns:
 
-```swift
-enum SessionAPI {
-    struct Session: Decodable { let accessToken: String }
-    private static let transport = URLSession(configuration: .ephemeral)
-
-    static func exchange(token: Data?, code: Data?) async throws {
-        guard let token, let code,
-              let jwt = String(data: token, encoding: .utf8),
-              let grant = String(data: code, encoding: .utf8) else { throw URLError(.badServerResponse) }
-
-        guard let endpoint = URL(string: "https://api.tasknest.app/auth/apple") else { throw URLError(.badURL) }
-        var call = URLRequest(url: endpoint)
-        call.httpMethod = "POST"
-        call.addValue("application/json", forHTTPHeaderField: "Content-Type")
-        let body = try JSONEncoder().encode(["identity_token": jwt, "authorization_code": grant])
-        let (bytes, reply) = try await transport.upload(for: call, from: body)
-        let status = (reply as? HTTPURLResponse)?.statusCode ?? 0
-        if status != 200 { throw URLError(.userAuthenticationRequired) }
-
-        let session = try JSONDecoder().decode(Session.self, from: bytes)
-        try TokenVault(service: "auth").store(Data(session.accessToken.utf8), account: "access")
-    }
-}
-```
+Code: [Server validation](references/code-examples.md#server-validation).
 
 `TokenVault` is in the [Keychain reference](references/keychain-biometric.md). The
 server verifies the JWT signature against Apple's published key set (the JWKS
@@ -388,3 +340,4 @@ mapping against OWASP MASVS/MASTG. App and device attestation belongs to `device
 - [ASAuthorizationPasswordProvider](https://developer.apple.com/documentation/authenticationservices/asauthorizationpasswordprovider)
 - [SignInWithAppleButton](https://developer.apple.com/documentation/authenticationservices/signinwithapplebutton)
 - Sample code: the AuthenticationServices sample on implementing user authentication with Apple ID sign-in
+- [Code examples](references/code-examples.md): open for the full code behind Delegate callbacks, Server validation.

package/pipeline/skills/shared/external/authentication/references/code-examples.md

@@ -0,0 +1,59 @@
+# Authentication Code Examples
+
+Full code samples for the SKILL.md sections that link here. The rules and the decision guidance stay in SKILL.md; each heading below matches the SKILL.md section the code belongs to.
+
+## Delegate callbacks
+
+```swift
+extension WelcomeViewController: ASAuthorizationControllerDelegate {
+    func authorizationController(controller: ASAuthorizationController,
+                                 didCompleteWithAuthorization authorization: ASAuthorization) {
+        let credential = authorization.credential
+        guard let apple = credential as? ASAuthorizationAppleIDCredential else { return }
+        AccountVault.shared.rememberAppleUser(apple.user)          // stable per-team ID
+        if let name = apple.fullName { ProfileDraft.shared.name = name }  // first time only
+        if let mail = apple.email { ProfileDraft.shared.email = mail }    // first time only
+        Task { try await SessionAPI.exchange(token: apple.identityToken, code: apple.authorizationCode) }
+    }
+
+    func authorizationController(controller: ASAuthorizationController,
+                                 didCompleteWithError error: Error) {
+        guard let authError = error as? ASAuthorizationError else { return }
+        switch authError.code {
+        case .canceled:        break                       // user closed the sheet
+        case .notInteractive:  break                       // silent check found nothing
+        case .failed, .invalidResponse, .notHandled:
+            showSignInProblem(authError)
+        default:
+            showSignInProblem(authError)
+        }
+    }
+}
+```
+
+## Server validation
+
+```swift
+enum SessionAPI {
+    struct Session: Decodable { let accessToken: String }
+    private static let transport = URLSession(configuration: .ephemeral)
+
+    static func exchange(token: Data?, code: Data?) async throws {
+        guard let token, let code,
+              let jwt = String(data: token, encoding: .utf8),
+              let grant = String(data: code, encoding: .utf8) else { throw URLError(.badServerResponse) }
+
+        guard let endpoint = URL(string: "https://api.tasknest.app/auth/apple") else { throw URLError(.badURL) }
+        var call = URLRequest(url: endpoint)
+        call.httpMethod = "POST"
+        call.addValue("application/json", forHTTPHeaderField: "Content-Type")
+        let body = try JSONEncoder().encode(["identity_token": jwt, "authorization_code": grant])
+        let (bytes, reply) = try await transport.upload(for: call, from: body)
+        let status = (reply as? HTTPURLResponse)?.statusCode ?? 0
+        if status != 200 { throw URLError(.userAuthenticationRequired) }
+
+        let session = try JSONDecoder().decode(Session.self, from: bytes)
+        try TokenVault(service: "auth").store(Data(session.accessToken.utf8), account: "access")
+    }
+}
+```

package/pipeline/skills/shared/external/callkit-voip/SKILL.md

@@ -145,34 +145,7 @@ ended with `.failed` and fail the action.
 Outgoing calls start with a request to `CXCallController`. The system checks it
 and hands it back through `provider(_:perform:)` with a `CXStartCallAction`.
 
-```swift
-extension PhoneLine {
-    func dial(_ address: String, video: Bool) -> UUID {
-        let id = UUID()
-        let start = CXStartCallAction(call: id, handle: CXHandle(type: .phoneNumber, value: address))
-        start.isVideo = video
-        controller.request(CXTransaction(action: start)) { error in
-            if let error { Log.calls.error("dial refused: \(error)") }
-        }
-        return id
-    }
-
-    func provider(_ cx: CXProvider, perform dial: CXStartCallAction) {
-        AudioRoute.prepareForCall()
-        let id = dial.callUUID
-        cx.reportOutgoingCall(with: id, startedConnectingAt: .now)
-        Task {
-            do {
-                try await SignalingClient.shared.place(call: id, to: dial.handle.value)
-                cx.reportOutgoingCall(with: id, connectedAt: .now)
-                dial.fulfill()
-            } catch {
-                dial.fail()
-            }
-        }
-    }
-}
-```
+Code: [Outgoing call flow](references/code-examples.md#outgoing-call-flow).
 
 Report both `startedConnectingAt` and `connectedAt`; Recents and the call timer
 use them.
@@ -199,62 +172,7 @@ Report rules:
 | 26.4+ delegate, `mustReport == false` | No | After local handling |
 | Older delegate | Treat every VoIP call push as required | After the report callback |
 
-```swift
-import PushKit
-
-@MainActor
-final class VoIPInbox: NSObject, @preconcurrency PKPushRegistryDelegate {
-    private let registry = PKPushRegistry(queue: .main)
-
-    func start() {
-        registry.delegate = self
-        registry.desiredPushTypes = [.voIP]
-    }
-
-    func pushRegistry(_ reg: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) {
-        let hex = credentials.token.reduce(into: "") { out, byte in out += String(format: "%02x", byte) }
-        Backend.shared.upload(voipToken: hex)
-    }
-
-    @available(iOS 26.4, *)
-    func pushRegistry(_ reg: PKPushRegistry,
-                      didReceiveIncomingVoIPPushWith payload: PKPushPayload,
-                      metadata: PKVoIPPushMetadata,
-                      withCompletionHandler completion: @escaping @Sendable () -> Void) {
-        guard metadata.mustReport else {
-            completion()
-            return
-        }
-        ring(from: payload, then: completion)
-    }
-
-    func pushRegistry(_ reg: PKPushRegistry,
-                      didReceiveIncomingPushWith payload: PKPushPayload,
-                      for type: PKPushType,
-                      completion: @escaping () -> Void) {
-        guard type == .voIP else {
-            completion()
-            return
-        }
-        ring(from: payload, then: completion)
-    }
-
-    private func ring(from payload: PKPushPayload, then completion: @escaping () -> Void) {
-        let body = payload.dictionaryPayload
-        let number = body["from"] as? String ?? "Unknown"
-        let name = body["display"] as? String ?? number
-        let video = body["video"] as? Bool ?? false
-        Task {
-            do {
-                try await PhoneLine.shared.announceIncoming(id: UUID(), number: number, name: name, video: video)
-            } catch {
-                Log.calls.notice("call filtered or rejected: \(error)")
-            }
-            completion()
-        }
-    }
-}
-```
+Code: [PushKit VoIP registration](references/code-examples.md#pushkit-voip-registration).
 
 Keep the older delegate method for iOS 26.0 through 26.3 and for lower
 deployment targets. The registry delivers on `.main`, which is why the inbox is
@@ -420,3 +338,4 @@ Rotating APNs keys and the usual notification registration are covered by
 - [PKVoIPPushMetadata](https://developer.apple.com/documentation/pushkit/pkvoippushmetadata)
 - Article: [VoIP call handling with CallKit](https://developer.apple.com/documentation/callkit/making-and-receiving-voip-calls)
 - Article: [PushKit VoIP notification handling](https://developer.apple.com/documentation/pushkit/responding-to-voip-notifications-from-pushkit)
+- [Code examples](references/code-examples.md): open for the full code behind Outgoing call flow, PushKit VoIP registration.

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

@@ -0,0 +1,93 @@
+# CallKit and PushKit Code Examples
+
+Full code samples for the SKILL.md sections that link here. The rules and the decision guidance stay in SKILL.md; each heading below matches the SKILL.md section the code belongs to.
+
+## Outgoing call flow
+
+```swift
+extension PhoneLine {
+    func dial(_ address: String, video: Bool) -> UUID {
+        let id = UUID()
+        let start = CXStartCallAction(call: id, handle: CXHandle(type: .phoneNumber, value: address))
+        start.isVideo = video
+        controller.request(CXTransaction(action: start)) { error in
+            if let error { Log.calls.error("dial refused: \(error)") }
+        }
+        return id
+    }
+
+    func provider(_ cx: CXProvider, perform dial: CXStartCallAction) {
+        AudioRoute.prepareForCall()
+        let id = dial.callUUID
+        cx.reportOutgoingCall(with: id, startedConnectingAt: .now)
+        Task {
+            do {
+                try await SignalingClient.shared.place(call: id, to: dial.handle.value)
+                cx.reportOutgoingCall(with: id, connectedAt: .now)
+                dial.fulfill()
+            } catch {
+                dial.fail()
+            }
+        }
+    }
+}
+```
+
+## PushKit VoIP registration
+
+```swift
+import PushKit
+
+@MainActor
+final class VoIPInbox: NSObject, @preconcurrency PKPushRegistryDelegate {
+    private let registry = PKPushRegistry(queue: .main)
+
+    func start() {
+        registry.delegate = self
+        registry.desiredPushTypes = [.voIP]
+    }
+
+    func pushRegistry(_ reg: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) {
+        let hex = credentials.token.reduce(into: "") { out, byte in out += String(format: "%02x", byte) }
+        Backend.shared.upload(voipToken: hex)
+    }
+
+    @available(iOS 26.4, *)
+    func pushRegistry(_ reg: PKPushRegistry,
+                      didReceiveIncomingVoIPPushWith payload: PKPushPayload,
+                      metadata: PKVoIPPushMetadata,
+                      withCompletionHandler completion: @escaping @Sendable () -> Void) {
+        guard metadata.mustReport else {
+            completion()
+            return
+        }
+        ring(from: payload, then: completion)
+    }
+
+    func pushRegistry(_ reg: PKPushRegistry,
+                      didReceiveIncomingPushWith payload: PKPushPayload,
+                      for type: PKPushType,
+                      completion: @escaping () -> Void) {
+        guard type == .voIP else {
+            completion()
+            return
+        }
+        ring(from: payload, then: completion)
+    }
+
+    private func ring(from payload: PKPushPayload, then completion: @escaping () -> Void) {
+        let body = payload.dictionaryPayload
+        let number = body["from"] as? String ?? "Unknown"
+        let name = body["display"] as? String ?? number
+        let video = body["video"] as? Bool ?? false
+        Task {
+            do {
+                try await PhoneLine.shared.announceIncoming(id: UUID(), number: number, name: name, video: video)
+            } catch {
+                Log.calls.notice("call filtered or rejected: \(error)")
+            }
+            completion()
+        }
+    }
+}
+```