@omnicross/core 0.1.1 → 0.1.3

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 };

package/dist/completion/BuiltinToolExecutor.cjs

@@ -1,327 +1,12 @@
-"use strict";
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res) => function __init() {
-  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-};
-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 __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
-  // If the importer is in node compatibility mode or this is not an ESM
-  // file that has been converted to a CommonJS file using a Babel-
-  // compatible transform (i.e. "__esModule" has not been set), then set
-  // "default" to the CommonJS "module.exports" for node compatibility.
-  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
-  mod
-));
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});
 
-// src/completion/builtin-web-fetch.ts
-var builtin_web_fetch_exports = {};
-__export(builtin_web_fetch_exports, {
-  fetchAndExtractUrl: () => fetchAndExtractUrl
-});
-async function fetchAndExtractUrl(url, maxChars) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
-  try {
-    const res = await fetchWithRedirectLimit(url, controller.signal);
-    clearTimeout(timer);
-    const contentType = res.headers.get("content-type") ?? "";
-    const rawText = await readBodyWithLimit(res);
-    let text;
-    if (contentType.includes("json")) {
-      try {
-        text = JSON.stringify(JSON.parse(rawText), null, 2);
-      } catch {
-        text = rawText;
-      }
-    } else if (contentType.includes("html")) {
-      text = extractHtml(rawText, res.url || url);
-    } else {
-      text = rawText;
-    }
-    return text.length > maxChars ? text.slice(0, maxChars) + "\n\n[Content truncated]" : text;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-function extractHtml(html, url) {
-  const dom = new import_jsdom.JSDOM(html, { url });
-  const doc = dom.window.document;
-  for (const sel of ["script", "style", "noscript", "nav", "footer", "aside", "iframe"]) {
-    doc.querySelectorAll(sel).forEach((el) => el.remove());
-  }
-  const reader = new import_readability.Readability(doc);
-  const article = reader.parse();
-  if (article?.content) {
-    return turndown.turndown(article.content).replace(/\n{3,}/g, "\n\n");
-  }
-  const body = doc.body?.textContent || "";
-  return body.replace(/\s+/g, " ").trim();
-}
-async function fetchWithRedirectLimit(url, signal) {
-  let currentUrl = url;
-  for (let i = 0; i < MAX_REDIRECTS; i++) {
-    const res = await fetch(currentUrl, { signal, redirect: "manual", headers: FETCH_HEADERS });
-    if (res.status >= 300 && res.status < 400) {
-      const location = res.headers.get("location");
-      if (!location) return res;
-      currentUrl = new URL(location, currentUrl).href;
-      continue;
-    }
-    Object.defineProperty(res, "url", { value: currentUrl, writable: false });
-    return res;
-  }
-  throw new Error(`Too many redirects (>${MAX_REDIRECTS})`);
-}
-async function readBodyWithLimit(res) {
-  const reader = res.body?.getReader();
-  if (!reader) return "";
-  const chunks = [];
-  let totalBytes = 0;
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    totalBytes += value.byteLength;
-    if (totalBytes > MAX_RESPONSE_BYTES) {
-      reader.cancel();
-      break;
-    }
-    chunks.push(value);
-  }
-  const combined = new Uint8Array(totalBytes > MAX_RESPONSE_BYTES ? MAX_RESPONSE_BYTES : totalBytes);
-  let offset = 0;
-  for (const chunk of chunks) {
-    const len = Math.min(chunk.byteLength, combined.byteLength - offset);
-    combined.set(chunk.subarray(0, len), offset);
-    offset += len;
-    if (offset >= combined.byteLength) break;
-  }
-  return new TextDecoder("utf-8", { fatal: false }).decode(combined);
-}
-var import_readability, import_jsdom, import_turndown, FETCH_TIMEOUT_MS, MAX_RESPONSE_BYTES, MAX_REDIRECTS, CHROME_UA, FETCH_HEADERS, turndown;
-var init_builtin_web_fetch = __esm({
-  "src/completion/builtin-web-fetch.ts"() {
-    "use strict";
-    import_readability = require("@mozilla/readability");
-    import_jsdom = require("jsdom");
-    import_turndown = __toESM(require("turndown"), 1);
-    FETCH_TIMEOUT_MS = 15e3;
-    MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
-    MAX_REDIRECTS = 5;
-    CHROME_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
-    FETCH_HEADERS = {
-      "User-Agent": CHROME_UA,
-      Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
-      "Accept-Language": "en-US,en;q=0.9"
-    };
-    turndown = new import_turndown.default({
-      headingStyle: "atx",
-      codeBlockStyle: "fenced",
-      bulletListMarker: "-"
-    });
-  }
-});
 
-// src/completion/BuiltinToolExecutor.ts
-var BuiltinToolExecutor_exports = {};
-__export(BuiltinToolExecutor_exports, {
-  BuiltinToolExecutor: () => BuiltinToolExecutor,
-  convertBuiltinToolsToAnthropic: () => convertBuiltinToolsToAnthropic,
-  convertBuiltinToolsToOpenAI: () => convertBuiltinToolsToOpenAI,
-  getBuiltinSearchTools: () => getBuiltinSearchTools
-});
-module.exports = __toCommonJS(BuiltinToolExecutor_exports);
-var DEFAULT_SEARCH_COUNT = 5;
-var DEFAULT_FETCH_MAX_CHARS = 2e4;
-var FALLBACK_ORDER = [
-  "tavily",
-  "jina",
-  "searxng",
-  "zhipu",
-  "z.ai",
-  "bocha",
-  "grok",
-  "local-google",
-  "local-bing",
-  "local-baidu",
-  "local-duckduckgo"
-];
-var IMPLICIT_LOCAL_FALLBACK = "local-google";
-var WEB_SEARCH_TOOL = {
-  id: "builtin__web_search",
-  serverId: "builtin",
-  serverName: "builtin",
-  name: "web_search",
-  description: "Search the web for current information. Returns a list of results with title, URL, and snippet. Use web_fetch afterwards to get full page content if snippets are insufficient.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      query: { type: "string", description: "The search query." },
-      count: { type: "integer", description: "Maximum number of results (1-10).", default: DEFAULT_SEARCH_COUNT }
-    },
-    required: ["query"]
-  },
-  type: "mcp",
-  isBuiltIn: true
-};
-var WEB_FETCH_TOOL = {
-  id: "builtin__web_fetch",
-  serverId: "builtin",
-  serverName: "builtin",
-  name: "web_fetch",
-  description: "Fetch and extract the main content of a web page as clean Markdown. Use this to read the full content of a URL found via web_search.",
-  inputSchema: {
-    type: "object",
-    properties: {
-      url: { type: "string", description: "The URL to fetch (http or https)." },
-      maxChars: { type: "integer", description: "Maximum characters to return.", default: DEFAULT_FETCH_MAX_CHARS }
-    },
-    required: ["url"]
-  },
-  type: "mcp",
-  isBuiltIn: true
-};
-var BuiltinToolExecutor = class {
-  constructor(webSearch) {
-    this.webSearch = webSearch;
-  }
-  webSearch;
-  async execute(toolName, args) {
-    switch (toolName) {
-      case "web_search":
-        return this.executeWebSearch(args);
-      case "web_fetch":
-        return this.executeWebFetch(args);
-      default:
-        return { isError: true, content: [{ type: "text", text: `Unknown built-in tool: ${toolName}` }] };
-    }
-  }
-  // -----------------------------------------------------------------------
-  // web_search
-  // -----------------------------------------------------------------------
-  async executeWebSearch(args) {
-    const query = String(args.query ?? "").trim();
-    if (!query) {
-      return { isError: true, content: [{ type: "text", text: "Error: query parameter is required." }] };
-    }
-    const count = Math.min(Math.max(Number(args.count ?? DEFAULT_SEARCH_COUNT), 1), 10);
-    const chain = this.resolveProviderChain();
-    let lastError = "";
-    for (const providerId of chain) {
-      try {
-        const result = await this.webSearch.search(query, providerId, { maxResults: count });
-        if (!result.success) {
-          lastError = result.error || "Unknown error";
-          console.log(`[BuiltinToolExecutor] Search provider ${providerId} failed: ${lastError}, trying next...`);
-          continue;
-        }
-        const items = result.results.slice(0, count);
-        if (items.length === 0) {
-          console.log(`[BuiltinToolExecutor] Search provider ${providerId} returned 0 results, trying next...`);
-          continue;
-        }
-        const text = items.map((r, i) => `${i + 1}. ${r.title}
-   URL: ${r.url}
-   ${r.content || ""}`).join("\n\n");
-        return { isError: false, content: [{ type: "text", text }] };
-      } catch (err) {
-        lastError = err instanceof Error ? err.message : String(err);
-        console.log(`[BuiltinToolExecutor] Search provider ${providerId} threw: ${lastError}, trying next...`);
-        continue;
-      }
-    }
-    return {
-      isError: false,
-      content: [{ type: "text", text: lastError ? `Search failed after trying ${chain.length} provider(s). Last error: ${lastError}` : `No results found for "${query}" after trying ${chain.length} provider(s). Try rephrasing your search.` }]
-    };
-  }
-  resolveProviderChain() {
-    const chain = [];
-    for (const id of FALLBACK_ORDER) {
-      if (this.webSearch.isProviderEnabled(id)) {
-        chain.push(id);
-      }
-    }
-    if (!chain.includes(IMPLICIT_LOCAL_FALLBACK)) {
-      chain.push(IMPLICIT_LOCAL_FALLBACK);
-    }
-    return chain;
-  }
-  // -----------------------------------------------------------------------
-  // web_fetch
-  // -----------------------------------------------------------------------
-  async executeWebFetch(args) {
-    const url = String(args.url ?? "").trim();
-    if (!url) {
-      return { isError: true, content: [{ type: "text", text: "Error: url parameter is required." }] };
-    }
-    try {
-      const parsed = new URL(url);
-      if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        return { isError: true, content: [{ type: "text", text: "Error: only http and https URLs are supported." }] };
-      }
-    } catch {
-      return { isError: true, content: [{ type: "text", text: `Error: invalid URL "${url}".` }] };
-    }
-    const maxChars = Number(args.maxChars ?? DEFAULT_FETCH_MAX_CHARS);
-    try {
-      const jinaResult = await this.webSearch.readUrl(url, { timeout: 15e3 });
-      if (jinaResult.success && jinaResult.content) {
-        const content = jinaResult.content.length > maxChars ? jinaResult.content.slice(0, maxChars) + "\n\n[Content truncated]" : jinaResult.content;
-        const header = jinaResult.title ? `# ${jinaResult.title}
 
-` : "";
-        return { isError: false, content: [{ type: "text", text: header + content }] };
-      }
-      const { fetchAndExtractUrl: fetchAndExtractUrl2 } = await Promise.resolve().then(() => (init_builtin_web_fetch(), builtin_web_fetch_exports));
-      const text = await fetchAndExtractUrl2(url, maxChars);
-      return { isError: false, content: [{ type: "text", text }] };
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      return { isError: true, content: [{ type: "text", text: `Fetch error: ${message}` }] };
-    }
-  }
-};
-function getBuiltinSearchTools() {
-  return [WEB_SEARCH_TOOL, WEB_FETCH_TOOL];
-}
-function convertBuiltinToolsToOpenAI(tools) {
-  return tools.map((t) => ({
-    type: "function",
-    function: {
-      name: t.id,
-      description: t.description || t.name,
-      parameters: t.inputSchema
-    }
-  }));
-}
-function convertBuiltinToolsToAnthropic(tools) {
-  return tools.map((t) => ({
-    name: t.id,
-    description: t.description || t.name,
-    input_schema: t.inputSchema
-  }));
-}
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  BuiltinToolExecutor,
-  convertBuiltinToolsToAnthropic,
-  convertBuiltinToolsToOpenAI,
-  getBuiltinSearchTools
-});
+
+var _chunkNZYN7C3Pcjs = require('../chunk-NZYN7C3P.cjs');
+
+
+
+
+
+exports.BuiltinToolExecutor = _chunkNZYN7C3Pcjs.BuiltinToolExecutor; exports.convertBuiltinToolsToAnthropic = _chunkNZYN7C3Pcjs.convertBuiltinToolsToAnthropic; exports.convertBuiltinToolsToOpenAI = _chunkNZYN7C3Pcjs.convertBuiltinToolsToOpenAI; exports.getBuiltinSearchTools = _chunkNZYN7C3Pcjs.getBuiltinSearchTools;