@sriinnu/runic 1.0.0

package/Sources/Runic/Core/Rendering/IconView.swift

@@ -0,0 +1,120 @@
+import RunicCore
+import SwiftUI
+
+@MainActor
+struct IconView: View {
+    let snapshot: UsageSnapshot?
+    let creditsRemaining: Double?
+    let isStale: Bool
+    let showLoadingAnimation: Bool
+    let style: IconStyle
+    @State private var phase: CGFloat = 0
+    @State private var displayLink = DisplayLinkDriver()
+    @State private var pattern: LoadingPattern = .knightRider
+    @State private var debugCycle = false
+    @State private var cycleIndex = 0
+    @State private var cycleCounter = 0
+    private let loadingFPS: Double = 12
+    // Advance to next pattern every N ticks when debug cycling.
+    private let cycleIntervalTicks = 20
+    private let patterns = LoadingPattern.allCases
+
+    private var isLoading: Bool { self.showLoadingAnimation && self.snapshot == nil }
+
+    var body: some View {
+        Group {
+            if let snapshot {
+                Image(nsImage: IconRenderer.makeIcon(
+                    primaryRemaining: snapshot.primary.remainingPercent,
+                    weeklyRemaining: snapshot.secondary?.remainingPercent,
+                    creditsRemaining: self.creditsRemaining,
+                    stale: self.isStale,
+                    style: self.style))
+                    .renderingMode(.original)
+                    .interpolation(.none)
+                    .frame(width: 20, height: 18, alignment: .center)
+                    .padding(.horizontal, RunicSpacing.xxxs)
+            } else if self.showLoadingAnimation {
+                // Loading: animate bars with the current pattern until data arrives.
+                Image(nsImage: self.loadingImage)
+                    .renderingMode(.original)
+                    .interpolation(.none)
+                    .frame(width: 20, height: 18, alignment: .center)
+                    .padding(.horizontal, RunicSpacing.xxxs)
+                    .onChange(of: self.displayLink.tick) { _, _ in
+                        self.phase += 0.09 // half-speed animation
+                        if self.debugCycle {
+                            self.cycleCounter += 1
+                            if self.cycleCounter >= self.cycleIntervalTicks {
+                                self.cycleCounter = 0
+                                self.cycleIndex = (self.cycleIndex + 1) % self.patterns.count
+                                self.pattern = self.patterns[self.cycleIndex]
+                            }
+                        }
+                    }
+            } else {
+                // No animation when usage/account is unavailable; show empty tracks.
+                Image(nsImage: IconRenderer.makeIcon(
+                    primaryRemaining: nil,
+                    weeklyRemaining: nil,
+                    creditsRemaining: self.creditsRemaining,
+                    stale: self.isStale,
+                    style: self.style))
+                    .renderingMode(.original)
+                    .interpolation(.none)
+                    .frame(width: 20, height: 18, alignment: .center)
+                    .padding(.horizontal, RunicSpacing.xxxs)
+            }
+        }
+        .onChange(of: self.isLoading, initial: true) { _, isLoading in
+            if isLoading {
+                self.displayLink.start(fps: self.loadingFPS)
+                if !self.debugCycle {
+                    self.pattern = self.patterns.randomElement() ?? .knightRider
+                }
+            } else {
+                self.displayLink.stop()
+                self.debugCycle = false
+                self.phase = 0
+            }
+        }
+        .onDisappear { self.displayLink.stop() }
+        .onReceive(NotificationCenter.default.publisher(for: .runicDebugReplayAllAnimations)) { notification in
+            if let raw = notification.userInfo?["pattern"] as? String,
+               let selected = LoadingPattern(rawValue: raw)
+            {
+                self.debugCycle = false
+                self.pattern = selected
+                self.cycleIndex = self.patterns.firstIndex(of: selected) ?? 0
+            } else {
+                self.debugCycle = true
+                self.cycleIndex = 0
+                self.pattern = self.patterns.first ?? .knightRider
+            }
+            self.cycleCounter = 0
+            self.phase = 0
+        }
+    }
+
+    private var loadingPrimary: Double {
+        self.pattern.value(phase: Double(self.phase))
+    }
+
+    private var loadingSecondary: Double {
+        self.pattern.value(phase: Double(self.phase + self.pattern.secondaryOffset))
+    }
+
+    private var loadingImage: NSImage {
+        if self.pattern == .unbraid {
+            let progress = self.loadingPrimary / 100
+            return IconRenderer.makeMorphIcon(progress: progress, style: self.style)
+        } else {
+            return IconRenderer.makeIcon(
+                primaryRemaining: self.loadingPrimary,
+                weeklyRemaining: self.loadingSecondary,
+                creditsRemaining: nil,
+                stale: false,
+                style: self.style)
+        }
+    }
+}

package/Sources/Runic/Core/Rendering/ProviderBrandIcon.swift

@@ -0,0 +1,71 @@
+import AppKit
+import RunicCore
+
+@MainActor
+enum ProviderBrandIcon {
+    private static let cache = NSCache<NSString, NSImage>()
+
+    static func image(for provider: UsageProvider, size: CGFloat = 16) -> NSImage? {
+        let cacheSize = Int(size.rounded())
+        let key = "\(provider.rawValue)-\(cacheSize)" as NSString
+        if let cached = self.cache.object(forKey: key) {
+            return cached
+        }
+
+        let baseName = ProviderDescriptorRegistry.descriptor(for: provider).branding.iconResourceName
+        guard let url = Bundle.main.url(forResource: baseName, withExtension: "svg"),
+              let image = NSImage(contentsOf: url)
+        else {
+            return nil
+        }
+
+        let targetSize = NSSize(width: size, height: size)
+        image.size = targetSize
+        image.isTemplate = true
+        let tinted = self.tintedImage(image, color: self.brandColor(for: provider), size: targetSize)
+        self.cache.setObject(tinted, forKey: key)
+        return tinted
+    }
+
+    static func templateImage(for provider: UsageProvider, size: CGFloat = 16) -> NSImage? {
+        let cacheSize = Int(size.rounded())
+        let key = "\(provider.rawValue)-\(cacheSize)-template" as NSString
+        if let cached = self.cache.object(forKey: key) {
+            return cached
+        }
+
+        let baseName = ProviderDescriptorRegistry.descriptor(for: provider).branding.iconResourceName
+        guard let url = Bundle.main.url(forResource: baseName, withExtension: "svg"),
+              let image = NSImage(contentsOf: url)
+        else {
+            return nil
+        }
+
+        image.size = NSSize(width: size, height: size)
+        image.isTemplate = true
+        self.cache.setObject(image, forKey: key)
+        return image
+    }
+
+    private static func brandColor(for provider: UsageProvider) -> NSColor {
+        let color = ProviderDescriptorRegistry.descriptor(for: provider).branding.color
+        return NSColor(
+            calibratedRed: CGFloat(color.red),
+            green: CGFloat(color.green),
+            blue: CGFloat(color.blue),
+            alpha: 1)
+    }
+
+    private static func tintedImage(_ image: NSImage, color: NSColor, size: NSSize) -> NSImage {
+        let rect = NSRect(origin: .zero, size: size)
+        // Use drawingHandler instead of deprecated lockFocus/unlockFocus.
+        let tinted = NSImage(size: size, flipped: false) { _ in
+            color.setFill()
+            rect.fill()
+            image.draw(in: rect, from: .zero, operation: .destinationIn, fraction: 1.0)
+            return true
+        }
+        tinted.isTemplate = false
+        return tinted
+    }
+}

package/Sources/Runic/Core/RunicAnimation.swift

@@ -0,0 +1,53 @@
+import SwiftUI
+
+/// Animation presets used across the Runic UI.
+enum RunicAnimation {
+    // MARK: - Spring Presets
+
+    /// Standard appear animation for progress bars and chart elements.
+    static let barAppear: Animation = .spring(response: 0.6, dampingFraction: 0.75)
+
+    /// Value-change animation for progress bars.
+    static let barUpdate: Animation = .spring(response: 0.5, dampingFraction: 0.8)
+
+    /// Menu content fade when switching providers.
+    static let providerSwitch: Animation = .easeInOut(duration: 0.25)
+
+    /// Highlight state transitions on menu items.
+    static let highlight: Animation = .easeOut(duration: 0.12)
+
+    // MARK: - Transition Durations
+
+    /// Duration for sheen / gloss sweeps on progress bars.
+    static let sheenDuration: Double = 0.9
+
+    /// Delay before sheen resets after sweeping.
+    static let sheenResetDelay: Duration = .seconds(1.1)
+
+    /// Duration for copy-confirmation checkmark display.
+    static let copyFeedbackDuration: Duration = .seconds(0.9)
+
+    /// Fade-out duration for copy confirmation revert.
+    static let copyFeedbackFadeOut: Animation = .easeOut(duration: 0.2)
+
+    // MARK: - Skeleton / Loading
+
+    /// Continuous shimmer animation for loading skeletons.
+    static let shimmer: Animation = .easeInOut(duration: 1.5).repeatForever(autoreverses: false)
+
+    /// Subtle hover feedback on interactive elements.
+    static let hoverFeedback: Animation = .easeInOut(duration: 0.15)
+
+    // MARK: - Chart Interaction
+
+    /// Fade animation for chart interaction hints.
+    static let chartHintFade: Animation = .easeOut(duration: 0.4)
+
+    // MARK: - Menu Card Entrance
+
+    /// Staggered spring entrance for menu card sections.
+    static let cardEntrance: Animation = .spring(response: 0.45, dampingFraction: 0.82)
+
+    /// Base delay between staggered card section entrances.
+    static let cardEntranceStagger: Double = 0.06
+}

package/Sources/Runic/Core/RunicColors.swift

@@ -0,0 +1,73 @@
+import SwiftUI
+
+/// Semantic color tokens for consistent theming across the Runic UI.
+enum RunicColors {
+    // MARK: - Status Colors
+
+    static let success = Color(nsColor: .systemGreen)
+    static let warning = Color(nsColor: .systemOrange)
+    static let error = Color(nsColor: .systemRed)
+    static let info = Color(nsColor: .systemBlue)
+
+    // MARK: - Chart Palette (6 accessible colors)
+
+    /// Ordered palette for chart series. Colors chosen for distinguishability in
+    /// both light and dark mode and for common color-vision deficiencies.
+    static let chartPalette: [Color] = [
+        Color(red: 0.26, green: 0.55, blue: 0.96),  // blue
+        Color(red: 0.94, green: 0.53, blue: 0.18),  // orange
+        Color(red: 0.46, green: 0.75, blue: 0.36),  // green
+        Color(red: 0.80, green: 0.45, blue: 0.92),  // purple
+        Color(red: 0.26, green: 0.78, blue: 0.86),  // teal
+        Color(red: 0.94, green: 0.74, blue: 0.26),  // yellow
+    ]
+
+    /// Returns a chart color for the given index, wrapping around if needed.
+    static func chartColor(at index: Int) -> Color {
+        self.chartPalette[index % self.chartPalette.count]
+    }
+
+    // MARK: - Model Family Colors
+
+    /// Color for Claude/Anthropic model family.
+    static let modelFamilyClaude = Color(red: 0.80, green: 0.45, blue: 0.30)
+    /// Color for GPT/OpenAI model family.
+    static let modelFamilyGPT = Color(red: 0.30, green: 0.70, blue: 0.40)
+    /// Color for Gemini/Google model family.
+    static let modelFamilyGemini = Color(red: 0.26, green: 0.55, blue: 0.96)
+    /// Default color for unknown model families.
+    static let modelFamilyDefault = Color(red: 0.55, green: 0.55, blue: 0.60)
+
+    /// Returns a color appropriate for the given model name based on its family.
+    static func colorForModel(_ model: String) -> Color {
+        let lower = model.lowercased()
+        if lower.contains("claude") || lower.contains("sonnet") || lower.contains("opus") || lower.contains("haiku") {
+            return self.modelFamilyClaude
+        }
+        if lower.contains("gpt") || lower.contains("o1") || lower.contains("o3") || lower.contains("o4") {
+            return self.modelFamilyGPT
+        }
+        if lower.contains("gemini") {
+            return self.modelFamilyGemini
+        }
+        return self.modelFamilyDefault
+    }
+
+    // MARK: - Named Chart Colors
+
+    /// Credits history chart bar color
+    static let creditsChartBar = Color(red: 73 / 255, green: 163 / 255, blue: 176 / 255)
+
+    // MARK: - Opacity Tokens
+
+    enum Opacity {
+        static let nano: Double = 0.045
+        static let subtle: Double = 0.08
+        static let light: Double = 0.12
+        static let medium: Double = 0.22
+        static let strong: Double = 0.35
+        static let emphasis: Double = 0.55
+        static let prominent: Double = 0.70
+        static let vivid: Double = 0.90
+    }
+}

package/Sources/Runic/Core/RunicCornerRadius.swift

@@ -0,0 +1,15 @@
+import Foundation
+
+/// Corner radius tokens replacing scattered literal values throughout the UI.
+enum RunicCornerRadius {
+    /// 4pt — badges, small tags, inline controls
+    static let xs: CGFloat = 4
+    /// 6pt — list rows, compact cards, buttons
+    static let sm: CGFloat = 6
+    /// 8pt — standard cards, menu sections
+    static let md: CGFloat = 8
+    /// 12pt — prominent panels, avatar frames, provider cards
+    static let lg: CGFloat = 12
+    /// 16pt — large icons, about pane, hero elements
+    static let xl: CGFloat = 16
+}

package/Sources/Runic/Core/RunicSpacing.swift

@@ -0,0 +1,68 @@
+import Foundation
+
+/// **Runic Spacing System**
+/// Defines global spacing constants following a 4pt grid system.
+/// All spacing values are multiples of 4 for consistent visual rhythm.
+enum RunicSpacing {
+    // MARK: - Base Spacing Scale
+
+    /// Extra extra extra small spacing (2pt)
+    static let xxxs: CGFloat = 2
+
+    /// Extra extra small spacing (4pt)
+    static let xxs: CGFloat = 4
+
+    /// Extra small spacing (8pt)
+    static let xs: CGFloat = 8
+
+    /// Small spacing (12pt)
+    static let sm: CGFloat = 12
+
+    /// Medium spacing (16pt)
+    static let md: CGFloat = 16
+
+    /// Large spacing (24pt)
+    static let lg: CGFloat = 24
+
+    /// Extra large spacing (32pt)
+    static let xl: CGFloat = 32
+
+    /// Extra extra large spacing (48pt)
+    static let xxl: CGFloat = 48
+
+    // MARK: - Semantic Spacing
+
+    /// Horizontal padding for menu content
+    static let menuHorizontalPadding: CGFloat = sm  // 12pt
+
+    /// Vertical padding for menu content
+    static let menuVerticalPadding: CGFloat = xs  // 8pt
+
+    /// Spacing between cards in menu
+    static let cardSpacing: CGFloat = xs  // 8pt
+
+    /// Spacing between major sections
+    static let sectionSpacing: CGFloat = lg  // 24pt
+
+    // MARK: - Preferences Spacing
+
+    /// Compact spacing (6pt) - Used between sm and xs, common in preference toggles
+    static let compact: CGFloat = 6
+
+    /// Standardized spacing for toggle rows
+    static let toggleRowSpacing: CGFloat = xs  // 8pt
+
+    /// Spacing after section headers
+    static let sectionHeaderSpacing: CGFloat = md  // 16pt
+
+    /// Spacing within stepper controls
+    static let stepperControlSpacing: CGFloat = xs  // 8pt
+
+    // MARK: - Chart Metrics
+
+    /// Standard height for chart views in menus
+    static let chartHeight: CGFloat = 130
+
+    /// Diameter for legend dot indicators
+    static let chartLegendDot: CGFloat = 7
+}

package/Sources/Runic/Core/Stores/AuggieTokenStore.swift

@@ -0,0 +1,143 @@
+import RunicCore
+import Foundation
+import Security
+
+protocol AuggieTokenStoring: Sendable {
+    func loadToken() throws -> String?
+    func storeToken(_ token: String?) throws
+}
+
+enum AuggieTokenStoreError: LocalizedError {
+    case keychainStatus(OSStatus)
+    case invalidData
+
+    var errorDescription: String? {
+        switch self {
+        case let .keychainStatus(status):
+            "Keychain error: \(status)"
+        case .invalidData:
+            "Keychain returned invalid data."
+        }
+    }
+}
+
+struct KeychainAuggieTokenStore: AuggieTokenStoring {
+    private static let log = RunicLog.logger("auggie-token-store")
+
+    private let service = "com.sriinnu.athena.Runic"
+    private let account = "auggie-api-token"
+
+    func loadToken() throws -> String? {
+        // Try standard keychain first.
+        if let token = try self.readToken(dataProtection: false) {
+            return token
+        }
+        // Migrate from the old Data Protection keychain if present.
+        if let token = try self.readToken(dataProtection: true) {
+            Self.log.info("Migrating Auggie token from Data Protection keychain")
+            // Store first, delete old only on success — prevents data loss.
+            if (try? self.storeToken(token)) != nil {
+                try? self.deleteToken(dataProtection: true)
+            }
+            return token
+        }
+        return nil
+    }
+
+    func storeToken(_ token: String?) throws {
+        let cleaned = token?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if cleaned == nil || cleaned?.isEmpty == true {
+            try? self.deleteToken(dataProtection: false)
+            try? self.deleteToken(dataProtection: true)
+            return
+        }
+
+        let data = cleaned!.data(using: .utf8)!
+        let query = self.baseQuery(dataProtection: false)
+        let attributes: [String: Any] = [
+            kSecValueData as String: data,
+            kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
+        ]
+
+        // Try update first.
+        let updateStatus = SecItemUpdate(query as CFDictionary, attributes as CFDictionary)
+        if updateStatus == errSecSuccess { return }
+
+        if updateStatus != errSecItemNotFound {
+            // Item exists but update failed — delete and re-add to reset ACL.
+            try? self.deleteToken(dataProtection: false)
+        }
+
+        var addQuery = query
+        for (key, value) in attributes { addQuery[key] = value }
+
+        // Grant the calling app permanent access so macOS never shows a
+        // Keychain password dialog for this item.
+        if let access = Self.createSelfAccess() {
+            addQuery[kSecAttrAccess as String] = access
+        }
+
+        let addStatus = SecItemAdd(addQuery as CFDictionary, nil)
+        guard addStatus == errSecSuccess else {
+            Self.log.error("Keychain add failed: \(addStatus)")
+            throw AuggieTokenStoreError.keychainStatus(addStatus)
+        }
+    }
+
+    // MARK: - Private
+
+    private func readToken(dataProtection: Bool) throws -> String? {
+        var result: CFTypeRef?
+        var query = self.baseQuery(dataProtection: dataProtection)
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        query[kSecReturnData as String] = true
+
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        if status == errSecItemNotFound || status == errSecInteractionNotAllowed {
+            return nil
+        }
+        guard status == errSecSuccess else {
+            Self.log.error("Keychain read failed: \(status)")
+            throw AuggieTokenStoreError.keychainStatus(status)
+        }
+        guard let data = result as? Data else {
+            throw AuggieTokenStoreError.invalidData
+        }
+        let token = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return (token?.isEmpty ?? true) ? nil : token
+    }
+
+    private func deleteToken(dataProtection: Bool) throws {
+        let query = self.baseQuery(dataProtection: dataProtection)
+        let status = SecItemDelete(query as CFDictionary)
+        if status == errSecSuccess || status == errSecItemNotFound { return }
+        Self.log.error("Keychain delete failed: \(status)")
+        throw AuggieTokenStoreError.keychainStatus(status)
+    }
+
+    private func baseQuery(dataProtection: Bool) -> [String: Any] {
+        var q: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: self.service,
+            kSecAttrAccount as String: self.account,
+        ]
+        if dataProtection {
+            q[kSecUseDataProtectionKeychain as String] = true
+        }
+        return q
+    }
+
+    /// Creates a SecAccess that grants the calling application permanent
+    /// read/write access without triggering the macOS Keychain password dialog.
+    private static func createSelfAccess() -> SecAccess? {
+        var trustedSelf: SecTrustedApplication?
+        guard SecTrustedApplicationCreateFromPath(nil, &trustedSelf) == errSecSuccess,
+              let trustedSelf else { return nil }
+        var access: SecAccess?
+        guard SecAccessCreate(
+            "Runic API Token" as CFString,
+            [trustedSelf] as CFArray,
+            &access) == errSecSuccess else { return nil }
+        return access
+    }
+}

package/Sources/Runic/Core/Stores/AzureOpenAITokenStore.swift

@@ -0,0 +1,143 @@
+import RunicCore
+import Foundation
+import Security
+
+protocol AzureOpenAITokenStoring: Sendable {
+    func loadToken() throws -> String?
+    func storeToken(_ token: String?) throws
+}
+
+enum AzureOpenAITokenStoreError: LocalizedError {
+    case keychainStatus(OSStatus)
+    case invalidData
+
+    var errorDescription: String? {
+        switch self {
+        case let .keychainStatus(status):
+            "Keychain error: \(status)"
+        case .invalidData:
+            "Keychain returned invalid data."
+        }
+    }
+}
+
+struct KeychainAzureOpenAITokenStore: AzureOpenAITokenStoring {
+    private static let log = RunicLog.logger("azure-openai-token-store")
+
+    private let service = "com.sriinnu.athena.Runic"
+    private let account = "azure-openai-api-token"
+
+    func loadToken() throws -> String? {
+        // Try standard keychain first.
+        if let token = try self.readToken(dataProtection: false) {
+            return token
+        }
+        // Migrate from the old Data Protection keychain if present.
+        if let token = try self.readToken(dataProtection: true) {
+            Self.log.info("Migrating Azure OpenAI token from Data Protection keychain")
+            // Store first, delete old only on success — prevents data loss.
+            if (try? self.storeToken(token)) != nil {
+                try? self.deleteToken(dataProtection: true)
+            }
+            return token
+        }
+        return nil
+    }
+
+    func storeToken(_ token: String?) throws {
+        let cleaned = token?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if cleaned == nil || cleaned?.isEmpty == true {
+            try? self.deleteToken(dataProtection: false)
+            try? self.deleteToken(dataProtection: true)
+            return
+        }
+
+        let data = cleaned!.data(using: .utf8)!
+        let query = self.baseQuery(dataProtection: false)
+        let attributes: [String: Any] = [
+            kSecValueData as String: data,
+            kSecAttrAccessible as String: kSecAttrAccessibleAfterFirstUnlock,
+        ]
+
+        // Try update first.
+        let updateStatus = SecItemUpdate(query as CFDictionary, attributes as CFDictionary)
+        if updateStatus == errSecSuccess { return }
+
+        if updateStatus != errSecItemNotFound {
+            // Item exists but update failed — delete and re-add to reset ACL.
+            try? self.deleteToken(dataProtection: false)
+        }
+
+        var addQuery = query
+        for (key, value) in attributes { addQuery[key] = value }
+
+        // Grant the calling app permanent access so macOS never shows a
+        // Keychain password dialog for this item.
+        if let access = Self.createSelfAccess() {
+            addQuery[kSecAttrAccess as String] = access
+        }
+
+        let addStatus = SecItemAdd(addQuery as CFDictionary, nil)
+        guard addStatus == errSecSuccess else {
+            Self.log.error("Keychain add failed: \(addStatus)")
+            throw AzureOpenAITokenStoreError.keychainStatus(addStatus)
+        }
+    }
+
+    // MARK: - Private
+
+    private func readToken(dataProtection: Bool) throws -> String? {
+        var result: CFTypeRef?
+        var query = self.baseQuery(dataProtection: dataProtection)
+        query[kSecMatchLimit as String] = kSecMatchLimitOne
+        query[kSecReturnData as String] = true
+
+        let status = SecItemCopyMatching(query as CFDictionary, &result)
+        if status == errSecItemNotFound || status == errSecInteractionNotAllowed {
+            return nil
+        }
+        guard status == errSecSuccess else {
+            Self.log.error("Keychain read failed: \(status)")
+            throw AzureOpenAITokenStoreError.keychainStatus(status)
+        }
+        guard let data = result as? Data else {
+            throw AzureOpenAITokenStoreError.invalidData
+        }
+        let token = String(data: data, encoding: .utf8)?.trimmingCharacters(in: .whitespacesAndNewlines)
+        return (token?.isEmpty ?? true) ? nil : token
+    }
+
+    private func deleteToken(dataProtection: Bool) throws {
+        let query = self.baseQuery(dataProtection: dataProtection)
+        let status = SecItemDelete(query as CFDictionary)
+        if status == errSecSuccess || status == errSecItemNotFound { return }
+        Self.log.error("Keychain delete failed: \(status)")
+        throw AzureOpenAITokenStoreError.keychainStatus(status)
+    }
+
+    private func baseQuery(dataProtection: Bool) -> [String: Any] {
+        var q: [String: Any] = [
+            kSecClass as String: kSecClassGenericPassword,
+            kSecAttrService as String: self.service,
+            kSecAttrAccount as String: self.account,
+        ]
+        if dataProtection {
+            q[kSecUseDataProtectionKeychain as String] = true
+        }
+        return q
+    }
+
+    /// Creates a SecAccess that grants the calling application permanent
+    /// read/write access without triggering the macOS Keychain password dialog.
+    private static func createSelfAccess() -> SecAccess? {
+        var trustedSelf: SecTrustedApplication?
+        guard SecTrustedApplicationCreateFromPath(nil, &trustedSelf) == errSecSuccess,
+              let trustedSelf else { return nil }
+        var access: SecAccess?
+        guard SecAccessCreate(
+            "Runic API Token" as CFString,
+            [trustedSelf] as CFArray,
+            &access) == errSecSuccess else { return nil }
+        return access
+    }
+}