@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/musickit-audio/evals/evals.json

@@ -3,41 +3,42 @@
   "evals": [
     {
       "id": 1,
-      "prompt": "Audit this proposed MusicKit setup for an iOS 26 app: the team adds a com.apple.developer.musickit entitlement in Xcode, skips NSAppleMusicUsageDescription, calls MusicAuthorization.request() during launch, and says authorization will crash when the entitlement is missing. Write a concise review with corrected setup and authorization guidance.",
-      "expected_output": "A review that replaces the invented entitlement guidance with MusicKit App Service setup for an explicit bundle ID, requires NSAppleMusicUsageDescription, and explains authorization behavior without overstating crashes.",
+      "prompt": "We are adding Apple Music to a running-coach app. What do we have to configure in the portal and in the project before MusicKit works, how should we ask for permission, and do we need anything extra so music keeps going when the screen locks? A teammate says we also need the com.apple.developer.musickit entitlement or authorization will crash.",
+      "expected_output": "A setup answer that names the App Service and usage string, explains request() versus currentStatus, treats background audio as conditional, and rejects the entitlement claim.",
       "files": [],
       "assertions": [
-        "Recommends enabling the MusicKit App Service for the app's explicit bundle ID so automatic developer token generation is configured.",
-        "Requires NSAppleMusicUsageDescription before accessing the user's music data or media library.",
-        "Explains that MusicAuthorization.request() presents the system consent dialog when necessary and currentStatus can be checked without prompting.",
-        "Does not claim that com.apple.developer.musickit is the required iOS app entitlement or that a missing entitlement causes authorization to crash.",
-        "Mentions UIBackgroundModes audio only when the app needs background playback."
+        "Says to enable the MusicKit App Service on the app's explicit App ID so developer tokens are generated automatically",
+        "Requires NSAppleMusicUsageDescription in Info.plist",
+        "Explains that MusicAuthorization.request() prompts only when needed and MusicAuthorization.currentStatus reads the state without prompting",
+        "Does not claim a com.apple.developer.musickit entitlement is required on iOS or that its absence crashes authorization",
+        "Adds audio to UIBackgroundModes only because playback must continue in the background"
       ]
     },
     {
       "id": 2,
-      "prompt": "Implement focused SwiftUI snippets for a MusicKit search-and-play flow: search Apple Music songs, play a selected catalog song with ApplicationMusicPlayer, and offer Apple Music subscription signup when playback is unavailable.",
-      "expected_output": "Swift snippets that separate catalog search from subscription playback, gate playback on MusicSubscription.current.canPlayCatalogContent, use ApplicationMusicPlayer, and present the Music subscription offer only when the user can become a subscriber.",
+      "prompt": "Build the flow where a user searches the Apple Music catalog, taps a song and it plays inside our app. Users without Apple Music should be invited to subscribe instead of seeing a broken play button.",
+      "expected_output": "Catalog search, a subscription gate before playback, app-scoped playback, and a correctly gated subscription offer.",
       "files": [],
       "assertions": [
-        "Uses MusicCatalogSearchRequest for catalog search and does not require subscription just to fetch catalog search results.",
-        "Checks MusicSubscription.current.canPlayCatalogContent before attempting catalog playback.",
-        "Uses ApplicationMusicPlayer.shared with queue assignment and play() for app-scoped playback.",
-        "Checks canBecomeSubscriber before presenting the Apple Music subscription offer.",
-        "Uses musicSubscriptionOffer(isPresented:options:onLoadCompletion:) or accurately notes the options and load-completion parameters for the offer sheet."
+        "Searches with MusicCatalogSearchRequest and does not require a subscription for searching",
+        "Gates playback on MusicSubscription.current canPlayCatalogContent",
+        "Plays through ApplicationMusicPlayer.shared by setting the queue and calling play()",
+        "Checks canBecomeSubscriber before showing the offer",
+        "Presents the offer with musicSubscriptionOffer(isPresented:options:onLoadCompletion:)"
       ]
     },
     {
       "id": 3,
-      "prompt": "Review a MusicKit implementation that fetches top songs with MusicCatalogChartsRequest(kinds: [.mostPlayed], types: [Song.self]), adds songs and playlists to the user's library without checking cloud library state, and manually updates MPNowPlayingInfoCenter for Apple Music playback. Explain what should change.",
-      "expected_output": "A review that uses the current chart request initializer shape, gates library writes on authorization and iCloud Music Library availability, and keeps Now Playing guidance scoped to custom audio versus MusicKit playback.",
+      "prompt": "Add a Top Charts screen, a button that saves a song to the user's library, and make sure the Lock Screen shows what is playing. Should we also build a CarPlay scene and an AVKit player while we are at it?",
+      "expected_output": "Charts with an explicit genre argument, guarded library writes, correct Now Playing ownership, and no unrelated AVKit or CarPlay work.",
       "files": [],
       "assertions": [
-        "Uses or recommends MusicCatalogChartsRequest(genre:kinds:types:) with an explicit genre argument such as nil.",
-        "Checks MusicAuthorization.currentStatus or requests authorization before library mutations.",
-        "Checks MusicSubscription.current.hasCloudLibraryEnabled before adding songs, albums, or playlist entries to the user's library.",
-        "Explains that ApplicationMusicPlayer handles Now Playing metadata automatically for Apple Music content.",
-        "Keeps MediaPlayer guidance limited to custom audio or remote command handling and does not broaden into unrelated AVKit or CarPlay implementation advice."
+        "Uses MusicCatalogChartsRequest(genre:kinds:types:) and passes genre explicitly, for example nil",
+        "Confirms authorization before library mutations",
+        "Checks hasCloudLibraryEnabled before adding to the library",
+        "States that ApplicationMusicPlayer publishes Now Playing automatically for Apple Music content",
+        "Limits MediaPlayer guidance to custom audio metadata and remote commands",
+        "Does not add AVKit player or CarPlay scene implementation"
       ]
     }
   ]

package/pipeline/skills/shared/external/musickit-audio/references/musickit-patterns.md

@@ -1,383 +1,294 @@
-# MusicKit + MediaPlayer Extended Patterns
+# MusicKit Patterns
 
-Overflow reference for the `musickit` skill. Contains advanced patterns that exceed the main skill file's scope.
+Longer examples for the `musickit-audio` skill. Its SKILL.md covers setup,
+authorization, subscription checks and the basic player; this file builds on
+that.
 
-## Contents
+## SwiftUI integration
 
-- [MusicKit SwiftUI Integration](#musickit-swiftui-integration)
-- [Genre and Chart Browsing](#genre-and-chart-browsing)
-- [Library Management](#library-management)
-- [Playlist Access](#playlist-access)
-- [Now Playing Session](#now-playing-session)
-- [Background Audio Configuration](#background-audio-configuration)
+### A shared player model
 
-## MusicKit SwiftUI Integration
-
-### Music Player Manager with `@Observable`
+One `@Observable` object on the main actor owns access and subscription state
+and drives the player. Views read it from the environment.
 
 ```swift
 import MusicKit
-import MediaPlayer
+import Observation
 
-@Observable
 @MainActor
-final class MusicPlayerManager {
-    let player = ApplicationMusicPlayer.shared
-
-    var currentSong: Song?
-    var isPlaying = false
-    var playbackTime: TimeInterval = 0
-    var queue: [Song] = []
-    var hasSubscription = false
-
-    func setup() async {
-        // Check authorization
-        let status = await MusicAuthorization.request()
-        guard status == .authorized else { return }
-
-        // Check subscription
-        if let subscription = try? await MusicSubscription.current {
-            hasSubscription = subscription.canPlayCatalogContent
-        }
+@Observable
+final class ListeningSession {
+    private(set) var accessGranted = false
+    private(set) var catalogPlayable = false
+    private var membershipWatcher: Task<Void, Never>?
+
+    func prepare() async {
+        accessGranted = await MusicAuthorization.request() == .authorized
+        guard accessGranted else { return }
+
+        catalogPlayable = (try? await MusicSubscription.current.canPlayCatalogContent) ?? false
 
-        // Observe subscription changes
-        Task {
-            for await subscription in MusicSubscription.subscriptionUpdates {
-                hasSubscription = subscription.canPlayCatalogContent
+        membershipWatcher = Task { [weak self] in
+            let updates = MusicSubscription.subscriptionUpdates
+            for await membership in updates {
+                self?.catalogPlayable = membership.canPlayCatalogContent
             }
         }
     }
 
-    func play(_ song: Song) async throws {
-        guard hasSubscription else { return }
-        player.queue = [song]
+    func play(_ track: Song) async throws {
+        guard catalogPlayable else { return }
+        let player = ApplicationMusicPlayer.shared
+        player.queue = [track]
         try await player.play()
-        currentSong = song
-        isPlaying = true
     }
 
-    func togglePlayPause() {
-        if player.state.playbackStatus == .playing {
-            player.pause()
-            isPlaying = false
-        } else {
-            Task {
-                try? await player.play()
-                isPlaying = true
-            }
-        }
+    func playOrPause() async throws {
+        let player = ApplicationMusicPlayer.shared
+        let isRunning = player.state.playbackStatus == .playing
+        if isRunning { player.pause() } else { try await player.play() }
     }
 
-    func skip() async {
-        try? await player.skipToNextEntry()
+    func next() async throws {
+        try await ApplicationMusicPlayer.shared.skipToNextEntry()
     }
 }
 ```
 
-### SwiftUI Player View
+Install it once near the root with `.environment(session)` and call
+`prepare()` from a `.task`. The model does not keep the player in a property:
+`ApplicationMusicPlayer` is not `Sendable`, and Swift 6 refuses an async call
+such as `play()` on one reached through main-actor state. Each method reads
+`ApplicationMusicPlayer.shared` into a local instead.
 
-```swift
-import SwiftUI
-import MusicKit
+### Mini player bar
+
+`ArtworkImage` renders MusicKit artwork at a requested size.
 
-struct MiniPlayerView: View {
-    @Environment(MusicPlayerManager.self) private var manager
+```swift
+struct NowPlayingBar: View {
+    @Environment(ListeningSession.self) private var session
+    let track: Song
 
     var body: some View {
-        HStack {
-            if let song = manager.currentSong {
-                if let artwork = song.artwork {
-                    ArtworkImage(artwork, width: 44, height: 44)
-                        .clipShape(.rect(cornerRadius: 6))
-                }
-
-                VStack(alignment: .leading) {
-                    Text(song.title)
-                        .font(.subheadline)
-                        .lineLimit(1)
-                    Text(song.artistName)
-                        .font(.caption)
-                        .foregroundStyle(.secondary)
-                }
-
-                Spacer()
-
-                Button {
-                    manager.togglePlayPause()
-                } label: {
-                    Image(systemName: manager.isPlaying ? "pause.fill" : "play.fill")
-                        .font(.title2)
-                }
-
-                Button {
-                    Task { await manager.skip() }
-                } label: {
-                    Image(systemName: "forward.fill")
-                }
+        HStack(alignment: .center, spacing: 10) {
+            if let cover = track.artwork {
+                ArtworkImage(cover, width: 48, height: 48)
+                    .clipShape(.rect(cornerRadius: 8))
             }
+            VStack(alignment: .leading, spacing: 2) {
+                Text(track.title).font(.subheadline.bold())
+                Text(track.artistName).foregroundStyle(.secondary).font(.caption)
+            }
+            Spacer(minLength: 8)
+            Button("Play or pause", systemImage: "playpause.fill") {
+                Task { try? await session.playOrPause() }
+            }
+            .labelStyle(.iconOnly)
         }
         .padding(.horizontal)
-        .frame(height: 60)
     }
 }
 ```
 
-### Search View
+### Search screen
+
+Search as the text changes and clear the list when the field is empty.
 
 ```swift
-struct MusicSearchView: View {
-    @State private var searchText = ""
-    @State private var results: MusicItemCollection<Song> = []
-    @Environment(MusicPlayerManager.self) private var manager
+struct CatalogFinder: View {
+    @State private var phrase = ""
+    @State private var hits: MusicItemCollection<Song> = []
 
     var body: some View {
-        NavigationStack {
-            List(results) { song in
-                Button {
-                    Task { try? await manager.play(song) }
-                } label: {
-                    HStack {
-                        if let artwork = song.artwork {
-                            ArtworkImage(artwork, width: 50, height: 50)
-                                .clipShape(.rect(cornerRadius: 4))
-                        }
-                        VStack(alignment: .leading) {
-                            Text(song.title)
-                            Text(song.artistName)
-                                .font(.caption)
-                                .foregroundStyle(.secondary)
-                        }
-                    }
-                }
-            }
-            .searchable(text: $searchText, prompt: "Search Apple Music")
-            .onChange(of: searchText) {
-                Task { await search() }
-            }
-            .navigationTitle("Search")
+        List(hits) { song in
+            LabeledContent(song.title, value: song.artistName)
+        }
+        .searchable(text: $phrase, prompt: "Artists, songs, albums")
+        .onChange(of: phrase) { _, newPhrase in
+            Task { await refresh(for: newPhrase) }
         }
     }
 
-    private func search() async {
-        guard !searchText.isEmpty else {
-            results = []
-            return
-        }
-        var request = MusicCatalogSearchRequest(term: searchText, types: [Song.self])
-        request.limit = 25
-        if let response = try? await request.response() {
-            results = response.songs
-        }
+    private func refresh(for text: String) async {
+        guard !text.isEmpty else { hits = []; return }
+        var search = MusicCatalogSearchRequest(term: text, types: [Song.self])
+        search.limit = 25
+        hits = (try? await search.response().songs) ?? []
     }
 }
 ```
 
-## Genre and Chart Browsing
+## Genre and chart browsing
 
-### Fetching Top Charts
+Pass `genre` explicitly, even when you want all genres, so the intent is clear
+at the call site.
 
 ```swift
-func fetchTopSongs() async throws -> MusicItemCollection<Song> {
-    var request = MusicCatalogChartsRequest(
-        genre: nil,
-        kinds: [.mostPlayed],
-        types: [Song.self]
-    )
-    request.limit = 50
-    let response = try await request.response()
-    return response.songCharts.first?.items ?? []
+func topTracks() async throws -> MusicItemCollection<Song> {
+    let wanted: [MusicCatalogChartKind] = [.mostPlayed]
+    var charts = MusicCatalogChartsRequest(genre: nil, kinds: wanted, types: [Song.self])
+    charts.limit = 50
+    let result = try await charts.response()
+    guard let chart = result.songCharts.first else { return [] }
+    return chart.items
 }
 ```
 
-### Fetching by Genre
+A simple way to browse by genre is to search with the genre's name:
 
 ```swift
-func fetchSongsByGenre(_ genre: Genre) async throws -> MusicItemCollection<Song> {
-    var request = MusicCatalogSearchRequest(term: genre.name, types: [Song.self])
-    request.limit = 25
-    let response = try await request.response()
-    return response.songs
+func tracks(tagged style: Genre) async throws -> MusicItemCollection<Song> {
+    let label = style.name
+    let search = MusicCatalogSearchRequest(term: label, types: [Song.self])
+    return try await search.response().songs
 }
 ```
 
-## Library Management
-
-Library writes require MusicKit authorization and an enabled iCloud Music Library.
-Check `MusicSubscription.current.hasCloudLibraryEnabled` before adding items or
-modifying playlists.
+## Library management
 
-### Adding to Library
+Writing to the user's library needs two things: authorization, and iCloud Music
+Library turned on for the account.
 
 ```swift
-func addToLibrary(_ song: Song) async throws {
-    guard MusicAuthorization.currentStatus == .authorized else { return }
-    let subscription = try await MusicSubscription.current
-    guard subscription.hasCloudLibraryEnabled else { return }
-
-    try await MusicLibrary.shared.add(song)
+func canWriteLibrary() async -> Bool {
+    if MusicAuthorization.currentStatus != .authorized { return false }
+    let membership = try? await MusicSubscription.current
+    return membership?.hasCloudLibraryEnabled ?? false
 }
 
-func addAlbumToLibrary(_ album: Album) async throws {
-    guard MusicAuthorization.currentStatus == .authorized else { return }
-    let subscription = try await MusicSubscription.current
-    guard subscription.hasCloudLibraryEnabled else { return }
+func save(_ track: Song) async throws {
+    let library = MusicLibrary.shared
+    if await canWriteLibrary() { try await library.add(track) }
+}
 
-    try await MusicLibrary.shared.add(album)
+func save(_ record: Album) async throws {
+    let library = MusicLibrary.shared
+    if await canWriteLibrary() { try await library.add(record) }
 }
 ```
 
-### Fetching Library Content
+Reading from the library uses `MusicLibraryRequest`:
 
 ```swift
-func fetchLibrarySongs() async throws -> MusicItemCollection<Song> {
-    var request = MusicLibraryRequest<Song>()
-    request.sort(by: \.lastPlayedDate, ascending: false)
-    request.limit = 50
-    let response = try await request.response()
-    return response.items
+func lastListened() async throws -> MusicItemCollection<Song> {
+    var query = MusicLibraryRequest<Song>()
+    query.sort(by: \.lastPlayedDate, ascending: false)
+    query.limit = 20
+    return try await query.response().items
 }
 ```
 
-## Playlist Access
+## Playlist access
 
-### Fetching User Playlists
+A library request for playlists sorts only by `lastPlayedDate`,
+`libraryAddedDate` or `name`; `Playlist.lastModifiedDate` exists but is not a
+sort key.
 
 ```swift
-func fetchPlaylists() async throws -> MusicItemCollection<Playlist> {
-    var request = MusicLibraryRequest<Playlist>()
-    request.sort(by: \.lastModifiedDate, ascending: false)
-    let response = try await request.response()
-    return response.items
+func recentPlaylists() async throws -> MusicItemCollection<Playlist> {
+    var query = MusicLibraryRequest<Playlist>()
+    query.sort(by: \.lastPlayedDate, ascending: false)
+    return try await query.response().items
 }
-```
-
-### Adding Tracks to a Playlist
 
-```swift
-func addToPlaylist(_ playlist: Playlist, songs: [Song]) async throws {
-    guard MusicAuthorization.currentStatus == .authorized else { return }
-    let subscription = try await MusicSubscription.current
-    guard subscription.hasCloudLibraryEnabled else { return }
-
-    try await MusicLibrary.shared.add(songs, to: playlist)
+func append(_ tracks: [Song], to list: Playlist) async throws {
+    guard await canWriteLibrary() else { return }
+    for track in tracks {
+        _ = try await MusicLibrary.shared.add(track, to: list)
+    }
 }
 ```
 
-## Now Playing Session
+## Now Playing session
 
-Use `MPNowPlayingSession` when your app manages multiple simultaneous audio
-sessions (e.g., picture-in-picture video plus background music).
+When an app runs more than one audio source at once (for example a
+Picture in Picture video next to a music stream), give each its own
+`MPNowPlayingSession`. Each session carries its own command center and info
+center, and the app says which one should be the system's Now Playing entry.
 
 ```swift
-import MediaPlayer
 import AVFoundation
+import MediaPlayer
 
-func createNowPlayingSession(for player: AVPlayer) -> MPNowPlayingSession {
-    let session = MPNowPlayingSession(players: [player])
-
-    // Session-scoped remote command center
-    session.remoteCommandCenter.playCommand.addTarget { _ in
-        player.play()
-        return .success
-    }
-
-    session.remoteCommandCenter.pauseCommand.addTarget { _ in
-        player.pause()
+@MainActor
+func makeVideoSession(for videoPlayer: AVPlayer) -> MPNowPlayingSession {
+    let clipSession = MPNowPlayingSession(players: [videoPlayer])
+    let controls = clipSession.remoteCommandCenter
+    controls.playCommand.addTarget { event in
+        videoPlayer.play()
         return .success
     }
-
-    // Session-scoped now playing info
-    session.nowPlayingInfoCenter.nowPlayingInfo = [
-        MPMediaItemPropertyTitle: "Track Title",
-        MPMediaItemPropertyArtist: "Artist Name"
+    clipSession.nowPlayingInfoCenter.nowPlayingInfo = [
+        MPMediaItemPropertyTitle: "Match highlights"
     ]
-
-    // Activate this session to become the "now playing" app
-    session.becomeActiveIfPossible { success in
-        print("Now playing session active: \(success)")
+    clipSession.becomeActiveIfPossible { didBecomeActive in
+        // didBecomeActive is false if another app currently owns Now Playing.
     }
-
-    return session
+    return clipSession
 }
 ```
 
-## Background Audio Configuration
+## Background audio configuration
 
-### Audio Session Setup
-
-Configure the audio session before starting playback to enable background audio.
+Set up the audio session before playback starts:
 
 ```swift
-import AVFoundation
-
 func configureAudioSession() throws {
-    let session = AVAudioSession.sharedInstance()
-    try session.setCategory(.playback, mode: .default)
-    try session.setActive(true)
+    let audio = AVAudioSession.sharedInstance()
+    try audio.setCategory(.playback, mode: .default)
+    try audio.setActive(true)
 }
 ```
 
-### Info.plist Background Mode
+Then list `audio` under the `UIBackgroundModes` key in Info.plist (in Xcode:
+Signing and Capabilities, Background Modes, "Audio, AirPlay, and Picture in
+Picture").
 
-Add `audio` to `UIBackgroundModes` in Info.plist:
+### Interruptions
 
-```xml
-<key>UIBackgroundModes</key>
-<array>
-    <string>audio</string>
-</array>
-```
-
-### Handling Interruptions
+Calls, alarms and Siri interrupt playback. Pause when it starts; resume only if
+the system says so when it ends. The async notification sequence keeps the
+handler on the main actor.
 
 ```swift
-func observeInterruptions() {
-    NotificationCenter.default.addObserver(
-        forName: AVAudioSession.interruptionNotification,
-        object: AVAudioSession.sharedInstance(),
-        queue: .main
-    ) { notification in
-        guard let typeValue = notification.userInfo?[AVAudioSessionInterruptionTypeKey] as? UInt,
-              let type = AVAudioSession.InterruptionType(rawValue: typeValue) else {
-            return
-        }
-
-        switch type {
-        case .began:
-            // Pause UI, save state
-            break
-        case .ended:
-            let options = notification.userInfo?[AVAudioSessionInterruptionOptionKey] as? UInt
-            if let options, AVAudioSession.InterruptionOptions(rawValue: options).contains(.shouldResume) {
-                // Resume playback
-            }
-        @unknown default:
-            break
+@MainActor
+func followInterruptions(for engine: EpisodeEngine) async {
+    let feed = NotificationCenter.default.notifications(named: AVAudioSession.interruptionNotification)
+    for await note in feed {
+        let info = note.userInfo ?? [:]
+        guard let kindValue = info[AVAudioSessionInterruptionTypeKey] as? UInt,
+              let kind = AVAudioSession.InterruptionType(rawValue: kindValue) else { continue }
+
+        if kind == .began {
+            engine.suspend()   // also remember the position
+        } else if kind == .ended {
+            let flags = AVAudioSession.InterruptionOptions(
+                rawValue: info[AVAudioSessionInterruptionOptionKey] as? UInt ?? 0)
+            if flags.contains(.shouldResume) { engine.resume() }
         }
     }
 }
 ```
 
-### Route Change Handling
+### Route changes
 
-Pause playback when headphones are unplugged to avoid unexpected speaker output.
+Pulling out headphones should stop the audio instead of moving it to the
+speaker. The system reports that as `.oldDeviceUnavailable`.
 
 ```swift
-func observeRouteChanges() {
-    NotificationCenter.default.addObserver(
-        forName: AVAudioSession.routeChangeNotification,
-        object: AVAudioSession.sharedInstance(),
-        queue: .main
-    ) { notification in
-        guard let reasonValue = notification.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt,
-              let reason = AVAudioSession.RouteChangeReason(rawValue: reasonValue) else {
-            return
-        }
-
-        if reason == .oldDeviceUnavailable {
-            // Headphones were unplugged -- pause playback
-            pausePlayback()
+@MainActor
+func followRouteChanges(for engine: EpisodeEngine) async {
+    let feed = NotificationCenter.default.notifications(named: AVAudioSession.routeChangeNotification)
+    for await note in feed {
+        let reasonValue = note.userInfo?[AVAudioSessionRouteChangeReasonKey] as? UInt ?? 0
+        if AVAudioSession.RouteChangeReason(rawValue: reasonValue) == .oldDeviceUnavailable {
+            engine.suspend()
         }
     }
 }
 ```
+
+Start both from a long-lived `.task` or from the engine's own setup.
+`EpisodeEngine` stands for whatever `@MainActor` type drives the app's custom
+audio.