@omnicross/core 0.1.1 → 0.1.2

package/dist/chunk-ZLX3KGXX.js

@@ -0,0 +1,173 @@
+// src/usage/pricing-engine.ts
+import { DEFAULT_LITELLM_PRICING_URL } from "@omnicross/contracts/pricing-types";
+var PricingEngine = class {
+  constructor(store, logger, options = {}) {
+    this.store = store;
+    this.logger = logger;
+    this.options = options;
+  }
+  store;
+  logger;
+  options;
+  cache = /* @__PURE__ */ new Map();
+  /**
+   * Secondary index keyed by modelId alone. Used as a fallback when no exact
+   * (providerId, modelId) match exists — usage may be recorded under a
+   * runtime provider alias while pricing rows use the canonical provider id,
+   * so matching by model name lets the price still resolve. First
+   * non-wildcard entry per model wins.
+   */
+  cacheByModel = /* @__PURE__ */ new Map();
+  cacheLoaded = false;
+  // ===== Cache management =====
+  /** Lazy-load and cache the full pricing table. */
+  async ensureCache() {
+    if (this.cacheLoaded) return;
+    const rows = await this.store.getAll();
+    this.cache = new Map(rows.map((r) => [keyOf(r.providerId, r.modelId), r]));
+    this.cacheByModel = /* @__PURE__ */ new Map();
+    for (const r of rows) {
+      if (r.providerId === "*") continue;
+      if (!this.cacheByModel.has(r.modelId)) this.cacheByModel.set(r.modelId, r);
+    }
+    this.cacheLoaded = true;
+  }
+  /** Force a cache refresh — call after any write. */
+  async invalidateCache() {
+    this.cacheLoaded = false;
+    await this.ensureCache();
+  }
+  // ===== Read API =====
+  async getAll() {
+    await this.ensureCache();
+    return Array.from(this.cache.values());
+  }
+  /**
+   * Look up a price for (provider, model). Resolution order:
+   *   1. exact (providerId, modelId)
+   *   2. wildcard provider ('*', modelId)
+   *   3. model name alone (any provider) — tolerates a runtime-alias vs
+   *      canonical provider-id mismatch for the same model.
+   */
+  async getEntry(providerId, modelId) {
+    await this.ensureCache();
+    return this.cache.get(keyOf(providerId, modelId)) ?? this.cache.get(keyOf("*", modelId)) ?? this.cacheByModel.get(modelId) ?? null;
+  }
+  // ===== Cost calculation =====
+  /**
+   * Compute the cost (and cache savings) for a single response.
+   *
+   * Cost formula (USD):
+   *   cost = (input  * inputPrice
+   *         + output * outputPrice
+   *         + cacheRead  * (cacheReadPrice  ?? inputPrice)
+   *         + cacheWrite * (cacheWritePrice ?? inputPrice)
+   *        ) / 1e6
+   *
+   * Cache savings:
+   *   savings = cacheRead * (inputPrice - cacheReadPrice) / 1e6
+   *           — clamped at 0 if cacheReadPrice is null or ≥ inputPrice.
+   */
+  async calculateCost(providerId, modelId, usage) {
+    const entry = await this.getEntry(providerId, modelId);
+    if (!entry) {
+      return { costUsd: 0, costSavedByCacheUsd: 0 };
+    }
+    const ip = entry.inputPricePer1m;
+    const op = entry.outputPricePer1m;
+    const crp = entry.cacheReadPricePer1m ?? ip;
+    const cwp = entry.cacheWritePricePer1m ?? ip;
+    const costUsd = (usage.inputTokens * ip + usage.outputTokens * op + usage.cacheReadTokens * crp + usage.cacheCreationTokens * cwp) / 1e6;
+    const savingsRate = entry.cacheReadPricePer1m == null ? 0 : Math.max(0, ip - crp);
+    const costSavedByCacheUsd = usage.cacheReadTokens * savingsRate / 1e6;
+    return { costUsd, costSavedByCacheUsd };
+  }
+  // ===== Manual upsert (used by inline editors) =====
+  async upsertManual(input) {
+    const updated = await this.store.upsert(
+      input,
+      /* asUserEdit */
+      true
+    );
+    this.cache.set(keyOf(updated.providerId, updated.modelId), updated);
+    if (updated.providerId !== "*") this.cacheByModel.set(updated.modelId, updated);
+    return updated;
+  }
+  // ===== Source refresh =====
+  async fetchLatestFromSource() {
+    const sourceUrl = this.options.sourceUrl ?? DEFAULT_LITELLM_PRICING_URL;
+    const fetchImpl = this.options.fetchImpl ?? fetch;
+    const fetchedAt = Date.now();
+    let json;
+    try {
+      const res = await fetchImpl(sourceUrl);
+      if (!res.ok) {
+        throw new Error(`Pricing-source fetch failed with status ${res.status}`);
+      }
+      json = await res.json();
+    } catch (e) {
+      this.logger.warn("[PricingEngine] pricing-source fetch failed", {
+        error: e instanceof Error ? e.message : String(e)
+      });
+      throw e;
+    }
+    const incoming = parseLitellmJson(json);
+    const { applied, conflicts } = await this.store.bulkApplyFromSource(incoming);
+    await this.invalidateCache();
+    return {
+      applied,
+      conflicts: conflicts.map((c) => ({
+        providerId: c.current.providerId,
+        modelId: c.current.modelId,
+        current: c.current,
+        incoming: c.incoming
+      })),
+      fetchedAt,
+      sourceUrl
+    };
+  }
+  // ===== Conflict resolution =====
+  async resolveConflicts(decisions, pendingIncoming) {
+    const resolutions = [];
+    for (const d of decisions) {
+      const incoming = pendingIncoming.get(keyOf(d.providerId, d.modelId));
+      if (!incoming) continue;
+      resolutions.push({ incoming, action: d.action });
+    }
+    const result = await this.store.applyResolutions(resolutions);
+    await this.invalidateCache();
+    return result;
+  }
+};
+var keyOf = (providerId, modelId) => `${providerId}::${modelId}`;
+var PROVIDER_ALIASES = {
+  vertex_ai: "gemini",
+  google: "gemini",
+  bedrock: "anthropic",
+  azure: "openai"
+};
+var parseLitellmJson = (json) => {
+  const out = [];
+  for (const [modelId, entry] of Object.entries(json)) {
+    if (!entry || typeof entry !== "object") continue;
+    if (entry.input_cost_per_token == null || entry.output_cost_per_token == null) {
+      continue;
+    }
+    const rawProvider = entry.litellm_provider ?? "";
+    const providerId = PROVIDER_ALIASES[rawProvider] ?? rawProvider;
+    if (!providerId) continue;
+    out.push({
+      providerId,
+      modelId,
+      inputPricePer1m: entry.input_cost_per_token * 1e6,
+      outputPricePer1m: entry.output_cost_per_token * 1e6,
+      cacheReadPricePer1m: entry.cache_read_input_token_cost != null ? entry.cache_read_input_token_cost * 1e6 : null,
+      cacheWritePricePer1m: entry.cache_creation_input_token_cost != null ? entry.cache_creation_input_token_cost * 1e6 : null
+    });
+  }
+  return out;
+};
+
+export {
+  PricingEngine
+};

package/dist/chunk-ZSVQT3PW.js

@@ -0,0 +1,43 @@
+// src/completion/openrouter-headers.ts
+var OPENROUTER_DEFAULT_BASE_URL = "https://openrouter.ai/api/v1";
+var OPENROUTER_HTTP_REFERER = "https://omnicross.dev";
+var OPENROUTER_X_TITLE = "Omnicross";
+function buildOpenRouterHeaders(credentials, options = {}) {
+  const apiKey = credentials.apiKey?.trim();
+  if (!apiKey) {
+    throw new Error("OpenRouter API key is required");
+  }
+  const headers = {
+    Authorization: `Bearer ${apiKey}`,
+    "HTTP-Referer": OPENROUTER_HTTP_REFERER,
+    "X-Title": OPENROUTER_X_TITLE
+  };
+  if (options.contentType !== false) {
+    headers["Content-Type"] = options.contentType ?? "application/json";
+  }
+  if (options.extra) {
+    for (const [key, value] of Object.entries(options.extra)) {
+      headers[key] = value;
+    }
+  }
+  return headers;
+}
+function resolveOpenRouterBaseUrl(endpoint) {
+  const raw = endpoint?.trim();
+  const base = raw && raw.length > 0 ? raw : OPENROUTER_DEFAULT_BASE_URL;
+  return base.replace(/\/+$/, "");
+}
+function buildOpenRouterUrl(endpoint, path) {
+  const base = resolveOpenRouterBaseUrl(endpoint);
+  const cleanPath = path.startsWith("/") ? path : `/${path}`;
+  return `${base}${cleanPath}`;
+}
+
+export {
+  OPENROUTER_DEFAULT_BASE_URL,
+  OPENROUTER_HTTP_REFERER,
+  OPENROUTER_X_TITLE,
+  buildOpenRouterHeaders,
+  resolveOpenRouterBaseUrl,
+  buildOpenRouterUrl
+};

package/dist/completion/ApiKeyPoolService.cjs

@@ -1,32 +1,8 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/completion/ApiKeyPoolService.ts
-var ApiKeyPoolService_exports = {};
-__export(ApiKeyPoolService_exports, {
-  ApiKeyPoolService: () => ApiKeyPoolService
-});
-module.exports = __toCommonJS(ApiKeyPoolService_exports);
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class;// src/completion/ApiKeyPoolService.ts
 var AUTH_FAILURE_CODES = /* @__PURE__ */ new Set([401, 403]);
 var RATE_LIMIT_CODES = /* @__PURE__ */ new Set([429, 529]);
-var ApiKeyPoolService = class {
-  constructor(loadKeys, resolveKey, logger, disableKey, markAutoDisabled) {
+var ApiKeyPoolService = (_class = class {
+  constructor(loadKeys, resolveKey, logger, disableKey, markAutoDisabled) {;_class.prototype.__init.call(this);_class.prototype.__init2.call(this);_class.prototype.__init3.call(this);_class.prototype.__init4.call(this);_class.prototype.__init5.call(this);_class.prototype.__init6.call(this);_class.prototype.__init7.call(this);_class.prototype.__init8.call(this);
     this.loadKeys = loadKeys;
     this.resolveKey = resolveKey;
     this.logger = logger;
@@ -34,27 +10,27 @@ var ApiKeyPoolService = class {
     this.markAutoDisabled = markAutoDisabled;
     this.cleanupTimer = setInterval(() => this.cleanupExpiredCooldowns(), 3e4);
   }
-  loadKeys;
-  resolveKey;
-  logger;
-  disableKey;
-  markAutoDisabled;
+  
+  
+  
+  
+  
   /** Session 鈫?key binding (session affinity) */
-  sessionBindings = /* @__PURE__ */ new Map();
+  __init() {this.sessionBindings = /* @__PURE__ */ new Map()}
   /** Provider 鈫?round-robin index */
-  rrIndex = /* @__PURE__ */ new Map();
+  __init2() {this.rrIndex = /* @__PURE__ */ new Map()}
   /** Provider 鈫?cached key list */
-  keyCache = /* @__PURE__ */ new Map();
+  __init3() {this.keyCache = /* @__PURE__ */ new Map()}
   /** Key ID 鈫?cooldown state */
-  cooldowns = /* @__PURE__ */ new Map();
+  __init4() {this.cooldowns = /* @__PURE__ */ new Map()}
   /** Cleanup interval handle */
-  cleanupTimer = null;
+  __init5() {this.cleanupTimer = null}
   // Cooldown configuration
-  DEFAULT_COOLDOWN_MS = 6e4;
+  __init6() {this.DEFAULT_COOLDOWN_MS = 6e4}
   // 60 seconds
-  MAX_COOLDOWN_MS = 15 * 6e4;
+  __init7() {this.MAX_COOLDOWN_MS = 15 * 6e4}
   // 15 minutes
-  COOLDOWN_MULTIPLIER = 2;
+  __init8() {this.COOLDOWN_MULTIPLIER = 2}
   /**
    * Get the API key for a session. Implements session affinity.
    *
@@ -202,7 +178,7 @@ var ApiKeyPoolService = class {
         health[key.id] = {
           until: cd.until,
           errors: cd.errors,
-          lastStatus: cd.lastStatus ?? null
+          lastStatus: _nullishCoalesce(cd.lastStatus, () => ( null))
         };
       }
     }
@@ -252,7 +228,7 @@ var ApiKeyPoolService = class {
    */
   applyCooldown(keyId, providerId, statusCode) {
     const current = this.cooldowns.get(keyId);
-    const errors = (current?.errors ?? 0) + 1;
+    const errors = (_nullishCoalesce(_optionalChain([current, 'optionalAccess', _ => _.errors]), () => ( 0))) + 1;
     const cooldownMs = Math.min(
       this.DEFAULT_COOLDOWN_MS * Math.pow(this.COOLDOWN_MULTIPLIER, errors - 1),
       this.MAX_COOLDOWN_MS
@@ -302,7 +278,7 @@ var ApiKeyPoolService = class {
   selectWeightedRoundRobin(providerId, keys) {
     if (keys.length === 1) return keys[0];
     const totalWeight = keys.reduce((sum, k) => sum + k.weight, 0);
-    const idx = ((this.rrIndex.get(providerId) ?? -1) + 1) % totalWeight;
+    const idx = ((_nullishCoalesce(this.rrIndex.get(providerId), () => ( -1))) + 1) % totalWeight;
     this.rrIndex.set(providerId, idx);
     let accum = 0;
     for (const key of keys) {
@@ -324,8 +300,7 @@ var ApiKeyPoolService = class {
       }
     }
   }
-};
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  ApiKeyPoolService
-});
+}, _class);
+
+
+exports.ApiKeyPoolService = ApiKeyPoolService;

package/dist/completion/ApiKeyPoolService.d.cts

@@ -1,2 +1,150 @@
-import '@omnicross/contracts/llm-config';
-export { a as ApiKeyAutoDisabler, b as ApiKeyDisabler, A as ApiKeyPoolService, c as ApiKeyResolver, d as ApiKeysLoader, K as KeyHealthEntry, e as KeyHealthMap } from '../ApiKeyPoolService-BmMkau07.cjs';
+import { ApiKeyEntry } from '@omnicross/contracts/llm-config';
+import { L as Logger } from '../logger-4GvQNzhE.cjs';
+
+/**
+ * ApiKeyPoolService - Multi-API-key load balancing with session affinity
+ *
+ * Manages a pool of API keys per provider, selecting keys via weighted
+ * round-robin and maintaining session-level key affinity to preserve
+ * prompt cache across requests within the same session.
+ */
+
+/** Live health snapshot for a single key currently in cooldown. */
+interface KeyHealthEntry {
+    /** Epoch-ms when the cooldown expires */
+    until: number;
+    /** Number of consecutive errors */
+    errors: number;
+    /** HTTP status that triggered the most recent cooldown */
+    lastStatus: number | null;
+}
+/** Provider-scoped map of keyId → live cooldown health (cooling keys only). */
+type KeyHealthMap = Record<string, KeyHealthEntry>;
+/** Function type for loading API keys from the database */
+type ApiKeysLoader = (providerId: string) => Promise<ApiKeyEntry[]>;
+/** Function type for disabling a key in the database (on auth failure) */
+type ApiKeyDisabler = (keyId: string) => Promise<boolean>;
+/**
+ * Function type for auto-disabling a key in the database on auth failure,
+ * persisting the offending status + timestamp so the client UI can surface
+ * a per-key health indicator. Preferred over {@link ApiKeyDisabler} when set.
+ */
+type ApiKeyAutoDisabler = (keyId: string, status: number, at: number) => Promise<void>;
+/** Function type for resolving environment variable references in API keys */
+type ApiKeyResolver = (rawKey: string) => string;
+declare class ApiKeyPoolService {
+    private loadKeys;
+    private resolveKey;
+    private logger;
+    private disableKey?;
+    private markAutoDisabled?;
+    /** Session 鈫?key binding (session affinity) */
+    private sessionBindings;
+    /** Provider 鈫?round-robin index */
+    private rrIndex;
+    /** Provider 鈫?cached key list */
+    private keyCache;
+    /** Key ID 鈫?cooldown state */
+    private cooldowns;
+    /** Cleanup interval handle */
+    private cleanupTimer;
+    private readonly DEFAULT_COOLDOWN_MS;
+    private readonly MAX_COOLDOWN_MS;
+    private readonly COOLDOWN_MULTIPLIER;
+    constructor(loadKeys: ApiKeysLoader, resolveKey: ApiKeyResolver, logger: Logger, disableKey?: ApiKeyDisabler | undefined, markAutoDisabled?: ApiKeyAutoDisabler | undefined);
+    /**
+     * Get the API key for a session. Implements session affinity.
+     *
+     * First call for a session binds it to a key via weighted round-robin.
+     * Subsequent calls return the same key (preserves prompt cache).
+     *
+     * @returns Resolved API key string, or empty string if no keys available
+     */
+    /**
+     * Read which key id is currently bound to the given session, if any.
+     * Returns null when the session has not yet been bound (first call hasn't
+     * happened) or when the binding is for a different provider.
+     *
+     * Used by the usage-recorder attribution path: after `getKeyForSession`
+     * completes the caller looks up the keyId so the recorded usage
+     * row can attribute spend to a specific pool key.
+     */
+    getKeyIdForSession(providerId: string, sessionId: string): string | null;
+    getKeyForSession(providerId: string, sessionId: string): Promise<string>;
+    /**
+     * Get a key without session affinity (for one-shot calls like testConnection).
+     *
+     * @returns Resolved API key string, or empty string if no keys available
+     */
+    getKey(providerId: string): Promise<string>;
+    /**
+     * Report an error for the current session's key.
+     *
+     * - 429/529 (rate limit / overload): puts key in cooldown with exponential backoff
+     * - 401/403 (auth failure): permanently disables the key in the database
+     *
+     * In both cases, re-binds the session to a different key if available.
+     *
+     * @param statusCode HTTP status code
+     * @returns New resolved API key if re-binding succeeded, null if no keys available
+     */
+    reportError(providerId: string, sessionId: string, statusCode: number): Promise<string | null>;
+    /**
+     * Report a successful request — resets cooldown counter for the session's key.
+     */
+    reportSuccess(sessionId: string): void;
+    /**
+     * Release session binding (call when session ends or is deleted).
+     */
+    releaseSession(sessionId: string): void;
+    /**
+     * Invalidate the key cache. Call after CRUD operations on API keys.
+     */
+    invalidateCache(providerId?: string): void;
+    /**
+     * Check if a provider has any keys in the pool.
+     */
+    hasKeys(providerId: string): Promise<boolean>;
+    /**
+     * Get the live (in-memory) rate-limit cooldown health for a provider's keys.
+     *
+     * Returns ONLY keys that are currently cooling down (cooldown `until` is in
+     * the future). A key absent from the returned map is not cooling. This is a
+     * pure read of the in-memory cooldown map — auth-failure auto-disable state
+     * is persisted on the key row itself (getApiKeys) and is NOT included here.
+     */
+    getKeyHealth(providerId: string): Promise<KeyHealthMap>;
+    /**
+     * Dispose of the service (stop cleanup timer).
+     */
+    dispose(): void;
+    /**
+     * Handle auth failure (401/403): disable the key in DB permanently.
+     */
+    private handleAuthFailure;
+    /**
+     * Apply cooldown with exponential backoff for rate-limit errors (429/529).
+     */
+    private applyCooldown;
+    /**
+     * Get all keys for a provider (with caching).
+     */
+    private getAllKeys;
+    /**
+     * Get available keys: enabled AND not in cooldown.
+     */
+    private getAvailableKeys;
+    /**
+     * Weighted round-robin selection.
+     *
+     * Each key's weight determines how many "slots" it occupies in the rotation.
+     * The round-robin index advances by 1 on each call per provider.
+     */
+    private selectWeightedRoundRobin;
+    /**
+     * Clean up expired cooldowns.
+     */
+    private cleanupExpiredCooldowns;
+}
+
+export { type ApiKeyAutoDisabler, type ApiKeyDisabler, ApiKeyPoolService, type ApiKeyResolver, type ApiKeysLoader, type KeyHealthEntry, type KeyHealthMap };

package/dist/completion/ApiKeyPoolService.d.ts

@@ -1,2 +1,150 @@
-import '@omnicross/contracts/llm-config';
-export { a as ApiKeyAutoDisabler, b as ApiKeyDisabler, A as ApiKeyPoolService, c as ApiKeyResolver, d as ApiKeysLoader, K as KeyHealthEntry, e as KeyHealthMap } from '../ApiKeyPoolService-BmMkau07.js';
+import { ApiKeyEntry } from '@omnicross/contracts/llm-config';
+import { L as Logger } from '../logger-4GvQNzhE.js';
+
+/**
+ * ApiKeyPoolService - Multi-API-key load balancing with session affinity
+ *
+ * Manages a pool of API keys per provider, selecting keys via weighted
+ * round-robin and maintaining session-level key affinity to preserve
+ * prompt cache across requests within the same session.
+ */
+
+/** Live health snapshot for a single key currently in cooldown. */
+interface KeyHealthEntry {
+    /** Epoch-ms when the cooldown expires */
+    until: number;
+    /** Number of consecutive errors */
+    errors: number;
+    /** HTTP status that triggered the most recent cooldown */
+    lastStatus: number | null;
+}
+/** Provider-scoped map of keyId → live cooldown health (cooling keys only). */
+type KeyHealthMap = Record<string, KeyHealthEntry>;
+/** Function type for loading API keys from the database */
+type ApiKeysLoader = (providerId: string) => Promise<ApiKeyEntry[]>;
+/** Function type for disabling a key in the database (on auth failure) */
+type ApiKeyDisabler = (keyId: string) => Promise<boolean>;
+/**
+ * Function type for auto-disabling a key in the database on auth failure,
+ * persisting the offending status + timestamp so the client UI can surface
+ * a per-key health indicator. Preferred over {@link ApiKeyDisabler} when set.
+ */
+type ApiKeyAutoDisabler = (keyId: string, status: number, at: number) => Promise<void>;
+/** Function type for resolving environment variable references in API keys */
+type ApiKeyResolver = (rawKey: string) => string;
+declare class ApiKeyPoolService {
+    private loadKeys;
+    private resolveKey;
+    private logger;
+    private disableKey?;
+    private markAutoDisabled?;
+    /** Session 鈫?key binding (session affinity) */
+    private sessionBindings;
+    /** Provider 鈫?round-robin index */
+    private rrIndex;
+    /** Provider 鈫?cached key list */
+    private keyCache;
+    /** Key ID 鈫?cooldown state */
+    private cooldowns;
+    /** Cleanup interval handle */
+    private cleanupTimer;
+    private readonly DEFAULT_COOLDOWN_MS;
+    private readonly MAX_COOLDOWN_MS;
+    private readonly COOLDOWN_MULTIPLIER;
+    constructor(loadKeys: ApiKeysLoader, resolveKey: ApiKeyResolver, logger: Logger, disableKey?: ApiKeyDisabler | undefined, markAutoDisabled?: ApiKeyAutoDisabler | undefined);
+    /**
+     * Get the API key for a session. Implements session affinity.
+     *
+     * First call for a session binds it to a key via weighted round-robin.
+     * Subsequent calls return the same key (preserves prompt cache).
+     *
+     * @returns Resolved API key string, or empty string if no keys available
+     */
+    /**
+     * Read which key id is currently bound to the given session, if any.
+     * Returns null when the session has not yet been bound (first call hasn't
+     * happened) or when the binding is for a different provider.
+     *
+     * Used by the usage-recorder attribution path: after `getKeyForSession`
+     * completes the caller looks up the keyId so the recorded usage
+     * row can attribute spend to a specific pool key.
+     */
+    getKeyIdForSession(providerId: string, sessionId: string): string | null;
+    getKeyForSession(providerId: string, sessionId: string): Promise<string>;
+    /**
+     * Get a key without session affinity (for one-shot calls like testConnection).
+     *
+     * @returns Resolved API key string, or empty string if no keys available
+     */
+    getKey(providerId: string): Promise<string>;
+    /**
+     * Report an error for the current session's key.
+     *
+     * - 429/529 (rate limit / overload): puts key in cooldown with exponential backoff
+     * - 401/403 (auth failure): permanently disables the key in the database
+     *
+     * In both cases, re-binds the session to a different key if available.
+     *
+     * @param statusCode HTTP status code
+     * @returns New resolved API key if re-binding succeeded, null if no keys available
+     */
+    reportError(providerId: string, sessionId: string, statusCode: number): Promise<string | null>;
+    /**
+     * Report a successful request — resets cooldown counter for the session's key.
+     */
+    reportSuccess(sessionId: string): void;
+    /**
+     * Release session binding (call when session ends or is deleted).
+     */
+    releaseSession(sessionId: string): void;
+    /**
+     * Invalidate the key cache. Call after CRUD operations on API keys.
+     */
+    invalidateCache(providerId?: string): void;
+    /**
+     * Check if a provider has any keys in the pool.
+     */
+    hasKeys(providerId: string): Promise<boolean>;
+    /**
+     * Get the live (in-memory) rate-limit cooldown health for a provider's keys.
+     *
+     * Returns ONLY keys that are currently cooling down (cooldown `until` is in
+     * the future). A key absent from the returned map is not cooling. This is a
+     * pure read of the in-memory cooldown map — auth-failure auto-disable state
+     * is persisted on the key row itself (getApiKeys) and is NOT included here.
+     */
+    getKeyHealth(providerId: string): Promise<KeyHealthMap>;
+    /**
+     * Dispose of the service (stop cleanup timer).
+     */
+    dispose(): void;
+    /**
+     * Handle auth failure (401/403): disable the key in DB permanently.
+     */
+    private handleAuthFailure;
+    /**
+     * Apply cooldown with exponential backoff for rate-limit errors (429/529).
+     */
+    private applyCooldown;
+    /**
+     * Get all keys for a provider (with caching).
+     */
+    private getAllKeys;
+    /**
+     * Get available keys: enabled AND not in cooldown.
+     */
+    private getAvailableKeys;
+    /**
+     * Weighted round-robin selection.
+     *
+     * Each key's weight determines how many "slots" it occupies in the rotation.
+     * The round-robin index advances by 1 on each call per provider.
+     */
+    private selectWeightedRoundRobin;
+    /**
+     * Clean up expired cooldowns.
+     */
+    private cleanupExpiredCooldowns;
+}
+
+export { type ApiKeyAutoDisabler, type ApiKeyDisabler, ApiKeyPoolService, type ApiKeyResolver, type ApiKeysLoader, type KeyHealthEntry, type KeyHealthMap };