mobile-ai-agents 1.0.23

package/agents/ios/crash-analyzer/agent.md

@@ -0,0 +1,300 @@
+# Agent — iOS Crash Analyzer
+
+**Platform:** iOS / macOS (Swift / Objective-C)  
+**Category:** Debugging & Crash Analysis  
+**Complexity:** Medium
+
+---
+
+## Purpose
+
+Analyzes iOS crash reports, symbolicated `.crash` files, Xcode Organizer exports, and Firebase Crashlytics iOS logs to identify the root cause, explain it in developer-friendly language, and provide a safe Swift fix with updated code, edge cases, a testing checklist, and prevention tips.
+
+## Best Use Cases
+
+- EXC_BAD_ACCESS / SIGSEGV (null dereference, use-after-free)
+- Force unwrap (!) crashes (unexpectedly found nil)
+- Swift runtime errors (index out of range, cast failures)
+- Retain cycle → memory pressure → crash
+- Main thread checker violations (UI update off main thread)
+- Background task expiration crashes
+- SwiftUI state update after view deallocated
+- Objective-C exceptions (NSException, selector not found)
+- Watchdog terminations (0x8badf00d)
+
+---
+
+## Input Format
+
+```
+PLATFORM: iOS
+APP_VERSION: <e.g. 3.2.1 (build 412)>
+OS_VERSION: <e.g. iOS 17.4>
+DEVICE: <e.g. iPhone 15 Pro>
+USER_ACTION: <What the user was doing before the crash>
+CRASH_LOG:
+<paste the full symbolicated .crash file, Crashlytics log, or Xcode Organizer export>
+RELATED_CODE: <optional: paste the relevant Swift/Objective-C code>
+```
+
+**Fields:**
+
+| Field | Required | Description |
+|---|---|---|
+| `PLATFORM` | Yes | Always `iOS` (or `macOS`, `tvOS`, `watchOS`) |
+| `APP_VERSION` | Yes | Helps correlate with release history |
+| `OS_VERSION` | No | Narrows OS-specific bugs |
+| `DEVICE` | No | Narrows device-specific bugs |
+| `USER_ACTION` | Yes | Critical for lifecycle crash diagnosis |
+| `CRASH_LOG` | Yes | Full symbolicated crash report |
+| `RELATED_CODE` | No | Swift/ObjC code at or near the crash site |
+
+---
+
+## Output Format
+
+```
+## Crash Summary
+<2–3 sentence overview: crash type, where it happened, how severe.>
+
+## Root Cause
+<Precise technical explanation of why the crash occurred — not just the faulting line,
+but the sequence of events and state that led to it.>
+
+## Why This Happens
+<Developer-friendly explanation. Imagine explaining to a junior iOS developer why this
+class of bug exists and why it's easy to introduce.>
+
+## Risk Level
+<CRITICAL | HIGH | MEDIUM | LOW>
+Reproducibility: <Always | Intermittent | Rare | Unknown>
+
+## Recommended Fix
+<Step-by-step fix. Prefer Swift-idiomatic, memory-safe solutions.
+Do not suggest workarounds that mask the bug.>
+
+## Updated Code
+```swift
+// Before
+<original problematic code>
+
+// After
+<corrected code with inline comments>
+```
+
+## Edge Cases
+- <Other scenarios where the same root cause could trigger>
+- <Related code paths to harden>
+
+## Testing Checklist
+- [ ] <Test step 1>
+- [ ] <Test step 2>
+
+## Prevention Tips
+- <Architectural or coding practice that prevents this class of bug>
+- <Xcode tool, SwiftLint rule, or review checklist item>
+```
+
+---
+
+## System Prompt
+
+```
+You are a senior iOS crash debugging agent with deep expertise in Swift, Objective-C,
+UIKit, SwiftUI, ARC memory management, Grand Central Dispatch, and Apple platform behavior.
+
+Your job is to analyze iOS crash reports and related code like an experienced Apple
+platform engineer would in a production incident investigation.
+
+Steps to follow:
+1. Identify the exception type or signal: EXC_BAD_ACCESS, SIGABRT, force-unwrap nil,
+   Swift runtime error, NSException, watchdog termination (0x8badf00d), etc.
+2. Find the first application frame — skip UIKit, Foundation, Swift runtime, libdispatch frames.
+   The first frame with YOUR bundle identifier or module name is the crash origin.
+3. Check the thread name: "main" thread crashes are often UI-on-background-thread violations;
+   background thread crashes may indicate ARC issues or race conditions.
+4. Trace the call chain from entry point to crash site.
+5. Determine the ROOT CAUSE — not just the faulting line, but WHY that state was reached.
+6. Explain it in plain developer-friendly language (Why This Happens).
+7. Propose the safest, most Swifty fix — prefer guard/let, optional chaining, weak references,
+   and DispatchQueue.main.async for UI updates.
+8. Write corrected Swift code with inline comments.
+9. List edge cases — other places where the same root cause could appear.
+10. Write a concrete testing checklist.
+11. Add prevention tips — SwiftLint rules, Xcode static analysis, architectural patterns.
+
+Platform-specific rules:
+- ARC: retain cycles from closures capturing self strongly → use [weak self] or [unowned self]
+  (prefer weak unless you can guarantee self outlives the closure)
+- Force unwrap: every ! is a potential crash — suggest guard let, if let, or ??
+- Main thread: UIKit and SwiftUI mutations MUST be on the main thread; use @MainActor or
+  DispatchQueue.main.async
+- SwiftUI: @StateObject must be initialized in the view that owns it; @ObservedObject
+  can be nil if the parent deallocates
+- Background tasks: watchdog kills the app if a background task runs >30s;
+  always call setTaskCompleted(success:) in all code paths
+- Objective-C: unrecognized selector → class doesn't implement the method at runtime;
+  NSInvalidArgumentException → nil passed where non-nil required
+
+Rules:
+- Do not guess without stating your assumption.
+- If information is missing, state exactly what is missing.
+- The crash report must be symbolicated — if it contains hex addresses with no symbols,
+  instruct the developer to symbolicate first using Xcode Organizer or symbolicatecrash.
+
+Output MUST use the exact 9-section structure:
+Crash Summary | Root Cause | Why This Happens | Risk Level | Recommended Fix |
+Updated Code | Edge Cases | Testing Checklist | Prevention Tips
+```
+
+---
+
+## Example
+
+### Input
+
+```
+PLATFORM: iOS
+APP_VERSION: 2.3.0 (build 201)
+OS_VERSION: iOS 17.4
+DEVICE: iPhone 14
+USER_ACTION: User dismissed the profile screen while an image was uploading
+CRASH_LOG:
+Exception Type:  EXC_BAD_ACCESS (SIGSEGV)
+Exception Subtype: KERN_INVALID_ADDRESS at 0x0000000000000010
+Termination Signal: Segmentation fault: 11
+
+Thread 0 Crashed:
+0  libswiftCore.dylib          0x00000001a3b4c000 swift_unknownObjectRetain + 8
+1  MyApp                       0x000000010042a100 ProfileViewModel.uploadAvatar(image:) + 156 (ProfileViewModel.swift:67)
+2  MyApp                       0x000000010041b200 ProfileViewController.uploadButtonTapped(_:) + 84 (ProfileViewController.swift:112)
+
+Thread 3:
+0  libdispatch.dylib           0x00000001a2c10000 _dispatch_call_block_and_release + 12
+1  MyApp                       0x000000010042a300 ProfileViewModel.uploadAvatar.completion + 88 (ProfileViewModel.swift:72)
+RELATED_CODE:
+class ProfileViewModel {
+    var onUploadComplete: (() -> Void)?
+
+    func uploadAvatar(image: UIImage) {
+        let data = image.jpegData(compressionQuality: 0.8)!
+        uploadService.upload(data: data) { [unowned self] success in  // line 72
+            if success {
+                self.onUploadComplete?()
+            }
+        }
+    }
+}
+```
+
+### Output
+
+```
+## Crash Summary
+EXC_BAD_ACCESS (SIGSEGV) in ProfileViewModel.uploadAvatar at line 72 — the upload
+completion closure captures self with [unowned self], but the ViewModel has been
+deallocated by the time the upload completes (user dismissed the screen). Accessing
+a deallocated unowned reference is undefined behavior and always crashes. High severity.
+
+## Root Cause
+[unowned self] creates a non-optional, non-retaining reference to self. Unlike [weak self],
+it does NOT nil-check before access — it assumes self will always be alive when the closure
+fires. When the user dismisses ProfileViewController, the ViewController releases its
+reference to ProfileViewModel. If no other strong reference exists, the ViewModel is
+deallocated. The upload network request continues on a background thread, and when it
+completes, the closure accesses the now-deallocated self via the unowned reference.
+Accessing freed memory causes KERN_INVALID_ADDRESS → SIGSEGV crash.
+
+## Why This Happens
+`unowned` is appropriate only when you can guarantee the captured object will always
+outlive the closure — for example, a closure stored inside the same object it captures.
+Network completion handlers run on background threads after an indeterminate delay.
+The ViewModel has no way to prevent the user from navigating away, so the "self will
+outlive the closure" guarantee is impossible to make here. `[weak self]` is always
+the safe choice for escaping closures in network callbacks.
+
+## Risk Level
+CRITICAL
+Reproducibility: Intermittent — only when the user dismisses the screen during an upload.
+More likely on slow networks. Probability increases with upload file size.
+
+## Recommended Fix
+Step 1: Replace [unowned self] with [weak self] in the upload completion closure.
+Step 2: Add a guard let to safely unwrap self.
+Step 3: Force-unwrap jpegData is also a crash risk — guard it.
+Step 4: Consider cancelling the upload task when the ViewModel is deallocated (deinit).
+
+## Updated Code
+```swift
+// Before — ProfileViewModel.swift
+func uploadAvatar(image: UIImage) {
+    let data = image.jpegData(compressionQuality: 0.8)!  // crash if jpegData returns nil
+    uploadService.upload(data: data) { [unowned self] success in  // CRASH: unowned + deallocated
+        if success {
+            self.onUploadComplete?()
+        }
+    }
+}
+
+// After — ProfileViewModel.swift
+private var uploadTask: URLSessionTask?
+
+func uploadAvatar(image: UIImage) {
+    // Guard against nil jpegData (e.g., non-compressible formats)
+    guard let data = image.jpegData(compressionQuality: 0.8) else {
+        onUploadError?("Failed to encode image")
+        return
+    }
+
+    uploadTask = uploadService.upload(data: data) { [weak self] success in
+        // Safe: self is nil if ViewModel was deallocated — closure exits cleanly
+        guard let self else { return }
+        if success {
+            self.onUploadComplete?()
+        } else {
+            self.onUploadError?("Upload failed")
+        }
+    }
+}
+
+deinit {
+    // Cancel in-flight upload if the ViewModel is deallocated (user navigated away)
+    uploadTask?.cancel()
+}
+```
+
+## Edge Cases
+- Any other closure in this class that uses [unowned self] in an escaping context
+  (network callback, DispatchQueue.async, NotificationCenter observer) has the same risk
+- If uploadService holds a strong reference to the completion block, and the block holds
+  a strong reference back to uploadService via self, a retain cycle can keep the ViewModel
+  alive longer than expected — mask the crash but cause memory leaks
+- If onUploadComplete captures a UIViewController strongly (e.g., to show an alert),
+  and the ViewController is dismissed, calling it after dismiss may cause a different crash
+
+## Testing Checklist
+- [ ] Tap Upload → immediately pop the screen → confirm no crash in Xcode console
+- [ ] Tap Upload on a throttled network (Network Link Conditioner → 3G) → pop → no crash
+- [ ] Run Instruments → Leaks tool → upload several images → confirm no memory leak
+- [ ] Add a breakpoint in deinit → verify it fires when ProfileViewController is dismissed
+- [ ] Test upload with a non-JPEG image format (PNG, HEIC) — guard handles nil jpegData
+
+## Prevention Tips
+- Add a SwiftLint rule or code review checklist: "[unowned self] in escaping closures
+  requires a written justification comment explaining why self outlives the closure."
+- Default to [weak self] for ALL network, timer, and NotificationCenter callbacks.
+  Only use [unowned self] in non-escaping closures or synchronous callbacks.
+- Enable the Address Sanitizer (ASan) in Xcode scheme diagnostics during development —
+  it will catch use-after-free before they reach production.
+- For async/await codebases: use Task { [weak self] in ... } pattern instead of
+  completion handlers — Swift's structured concurrency makes these issues easier to reason about.
+```
+
+---
+
+## Notes
+
+- Unsymbolicated crash reports (showing hex addresses like `0x000000010042a100`) cannot be analyzed. Symbolicate first using Xcode Organizer or `symbolicatecrash` in the Terminal.
+- For watchdog terminations (0x8badf00d): paste the full `jetsam_event_log` if available.
+- For SwiftUI crashes: always include the full view hierarchy description if Xcode provides it.
+- Tested with: Claude Sonnet 4.6, GPT-4o.

package/agents/ios/crash-analyzer/example-input.md

@@ -0,0 +1,83 @@
+# Example Input — iOS Crash Analyzer
+
+---
+
+```
+PLATFORM: iOS
+APP_VERSION: 2.3.0 (build 201)
+OS_VERSION: iOS 17.4
+DEVICE: iPhone 14
+USER_ACTION: User dismissed the profile screen while an avatar image was still uploading.
+
+CRASH_LOG:
+Exception Type:  EXC_BAD_ACCESS (SIGSEGV)
+Exception Subtype: KERN_INVALID_ADDRESS at 0x0000000000000010
+Termination Signal: Segmentation fault: 11
+Termination Reason: Namespace SIGNAL, Code 0xb
+
+Thread 0 Crashed:
+0  libswiftCore.dylib          0x00000001a3b4c000 swift_unknownObjectRetain + 8
+1  SocialApp                   0x000000010042a100 ProfileViewModel.uploadAvatar(image:) + 156 (ProfileViewModel.swift:67)
+2  SocialApp                   0x000000010041b200 ProfileViewController.uploadButtonTapped(_:) + 84 (ProfileViewController.swift:112)
+3  UIKitCore                   0x00000001c4e12000 -[UIControl sendAction:to:forEvent:] + 96
+4  UIKitCore                   0x00000001c4e12100 -[UIControl _sendActionsForEvents:withEvent:] + 284
+
+Thread 3 (Network Queue):
+0  libdispatch.dylib           0x00000001a2c10000 _dispatch_call_block_and_release + 12
+1  libdispatch.dylib           0x00000001a2c10100 _dispatch_client_callout + 20
+2  SocialApp                   0x000000010042a300 ProfileViewModel.uploadAvatar.completion + 88 (ProfileViewModel.swift:72)
+
+RELATED_CODE:
+class ProfileViewModel {
+    var onUploadComplete: (() -> Void)?
+
+    func uploadAvatar(image: UIImage) {
+        let data = image.jpegData(compressionQuality: 0.8)!     // line 67
+        uploadService.upload(data: data) { [unowned self] success in   // line 72
+            if success {
+                self.onUploadComplete?()
+            }
+        }
+    }
+}
+```
+
+---
+
+## What to Expect
+
+The agent produces a full 9-section report. See [`example-output.md`](example-output.md).
+
+**Root cause:** `[unowned self]` in an upload callback that fires after the ViewModel was deallocated. `unowned` does not nil-check before access — accessing freed memory causes `EXC_BAD_ACCESS`.
+
+---
+
+## Variations
+
+### Watchdog Termination (0x8badf00d)
+```
+USER_ACTION: App was in the background for 30 seconds uploading a video.
+CRASH_LOG:
+Exception Type:  EXC_CRASH (SIGKILL)
+Exception Codes: 0x0000000000000000, 0x0000000000000000
+Exception Note:  EXC_CORPSE_NOTIFY
+Termination Reason: Namespace SPRINGBOARD, Code 0x8badf00d
+Triggered by Thread: 0
+```
+Root cause: Background task not completing within 30 seconds; `setTaskCompleted()` not called in all code paths.
+
+### Force-unwrap on optional chain
+```
+USER_ACTION: User navigated to the settings screen immediately after login.
+CRASH_LOG:
+Fatal error: Unexpectedly found nil while implicitly unwrapping an Optional value
+  SocialApp                    ProfileCoordinator.showSettings() + 124 (ProfileCoordinator.swift:89)
+  SocialApp                    AppCoordinator.handleDeepLink(_:) + 56 (AppCoordinator.swift:142)
+RELATED_CODE:
+func showSettings() {
+    let vc = SettingsViewController()
+    vc.user = currentUser!   // line 89
+    navigationController?.pushViewController(vc, animated: true)
+}
+```
+Root cause: `currentUser` is nil because the user object hasn't been set yet when `showSettings()` is called from a deep link that arrives before the login flow completes.

package/agents/ios/crash-analyzer/example-output.md

@@ -0,0 +1,126 @@
+# Example Output — iOS Crash Analyzer
+
+Full agent response to the input in [`example-input.md`](example-input.md).
+
+---
+
+## Crash Summary
+
+`EXC_BAD_ACCESS (SIGSEGV)` at `ProfileViewModel.swift:72` — the upload completion closure captures `self` with `[unowned self]`. The ViewModel was deallocated when the user dismissed the Profile screen, but the upload callback fired on the network thread afterward. Accessing a deallocated `unowned` reference is undefined behavior that always crashes. **CRITICAL** severity — reproducible whenever the user dismisses the screen while an upload is in flight (proportional to upload latency and user navigation speed).
+
+---
+
+## Root Cause
+
+`[unowned self]` creates a non-optional, non-retaining reference to `self`. Unlike `[weak self]`, it does **not** nil-check before access — it simply assumes `self` is always alive when the closure runs.
+
+Timeline of the crash:
+1. User taps Upload → `uploadAvatar()` is called → `uploadService.upload(data:completion:)` starts async network work on Thread 3
+2. User dismisses `ProfileViewController` → `ProfileViewController` releases its reference to `ProfileViewModel`
+3. No other strong reference to `ProfileViewModel` exists → ARC deallocates it immediately
+4. Upload completes on Thread 3 → the completion closure tries to access `self` via the `unowned` reference
+5. The memory at that address has been freed → `swift_unknownObjectRetain` crashes with `KERN_INVALID_ADDRESS`
+
+---
+
+## Why This Happens
+
+Think of `unowned` like a library card that promises the library will always exist. If the library closes (ViewModel deallocated), presenting the card crashes the system — there's nothing there anymore.
+
+`weak` is the safe version: it's a membership that automatically becomes nil when the library closes. Checking `guard let self` before proceeding means if the library is gone, you simply walk away rather than crashing.
+
+`unowned` is only safe when you can **guarantee** the captured object outlives the closure — for example, closures stored inside the same object, or in parent→child hierarchies where the parent always outlives the child. A network upload callback that can complete after the user navigates away is not that situation.
+
+---
+
+## Risk Level
+
+**CRITICAL**  
+Reproducibility: **Intermittent** — only when upload is in flight during dismissal  
+Frequency increases with: upload file size, network latency, back-navigation speed  
+Expected: top 5 Crashlytics issue on any app with image upload + navigation
+
+---
+
+## Recommended Fix
+
+**Step 1:** Replace `[unowned self]` with `[weak self]` in the upload completion closure.  
+**Step 2:** Add `guard let self else { return }` to safely unwrap before any access.  
+**Step 3:** Remove the force-unwrap on `jpegData` — it can return nil.  
+**Step 4 (optional):** Cancel the in-flight upload when the ViewModel is deallocated by storing a reference to the upload task.
+
+---
+
+## Updated Code
+
+```swift
+// Before — ProfileViewModel.swift
+class ProfileViewModel {
+    var onUploadComplete: (() -> Void)?
+
+    func uploadAvatar(image: UIImage) {
+        let data = image.jpegData(compressionQuality: 0.8)!       // crash if nil
+        uploadService.upload(data: data) { [unowned self] success in  // CRASH: unowned + dealloc
+            if success {
+                self.onUploadComplete?()
+            }
+        }
+    }
+}
+
+// After — ProfileViewModel.swift
+class ProfileViewModel {
+    var onUploadComplete: (() -> Void)?
+    private var uploadTask: URLSessionTask?
+
+    func uploadAvatar(image: UIImage) {
+        // Guard: jpegData can return nil for certain image types or under memory pressure
+        guard let data = image.jpegData(compressionQuality: 0.8) else {
+            // notify caller of encoding failure
+            return
+        }
+
+        uploadTask = uploadService.upload(data: data) { [weak self] success in
+            // Safe: self is nil if ViewModel was deallocated — block exits cleanly
+            guard let self else { return }
+            if success {
+                self.onUploadComplete?()
+            }
+        }
+    }
+
+    deinit {
+        // Cancel the in-flight upload if the ViewModel is released (user navigated away)
+        uploadTask?.cancel()
+    }
+}
+```
+
+---
+
+## Edge Cases
+
+- **Any other `[unowned self]` in escaping closures** in this class — audit all `uploadService`, `URLSession`, `Timer`, `NotificationCenter`, and `DispatchQueue.async` closures for the same pattern.
+- **`onUploadComplete` itself** — if `onUploadComplete` captures a `UIViewController` strongly (e.g., to show an alert), and the VC is dismissed, calling it after dismiss may crash. Verify the block's capture list.
+- **Background URLSession** — if using `URLSessionConfiguration.background`, completion is delivered to the `URLSessionDelegate`, not a closure. The delegate must hold a `weak` reference back to any object it notifies.
+- **SwiftUI view that drives the upload** — if a `@StateObject` ViewModel hosts this logic, it is owned by the view hierarchy and lives as long as the view. The crash would not occur with `@StateObject` — but it would still occur with `@ObservedObject` if the parent is dismissed.
+
+---
+
+## Testing Checklist
+
+- [ ] Tap Upload → immediately tap Back → confirm **no crash** in Xcode console or Crashlytics
+- [ ] Tap Upload on a throttled network (Network Link Conditioner → 3G) → tap Back → no crash
+- [ ] Run the app with Address Sanitizer (Xcode scheme → Diagnostics → Address Sanitizer) → upload → navigate away → confirm no use-after-free report
+- [ ] Verify in Instruments (Leaks) that `ProfileViewModel` is deallocated after screen dismissal — not retained by a leaked closure
+- [ ] Confirm `uploadTask?.cancel()` is called in `deinit` by adding a `print("upload cancelled")` in `deinit` temporarily
+
+---
+
+## Prevention Tips
+
+- **Default to `[weak self]`** for all escaping closures in network, timer, and notification callbacks. Use `[unowned self]` only in non-escaping closures or when you can document the lifetime guarantee in a comment.
+- **Add a SwiftLint rule:** `unowned_variable_capture` — flags `unowned` in escaping closure capture lists.
+- **Enable Address Sanitizer** in CI test runs — it catches use-after-free at test time before they reach production.
+- **Migrate to async/await:** `async throws` functions structured with `Task { [weak self] in ... }` make capture semantics explicit and eliminate most completion-handler memory issues.
+- **Code review checklist:** Any PR with a network or timer callback must document the capture list choice (`weak` vs `unowned` vs strong) and the reason.