@mmerterden/multi-agent-pipeline 8.6.1 → 10.0.6

package/pipeline/skills/shared/external/core-bluetooth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: core-bluetooth
-description: "Scan, connect, and communicate with Bluetooth Low Energy peripherals and publish local peripheral services using Core Bluetooth. Use when implementing BLE central or peripheral roles, discovering services and characteristics, reading and writing characteristic values, subscribing to notifications, configuring background BLE modes, restoring state after app relaunch, or working with CBCentralManager, CBPeripheral, CBPeripheralManager, CBService, CBCharacteristic, CBUUID, or Bluetooth Low Energy workflows."
+description: "Build direct Bluetooth Low Energy workflows with Core Bluetooth. Use when implementing BLE central or peripheral GATT communication, scanning or connecting with CBCentralManager, discovering services and characteristics, reading/writing/subscribing with CBPeripheral, publishing local services with CBPeripheralManager, handling Bluetooth authorization, background BLE modes, state restoration, write flow control, or CBUUID-based workflows. For privacy-preserving accessory setup/picker flows, use accessorysetupkit first and return here for post-setup GATT communication."
 ---
 
 # Core Bluetooth
@@ -8,7 +8,9 @@ description: "Scan, connect, and communicate with Bluetooth Low Energy periphera
 Scan for, connect to, and exchange data with Bluetooth Low Energy (BLE) devices.
 Covers the central role (scanning and connecting to peripherals), the peripheral
 role (advertising services), background modes, and state restoration.
-Targets Swift 6.2 / iOS 26+.
+Targets Swift 6.3 / iOS 26+.
+Use `accessorysetupkit` for privacy-preserving accessory discovery and setup;
+use this skill for direct Core Bluetooth GATT communication.
 
 ## Contents
 
@@ -36,9 +38,12 @@ Targets Swift 6.2 / iOS 26+.
 
 ### Bluetooth Authorization
 
-iOS prompts for Bluetooth permission automatically when you create a
-`CBCentralManager` or `CBPeripheralManager`. The usage description from
-`NSBluetoothAlwaysUsageDescription` is shown in the permission dialog.
+Core Bluetooth has no explicit permission request API. Add
+`NSBluetoothAlwaysUsageDescription`, create the manager when the app is ready for
+Bluetooth access, then check `manager.authorization` and `manager.state`.
+Treat `.denied` and `.restricted` as terminal until the user changes Settings;
+wait for `.poweredOn` before scanning, connecting, advertising, or publishing
+services.
 
 ## Central Role: Scanning
 
@@ -59,23 +64,8 @@ final class BluetoothManager: NSObject, CBCentralManagerDelegate {
     }
 
     func centralManagerDidUpdateState(_ central: CBCentralManager) {
-        switch central.state {
-        case .poweredOn:
-            startScanning()
-        case .poweredOff:
-            // Bluetooth is off -- prompt user to enable
-            break
-        case .unauthorized:
-            // App not authorized for Bluetooth
-            break
-        case .unsupported:
-            // Device does not support BLE
-            break
-        case .resetting, .unknown:
-            break
-        @unknown default:
-            break
-        }
+        guard central.state == .poweredOn else { return }
+        startScanning()
     }
 }
 ```
@@ -121,15 +111,6 @@ func centralManager(
     peripheral.discoverServices([heartRateServiceUUID])
 }
 
-func centralManager(
-    _ central: CBCentralManager,
-    didFailToConnect peripheral: CBPeripheral,
-    error: Error?
-) {
-    // Handle connection failure -- retry or inform user
-    discoveredPeripheral = nil
-}
-
 func centralManager(
     _ central: CBCentralManager,
     didDisconnectPeripheral peripheral: CBPeripheral,
@@ -180,20 +161,6 @@ extension BluetoothManager: CBPeripheralDelegate {
 }
 ```
 
-### Common Service and Characteristic UUIDs
-
-| Service | UUID | Characteristics |
-|---|---|---|
-| Heart Rate | `180D` | Heart Rate Measurement (`2A37`), Body Sensor Location (`2A38`) |
-| Battery | `180F` | Battery Level (`2A19`) |
-| Device Information | `180A` | Manufacturer Name (`2A29`), Model Number (`2A24`) |
-| Generic Access | `1800` | Device Name (`2A00`), Appearance (`2A01`) |
-
-```swift
-let heartRateMeasurementUUID = CBUUID(string: "2A37")
-let batteryLevelUUID = CBUUID(string: "2A19")
-```
-
 ## Reading, Writing, and Notifications
 
 ### Reading a Value
@@ -208,8 +175,9 @@ func peripheral(
 
     switch characteristic.uuid {
     case CBUUID(string: "2A37"):
-        let heartRate = parseHeartRate(data)
-        print("Heart rate: \(heartRate) bpm")
+        if let heartRate = parseHeartRate(data) {
+            print("Heart rate: \(heartRate) bpm")
+        }
     case CBUUID(string: "2A19"):
         let batteryLevel = data.first.map { Int($0) } ?? 0
         print("Battery: \(batteryLevel)%")
@@ -218,10 +186,12 @@ func peripheral(
     }
 }
 
-private func parseHeartRate(_ data: Data) -> Int {
+private func parseHeartRate(_ data: Data) -> Int? {
+    guard data.count >= 2 else { return nil }
     let flags = data[0]
     let is16Bit = (flags & 0x01) != 0
     if is16Bit {
+        guard data.count >= 3 else { return nil }
         return Int(data[1]) | (Int(data[2]) << 8)
     } else {
         return Int(data[1])
@@ -233,15 +203,25 @@ private func parseHeartRate(_ data: Data) -> Int {
 
 ```swift
 func writeValue(_ data: Data, to characteristic: CBCharacteristic,
-                on peripheral: CBPeripheral) {
-    if characteristic.properties.contains(.writeWithoutResponse) {
-        peripheral.writeValue(data, for: characteristic, type: .withoutResponse)
+                on peripheral: CBPeripheral,
+                preferResponse: Bool = true) {
+    let type: CBCharacteristicWriteType
+    if preferResponse, characteristic.properties.contains(.write) {
+        type = .withResponse
+    } else if characteristic.properties.contains(.writeWithoutResponse),
+              peripheral.canSendWriteWithoutResponse {
+        type = .withoutResponse
     } else if characteristic.properties.contains(.write) {
-        peripheral.writeValue(data, for: characteristic, type: .withResponse)
+        type = .withResponse
+    } else {
+        return
     }
+
+    guard data.count <= peripheral.maximumWriteValueLength(for: type) else { return }
+    peripheral.writeValue(data, for: characteristic, type: type)
 }
 
-// Confirmation callback for .withResponse writes
+// Confirmation callback for .withResponse writes.
 func peripheral(
     _ peripheral: CBPeripheral,
     didWriteValueFor characteristic: CBCharacteristic,
@@ -251,6 +231,9 @@ func peripheral(
         print("Write failed: \(error.localizedDescription)")
     }
 }
+
+// Resume queued .withoutResponse writes here.
+func peripheralIsReady(toSendWriteWithoutResponse peripheral: CBPeripheral) {}
 ```
 
 ### Subscribing to Notifications
@@ -327,16 +310,16 @@ final class BLEPeripheralManager: NSObject, CBPeripheralManagerDelegate {
 
 Add `bluetooth-central` to `UIBackgroundModes`. In the background:
 
-- Scanning continues but only for specific service UUIDs
-- `CBCentralManagerScanOptionAllowDuplicatesKey` is ignored (always `false`)
-- Discovery callbacks are coalesced and delivered in batches
+- Scanning must specify one or more service UUIDs; `nil` scans are foreground-only
+- Scan options, including `CBCentralManagerScanOptionAllowDuplicatesKey`, have no effect
 
 ### Background Peripheral Mode
 
 Add `bluetooth-peripheral` to `UIBackgroundModes`. In the background:
 
-- Advertising continues but data is reduced to service UUIDs only
-- The local name is not included in background advertisements
+- Without this mode, published service contents are disabled while suspended
+- The local name is not advertised
+- Service UUIDs move to the overflow area and require explicit service scans
 
 ## State Restoration
 
@@ -366,6 +349,11 @@ func centralManager(
             discoveredPeripheral = peripheral
         }
     }
+    let restoredServices = dict[CBCentralManagerRestoredStateScanServicesKey]
+        as? [CBUUID]
+    let restoredOptions = dict[CBCentralManagerRestoredStateScanOptionsKey]
+        as? [String: Any]
+    // Resume scanning with restoredServices/restoredOptions if still needed.
 }
 ```
 
@@ -382,7 +370,11 @@ func peripheralManager(
     _ peripheral: CBPeripheralManager,
     willRestoreState dict: [String: Any]
 ) {
-    // Restore published services, advertising state, etc.
+    let services = dict[CBPeripheralManagerRestoredStateServicesKey]
+        as? [CBMutableService]
+    let advertisement = dict[CBPeripheralManagerRestoredStateAdvertisementDataKey]
+        as? [String: Any]
+    // Reconnect app state to restored services/advertisement as needed.
 }
 ```
 
@@ -448,16 +440,19 @@ func centralManager(_ central: CBCentralManager,
 }
 ```
 
-### DON'T: Write to a characteristic without checking properties
+### DON'T: Write without checking properties and flow control
 
 ```swift
-// WRONG: Crashes or silently fails if write is unsupported
+// WRONG: May fail, report an error, or provide no confirmation
 peripheral.writeValue(data, for: characteristic, type: .withResponse)
 
-// CORRECT: Check properties first
-if characteristic.properties.contains(.write) {
+// CORRECT: Check properties, length, and .withoutResponse flow control
+if characteristic.properties.contains(.write),
+   data.count <= peripheral.maximumWriteValueLength(for: .withResponse) {
     peripheral.writeValue(data, for: characteristic, type: .withResponse)
-} else if characteristic.properties.contains(.writeWithoutResponse) {
+} else if characteristic.properties.contains(.writeWithoutResponse),
+          peripheral.canSendWriteWithoutResponse,
+          data.count <= peripheral.maximumWriteValueLength(for: .withoutResponse) {
     peripheral.writeValue(data, for: characteristic, type: .withoutResponse)
 }
 ```
@@ -470,6 +465,8 @@ if characteristic.properties.contains(.write) {
 - [ ] Scanning uses specific service UUIDs (not `nil`) in production
 - [ ] `CBPeripheralDelegate` set before calling `discoverServices`
 - [ ] Characteristic properties checked before read/write/notify
+- [ ] Write payloads stay within `maximumWriteValueLength(for:)`
+- [ ] `.withoutResponse` writes honor `canSendWriteWithoutResponse`
 - [ ] Background mode (`bluetooth-central` or `bluetooth-peripheral`) added if needed
 - [ ] State restoration identifier set if app needs relaunch-on-BLE-event support
 - [ ] `willRestoreState` delegate method implemented when using state restoration
@@ -479,7 +476,7 @@ if characteristic.properties.contains(.write) {
 
 ## References
 
-- Extended patterns (reconnection strategies, data parsing, SwiftUI integration): `references/ble-patterns.md`
+- Extended patterns (reconnection strategies, data parsing, SwiftUI integration): [references/ble-patterns.md](references/ble-patterns.md)
 - [Core Bluetooth framework](https://sosumi.ai/documentation/corebluetooth)
 - [CBCentralManager](https://sosumi.ai/documentation/corebluetooth/cbcentralmanager)
 - [CBPeripheral](https://sosumi.ai/documentation/corebluetooth/cbperipheral)
@@ -489,3 +486,11 @@ if characteristic.properties.contains(.write) {
 - [CBUUID](https://sosumi.ai/documentation/corebluetooth/cbuuid)
 - [CBCentralManagerDelegate](https://sosumi.ai/documentation/corebluetooth/cbcentralmanagerdelegate)
 - [CBPeripheralDelegate](https://sosumi.ai/documentation/corebluetooth/cbperipheraldelegate)
+- [NSBluetoothAlwaysUsageDescription](https://sosumi.ai/documentation/bundleresources/information-property-list/nsbluetoothalwaysusagedescription)
+- [CBManagerAuthorization](https://sosumi.ai/documentation/corebluetooth/cbmanagerauthorization)
+- [scanForPeripherals(withServices:options:)](https://sosumi.ai/documentation/corebluetooth/cbcentralmanager/scanforperipherals(withservices:options:))
+- [startAdvertising(_:)](https://sosumi.ai/documentation/corebluetooth/cbperipheralmanager/startadvertising(_:))
+- [writeValue(_:for:type:)](https://sosumi.ai/documentation/corebluetooth/cbperipheral/writevalue(_:for:type:))
+- [maximumWriteValueLength(for:)](https://sosumi.ai/documentation/corebluetooth/cbperipheral/maximumwritevaluelength(for:))
+- [canSendWriteWithoutResponse](https://sosumi.ai/documentation/corebluetooth/cbperipheral/cansendwritewithoutresponse)
+- [Configuring background execution modes](https://sosumi.ai/documentation/xcode/configuring-background-execution-modes)

package/pipeline/skills/shared/external/core-bluetooth/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "skill_name": "core-bluetooth",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm building an iOS heart-rate monitor screen that scans for service 180D, connects, subscribes to 2A37, parses the BPM, and sends a small command to a writable characteristic. Show the Core Bluetooth manager code and the safety checks I should include.",
+      "expected_output": "Guidance creates a CBCentralManager, waits for poweredOn, checks Bluetooth authorization, scans with service UUID 180D, retains the discovered peripheral, sets the peripheral delegate before discovery, subscribes to notify characteristics, parses heart-rate data with byte-count guards, and chooses write types using characteristic properties plus maximumWriteValueLength and canSendWriteWithoutResponse.",
+      "files": [],
+      "assertions": [
+        "The output checks Bluetooth authorization and gates BLE operations on the manager reaching poweredOn.",
+        "The output scans for service UUID 180D rather than using a nil production scan.",
+        "The output retains the discovered CBPeripheral and sets its delegate before service discovery.",
+        "The output parses heart-rate measurement data with explicit guards for the flags byte and 16-bit BPM payload length.",
+        "The output checks characteristic write properties, maximumWriteValueLength(for:), and canSendWriteWithoutResponse before using writeValue."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this BLE background plan: scan for all peripherals with nil services while in the background, rely on allowDuplicates for live RSSI, advertise a local name from the phone, skip bluetooth-peripheral because the service was added before suspension, and restore only the peripheral identifier after relaunch.",
+      "expected_output": "Review flags each background/state-restoration issue. It explains that background central scans require explicit service UUIDs and scan options have no effect; background peripheral advertising omits the local name and puts service UUIDs in overflow; published service contents are disabled without bluetooth-peripheral; and restoration should use Core Bluetooth restoration identifiers plus restored state dictionaries for peripherals, scan services/options, services, and advertisement data.",
+      "files": [],
+      "assertions": [
+        "The output rejects nil-service background scanning and requires explicit service UUIDs for bluetooth-central background scans.",
+        "The output states scan options such as allowDuplicates have no effect while scanning in the background.",
+        "The output states background peripheral advertising does not include the local name and service UUIDs are discoverable only through explicit service scans.",
+        "The output states published service contents are disabled in the background without bluetooth-peripheral mode.",
+        "The output recommends Core Bluetooth restoration identifiers and restored state dictionary keys instead of restoring only an app-stored peripheral identifier."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We need a privacy-preserving first-run picker for a BLE thermostat, then after the user picks it we need to read and write GATT characteristics. Should this be handled entirely by Core Bluetooth, entirely by AccessorySetupKit, or split? Give the implementation boundary.",
+      "expected_output": "The answer splits responsibility: AccessorySetupKit owns the privacy-preserving picker/discovery/authorization step, and Core Bluetooth owns post-setup GATT communication using the selected accessory identifier. It avoids broadening Core Bluetooth into picker setup and avoids using AccessorySetupKit for characteristic read/write logic.",
+      "files": [],
+      "assertions": [
+        "The output routes the first-run privacy-preserving accessory picker to AccessorySetupKit.",
+        "The output routes post-selection GATT reads, writes, notifications, services, and characteristics to Core Bluetooth.",
+        "The output does not recommend broad direct Core Bluetooth scanning for the initial privacy-preserving picker use case.",
+        "The output does not expand AccessorySetupKit into characteristic read/write implementation.",
+        "The output describes the handoff from selected accessory identity to Core Bluetooth communication."
+      ]
+    }
+  ]
+}

package/pipeline/skills/shared/external/core-bluetooth/references/ble-patterns.md

@@ -7,6 +7,7 @@ Overflow reference for the `core-bluetooth` skill. Contains advanced patterns th
 - [SwiftUI BLE Integration](#swiftui-ble-integration)
 - [Reconnection Strategies](#reconnection-strategies)
 - [Data Parsing Helpers](#data-parsing-helpers)
+- [Write Flow Control](#write-flow-control)
 - [Multiple Peripheral Management](#multiple-peripheral-management)
 - [L2CAP Channels](#l2cap-channels)
 - [Peripheral Role: Responding to Requests](#peripheral-role-responding-to-requests)
@@ -156,6 +157,7 @@ extension BLEViewModel: CBPeripheralDelegate {
         let flags = data[0]
         let bpm: Int
         if (flags & 0x01) != 0 {
+            guard data.count >= 3 else { return }
             bpm = Int(data[1]) | (Int(data[2]) << 8)
         } else {
             bpm = Int(data[1])
@@ -177,7 +179,7 @@ struct HeartRateView: View {
         NavigationStack {
             Group {
                 if viewModel.isConnected {
-                    VStack(spacing: 20) {
+                    VStack {
                         Image(systemName: "heart.fill")
                             .font(.system(size: 60))
                             .foregroundStyle(.red)
@@ -295,6 +297,28 @@ func parseBatteryLevel(_ data: Data) -> Int? {
 }
 ```
 
+## Write Flow Control
+
+Use `.withResponse` for commands that need delivery confirmation. Reserve
+`.withoutResponse` for streaming or fire-and-forget payloads, and pause when the
+peripheral cannot accept more unacknowledged writes.
+
+```swift
+func writeChunks(_ chunks: [Data],
+                 to characteristic: CBCharacteristic,
+                 on peripheral: CBPeripheral) {
+    for chunk in chunks {
+        guard chunk.count <= peripheral.maximumWriteValueLength(for: .withoutResponse),
+              peripheral.canSendWriteWithoutResponse else { return }
+        peripheral.writeValue(chunk, for: characteristic, type: .withoutResponse)
+    }
+}
+
+func peripheralIsReady(toSendWriteWithoutResponse peripheral: CBPeripheral) {
+    // Continue draining queued chunks here.
+}
+```
+
 ## Multiple Peripheral Management
 
 ### Managing Several Connections