@sriinnu/runic 1.0.0

package/Sources/RunicCore/Providers/Codex/CodexProviderDescriptor.swift

@@ -0,0 +1,243 @@
+import RunicMacroSupport
+import Foundation
+
+@ProviderDescriptorRegistration
+@ProviderDescriptorDefinition
+public enum CodexProviderDescriptor {
+    static func makeDescriptor() -> ProviderDescriptor {
+        ProviderDescriptor(
+            id: .codex,
+            metadata: ProviderMetadata(
+                id: .codex,
+                displayName: "Codex",
+                sessionLabel: "Session",
+                weeklyLabel: "Weekly",
+                opusLabel: nil,
+                supportsOpus: false,
+                supportsCredits: true,
+                creditsHint: "Credits unavailable; keep Codex running to refresh.",
+                toggleTitle: "Show Codex usage",
+                cliName: "codex",
+                defaultEnabled: true,
+                isPrimaryProvider: true,
+                usesAccountFallback: true,
+                browserCookieOrder: ProviderBrowserCookieDefaults.defaultImportOrder,
+                dashboardURL: "https://chatgpt.com/codex/settings/usage",
+                statusPageURL: "https://status.openai.com/",
+                usageCoverage: ProviderUsageCoverage(
+                    supportsModelBreakdown: true,
+                    supportsTokenMetrics: true,
+                    supportsProjectAttribution: true)),
+            branding: ProviderBranding(
+                iconStyle: .codex,
+                iconResourceName: "ProviderIcon-codex",
+                color: ProviderColor(red: 73 / 255, green: 163 / 255, blue: 176 / 255)),
+            tokenCost: ProviderTokenCostConfig(
+                supportsTokenCost: true,
+                noDataMessage: self.noDataMessage),
+            fetchPlan: ProviderFetchPlan(
+                sourceModes: [.auto, .web, .cli, .oauth],
+                pipeline: ProviderFetchPipeline(resolveStrategies: self.resolveStrategies)),
+            cli: ProviderCLIConfig(
+                name: "codex",
+                versionDetector: { ProviderVersionDetector.codexVersion() }))
+    }
+
+    private static func resolveStrategies(context: ProviderFetchContext) async -> [any ProviderFetchStrategy] {
+        let cli = CodexCLIUsageStrategy()
+        let oauth = CodexOAuthFetchStrategy()
+        let web = CodexWebDashboardStrategy()
+
+        switch context.runtime {
+        case .cli:
+            switch context.sourceMode {
+            case .oauth:
+                return [oauth]
+            case .web:
+                return [web]
+            case .cli:
+                return [cli]
+            case .auto:
+                return [web, cli]
+            case .api:
+                return []
+            }
+        case .app:
+            let settings = context.settings
+            let debugMenuEnabled = settings?.debugMenuEnabled ?? false
+            let codexSettings = settings?.codex
+            let selected = codexSettings?.usageDataSource ?? .oauth
+            let hasOAuthCredentials = (try? CodexOAuthCredentialsStore.load()) != nil
+            let strategy = Self.resolveUsageStrategy(
+                debugMenuEnabled: debugMenuEnabled,
+                selectedDataSource: selected,
+                hasOAuthCredentials: hasOAuthCredentials)
+            switch strategy.dataSource {
+            case .oauth:
+                return [oauth, cli]
+            case .cli:
+                return [cli]
+            }
+        }
+    }
+
+    private static func noDataMessage() -> String {
+        let fm = FileManager.default
+        let home = fm.homeDirectoryForCurrentUser.path
+        let root = ProcessInfo.processInfo.environment["CODEX_HOME"].flatMap { raw -> String? in
+            let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard !trimmed.isEmpty else { return nil }
+            return "\(trimmed)/sessions"
+        } ?? "\(home)/.codex/sessions"
+        return "No Codex sessions found in \(root)."
+    }
+
+    public static func resolveUsageStrategy(
+        debugMenuEnabled: Bool,
+        selectedDataSource: CodexUsageDataSource,
+        hasOAuthCredentials: Bool) -> CodexUsageStrategy
+    {
+        if debugMenuEnabled {
+            if selectedDataSource == .oauth, !hasOAuthCredentials {
+                return CodexUsageStrategy(dataSource: .cli)
+            }
+            return CodexUsageStrategy(dataSource: selectedDataSource)
+        }
+
+        if hasOAuthCredentials {
+            return CodexUsageStrategy(dataSource: .oauth)
+        }
+        return CodexUsageStrategy(dataSource: .cli)
+    }
+}
+
+public struct CodexUsageStrategy: Equatable, Sendable {
+    public let dataSource: CodexUsageDataSource
+}
+
+struct CodexCLIUsageStrategy: ProviderFetchStrategy {
+    let id: String = "codex.cli"
+    let kind: ProviderFetchKind = .cli
+
+    func isAvailable(_: ProviderFetchContext) async -> Bool { true }
+
+    func fetch(_ context: ProviderFetchContext) async throws -> ProviderFetchResult {
+        let usage = try await context.fetcher.loadLatestUsage()
+        let credits = await context.includeCredits ? (try? context.fetcher.loadLatestCredits()) : nil
+        return self.makeResult(
+            usage: usage,
+            credits: credits,
+            sourceLabel: "codex-cli")
+    }
+
+    func shouldFallback(on _: Error, context _: ProviderFetchContext) -> Bool {
+        false
+    }
+}
+
+struct CodexOAuthFetchStrategy: ProviderFetchStrategy {
+    let id: String = "codex.oauth"
+    let kind: ProviderFetchKind = .oauth
+
+    func isAvailable(_: ProviderFetchContext) async -> Bool {
+        (try? CodexOAuthCredentialsStore.load()) != nil
+    }
+
+    func fetch(_: ProviderFetchContext) async throws -> ProviderFetchResult {
+        var credentials = try CodexOAuthCredentialsStore.load()
+
+        if credentials.needsRefresh, !credentials.refreshToken.isEmpty {
+            credentials = try await CodexTokenRefresher.refresh(credentials)
+            try CodexOAuthCredentialsStore.save(credentials)
+        }
+
+        let usage = try await CodexOAuthUsageFetcher.fetchUsage(
+            accessToken: credentials.accessToken,
+            accountId: credentials.accountId)
+
+        return self.makeResult(
+            usage: Self.mapUsage(usage, credentials: credentials),
+            credits: Self.mapCredits(usage.credits),
+            sourceLabel: "oauth")
+    }
+
+    func shouldFallback(on error: Error, context: ProviderFetchContext) -> Bool {
+        guard context.sourceMode == .auto else { return false }
+        if let fetchError = error as? CodexOAuthFetchError {
+            switch fetchError {
+            case .unauthorized, .invalidResponse, .serverError, .networkError:
+                return true
+            }
+        }
+        if error is CodexOAuthCredentialsError { return true }
+        if error is CodexTokenRefresher.RefreshError { return true }
+        return false
+    }
+
+    private static func mapUsage(_ response: CodexUsageResponse, credentials: CodexOAuthCredentials) -> UsageSnapshot {
+        let primary = Self.makeWindow(response.rateLimit?.primaryWindow)
+        let secondary = Self.makeWindow(response.rateLimit?.secondaryWindow)
+
+        let identity = ProviderIdentitySnapshot(
+            providerID: .codex,
+            accountEmail: Self.resolveAccountEmail(from: credentials),
+            accountOrganization: nil,
+            loginMethod: Self.resolvePlan(response: response, credentials: credentials))
+
+        return UsageSnapshot(
+            primary: primary ?? RateWindow(usedPercent: 0, windowMinutes: nil, resetsAt: nil, resetDescription: nil),
+            secondary: secondary,
+            tertiary: nil,
+            updatedAt: Date(),
+            identity: identity)
+    }
+
+    private static func mapCredits(_ credits: CodexUsageResponse.CreditDetails?) -> CreditsSnapshot? {
+        guard let credits, let balance = credits.balance else { return nil }
+        return CreditsSnapshot(remaining: balance, events: [], updatedAt: Date())
+    }
+
+    private static func makeWindow(_ window: CodexUsageResponse.WindowSnapshot?) -> RateWindow? {
+        guard let window else { return nil }
+        let resetDate = Date(timeIntervalSince1970: TimeInterval(window.resetAt))
+        let resetDescription = UsageFormatter.resetDescription(from: resetDate)
+        return RateWindow(
+            usedPercent: Double(window.usedPercent),
+            windowMinutes: window.limitWindowSeconds / 60,
+            resetsAt: resetDate,
+            resetDescription: resetDescription)
+    }
+
+    private static func resolveAccountEmail(from credentials: CodexOAuthCredentials) -> String? {
+        guard let idToken = credentials.idToken,
+              let payload = UsageFetcher.parseJWT(idToken)
+        else {
+            return nil
+        }
+
+        let profileDict = payload["https://api.openai.com/profile"] as? [String: Any]
+        let email = (payload["email"] as? String) ?? (profileDict?["email"] as? String)
+        return email?.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+
+    private static func resolvePlan(response: CodexUsageResponse, credentials: CodexOAuthCredentials) -> String? {
+        if let plan = response.planType?.rawValue, !plan.isEmpty { return plan }
+        guard let idToken = credentials.idToken,
+              let payload = UsageFetcher.parseJWT(idToken)
+        else {
+            return nil
+        }
+        let authDict = payload["https://api.openai.com/auth"] as? [String: Any]
+        let plan = (authDict?["chatgpt_plan_type"] as? String) ?? (payload["chatgpt_plan_type"] as? String)
+        return plan?.trimmingCharacters(in: .whitespacesAndNewlines)
+    }
+}
+
+#if DEBUG
+extension CodexOAuthFetchStrategy {
+    static func _mapUsageForTesting(_ data: Data, credentials: CodexOAuthCredentials) throws -> UsageSnapshot {
+        let usage = try JSONDecoder().decode(CodexUsageResponse.self, from: data)
+        return Self.mapUsage(usage, credentials: credentials)
+    }
+}
+#endif

package/Sources/RunicCore/Providers/Codex/CodexStatusProbe.swift

@@ -0,0 +1,125 @@
+import Foundation
+
+public struct CodexStatusSnapshot: Sendable {
+    public let credits: Double?
+    public let fiveHourPercentLeft: Int?
+    public let weeklyPercentLeft: Int?
+    public let fiveHourResetDescription: String?
+    public let weeklyResetDescription: String?
+    public let rawText: String
+
+    public init(
+        credits: Double?,
+        fiveHourPercentLeft: Int?,
+        weeklyPercentLeft: Int?,
+        fiveHourResetDescription: String?,
+        weeklyResetDescription: String?,
+        rawText: String)
+    {
+        self.credits = credits
+        self.fiveHourPercentLeft = fiveHourPercentLeft
+        self.weeklyPercentLeft = weeklyPercentLeft
+        self.fiveHourResetDescription = fiveHourResetDescription
+        self.weeklyResetDescription = weeklyResetDescription
+        self.rawText = rawText
+    }
+}
+
+public enum CodexStatusProbeError: LocalizedError, Sendable {
+    case codexNotInstalled
+    case parseFailed(String)
+    case timedOut
+    case updateRequired(String)
+
+    public var errorDescription: String? {
+        switch self {
+        case .codexNotInstalled:
+            "Codex CLI missing. Install via `npm i -g @openai/codex` (or bun install) and restart."
+        case .parseFailed:
+            "Could not parse Codex status; will retry shortly."
+        case .timedOut:
+            "Codex status probe timed out."
+        case let .updateRequired(msg):
+            "Codex CLI update needed: \(msg)"
+        }
+    }
+}
+
+/// Runs `codex` inside a PTY, sends `/status`, captures text, and parses credits/limits.
+public struct CodexStatusProbe {
+    public var codexBinary: String = "codex"
+    public var timeout: TimeInterval = 18.0
+
+    public init() {}
+
+    public init(codexBinary: String = "codex", timeout: TimeInterval = 18.0) {
+        self.codexBinary = codexBinary
+        self.timeout = timeout
+    }
+
+    public func fetch() async throws -> CodexStatusSnapshot {
+        guard TTYCommandRunner.which(self.codexBinary) != nil else { throw CodexStatusProbeError.codexNotInstalled }
+        do {
+            return try self.runAndParse(rows: 60, cols: 200, timeout: self.timeout)
+        } catch let error as CodexStatusProbeError {
+            // Codex sometimes returns an incomplete screen on the first try; retry once with a longer window.
+            switch error {
+            case .parseFailed, .timedOut:
+                return try self.runAndParse(rows: 70, cols: 220, timeout: max(self.timeout, 24.0))
+            default:
+                throw error
+            }
+        }
+    }
+
+    // MARK: - Parsing
+
+    public static func parse(text: String) throws -> CodexStatusSnapshot {
+        let clean = TextParsing.stripANSICodes(text)
+        guard !clean.isEmpty else { throw CodexStatusProbeError.timedOut }
+        if clean.localizedCaseInsensitiveContains("data not available yet") {
+            throw CodexStatusProbeError.parseFailed("data not available yet")
+        }
+        if self.containsUpdatePrompt(clean) {
+            throw CodexStatusProbeError.updateRequired(
+                "Run `bun install -g @openai/codex` to continue (update prompt blocking /status).")
+        }
+        let credits = TextParsing.firstNumber(pattern: #"Credits:\s*([0-9][0-9.,]*)"#, text: clean)
+        // Pull reset info from the same lines that contain the percentages.
+        let fiveLine = TextParsing.firstLine(matching: #"5h limit[^\n]*"#, text: clean)
+        let weekLine = TextParsing.firstLine(matching: #"Weekly limit[^\n]*"#, text: clean)
+        let fivePct = fiveLine.flatMap(TextParsing.percentLeft(fromLine:))
+        let weekPct = weekLine.flatMap(TextParsing.percentLeft(fromLine:))
+        let fiveReset = fiveLine.flatMap(TextParsing.resetString(fromLine:))
+        let weekReset = weekLine.flatMap(TextParsing.resetString(fromLine:))
+        if credits == nil, fivePct == nil, weekPct == nil {
+            throw CodexStatusProbeError.parseFailed(clean.prefix(400).description)
+        }
+        return CodexStatusSnapshot(
+            credits: credits,
+            fiveHourPercentLeft: fivePct,
+            weeklyPercentLeft: weekPct,
+            fiveHourResetDescription: fiveReset,
+            weeklyResetDescription: weekReset,
+            rawText: clean)
+    }
+
+    private func runAndParse(rows: UInt16, cols: UInt16, timeout: TimeInterval) throws -> CodexStatusSnapshot {
+        let runner = TTYCommandRunner()
+        let script = "/status\n"
+        let result = try runner.run(
+            binary: self.codexBinary,
+            send: script,
+            options: .init(
+                rows: rows,
+                cols: cols,
+                timeout: timeout,
+                extraArgs: ["-s", "read-only", "-a", "untrusted"]))
+        return try Self.parse(text: result.text)
+    }
+
+    private static func containsUpdatePrompt(_ text: String) -> Bool {
+        let lower = text.lowercased()
+        return lower.contains("update available") && lower.contains("codex")
+    }
+}

package/Sources/RunicCore/Providers/Codex/CodexUsageDataSource.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+public enum CodexUsageDataSource: String, CaseIterable, Identifiable, Sendable {
+    case oauth
+    case cli
+
+    public var id: String { self.rawValue }
+
+    public var displayName: String {
+        switch self {
+        case .oauth: "OAuth API"
+        case .cli: "CLI (RPC/PTY)"
+        }
+    }
+
+    public var sourceLabel: String {
+        switch self {
+        case .oauth:
+            "oauth"
+        case .cli:
+            "cli"
+        }
+    }
+}

package/Sources/RunicCore/Providers/Codex/CodexWebDashboardStrategy.swift

@@ -0,0 +1,181 @@
+#if os(macOS)
+import AppKit
+import Foundation
+
+public struct CodexWebDashboardStrategy: ProviderFetchStrategy {
+    public let id: String = "codex.web.dashboard"
+    public let kind: ProviderFetchKind = .webDashboard
+
+    public init() {}
+
+    public func isAvailable(_ context: ProviderFetchContext) async -> Bool {
+        context.sourceMode.usesWeb
+    }
+
+    public func fetch(_ context: ProviderFetchContext) async throws -> ProviderFetchResult {
+        // Ensure AppKit is initialized before using WebKit in a CLI.
+        await MainActor.run {
+            _ = NSApplication.shared
+        }
+
+        let accountEmail = context.fetcher.loadAccountInfo().email?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+        let result = try await Self.fetchOpenAIWebCodex(
+            accountEmail: accountEmail,
+            fetcher: context.fetcher,
+            timeout: context.webTimeout,
+            debugDumpHTML: context.webDebugDumpHTML,
+            verbose: context.verbose)
+        return self.makeResult(
+            usage: result.usage,
+            credits: result.credits,
+            dashboard: result.dashboard,
+            sourceLabel: "openai-web")
+    }
+
+    public func shouldFallback(on error: Error, context: ProviderFetchContext) -> Bool {
+        guard context.sourceMode == .auto else { return false }
+        return Self.shouldFallbackToCodexCLI(for: error)
+    }
+}
+
+private struct OpenAIWebCodexResult: Sendable {
+    let usage: UsageSnapshot
+    let credits: CreditsSnapshot?
+    let dashboard: OpenAIDashboardSnapshot
+}
+
+private enum OpenAIWebCodexError: LocalizedError {
+    case missingUsage
+
+    var errorDescription: String? {
+        switch self {
+        case .missingUsage:
+            "OpenAI web dashboard did not include usage limits."
+        }
+    }
+}
+
+private struct OpenAIWebOptions: Sendable {
+    let timeout: TimeInterval
+    let debugDumpHTML: Bool
+    let verbose: Bool
+}
+
+@MainActor
+private final class WebLogBuffer {
+    private var lines: [String] = []
+    private let maxCount: Int
+    private let verbose: Bool
+
+    init(maxCount: Int = 300, verbose: Bool) {
+        self.maxCount = maxCount
+        self.verbose = verbose
+    }
+
+    func append(_ line: String) {
+        self.lines.append(line)
+        if self.lines.count > self.maxCount {
+            self.lines.removeFirst(self.lines.count - self.maxCount)
+        }
+        if self.verbose {
+            fputs("\(line)\n", stderr)
+        }
+    }
+
+    func snapshot() -> [String] {
+        self.lines
+    }
+}
+
+extension CodexWebDashboardStrategy {
+    @MainActor
+    fileprivate static func fetchOpenAIWebCodex(
+        accountEmail: String?,
+        fetcher: UsageFetcher,
+        timeout: TimeInterval,
+        debugDumpHTML: Bool,
+        verbose: Bool) async throws -> OpenAIWebCodexResult
+    {
+        let options = OpenAIWebOptions(timeout: timeout, debugDumpHTML: debugDumpHTML, verbose: verbose)
+        let logger = WebLogBuffer(verbose: verbose)
+        let log: @MainActor (String) -> Void = { line in
+            logger.append(line)
+        }
+        let dashboard = try await Self.fetchOpenAIWebDashboard(
+            accountEmail: accountEmail,
+            fetcher: fetcher,
+            options: options,
+            logger: log)
+        guard let usage = dashboard.toUsageSnapshot(provider: .codex, accountEmail: accountEmail) else {
+            throw OpenAIWebCodexError.missingUsage
+        }
+        let credits = dashboard.toCreditsSnapshot()
+        return OpenAIWebCodexResult(usage: usage, credits: credits, dashboard: dashboard)
+    }
+
+    @MainActor
+    fileprivate static func fetchOpenAIWebDashboard(
+        accountEmail: String?,
+        fetcher: UsageFetcher,
+        options: OpenAIWebOptions,
+        logger: @MainActor @escaping (String) -> Void) async throws -> OpenAIDashboardSnapshot
+    {
+        let trimmed = accountEmail?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let fallback = fetcher.loadAccountInfo().email?.trimmingCharacters(in: .whitespacesAndNewlines)
+        let codexEmail = trimmed?.isEmpty == false ? trimmed : (fallback?.isEmpty == false ? fallback : nil)
+        let allowAnyAccount = codexEmail == nil
+
+        let importResult = try await OpenAIDashboardBrowserCookieImporter()
+            .importBestCookies(intoAccountEmail: codexEmail, allowAnyAccount: allowAnyAccount, logger: logger)
+        let effectiveEmail = codexEmail ?? importResult.signedInEmail?
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+
+        let dash = try await OpenAIDashboardFetcher().loadLatestDashboard(
+            accountEmail: effectiveEmail,
+            logger: logger,
+            debugDumpHTML: options.debugDumpHTML,
+            timeout: options.timeout)
+        let cacheEmail = effectiveEmail ?? dash.signedInEmail?.trimmingCharacters(in: .whitespacesAndNewlines)
+        if let cacheEmail, !cacheEmail.isEmpty {
+            OpenAIDashboardCacheStore.save(OpenAIDashboardCache(accountEmail: cacheEmail, snapshot: dash))
+        }
+        return dash
+    }
+
+    fileprivate static func shouldFallbackToCodexCLI(for error: Error) -> Bool {
+        if let importError = error as? OpenAIDashboardBrowserCookieImporter.ImportError {
+            switch importError {
+            case .noCookiesFound,
+                 .browserAccessDenied,
+                 .dashboardStillRequiresLogin,
+                 .noMatchingAccount:
+                return true
+            }
+        }
+
+        if let fetchError = error as? OpenAIDashboardFetcher.FetchError {
+            if case .loginRequired = fetchError { return true }
+        }
+
+        return false
+    }
+}
+#else
+public struct CodexWebDashboardStrategy: ProviderFetchStrategy {
+    public let id: String = "codex.web.dashboard"
+    public let kind: ProviderFetchKind = .webDashboard
+
+    public init() {}
+
+    public func isAvailable(_: ProviderFetchContext) async -> Bool { false }
+
+    public func fetch(_: ProviderFetchContext) async throws -> ProviderFetchResult {
+        throw ProviderFetchError.noAvailableStrategy(.codex)
+    }
+
+    public func shouldFallback(on _: Error, context _: ProviderFetchContext) -> Bool {
+        false
+    }
+}
+#endif

package/Sources/RunicCore/Providers/Cohere/CohereProviderDescriptor.swift

@@ -0,0 +1,83 @@
+import RunicMacroSupport
+import Foundation
+
+@ProviderDescriptorRegistration
+@ProviderDescriptorDefinition
+public enum CohereProviderDescriptor {
+    static func makeDescriptor() -> ProviderDescriptor {
+        ProviderDescriptor(
+            id: .cohere,
+            metadata: ProviderMetadata(
+                id: .cohere,
+                displayName: "Cohere",
+                sessionLabel: "Models",
+                weeklyLabel: "",
+                opusLabel: nil,
+                supportsOpus: false,
+                supportsCredits: false,
+                creditsHint: "Shows model availability from Cohere API.",
+                toggleTitle: "Show Cohere usage",
+                cliName: "cohere",
+                defaultEnabled: false,
+                isPrimaryProvider: false,
+                usesAccountFallback: false,
+                dashboardURL: "https://dashboard.cohere.com/api-keys",
+                statusPageURL: nil,
+                usageCoverage: ProviderUsageCoverage(
+                    supportsModelBreakdown: true,
+                    supportsTokenMetrics: false,
+                    supportsProjectAttribution: false)),
+            branding: ProviderBranding(
+                iconStyle: .cohere,
+                iconResourceName: "ProviderIcon-cohere",
+                color: ProviderColor(red: 58 / 255, green: 95 / 255, blue: 255 / 255)),
+            tokenCost: ProviderTokenCostConfig(
+                supportsTokenCost: false,
+                noDataMessage: { "Cohere cost summary is not supported." }),
+            fetchPlan: ProviderFetchPlan(
+                sourceModes: [.auto, .cli],
+                pipeline: ProviderFetchPipeline(resolveStrategies: { _ in [CohereAPIFetchStrategy()] })),
+            cli: ProviderCLIConfig(
+                name: "cohere",
+                aliases: [],
+                versionDetector: nil))
+    }
+}
+
+struct CohereAPIFetchStrategy: ProviderFetchStrategy {
+    let id: String = "cohere.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 CohereSettingsError.missingToken
+        }
+        let usage = try await CohereUsageFetcher.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.cohereResolution(environment: environment)
+    }
+}
+
+enum CohereSettingsError: LocalizedError, Sendable {
+    case missingToken
+
+    var errorDescription: String? {
+        switch self {
+        case .missingToken:
+            "Cohere API key not found. Set it in Preferences → Providers → Cohere or export COHERE_API_KEY."
+        }
+    }
+}