@sriinnu/runic 1.0.0

package/Sources/RunicCore/Providers/Mistral/MistralProviderDescriptor.swift

@@ -0,0 +1,84 @@
+import RunicMacroSupport
+import Foundation
+
+@ProviderDescriptorRegistration
+@ProviderDescriptorDefinition
+public enum MistralProviderDescriptor {
+    static func makeDescriptor() -> ProviderDescriptor {
+        ProviderDescriptor(
+            id: .mistral,
+            metadata: ProviderMetadata(
+                id: .mistral,
+                displayName: "Mistral",
+                sessionLabel: "Models",
+                weeklyLabel: "",
+                opusLabel: nil,
+                supportsOpus: false,
+                supportsCredits: false,
+                creditsHint: "Shows model availability from Mistral API.",
+                toggleTitle: "Show Mistral usage",
+                cliName: "mistral",
+                defaultEnabled: false,
+                isPrimaryProvider: false,
+                usesAccountFallback: false,
+                dashboardURL: "https://console.mistral.ai",
+                statusPageURL: nil,
+                usageCoverage: ProviderUsageCoverage(
+                    supportsModelBreakdown: true,
+                    supportsTokenMetrics: false,
+                    supportsProjectAttribution: false)),
+            branding: ProviderBranding(
+                iconStyle: .mistral,
+                iconResourceName: "ProviderIcon-mistral",
+                color: ProviderColor(red: 255 / 255, green: 90 / 255, blue: 52 / 255)),
+            tokenCost: ProviderTokenCostConfig(
+                supportsTokenCost: false,
+                noDataMessage: { "Mistral cost summary is not supported." }),
+            fetchPlan: ProviderFetchPlan(
+                sourceModes: [.auto, .cli],
+                pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [MistralAPIFetchStrategy()] })),
+            cli: ProviderCLIConfig(
+                name: "mistral",
+                aliases: [],
+                versionDetector: nil))
+    }
+}
+
+struct MistralAPIFetchStrategy: ProviderFetchStrategy {
+    let id: String = "mistral.api"
+    let kind: ProviderFetchKind = .apiToken
+
+    func isAvailable(_ context: ProviderFetchContext) async -> Bool {
+        Self.resolveTokenResolution(environment: context.env) != nil
+    }
+
+    func fetch(_ context: ProviderFetchContext) async throws -> ProviderFetchResult {
+        guard let tokenRes = Self.resolveTokenResolution(environment: context.env) else {
+            throw MistralSettingsError.missingToken
+        }
+        let usage = try await MistralUsageFetcher.fetchModels(apiKey: tokenRes.token)
+        return self.makeResult(
+            usage: usage.toUsageSnapshot(),
+            sourceLabel: tokenRes.source.rawValue)
+    }
+
+    func shouldFallback(on _: Error, context _: ProviderFetchContext) -> Bool {
+        false
+    }
+
+    private static func resolveTokenResolution(environment: [String: String]) -> ProviderTokenResolution? {
+        ProviderTokenResolver.mistralResolution(environment: environment)
+    }
+}
+
+enum MistralSettingsError: LocalizedError, Sendable {
+    case missingToken
+
+    var errorDescription: String? {
+        switch self {
+        case .missingToken:
+            "Mistral API key not found. Set it in Preferences → Providers → Mistral or " +
+                "export MISTRAL_API_KEY."
+        }
+    }
+}

package/Sources/RunicCore/Providers/Mistral/MistralUsageFetcher.swift

@@ -0,0 +1,75 @@
+import Foundation
+
+struct MistralModelsResponse: Decodable {
+    let data: [Model]?
+
+    struct Model: Decodable {
+        let id: String?
+    }
+}
+
+struct MistralUsageFetcher {
+    static let apiURL = URL(string: "https://api.mistral.ai/v1/models")!
+
+    static func fetchModels(apiKey: String) async throws -> MistralModelsResponse {
+        var request = URLRequest(url: apiURL)
+        request.addValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
+        request.addValue("application/json", forHTTPHeaderField: "Content-Type")
+
+        let (data, response) = try await URLSession.shared.data(for: request)
+
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw MistralAPIError.invalidResponse
+        }
+
+        guard httpResponse.statusCode == 200 else {
+            let body = String(data: data, encoding: .utf8)?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            throw MistralAPIError.httpError(
+                statusCode: httpResponse.statusCode,
+                body: body?.isEmpty == false ? body : nil)
+        }
+
+        let decoder = JSONDecoder()
+        return try decoder.decode(MistralModelsResponse.self, from: data)
+    }
+}
+
+extension MistralModelsResponse {
+    func toUsageSnapshot() -> UsageSnapshot {
+        let models = (self.data ?? []).compactMap(\.id)
+        var summary = "Models available: \(models.count)"
+        let preview = models.prefix(3).joined(separator: ", ")
+        if !preview.isEmpty {
+            summary += " (\(preview))"
+        }
+
+        return UsageSnapshot(
+            primary: RateWindow(
+                usedPercent: 0,
+                windowMinutes: nil,
+                resetsAt: nil,
+                resetDescription: summary),
+            secondary: nil,
+            tertiary: nil,
+            updatedAt: Date(),
+            identity: nil)
+    }
+}
+
+enum MistralAPIError: LocalizedError, Sendable {
+    case invalidResponse
+    case httpError(statusCode: Int, body: String?)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidResponse:
+            return "Invalid response from Mistral API"
+        case let .httpError(statusCode, body):
+            if let body, !body.isEmpty {
+                return "Mistral API returned status code \(statusCode): \(body)"
+            }
+            return "Mistral API returned status code \(statusCode)"
+        }
+    }
+}

package/Sources/RunicCore/Providers/OpenRouter/OpenRouterProviderDescriptor.swift

@@ -0,0 +1,87 @@
+import RunicMacroSupport
+import Foundation
+
+@ProviderDescriptorRegistration
+@ProviderDescriptorDefinition
+public enum OpenRouterProviderDescriptor {
+    static func makeDescriptor() -> ProviderDescriptor {
+        ProviderDescriptor(
+            id: .openrouter,
+            metadata: ProviderMetadata(
+                id: .openrouter,
+                displayName: "OpenRouter",
+                sessionLabel: "Credits",
+                weeklyLabel: "",
+                opusLabel: nil,
+                supportsOpus: false,
+                supportsCredits: true,
+                creditsHint: "Shows credits from OpenRouter API",
+                toggleTitle: "Show OpenRouter usage",
+                cliName: "openrouter",
+                defaultEnabled: false,
+                isPrimaryProvider: false,
+                usesAccountFallback: false,
+                dashboardURL: "https://openrouter.ai/account",
+                statusPageURL: nil,
+                usageCoverage: ProviderUsageCoverage(
+                    supportsModelBreakdown: false,
+                    supportsTokenMetrics: false,
+                    supportsProjectAttribution: false)),
+            branding: ProviderBranding(
+                iconStyle: .openrouter,
+                iconResourceName: "ProviderIcon-openrouter",
+                color: ProviderColor(red: 255 / 255, green: 90 / 255, blue: 0 / 255)),
+            tokenCost: ProviderTokenCostConfig(
+                supportsTokenCost: false,
+                noDataMessage: { "OpenRouter cost summary is not supported." }),
+            fetchPlan: ProviderFetchPlan(
+                sourceModes: [.auto, .cli],
+                pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [OpenRouterAPIFetchStrategy()] })),
+            cli: ProviderCLIConfig(
+                name: "openrouter",
+                aliases: ["or"],
+                versionDetector: nil))
+    }
+}
+
+struct OpenRouterAPIFetchStrategy: ProviderFetchStrategy {
+    let id: String = "openrouter.api"
+    let kind: ProviderFetchKind = .apiToken
+
+    func isAvailable(_ context: ProviderFetchContext) async -> Bool {
+        Self.resolveToken(environment: context.env) != nil
+    }
+
+    func fetch(_ context: ProviderFetchContext) async throws -> ProviderFetchResult {
+        guard let apiKey = Self.resolveToken(environment: context.env) else {
+            throw OpenRouterSettingsError.missingToken
+        }
+        let (credits, keyInfo) = try await OpenRouterUsageFetcher.fetchAll(apiKey: apiKey)
+        return self.makeResult(
+            usage: credits.toUsageSnapshot(keyInfo: keyInfo),
+            credits: credits.toCreditsSnapshot(),
+            sourceLabel: "api")
+    }
+
+    func shouldFallback(on _: Error, context _: ProviderFetchContext) -> Bool {
+        false
+    }
+
+    private static func resolveToken(environment: [String: String]) -> String? {
+        ProviderTokenResolver.openRouterToken(environment: environment)
+    }
+}
+
+// MARK: - Settings Errors
+
+enum OpenRouterSettingsError: LocalizedError, Sendable {
+    case missingToken
+
+    var errorDescription: String? {
+        switch self {
+        case .missingToken:
+            "OpenRouter API key not found. Set it in Preferences → Providers → OpenRouter or " +
+                "export OPENROUTER_API_KEY."
+        }
+    }
+}

package/Sources/RunicCore/Providers/OpenRouter/OpenRouterUsageFetcher.swift

@@ -0,0 +1,207 @@
+import Foundation
+
+// MARK: - API response models
+
+struct OpenRouterCreditsResponse: Decodable {
+    let data: CreditData?
+    let credits: Double?
+
+    struct CreditData: Decodable {
+        let credits: Double?
+        let total_credits: Double?
+        let total_usage: Double?
+    }
+
+    /// Resolved total credits purchased.
+    var totalCredits: Double {
+        self.data?.total_credits ?? self.data?.credits ?? self.credits ?? 0
+    }
+
+    /// Resolved total credits consumed.
+    var totalUsage: Double {
+        self.data?.total_usage ?? 0
+    }
+
+    /// Remaining balance.
+    var remaining: Double {
+        max(0, self.totalCredits - self.totalUsage)
+    }
+
+    /// Usage percentage (0–100).
+    var usedPercent: Double {
+        guard self.totalCredits > 0 else { return 0 }
+        return min(100, max(0, (self.totalUsage / self.totalCredits) * 100))
+    }
+}
+
+/// Response from /api/v1/auth/key — lightweight key info.
+struct OpenRouterKeyInfoResponse: Decodable {
+    let data: KeyData?
+
+    struct KeyData: Decodable {
+        let label: String?
+        let usage: Double?
+        let limit: Double?
+        let is_free_tier: Bool?
+        let rate_limit: RateLimit?
+
+        struct RateLimit: Decodable {
+            let requests: Int?
+            let interval: String?
+        }
+    }
+
+    var keyUsage: Double { self.data?.usage ?? 0 }
+    var keyLimit: Double? { self.data?.limit }
+    var isFreeTier: Bool { self.data?.is_free_tier ?? false }
+    var rateLimitRequests: Int? { self.data?.rate_limit?.requests }
+    var rateLimitInterval: String? { self.data?.rate_limit?.interval }
+}
+
+// MARK: - Fetcher
+
+struct OpenRouterUsageFetcher {
+    static let creditsURL = URL(string: "https://openrouter.ai/api/v1/credits")!
+    static let keyInfoURL = URL(string: "https://openrouter.ai/api/v1/auth/key")!
+    private static let requestTimeout: TimeInterval = 15
+    private static let log = RunicLog.logger("openrouter-usage")
+
+    /// Fetches credits + key info in parallel for maximum data.
+    static func fetchAll(apiKey: String) async throws -> (OpenRouterCreditsResponse, OpenRouterKeyInfoResponse?) {
+        async let creditsTask = Self.fetchCredits(apiKey: apiKey)
+        async let keyInfoTask = Self.fetchKeyInfoBestEffort(apiKey: apiKey)
+
+        let credits = try await creditsTask
+        let keyInfo = await keyInfoTask
+        return (credits, keyInfo)
+    }
+
+    static func fetchCredits(apiKey: String) async throws -> OpenRouterCreditsResponse {
+        var request = URLRequest(url: creditsURL)
+        request.timeoutInterval = Self.requestTimeout
+        request.addValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
+        request.addValue("application/json", forHTTPHeaderField: "Content-Type")
+
+        let (data, response) = try await URLSession.shared.data(for: request)
+
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw OpenRouterAPIError.invalidResponse
+        }
+        guard httpResponse.statusCode == 200 else {
+            throw OpenRouterAPIError.httpError(statusCode: httpResponse.statusCode)
+        }
+
+        if let json = String(data: data, encoding: .utf8) {
+            Self.log.debug("OpenRouter credits response: \(json)")
+        }
+
+        return try JSONDecoder().decode(OpenRouterCreditsResponse.self, from: data)
+    }
+
+    private static func fetchKeyInfoBestEffort(apiKey: String) async -> OpenRouterKeyInfoResponse? {
+        do {
+            return try await Self.fetchKeyInfo(apiKey: apiKey)
+        } catch {
+            Self.log.info("OpenRouter key info unavailable: \(error.localizedDescription)")
+            return nil
+        }
+    }
+
+    static func fetchKeyInfo(apiKey: String) async throws -> OpenRouterKeyInfoResponse {
+        var request = URLRequest(url: keyInfoURL)
+        request.timeoutInterval = Self.requestTimeout
+        request.addValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
+        request.addValue("application/json", forHTTPHeaderField: "Content-Type")
+
+        let (data, response) = try await URLSession.shared.data(for: request)
+
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw OpenRouterAPIError.invalidResponse
+        }
+        guard httpResponse.statusCode == 200 else {
+            throw OpenRouterAPIError.httpError(statusCode: httpResponse.statusCode)
+        }
+
+        if let json = String(data: data, encoding: .utf8) {
+            Self.log.debug("OpenRouter key info response: \(json)")
+        }
+
+        return try JSONDecoder().decode(OpenRouterKeyInfoResponse.self, from: data)
+    }
+
+}
+
+// MARK: - Snapshot conversion
+
+extension OpenRouterCreditsResponse {
+    func toUsageSnapshot(keyInfo: OpenRouterKeyInfoResponse? = nil) -> UsageSnapshot {
+        let balance = self.remaining
+        let used = self.totalUsage
+        let total = self.totalCredits
+        let percent = self.usedPercent
+
+        let balanceStr = String(format: "$%.2f", balance)
+        let usedStr = String(format: "$%.2f", used)
+
+        var resetDesc = "Balance: \(balanceStr)"
+        if used > 0 {
+            resetDesc += " · Spent: \(usedStr)"
+        }
+
+        var identityMethod: String?
+        if let keyInfo {
+            var parts: [String] = []
+            if keyInfo.isFreeTier { parts.append("Free tier") }
+            if let label = keyInfo.data?.label, !label.isEmpty { parts.append(label) }
+            if let rpm = keyInfo.rateLimitRequests, let interval = keyInfo.rateLimitInterval {
+                parts.append("\(rpm) req/\(interval)")
+            }
+            if !parts.isEmpty { identityMethod = parts.joined(separator: " · ") }
+        }
+
+        let identity = identityMethod.map {
+            ProviderIdentitySnapshot(
+                providerID: .openrouter,
+                accountEmail: nil,
+                accountOrganization: nil,
+                loginMethod: $0)
+        }
+
+        return UsageSnapshot(
+            primary: RateWindow(
+                usedPercent: total > 0 ? percent : 0,
+                windowMinutes: nil,
+                resetsAt: nil,
+                resetDescription: resetDesc),
+            secondary: nil,
+            tertiary: nil,
+            updatedAt: Date(),
+            identity: identity)
+    }
+
+    func toCreditsSnapshot() -> CreditsSnapshot {
+        CreditsSnapshot(
+            remaining: self.remaining,
+            events: [],
+            updatedAt: Date())
+    }
+}
+
+// MARK: - Errors
+
+enum OpenRouterAPIError: LocalizedError, Sendable {
+    case invalidResponse
+    case httpError(statusCode: Int)
+    case decodingError
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidResponse:
+            "Invalid response from OpenRouter API"
+        case let .httpError(statusCode):
+            "OpenRouter API returned status code \(statusCode)"
+        case .decodingError:
+            "Failed to decode OpenRouter API response"
+        }
+    }
+}

package/Sources/RunicCore/Providers/Perplexity/PerplexityProviderDescriptor.swift

@@ -0,0 +1,84 @@
+import RunicMacroSupport
+import Foundation
+
+@ProviderDescriptorRegistration
+@ProviderDescriptorDefinition
+public enum PerplexityProviderDescriptor {
+    static func makeDescriptor() -> ProviderDescriptor {
+        ProviderDescriptor(
+            id: .perplexity,
+            metadata: ProviderMetadata(
+                id: .perplexity,
+                displayName: "Perplexity",
+                sessionLabel: "Models",
+                weeklyLabel: "",
+                opusLabel: nil,
+                supportsOpus: false,
+                supportsCredits: false,
+                creditsHint: "Shows model availability from Perplexity API.",
+                toggleTitle: "Show Perplexity usage",
+                cliName: "perplexity",
+                defaultEnabled: false,
+                isPrimaryProvider: false,
+                usesAccountFallback: false,
+                dashboardURL: "https://www.perplexity.ai/settings/api",
+                statusPageURL: nil,
+                usageCoverage: ProviderUsageCoverage(
+                    supportsModelBreakdown: true,
+                    supportsTokenMetrics: false,
+                    supportsProjectAttribution: false)),
+            branding: ProviderBranding(
+                iconStyle: .perplexity,
+                iconResourceName: "ProviderIcon-perplexity",
+                color: ProviderColor(red: 35 / 255, green: 180 / 255, blue: 146 / 255)),
+            tokenCost: ProviderTokenCostConfig(
+                supportsTokenCost: false,
+                noDataMessage: { "Perplexity cost summary is not supported." }),
+            fetchPlan: ProviderFetchPlan(
+                sourceModes: [.auto, .cli],
+                pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [PerplexityAPIFetchStrategy()] })),
+            cli: ProviderCLIConfig(
+                name: "perplexity",
+                aliases: ["pplx"],
+                versionDetector: nil))
+    }
+}
+
+struct PerplexityAPIFetchStrategy: ProviderFetchStrategy {
+    let id: String = "perplexity.api"
+    let kind: ProviderFetchKind = .apiToken
+
+    func isAvailable(_ context: ProviderFetchContext) async -> Bool {
+        Self.resolveTokenResolution(environment: context.env) != nil
+    }
+
+    func fetch(_ context: ProviderFetchContext) async throws -> ProviderFetchResult {
+        guard let tokenRes = Self.resolveTokenResolution(environment: context.env) else {
+            throw PerplexitySettingsError.missingToken
+        }
+        let usage = try await PerplexityUsageFetcher.fetchModels(apiKey: tokenRes.token)
+        return self.makeResult(
+            usage: usage.toUsageSnapshot(),
+            sourceLabel: tokenRes.source.rawValue)
+    }
+
+    func shouldFallback(on _: Error, context _: ProviderFetchContext) -> Bool {
+        false
+    }
+
+    private static func resolveTokenResolution(environment: [String: String]) -> ProviderTokenResolution? {
+        ProviderTokenResolver.perplexityResolution(environment: environment)
+    }
+}
+
+enum PerplexitySettingsError: LocalizedError, Sendable {
+    case missingToken
+
+    var errorDescription: String? {
+        switch self {
+        case .missingToken:
+            "Perplexity API key not found. Set it in Preferences → Providers → Perplexity or " +
+                "export PPLX_API_KEY."
+        }
+    }
+}

package/Sources/RunicCore/Providers/Perplexity/PerplexityUsageFetcher.swift

@@ -0,0 +1,75 @@
+import Foundation
+
+struct PerplexityModelsResponse: Decodable {
+    let data: [Model]?
+
+    struct Model: Decodable {
+        let id: String?
+    }
+}
+
+struct PerplexityUsageFetcher {
+    static let apiURL = URL(string: "https://api.perplexity.ai/models")!
+
+    static func fetchModels(apiKey: String) async throws -> PerplexityModelsResponse {
+        var request = URLRequest(url: apiURL)
+        request.addValue("Bearer \(apiKey)", forHTTPHeaderField: "Authorization")
+        request.addValue("application/json", forHTTPHeaderField: "Content-Type")
+
+        let (data, response) = try await URLSession.shared.data(for: request)
+
+        guard let httpResponse = response as? HTTPURLResponse else {
+            throw PerplexityAPIError.invalidResponse
+        }
+
+        guard httpResponse.statusCode == 200 else {
+            let body = String(data: data, encoding: .utf8)?
+                .trimmingCharacters(in: .whitespacesAndNewlines)
+            throw PerplexityAPIError.httpError(
+                statusCode: httpResponse.statusCode,
+                body: body?.isEmpty == false ? body : nil)
+        }
+
+        let decoder = JSONDecoder()
+        return try decoder.decode(PerplexityModelsResponse.self, from: data)
+    }
+}
+
+extension PerplexityModelsResponse {
+    func toUsageSnapshot() -> UsageSnapshot {
+        let models = (self.data ?? []).compactMap(\.id)
+        var summary = "Models available: \(models.count)"
+        let preview = models.prefix(3).joined(separator: ", ")
+        if !preview.isEmpty {
+            summary += " (\(preview))"
+        }
+
+        return UsageSnapshot(
+            primary: RateWindow(
+                usedPercent: 0,
+                windowMinutes: nil,
+                resetsAt: nil,
+                resetDescription: summary),
+            secondary: nil,
+            tertiary: nil,
+            updatedAt: Date(),
+            identity: nil)
+    }
+}
+
+enum PerplexityAPIError: LocalizedError, Sendable {
+    case invalidResponse
+    case httpError(statusCode: Int, body: String?)
+
+    var errorDescription: String? {
+        switch self {
+        case .invalidResponse:
+            return "Invalid response from Perplexity API"
+        case let .httpError(statusCode, body):
+            if let body, !body.isEmpty {
+                return "Perplexity API returned status code \(statusCode): \(body)"
+            }
+            return "Perplexity API returned status code \(statusCode)"
+        }
+    }
+}

package/Sources/RunicCore/Providers/ProviderBranding.swift

@@ -0,0 +1,25 @@
+import Foundation
+
+public struct ProviderColor: Sendable, Equatable {
+    public let red: Double
+    public let green: Double
+    public let blue: Double
+
+    public init(red: Double, green: Double, blue: Double) {
+        self.red = red
+        self.green = green
+        self.blue = blue
+    }
+}
+
+public struct ProviderBranding: Sendable {
+    public let iconStyle: IconStyle
+    public let iconResourceName: String
+    public let color: ProviderColor
+
+    public init(iconStyle: IconStyle, iconResourceName: String, color: ProviderColor) {
+        self.iconStyle = iconStyle
+        self.iconResourceName = iconResourceName
+        self.color = color
+    }
+}

package/Sources/RunicCore/Providers/ProviderCLIConfig.swift

@@ -0,0 +1,17 @@
+import Foundation
+
+public struct ProviderCLIConfig: Sendable {
+    public let name: String
+    public let aliases: [String]
+    public let versionDetector: (@Sendable () -> String?)?
+
+    public init(
+        name: String,
+        aliases: [String] = [],
+        versionDetector: (@Sendable () -> String?)?)
+    {
+        self.name = name
+        self.aliases = aliases
+        self.versionDetector = versionDetector
+    }
+}