@omnicross/core 0.1.0

package/dist/completion/ApiKeyPoolService.cjs

@@ -0,0 +1,331 @@
+"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);
+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) {
+    this.loadKeys = loadKeys;
+    this.resolveKey = resolveKey;
+    this.logger = logger;
+    this.disableKey = disableKey;
+    this.markAutoDisabled = markAutoDisabled;
+    this.cleanupTimer = setInterval(() => this.cleanupExpiredCooldowns(), 3e4);
+  }
+  loadKeys;
+  resolveKey;
+  logger;
+  disableKey;
+  markAutoDisabled;
+  /** Session 鈫?key binding (session affinity) */
+  sessionBindings = /* @__PURE__ */ new Map();
+  /** Provider 鈫?round-robin index */
+  rrIndex = /* @__PURE__ */ new Map();
+  /** Provider 鈫?cached key list */
+  keyCache = /* @__PURE__ */ new Map();
+  /** Key ID 鈫?cooldown state */
+  cooldowns = /* @__PURE__ */ new Map();
+  /** Cleanup interval handle */
+  cleanupTimer = null;
+  // Cooldown configuration
+  DEFAULT_COOLDOWN_MS = 6e4;
+  // 60 seconds
+  MAX_COOLDOWN_MS = 15 * 6e4;
+  // 15 minutes
+  COOLDOWN_MULTIPLIER = 2;
+  /**
+   * 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, sessionId) {
+    const binding = this.sessionBindings.get(sessionId);
+    if (!binding) return null;
+    if (binding.providerId !== providerId) return null;
+    return binding.keyId;
+  }
+  async getKeyForSession(providerId, sessionId) {
+    const binding = this.sessionBindings.get(sessionId);
+    if (binding && binding.providerId === providerId) {
+      const keys2 = await this.getAvailableKeys(providerId);
+      const boundKey = keys2.find((k) => k.id === binding.keyId);
+      if (boundKey) {
+        return this.resolveKey(boundKey.apiKey);
+      }
+      this.logger.info("Session key no longer available, re-binding", {
+        sessionId,
+        keyId: binding.keyId,
+        providerId
+      });
+    }
+    const keys = await this.getAvailableKeys(providerId);
+    if (keys.length === 0) return "";
+    const selected = this.selectWeightedRoundRobin(providerId, keys);
+    this.sessionBindings.set(sessionId, { keyId: selected.id, providerId });
+    this.logger.debug("Session bound to API key", {
+      sessionId,
+      keyId: selected.id,
+      label: selected.label,
+      providerId
+    });
+    return this.resolveKey(selected.apiKey);
+  }
+  /**
+   * Get a key without session affinity (for one-shot calls like testConnection).
+   *
+   * @returns Resolved API key string, or empty string if no keys available
+   */
+  async getKey(providerId) {
+    const keys = await this.getAvailableKeys(providerId);
+    if (keys.length === 0) return "";
+    const selected = this.selectWeightedRoundRobin(providerId, keys);
+    return this.resolveKey(selected.apiKey);
+  }
+  /**
+   * 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
+   */
+  async reportError(providerId, sessionId, statusCode) {
+    const isRateLimit = RATE_LIMIT_CODES.has(statusCode);
+    const isAuthFailure = AUTH_FAILURE_CODES.has(statusCode);
+    if (!isRateLimit && !isAuthFailure) return null;
+    const binding = this.sessionBindings.get(sessionId);
+    if (!binding) return null;
+    if (isAuthFailure) {
+      await this.handleAuthFailure(binding.keyId, providerId, statusCode);
+    } else {
+      this.applyCooldown(binding.keyId, providerId, statusCode);
+    }
+    const keys = await this.getAvailableKeys(providerId);
+    if (keys.length === 0) {
+      this.logger.warn("No available API keys after error", { providerId, statusCode });
+      return null;
+    }
+    const newKey = this.selectWeightedRoundRobin(providerId, keys);
+    this.sessionBindings.set(sessionId, { keyId: newKey.id, providerId });
+    this.logger.info("Session re-bound to new API key", {
+      sessionId,
+      newKeyId: newKey.id,
+      label: newKey.label
+    });
+    return this.resolveKey(newKey.apiKey);
+  }
+  /**
+   * Report a successful request — resets cooldown counter for the session's key.
+   */
+  reportSuccess(sessionId) {
+    const binding = this.sessionBindings.get(sessionId);
+    if (!binding) return;
+    if (this.cooldowns.has(binding.keyId)) {
+      this.cooldowns.delete(binding.keyId);
+    }
+  }
+  /**
+   * Release session binding (call when session ends or is deleted).
+   */
+  releaseSession(sessionId) {
+    this.sessionBindings.delete(sessionId);
+  }
+  /**
+   * Invalidate the key cache. Call after CRUD operations on API keys.
+   */
+  invalidateCache(providerId) {
+    if (providerId) {
+      this.keyCache.delete(providerId);
+    } else {
+      this.keyCache.clear();
+    }
+  }
+  /**
+   * Check if a provider has any keys in the pool.
+   */
+  async hasKeys(providerId) {
+    const keys = await this.getAllKeys(providerId);
+    return keys.length > 0;
+  }
+  /**
+   * 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.
+   */
+  async getKeyHealth(providerId) {
+    const keys = await this.getAllKeys(providerId);
+    const now = Date.now();
+    const health = {};
+    for (const key of keys) {
+      const cd = this.cooldowns.get(key.id);
+      if (cd && cd.until > now) {
+        health[key.id] = {
+          until: cd.until,
+          errors: cd.errors,
+          lastStatus: cd.lastStatus ?? null
+        };
+      }
+    }
+    return health;
+  }
+  /**
+   * Dispose of the service (stop cleanup timer).
+   */
+  dispose() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.sessionBindings.clear();
+    this.keyCache.clear();
+    this.cooldowns.clear();
+  }
+  // ==========================================================================
+  // Private methods
+  // ==========================================================================
+  /**
+   * Handle auth failure (401/403): disable the key in DB permanently.
+   */
+  async handleAuthFailure(keyId, providerId, statusCode) {
+    this.logger.warn("API key auth failure \u2014 disabling permanently", {
+      keyId,
+      providerId,
+      statusCode
+    });
+    if (this.markAutoDisabled) {
+      try {
+        await this.markAutoDisabled(keyId, statusCode, Date.now());
+      } catch (err) {
+        this.logger.error("Failed to auto-disable API key in database", err instanceof Error ? err : void 0, { keyId });
+      }
+    } else if (this.disableKey) {
+      try {
+        await this.disableKey(keyId);
+      } catch (err) {
+        this.logger.error("Failed to disable API key in database", err instanceof Error ? err : void 0, { keyId });
+      }
+    }
+    this.keyCache.delete(providerId);
+  }
+  /**
+   * Apply cooldown with exponential backoff for rate-limit errors (429/529).
+   */
+  applyCooldown(keyId, providerId, statusCode) {
+    const current = this.cooldowns.get(keyId);
+    const errors = (current?.errors ?? 0) + 1;
+    const cooldownMs = Math.min(
+      this.DEFAULT_COOLDOWN_MS * Math.pow(this.COOLDOWN_MULTIPLIER, errors - 1),
+      this.MAX_COOLDOWN_MS
+    );
+    this.cooldowns.set(keyId, {
+      until: Date.now() + cooldownMs,
+      errors,
+      lastStatus: statusCode
+    });
+    this.logger.info("API key put in cooldown", {
+      keyId,
+      providerId,
+      statusCode,
+      cooldownMs,
+      errors
+    });
+  }
+  /**
+   * Get all keys for a provider (with caching).
+   */
+  async getAllKeys(providerId) {
+    if (!this.keyCache.has(providerId)) {
+      const keys = await this.loadKeys(providerId);
+      this.keyCache.set(providerId, keys);
+    }
+    return this.keyCache.get(providerId);
+  }
+  /**
+   * Get available keys: enabled AND not in cooldown.
+   */
+  async getAvailableKeys(providerId) {
+    const all = await this.getAllKeys(providerId);
+    const now = Date.now();
+    return all.filter((k) => {
+      if (!k.enabled) return false;
+      const cd = this.cooldowns.get(k.id);
+      if (cd && cd.until > now) return false;
+      return true;
+    });
+  }
+  /**
+   * 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.
+   */
+  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;
+    this.rrIndex.set(providerId, idx);
+    let accum = 0;
+    for (const key of keys) {
+      accum += key.weight;
+      if (idx < accum) {
+        return key;
+      }
+    }
+    return keys[0];
+  }
+  /**
+   * Clean up expired cooldowns.
+   */
+  cleanupExpiredCooldowns() {
+    const now = Date.now();
+    for (const [keyId, cd] of this.cooldowns) {
+      if (cd.until <= now) {
+        this.cooldowns.delete(keyId);
+      }
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApiKeyPoolService
+});

package/dist/completion/ApiKeyPoolService.d.cts

@@ -0,0 +1,2 @@
+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';

package/dist/completion/ApiKeyPoolService.d.ts

@@ -0,0 +1,2 @@
+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';

package/dist/completion/ApiKeyPoolService.js

@@ -0,0 +1,306 @@
+// 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) {
+    this.loadKeys = loadKeys;
+    this.resolveKey = resolveKey;
+    this.logger = logger;
+    this.disableKey = disableKey;
+    this.markAutoDisabled = markAutoDisabled;
+    this.cleanupTimer = setInterval(() => this.cleanupExpiredCooldowns(), 3e4);
+  }
+  loadKeys;
+  resolveKey;
+  logger;
+  disableKey;
+  markAutoDisabled;
+  /** Session 鈫?key binding (session affinity) */
+  sessionBindings = /* @__PURE__ */ new Map();
+  /** Provider 鈫?round-robin index */
+  rrIndex = /* @__PURE__ */ new Map();
+  /** Provider 鈫?cached key list */
+  keyCache = /* @__PURE__ */ new Map();
+  /** Key ID 鈫?cooldown state */
+  cooldowns = /* @__PURE__ */ new Map();
+  /** Cleanup interval handle */
+  cleanupTimer = null;
+  // Cooldown configuration
+  DEFAULT_COOLDOWN_MS = 6e4;
+  // 60 seconds
+  MAX_COOLDOWN_MS = 15 * 6e4;
+  // 15 minutes
+  COOLDOWN_MULTIPLIER = 2;
+  /**
+   * 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, sessionId) {
+    const binding = this.sessionBindings.get(sessionId);
+    if (!binding) return null;
+    if (binding.providerId !== providerId) return null;
+    return binding.keyId;
+  }
+  async getKeyForSession(providerId, sessionId) {
+    const binding = this.sessionBindings.get(sessionId);
+    if (binding && binding.providerId === providerId) {
+      const keys2 = await this.getAvailableKeys(providerId);
+      const boundKey = keys2.find((k) => k.id === binding.keyId);
+      if (boundKey) {
+        return this.resolveKey(boundKey.apiKey);
+      }
+      this.logger.info("Session key no longer available, re-binding", {
+        sessionId,
+        keyId: binding.keyId,
+        providerId
+      });
+    }
+    const keys = await this.getAvailableKeys(providerId);
+    if (keys.length === 0) return "";
+    const selected = this.selectWeightedRoundRobin(providerId, keys);
+    this.sessionBindings.set(sessionId, { keyId: selected.id, providerId });
+    this.logger.debug("Session bound to API key", {
+      sessionId,
+      keyId: selected.id,
+      label: selected.label,
+      providerId
+    });
+    return this.resolveKey(selected.apiKey);
+  }
+  /**
+   * Get a key without session affinity (for one-shot calls like testConnection).
+   *
+   * @returns Resolved API key string, or empty string if no keys available
+   */
+  async getKey(providerId) {
+    const keys = await this.getAvailableKeys(providerId);
+    if (keys.length === 0) return "";
+    const selected = this.selectWeightedRoundRobin(providerId, keys);
+    return this.resolveKey(selected.apiKey);
+  }
+  /**
+   * 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
+   */
+  async reportError(providerId, sessionId, statusCode) {
+    const isRateLimit = RATE_LIMIT_CODES.has(statusCode);
+    const isAuthFailure = AUTH_FAILURE_CODES.has(statusCode);
+    if (!isRateLimit && !isAuthFailure) return null;
+    const binding = this.sessionBindings.get(sessionId);
+    if (!binding) return null;
+    if (isAuthFailure) {
+      await this.handleAuthFailure(binding.keyId, providerId, statusCode);
+    } else {
+      this.applyCooldown(binding.keyId, providerId, statusCode);
+    }
+    const keys = await this.getAvailableKeys(providerId);
+    if (keys.length === 0) {
+      this.logger.warn("No available API keys after error", { providerId, statusCode });
+      return null;
+    }
+    const newKey = this.selectWeightedRoundRobin(providerId, keys);
+    this.sessionBindings.set(sessionId, { keyId: newKey.id, providerId });
+    this.logger.info("Session re-bound to new API key", {
+      sessionId,
+      newKeyId: newKey.id,
+      label: newKey.label
+    });
+    return this.resolveKey(newKey.apiKey);
+  }
+  /**
+   * Report a successful request — resets cooldown counter for the session's key.
+   */
+  reportSuccess(sessionId) {
+    const binding = this.sessionBindings.get(sessionId);
+    if (!binding) return;
+    if (this.cooldowns.has(binding.keyId)) {
+      this.cooldowns.delete(binding.keyId);
+    }
+  }
+  /**
+   * Release session binding (call when session ends or is deleted).
+   */
+  releaseSession(sessionId) {
+    this.sessionBindings.delete(sessionId);
+  }
+  /**
+   * Invalidate the key cache. Call after CRUD operations on API keys.
+   */
+  invalidateCache(providerId) {
+    if (providerId) {
+      this.keyCache.delete(providerId);
+    } else {
+      this.keyCache.clear();
+    }
+  }
+  /**
+   * Check if a provider has any keys in the pool.
+   */
+  async hasKeys(providerId) {
+    const keys = await this.getAllKeys(providerId);
+    return keys.length > 0;
+  }
+  /**
+   * 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.
+   */
+  async getKeyHealth(providerId) {
+    const keys = await this.getAllKeys(providerId);
+    const now = Date.now();
+    const health = {};
+    for (const key of keys) {
+      const cd = this.cooldowns.get(key.id);
+      if (cd && cd.until > now) {
+        health[key.id] = {
+          until: cd.until,
+          errors: cd.errors,
+          lastStatus: cd.lastStatus ?? null
+        };
+      }
+    }
+    return health;
+  }
+  /**
+   * Dispose of the service (stop cleanup timer).
+   */
+  dispose() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = null;
+    }
+    this.sessionBindings.clear();
+    this.keyCache.clear();
+    this.cooldowns.clear();
+  }
+  // ==========================================================================
+  // Private methods
+  // ==========================================================================
+  /**
+   * Handle auth failure (401/403): disable the key in DB permanently.
+   */
+  async handleAuthFailure(keyId, providerId, statusCode) {
+    this.logger.warn("API key auth failure \u2014 disabling permanently", {
+      keyId,
+      providerId,
+      statusCode
+    });
+    if (this.markAutoDisabled) {
+      try {
+        await this.markAutoDisabled(keyId, statusCode, Date.now());
+      } catch (err) {
+        this.logger.error("Failed to auto-disable API key in database", err instanceof Error ? err : void 0, { keyId });
+      }
+    } else if (this.disableKey) {
+      try {
+        await this.disableKey(keyId);
+      } catch (err) {
+        this.logger.error("Failed to disable API key in database", err instanceof Error ? err : void 0, { keyId });
+      }
+    }
+    this.keyCache.delete(providerId);
+  }
+  /**
+   * Apply cooldown with exponential backoff for rate-limit errors (429/529).
+   */
+  applyCooldown(keyId, providerId, statusCode) {
+    const current = this.cooldowns.get(keyId);
+    const errors = (current?.errors ?? 0) + 1;
+    const cooldownMs = Math.min(
+      this.DEFAULT_COOLDOWN_MS * Math.pow(this.COOLDOWN_MULTIPLIER, errors - 1),
+      this.MAX_COOLDOWN_MS
+    );
+    this.cooldowns.set(keyId, {
+      until: Date.now() + cooldownMs,
+      errors,
+      lastStatus: statusCode
+    });
+    this.logger.info("API key put in cooldown", {
+      keyId,
+      providerId,
+      statusCode,
+      cooldownMs,
+      errors
+    });
+  }
+  /**
+   * Get all keys for a provider (with caching).
+   */
+  async getAllKeys(providerId) {
+    if (!this.keyCache.has(providerId)) {
+      const keys = await this.loadKeys(providerId);
+      this.keyCache.set(providerId, keys);
+    }
+    return this.keyCache.get(providerId);
+  }
+  /**
+   * Get available keys: enabled AND not in cooldown.
+   */
+  async getAvailableKeys(providerId) {
+    const all = await this.getAllKeys(providerId);
+    const now = Date.now();
+    return all.filter((k) => {
+      if (!k.enabled) return false;
+      const cd = this.cooldowns.get(k.id);
+      if (cd && cd.until > now) return false;
+      return true;
+    });
+  }
+  /**
+   * 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.
+   */
+  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;
+    this.rrIndex.set(providerId, idx);
+    let accum = 0;
+    for (const key of keys) {
+      accum += key.weight;
+      if (idx < accum) {
+        return key;
+      }
+    }
+    return keys[0];
+  }
+  /**
+   * Clean up expired cooldowns.
+   */
+  cleanupExpiredCooldowns() {
+    const now = Date.now();
+    for (const [keyId, cd] of this.cooldowns) {
+      if (cd.until <= now) {
+        this.cooldowns.delete(keyId);
+      }
+    }
+  }
+};
+export {
+  ApiKeyPoolService
+};