@kb-labs/core-resource-broker 1.0.0

package/dist/index.js

@@ -0,0 +1,1418 @@
+import { randomUUID } from 'crypto';
+
+// src/types.ts
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  baseDelay: 1e3,
+  maxDelay: 3e4,
+  jitter: 0.1,
+  retryableErrors: ["rate_limit", "server_error", "timeout", "network"]
+};
+var DEFAULT_RATE_LIMIT_CONFIG = {
+  safetyMargin: 0.9
+};
+
+// src/queue/priority-queue.ts
+var PriorityQueue = class {
+  high = [];
+  normal = [];
+  low = [];
+  /**
+   * Add an item to the queue.
+   *
+   * @param item - Queue item to add
+   */
+  enqueue(item) {
+    const priority = item.request.priority;
+    switch (priority) {
+      case "high":
+        this.high.push(item);
+        break;
+      case "low":
+        this.low.push(item);
+        break;
+      default:
+        this.normal.push(item);
+    }
+  }
+  /**
+   * Remove and return the highest priority item.
+   *
+   * @returns The next item or undefined if queue is empty
+   */
+  dequeue() {
+    if (this.high.length > 0) {
+      return this.high.shift();
+    }
+    if (this.normal.length > 0) {
+      return this.normal.shift();
+    }
+    if (this.low.length > 0) {
+      return this.low.shift();
+    }
+    return void 0;
+  }
+  /**
+   * Peek at the highest priority item without removing it.
+   *
+   * @returns The next item or undefined if queue is empty
+   */
+  peek() {
+    if (this.high.length > 0) {
+      return this.high[0];
+    }
+    if (this.normal.length > 0) {
+      return this.normal[0];
+    }
+    if (this.low.length > 0) {
+      return this.low[0];
+    }
+    return void 0;
+  }
+  /**
+   * Get total queue size.
+   */
+  size() {
+    return this.high.length + this.normal.length + this.low.length;
+  }
+  /**
+   * Get queue size by priority.
+   */
+  sizeByPriority() {
+    return {
+      high: this.high.length,
+      normal: this.normal.length,
+      low: this.low.length
+    };
+  }
+  /**
+   * Check if queue is empty.
+   */
+  isEmpty() {
+    return this.size() === 0;
+  }
+  /**
+   * Clear all items from the queue.
+   *
+   * @returns All removed items (for cleanup/rejection)
+   */
+  clear() {
+    const all = [...this.high, ...this.normal, ...this.low];
+    this.high = [];
+    this.normal = [];
+    this.low = [];
+    return all;
+  }
+  /**
+   * Remove a specific item by request ID.
+   *
+   * @param requestId - ID of the request to remove
+   * @returns The removed item or undefined if not found
+   */
+  remove(requestId) {
+    const highIndex = this.high.findIndex((item) => item.request.id === requestId);
+    if (highIndex !== -1) {
+      return this.high.splice(highIndex, 1)[0];
+    }
+    const normalIndex = this.normal.findIndex((item) => item.request.id === requestId);
+    if (normalIndex !== -1) {
+      return this.normal.splice(normalIndex, 1)[0];
+    }
+    const lowIndex = this.low.findIndex((item) => item.request.id === requestId);
+    if (lowIndex !== -1) {
+      return this.low.splice(lowIndex, 1)[0];
+    }
+    return void 0;
+  }
+  /**
+   * Get all items for a specific resource.
+   *
+   * @param resource - Resource identifier
+   * @returns Items matching the resource
+   */
+  getByResource(resource) {
+    return [
+      ...this.high.filter((item) => item.request.resource === resource),
+      ...this.normal.filter((item) => item.request.resource === resource),
+      ...this.low.filter((item) => item.request.resource === resource)
+    ];
+  }
+  /**
+   * Get queue size for a specific resource.
+   *
+   * @param resource - Resource identifier
+   */
+  sizeByResource(resource) {
+    return this.high.filter((item) => item.request.resource === resource).length + this.normal.filter((item) => item.request.resource === resource).length + this.low.filter((item) => item.request.resource === resource).length;
+  }
+  /**
+   * Iterate over all items (for inspection, not removal).
+   */
+  *[Symbol.iterator]() {
+    yield* this.high;
+    yield* this.normal;
+    yield* this.low;
+  }
+};
+
+// src/rate-limit/presets.ts
+var RATE_LIMIT_PRESETS = {
+  // ═══════════════════════════════════════════════════════════════════════════
+  // OPENAI
+  // https://platform.openai.com/docs/guides/rate-limits
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * OpenAI Tier 1 (paid accounts, entry level)
+   * Updated Nov 2024: Tier 1 now has 1M TPM for embeddings
+   */
+  "openai-tier-1": {
+    tokensPerMinute: 1e6,
+    requestsPerMinute: 3e3,
+    maxTokensPerRequest: 8191,
+    safetyMargin: 0.85
+    // More conservative to avoid edge cases
+  },
+  /**
+   * OpenAI Tier 2 (after $50+ spent)
+   */
+  "openai-tier-2": {
+    tokensPerMinute: 2e6,
+    requestsPerMinute: 5e3,
+    maxTokensPerRequest: 8191,
+    safetyMargin: 0.9
+  },
+  /**
+   * OpenAI Tier 3
+   */
+  "openai-tier-3": {
+    tokensPerMinute: 5e6,
+    requestsPerMinute: 5e3,
+    maxTokensPerRequest: 8191,
+    safetyMargin: 0.9
+  },
+  /**
+   * OpenAI Tier 4
+   */
+  "openai-tier-4": {
+    tokensPerMinute: 1e7,
+    requestsPerMinute: 1e4,
+    maxTokensPerRequest: 8191,
+    safetyMargin: 0.9
+  },
+  /**
+   * OpenAI Tier 5 (enterprise)
+   */
+  "openai-tier-5": {
+    tokensPerMinute: 5e7,
+    requestsPerMinute: 1e4,
+    maxTokensPerRequest: 8191,
+    safetyMargin: 0.9
+  },
+  /**
+   * OpenAI GPT-4 specific limits (more restrictive)
+   */
+  "openai-gpt4": {
+    tokensPerMinute: 15e4,
+    requestsPerMinute: 500,
+    maxTokensPerRequest: 8192,
+    safetyMargin: 0.85
+  },
+  // ═══════════════════════════════════════════════════════════════════════════
+  // ANTHROPIC
+  // https://docs.anthropic.com/en/api/rate-limits
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Anthropic Tier 1 (default)
+   */
+  "anthropic-tier-1": {
+    tokensPerMinute: 4e4,
+    requestsPerMinute: 50,
+    maxTokensPerRequest: 4096,
+    safetyMargin: 0.85
+  },
+  /**
+   * Anthropic Tier 2
+   */
+  "anthropic-tier-2": {
+    tokensPerMinute: 8e4,
+    requestsPerMinute: 100,
+    maxTokensPerRequest: 4096,
+    safetyMargin: 0.9
+  },
+  /**
+   * Anthropic Tier 3
+   */
+  "anthropic-tier-3": {
+    tokensPerMinute: 16e4,
+    requestsPerMinute: 200,
+    maxTokensPerRequest: 4096,
+    safetyMargin: 0.9
+  },
+  /**
+   * Anthropic Tier 4
+   */
+  "anthropic-tier-4": {
+    tokensPerMinute: 4e5,
+    requestsPerMinute: 400,
+    maxTokensPerRequest: 4096,
+    safetyMargin: 0.9
+  },
+  // ═══════════════════════════════════════════════════════════════════════════
+  // RUSSIAN PROVIDERS
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Sber GigaChat API
+   * Conservative limits for typical access
+   */
+  "sber-gigachat": {
+    requestsPerMinute: 100,
+    requestsPerSecond: 5,
+    safetyMargin: 0.8
+  },
+  /**
+   * Yandex GPT API
+   */
+  "yandex-gpt": {
+    requestsPerMinute: 100,
+    requestsPerSecond: 10,
+    safetyMargin: 0.8
+  },
+  // ═══════════════════════════════════════════════════════════════════════════
+  // LOCAL MODELS
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * Local Ollama
+   * No external rate limits, only GPU concurrency
+   */
+  "ollama-local": {
+    maxConcurrentRequests: 4
+  },
+  /**
+   * Self-hosted vLLM
+   */
+  "vllm-local": {
+    maxConcurrentRequests: 8,
+    requestsPerSecond: 100
+  },
+  /**
+   * Self-hosted text-embeddings-inference
+   */
+  "tei-local": {
+    maxConcurrentRequests: 16
+  },
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SPECIAL
+  // ═══════════════════════════════════════════════════════════════════════════
+  /**
+   * No rate limiting (for testing or unlimited APIs)
+   */
+  unlimited: {},
+  /**
+   * Very conservative (for debugging rate limit issues)
+   */
+  debug: {
+    tokensPerMinute: 1e4,
+    requestsPerMinute: 10,
+    maxConcurrentRequests: 1,
+    safetyMargin: 0.5
+  }
+};
+function getRateLimitConfig(configOrPreset) {
+  if (!configOrPreset) {
+    return RATE_LIMIT_PRESETS["openai-tier-2"];
+  }
+  if (typeof configOrPreset === "string") {
+    const preset = RATE_LIMIT_PRESETS[configOrPreset];
+    if (!preset) {
+      throw new Error(`Unknown rate limit preset: ${configOrPreset}`);
+    }
+    return preset;
+  }
+  return configOrPreset;
+}
+function estimateTokens(text) {
+  return Math.ceil(text.length / 3.5);
+}
+function estimateBatchTokens(texts) {
+  return texts.reduce((sum, text) => sum + estimateTokens(text), 0);
+}
+
+// src/retry/error-classifier.ts
+function classifyError(error) {
+  if (!error) {
+    return "unknown";
+  }
+  if (error instanceof Error) {
+    const message = error.message.toLowerCase();
+    const name = error.name.toLowerCase();
+    if (message.includes("429") || message.includes("rate limit") || message.includes("too many requests") || message.includes("quota exceeded") || name.includes("ratelimit")) {
+      return "rate_limit";
+    }
+    if (message.includes("timeout") || message.includes("timed out") || message.includes("etimedout") || message.includes("deadline exceeded") || name.includes("timeout")) {
+      return "timeout";
+    }
+    if (message.includes("econnrefused") || message.includes("econnreset") || message.includes("enotfound") || message.includes("network") || message.includes("socket") || message.includes("dns") || name.includes("fetch") || name.includes("network")) {
+      return "network";
+    }
+    if (message.includes("500") || message.includes("502") || message.includes("503") || message.includes("504") || message.includes("internal server") || message.includes("bad gateway") || message.includes("service unavailable") || message.includes("gateway timeout")) {
+      return "server_error";
+    }
+    if (message.includes("400") || message.includes("401") || message.includes("403") || message.includes("404") || message.includes("bad request") || message.includes("unauthorized") || message.includes("forbidden") || message.includes("not found")) {
+      return "client_error";
+    }
+  }
+  if (typeof error === "object" && error !== null) {
+    const obj = error;
+    const status = obj.status ?? obj.statusCode ?? obj.code;
+    if (typeof status === "number") {
+      if (status === 429) {
+        return "rate_limit";
+      }
+      if (status >= 500) {
+        return "server_error";
+      }
+      if (status >= 400) {
+        return "client_error";
+      }
+    }
+    const code = obj.code;
+    if (typeof code === "string") {
+      const lowerCode = code.toLowerCase();
+      if (lowerCode.includes("timeout")) {
+        return "timeout";
+      }
+      if (lowerCode.includes("econnrefused")) {
+        return "network";
+      }
+      if (lowerCode.includes("econnreset")) {
+        return "network";
+      }
+      if (lowerCode.includes("enotfound")) {
+        return "network";
+      }
+    }
+  }
+  return "unknown";
+}
+function isRateLimitError(error) {
+  return classifyError(error) === "rate_limit";
+}
+function isRetryableError(error, retryableTypes = ["rate_limit", "server_error", "timeout", "network"]) {
+  const errorType = classifyError(error);
+  return retryableTypes.includes(errorType);
+}
+function extractRetryAfter(error) {
+  if (!error || typeof error !== "object") {
+    return void 0;
+  }
+  const obj = error;
+  const retryAfter = obj.retryAfter ?? obj["retry-after"] ?? obj.retryAfterMs ?? obj.headers?.["retry-after"];
+  if (typeof retryAfter === "number") {
+    return retryAfter < 1e3 ? retryAfter * 1e3 : retryAfter;
+  }
+  if (typeof retryAfter === "string") {
+    const parsed = parseInt(retryAfter, 10);
+    if (!isNaN(parsed)) {
+      return parsed < 1e3 ? parsed * 1e3 : parsed;
+    }
+  }
+  return void 0;
+}
+
+// src/retry/retry-strategy.ts
+function calculateBackoffDelay(attempt, config, retryAfterHint) {
+  if (retryAfterHint !== void 0 && retryAfterHint > 0) {
+    return Math.min(retryAfterHint, config.maxDelay);
+  }
+  const exponentialDelay = config.baseDelay * Math.pow(2, attempt);
+  const cappedDelay = Math.min(exponentialDelay, config.maxDelay);
+  const jitterMultiplier = 1 + Math.random() * config.jitter;
+  return Math.floor(cappedDelay * jitterMultiplier);
+}
+function shouldRetry(error, attempt, config = {}) {
+  const fullConfig = {
+    ...DEFAULT_RETRY_CONFIG,
+    ...config
+  };
+  const errorType = classifyError(error);
+  const isRetryable = isRetryableError(error, fullConfig.retryableErrors);
+  const hasAttemptsLeft = attempt < fullConfig.maxRetries;
+  const shouldRetryNow = isRetryable && hasAttemptsLeft;
+  let delayMs = 0;
+  if (shouldRetryNow) {
+    const retryAfterHint = extractRetryAfter(error);
+    if (errorType === "rate_limit") {
+      const rateLimitConfig = {
+        ...fullConfig,
+        baseDelay: Math.max(fullConfig.baseDelay, 5e3)
+        // At least 5s for rate limits
+      };
+      delayMs = calculateBackoffDelay(attempt, rateLimitConfig, retryAfterHint);
+    } else {
+      delayMs = calculateBackoffDelay(attempt, fullConfig, retryAfterHint);
+    }
+  }
+  return {
+    shouldRetry: shouldRetryNow,
+    delayMs,
+    errorType,
+    attempt,
+    maxAttempts: fullConfig.maxRetries
+  };
+}
+async function withRetry(fn, config = {}) {
+  const fullConfig = {
+    ...DEFAULT_RETRY_CONFIG,
+    ...config
+  };
+  let lastError;
+  let attempts = 0;
+  for (let attempt = 0; attempt <= fullConfig.maxRetries; attempt++) {
+    attempts = attempt + 1;
+    try {
+      const result = await fn();
+      return { result, attempts };
+    } catch (error) {
+      lastError = error;
+      const decision = shouldRetry(error, attempt, fullConfig);
+      if (!decision.shouldRetry) {
+        break;
+      }
+      await sleep(decision.delayMs);
+    }
+  }
+  throw lastError;
+}
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+function createRateLimitRetryConfig(maxRetries = 5) {
+  return {
+    maxRetries,
+    baseDelay: 5e3,
+    // Start with 5s for rate limits
+    maxDelay: 6e4,
+    // Cap at 1 minute
+    jitter: 0.2,
+    // 20% jitter for distributed systems
+    retryableErrors: ["rate_limit", "server_error", "timeout", "network"]
+  };
+}
+function createQuickRetryConfig(maxRetries = 3) {
+  return {
+    maxRetries,
+    baseDelay: 500,
+    // Start with 500ms
+    maxDelay: 5e3,
+    // Cap at 5s
+    jitter: 0.1,
+    // 10% jitter
+    retryableErrors: ["server_error", "timeout", "network"]
+  };
+}
+
+// src/broker/resource-broker.ts
+var ResourceBroker = class {
+  constructor(rateLimitBackend) {
+    this.rateLimitBackend = rateLimitBackend;
+  }
+  resources = /* @__PURE__ */ new Map();
+  queue = new PriorityQueue();
+  processing = false;
+  shuttingDown = false;
+  startTime = Date.now();
+  /**
+   * Active processing count per resource (for concurrent limit tracking).
+   */
+  activeProcessing = /* @__PURE__ */ new Map();
+  /**
+   * Register a resource with its configuration.
+   *
+   * @param resource - Resource identifier ('llm', 'embeddings', 'vectorStore')
+   * @param config - Resource configuration including executor
+   */
+  register(resource, config) {
+    const rateLimits = typeof config.rateLimits === "string" ? getRateLimitConfig(config.rateLimits) : config.rateLimits ?? DEFAULT_RATE_LIMIT_CONFIG;
+    this.resources.set(resource, {
+      config,
+      rateLimits,
+      stats: {
+        totalRequests: 0,
+        totalSuccess: 0,
+        totalErrors: 0,
+        totalWaitTime: 0,
+        totalProcessingTime: 0
+      }
+    });
+    this.activeProcessing.set(resource, 0);
+  }
+  /**
+   * Enqueue a request for execution.
+   *
+   * @param request - Resource request (without id and createdAt)
+   * @returns Promise that resolves with response when execution completes
+   */
+  enqueue(request) {
+    if (this.shuttingDown) {
+      return Promise.resolve({
+        success: false,
+        error: new Error("ResourceBroker is shutting down"),
+        retries: 0,
+        waitTime: 0,
+        processingTime: 0,
+        totalTime: 0
+      });
+    }
+    const registered = this.resources.get(request.resource);
+    if (!registered) {
+      return Promise.resolve({
+        success: false,
+        error: new Error(`Resource not registered: ${request.resource}`),
+        retries: 0,
+        waitTime: 0,
+        processingTime: 0,
+        totalTime: 0
+      });
+    }
+    const fullRequest = {
+      ...request,
+      id: randomUUID(),
+      createdAt: Date.now(),
+      timeout: request.timeout ?? registered.config.timeout ?? 6e4,
+      maxRetries: request.maxRetries ?? registered.config.maxRetries ?? DEFAULT_RETRY_CONFIG.maxRetries
+    };
+    return new Promise((resolve, reject) => {
+      const item = {
+        request: fullRequest,
+        resolve,
+        reject,
+        enqueuedAt: Date.now()
+      };
+      this.queue.enqueue(item);
+      registered.stats.totalRequests++;
+      this.processQueue();
+    });
+  }
+  /**
+   * Process queue items continuously.
+   */
+  async processQueue() {
+    if (this.processing) {
+      return;
+    }
+    this.processing = true;
+    try {
+      while (!this.queue.isEmpty() && !this.shuttingDown) {
+        const item = this.queue.peek();
+        if (!item) {
+          break;
+        }
+        const registered = this.resources.get(item.request.resource);
+        if (!registered) {
+          this.queue.dequeue();
+          item.reject(new Error(`Resource not registered: ${item.request.resource}`));
+          continue;
+        }
+        const tokens = item.request.estimatedTokens ?? 0;
+        const acquireResult = await this.rateLimitBackend.acquire(
+          item.request.resource,
+          tokens,
+          registered.rateLimits
+        );
+        if (!acquireResult.allowed) {
+          await sleep(acquireResult.waitTimeMs ?? 100);
+          continue;
+        }
+        this.queue.dequeue();
+        const currentActive = this.activeProcessing.get(item.request.resource) ?? 0;
+        this.activeProcessing.set(item.request.resource, currentActive + 1);
+        this.executeItem(item, registered).catch(() => {
+        });
+      }
+    } finally {
+      this.processing = false;
+      if (!this.queue.isEmpty() && !this.shuttingDown) {
+        setImmediate(() => this.processQueue());
+      }
+    }
+  }
+  /**
+   * Execute a single queue item with retry logic.
+   */
+  async executeItem(item, registered) {
+    const startTime = Date.now();
+    const waitTime = startTime - item.enqueuedAt;
+    let retries = 0;
+    let lastError;
+    const retryConfig = {
+      maxRetries: item.request.maxRetries ?? DEFAULT_RETRY_CONFIG.maxRetries,
+      baseDelay: registered.config.baseDelay ?? DEFAULT_RETRY_CONFIG.baseDelay,
+      maxDelay: registered.config.maxDelay ?? DEFAULT_RETRY_CONFIG.maxDelay,
+      jitter: DEFAULT_RETRY_CONFIG.jitter,
+      retryableErrors: DEFAULT_RETRY_CONFIG.retryableErrors
+    };
+    try {
+      for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
+        try {
+          const timeoutMs = item.request.timeout ?? 6e4;
+          const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new Error(`Request timeout after ${timeoutMs}ms`)), timeoutMs);
+          });
+          const executionPromise = registered.config.executor(
+            item.request.operation,
+            item.request.args
+          );
+          const result = await Promise.race([executionPromise, timeoutPromise]);
+          const endTime2 = Date.now();
+          const processingTime2 = endTime2 - startTime;
+          registered.stats.totalSuccess++;
+          registered.stats.totalWaitTime += waitTime;
+          registered.stats.totalProcessingTime += processingTime2;
+          item.resolve({
+            success: true,
+            data: result,
+            retries,
+            waitTime,
+            processingTime: processingTime2,
+            totalTime: endTime2 - item.enqueuedAt
+          });
+          return;
+        } catch (error) {
+          lastError = error instanceof Error ? error : new Error(String(error));
+          retries = attempt;
+          const decision = shouldRetry(error, attempt, retryConfig);
+          if (!decision.shouldRetry) {
+            break;
+          }
+          await sleep(decision.delayMs);
+          const tokens = item.request.estimatedTokens ?? 0;
+          const acquireResult = await this.rateLimitBackend.acquire(
+            item.request.resource,
+            tokens,
+            registered.rateLimits
+          );
+          if (!acquireResult.allowed && acquireResult.waitTimeMs) {
+            await sleep(acquireResult.waitTimeMs);
+          }
+        }
+      }
+      const endTime = Date.now();
+      const processingTime = endTime - startTime;
+      registered.stats.totalErrors++;
+      registered.stats.totalWaitTime += waitTime;
+      registered.stats.totalProcessingTime += processingTime;
+      item.resolve({
+        success: false,
+        error: lastError,
+        retries,
+        waitTime,
+        processingTime,
+        totalTime: endTime - item.enqueuedAt
+      });
+    } finally {
+      await this.rateLimitBackend.release(item.request.resource);
+      const currentActive = this.activeProcessing.get(item.request.resource) ?? 1;
+      this.activeProcessing.set(item.request.resource, Math.max(0, currentActive - 1));
+    }
+  }
+  /**
+   * Get broker statistics.
+   */
+  getStats() {
+    const resources = {};
+    let totalRequests = 0;
+    let totalSuccess = 0;
+    let totalErrors = 0;
+    for (const [resourceName, registered] of this.resources) {
+      const queueByPriority = this.queue.sizeByPriority();
+      const queueSize = this.queue.sizeByResource(resourceName);
+      const activeRequests = this.activeProcessing.get(resourceName) ?? 0;
+      const rateLimitStats = {
+        resource: resourceName,
+        tokensThisMinute: 0,
+        requestsThisMinute: 0,
+        requestsThisSecond: 0,
+        activeRequests,
+        totalRequests: registered.stats.totalRequests,
+        totalTokens: 0,
+        waitCount: 0,
+        totalWaitTime: registered.stats.totalWaitTime
+      };
+      const avgWaitTime = registered.stats.totalRequests > 0 ? registered.stats.totalWaitTime / registered.stats.totalRequests : 0;
+      const avgProcessingTime = registered.stats.totalRequests > 0 ? registered.stats.totalProcessingTime / registered.stats.totalRequests : 0;
+      resources[resourceName] = {
+        rateLimits: rateLimitStats,
+        queueSize,
+        queueByPriority,
+        totalRequests: registered.stats.totalRequests,
+        totalSuccess: registered.stats.totalSuccess,
+        totalErrors: registered.stats.totalErrors,
+        avgWaitTime,
+        avgProcessingTime
+      };
+      totalRequests += registered.stats.totalRequests;
+      totalSuccess += registered.stats.totalSuccess;
+      totalErrors += registered.stats.totalErrors;
+    }
+    return {
+      resources,
+      totalRequests,
+      totalSuccess,
+      totalErrors,
+      queueSize: this.queue.size(),
+      uptime: Date.now() - this.startTime
+    };
+  }
+  /**
+   * Graceful shutdown - drain queues and stop processing.
+   *
+   * @param timeoutMs - Maximum time to wait for drain (default: 30000)
+   */
+  async shutdown(timeoutMs = 3e4) {
+    this.shuttingDown = true;
+    const startTime = Date.now();
+    while (!this.queue.isEmpty() && Date.now() - startTime < timeoutMs) {
+      await sleep(100);
+    }
+    const remaining = this.queue.clear();
+    for (const item of remaining) {
+      item.resolve({
+        success: false,
+        error: new Error("ResourceBroker shutdown"),
+        retries: 0,
+        waitTime: Date.now() - item.enqueuedAt,
+        processingTime: 0,
+        totalTime: Date.now() - item.enqueuedAt
+      });
+    }
+  }
+  /**
+   * Check if broker is shutting down.
+   */
+  isShuttingDown() {
+    return this.shuttingDown;
+  }
+  /**
+   * Get registered resource names.
+   */
+  getRegisteredResources() {
+    return Array.from(this.resources.keys());
+  }
+  /**
+   * Check if a resource is registered.
+   */
+  hasResource(resource) {
+    return this.resources.has(resource);
+  }
+  /**
+   * Unregister a resource.
+   * Note: Pending requests for this resource will fail.
+   */
+  unregister(resource) {
+    this.resources.delete(resource);
+    this.activeProcessing.delete(resource);
+  }
+};
+
+// src/rate-limit/in-memory-backend.ts
+var InMemoryRateLimitBackend = class {
+  states = /* @__PURE__ */ new Map();
+  /**
+   * Get or create state for a resource.
+   */
+  getState(resource) {
+    let state = this.states.get(resource);
+    if (!state) {
+      const now = Date.now();
+      state = {
+        tokensThisMinute: 0,
+        requestsThisMinute: 0,
+        requestsThisSecond: 0,
+        activeRequests: 0,
+        minuteWindowStart: now,
+        secondWindowStart: now,
+        totalRequests: 0,
+        totalTokens: 0,
+        waitCount: 0,
+        totalWaitTime: 0
+      };
+      this.states.set(resource, state);
+    }
+    return state;
+  }
+  /**
+   * Reset windows if time has passed.
+   */
+  resetWindowsIfNeeded(state) {
+    const now = Date.now();
+    if (now - state.minuteWindowStart >= 6e4) {
+      state.tokensThisMinute = 0;
+      state.requestsThisMinute = 0;
+      state.minuteWindowStart = now;
+    }
+    if (now - state.secondWindowStart >= 1e3) {
+      state.requestsThisSecond = 0;
+      state.secondWindowStart = now;
+    }
+  }
+  /**
+   * Check if all limits allow proceeding.
+   */
+  checkLimits(state, tokens, config) {
+    const now = Date.now();
+    const safetyMargin = config.safetyMargin ?? 0.9;
+    const effectiveTPM = config.tokensPerMinute ? Math.floor(config.tokensPerMinute * safetyMargin) : void 0;
+    const effectiveRPM = config.requestsPerMinute ? Math.floor(config.requestsPerMinute * safetyMargin) : void 0;
+    const effectiveRPS = config.requestsPerSecond ? Math.floor(config.requestsPerSecond * safetyMargin) : void 0;
+    const delays = [];
+    if (effectiveTPM !== void 0 && state.tokensThisMinute + tokens > effectiveTPM) {
+      const timeUntilMinuteReset = 6e4 - (now - state.minuteWindowStart);
+      delays.push(Math.max(100, timeUntilMinuteReset + 100));
+    }
+    if (effectiveRPM !== void 0 && state.requestsThisMinute >= effectiveRPM) {
+      const timeUntilMinuteReset = 6e4 - (now - state.minuteWindowStart);
+      delays.push(Math.max(100, timeUntilMinuteReset + 100));
+    }
+    if (effectiveRPS !== void 0 && state.requestsThisSecond >= effectiveRPS) {
+      const timeUntilSecondReset = 1e3 - (now - state.secondWindowStart);
+      delays.push(Math.max(50, timeUntilSecondReset + 50));
+    }
+    if (config.maxConcurrentRequests !== void 0 && state.activeRequests >= config.maxConcurrentRequests) {
+      delays.push(100);
+    }
+    if (delays.length > 0) {
+      return { allowed: false, waitTimeMs: Math.min(...delays) };
+    }
+    return { allowed: true };
+  }
+  /**
+   * @inheritdoc
+   */
+  async acquire(resource, tokens, config) {
+    const state = this.getState(resource);
+    this.resetWindowsIfNeeded(state);
+    const check = this.checkLimits(state, tokens, config);
+    if (!check.allowed) {
+      state.waitCount++;
+      state.totalWaitTime += check.waitTimeMs ?? 0;
+      const safetyMargin2 = config.safetyMargin ?? 0.9;
+      const effectiveTPM2 = config.tokensPerMinute ? Math.floor(config.tokensPerMinute * safetyMargin2) : void 0;
+      const effectiveRPM2 = config.requestsPerMinute ? Math.floor(config.requestsPerMinute * safetyMargin2) : void 0;
+      return {
+        allowed: false,
+        waitTimeMs: check.waitTimeMs,
+        tokensRemaining: effectiveTPM2 ? Math.max(0, effectiveTPM2 - state.tokensThisMinute) : void 0,
+        requestsRemaining: effectiveRPM2 ? Math.max(0, effectiveRPM2 - state.requestsThisMinute) : void 0,
+        activeRequests: state.activeRequests
+      };
+    }
+    state.tokensThisMinute += tokens;
+    state.requestsThisMinute++;
+    state.requestsThisSecond++;
+    state.activeRequests++;
+    state.totalRequests++;
+    state.totalTokens += tokens;
+    const safetyMargin = config.safetyMargin ?? 0.9;
+    const effectiveTPM = config.tokensPerMinute ? Math.floor(config.tokensPerMinute * safetyMargin) : void 0;
+    const effectiveRPM = config.requestsPerMinute ? Math.floor(config.requestsPerMinute * safetyMargin) : void 0;
+    return {
+      allowed: true,
+      tokensRemaining: effectiveTPM ? Math.max(0, effectiveTPM - state.tokensThisMinute) : void 0,
+      requestsRemaining: effectiveRPM ? Math.max(0, effectiveRPM - state.requestsThisMinute) : void 0,
+      activeRequests: state.activeRequests
+    };
+  }
+  /**
+   * @inheritdoc
+   */
+  async release(resource) {
+    const state = this.states.get(resource);
+    if (state) {
+      state.activeRequests = Math.max(0, state.activeRequests - 1);
+    }
+  }
+  /**
+   * @inheritdoc
+   */
+  async getStats(resource) {
+    const state = this.getState(resource);
+    this.resetWindowsIfNeeded(state);
+    return {
+      resource,
+      tokensThisMinute: state.tokensThisMinute,
+      requestsThisMinute: state.requestsThisMinute,
+      requestsThisSecond: state.requestsThisSecond,
+      activeRequests: state.activeRequests,
+      totalRequests: state.totalRequests,
+      totalTokens: state.totalTokens,
+      waitCount: state.waitCount,
+      totalWaitTime: state.totalWaitTime
+    };
+  }
+  /**
+   * @inheritdoc
+   */
+  async reset(resource) {
+    this.states.delete(resource);
+  }
+  /**
+   * Reset all resources.
+   */
+  resetAll() {
+    this.states.clear();
+  }
+};
+
+// src/rate-limit/state-broker-backend.ts
+var StateBrokerRateLimitBackend = class {
+  constructor(broker) {
+    this.broker = broker;
+  }
+  /**
+   * Get current minute window key.
+   */
+  getMinuteKey(resource) {
+    const window = (/* @__PURE__ */ new Date()).toISOString().slice(0, 16);
+    return `ratelimit:${resource}:minute:${window}`;
+  }
+  /**
+   * Get current second window key.
+   */
+  getSecondKey(resource) {
+    const window = (/* @__PURE__ */ new Date()).toISOString().slice(0, 19);
+    return `ratelimit:${resource}:second:${window}`;
+  }
+  /**
+   * Get active requests key.
+   */
+  getActiveKey(resource) {
+    return `ratelimit:${resource}:active`;
+  }
+  /**
+   * Get stats key.
+   */
+  getStatsKey(resource) {
+    return `ratelimit:${resource}:stats`;
+  }
+  /**
+   * Get or initialize window state.
+   */
+  async getWindowState(key) {
+    const state = await this.broker.get(key);
+    return state ?? { tokens: 0, requests: 0, activeRequests: 0, updatedAt: Date.now() };
+  }
+  /**
+   * Get or initialize stats.
+   */
+  async getCumulativeStats(resource) {
+    const stats = await this.broker.get(this.getStatsKey(resource));
+    return stats ?? { totalRequests: 0, totalTokens: 0, waitCount: 0, totalWaitTime: 0 };
+  }
+  /**
+   * @inheritdoc
+   */
+  async acquire(resource, tokens, config) {
+    const safetyMargin = config.safetyMargin ?? 0.9;
+    const [minuteState, secondState, activeCount] = await Promise.all([
+      this.getWindowState(this.getMinuteKey(resource)),
+      this.getWindowState(this.getSecondKey(resource)),
+      this.broker.get(this.getActiveKey(resource)).then((v) => v ?? 0)
+    ]);
+    const effectiveTPM = config.tokensPerMinute ? Math.floor(config.tokensPerMinute * safetyMargin) : void 0;
+    const effectiveRPM = config.requestsPerMinute ? Math.floor(config.requestsPerMinute * safetyMargin) : void 0;
+    const effectiveRPS = config.requestsPerSecond ? Math.floor(config.requestsPerSecond * safetyMargin) : void 0;
+    const delays = [];
+    const now = Date.now();
+    if (effectiveTPM && minuteState.tokens + tokens > effectiveTPM) {
+      const secondsRemaining = 60 - (/* @__PURE__ */ new Date()).getSeconds();
+      delays.push(secondsRemaining * 1e3 + 100);
+    }
+    if (effectiveRPM && minuteState.requests >= effectiveRPM) {
+      const secondsRemaining = 60 - (/* @__PURE__ */ new Date()).getSeconds();
+      delays.push(secondsRemaining * 1e3 + 100);
+    }
+    if (effectiveRPS && secondState.requests >= effectiveRPS) {
+      const msRemaining = 1e3 - (/* @__PURE__ */ new Date()).getMilliseconds();
+      delays.push(msRemaining + 50);
+    }
+    if (config.maxConcurrentRequests && activeCount >= config.maxConcurrentRequests) {
+      delays.push(100);
+    }
+    if (delays.length > 0) {
+      const stats2 = await this.getCumulativeStats(resource);
+      stats2.waitCount++;
+      stats2.totalWaitTime += Math.min(...delays);
+      await this.broker.set(this.getStatsKey(resource), stats2);
+      return {
+        allowed: false,
+        waitTimeMs: Math.min(...delays),
+        tokensRemaining: effectiveTPM ? Math.max(0, effectiveTPM - minuteState.tokens) : void 0,
+        requestsRemaining: effectiveRPM ? Math.max(0, effectiveRPM - minuteState.requests) : void 0,
+        activeRequests: activeCount
+      };
+    }
+    const minuteKey = this.getMinuteKey(resource);
+    const secondKey = this.getSecondKey(resource);
+    const activeKey = this.getActiveKey(resource);
+    const statsKey = this.getStatsKey(resource);
+    const newMinuteState = {
+      tokens: minuteState.tokens + tokens,
+      requests: minuteState.requests + 1,
+      activeRequests: activeCount + 1,
+      updatedAt: now
+    };
+    await this.broker.set(minuteKey, newMinuteState, 12e4);
+    const newSecondState = {
+      tokens: secondState.tokens + tokens,
+      requests: secondState.requests + 1,
+      activeRequests: activeCount + 1,
+      updatedAt: now
+    };
+    await this.broker.set(secondKey, newSecondState, 1e4);
+    await this.broker.set(activeKey, activeCount + 1);
+    const stats = await this.getCumulativeStats(resource);
+    stats.totalRequests++;
+    stats.totalTokens += tokens;
+    await this.broker.set(statsKey, stats);
+    return {
+      allowed: true,
+      tokensRemaining: effectiveTPM ? Math.max(0, effectiveTPM - newMinuteState.tokens) : void 0,
+      requestsRemaining: effectiveRPM ? Math.max(0, effectiveRPM - newMinuteState.requests) : void 0,
+      activeRequests: activeCount + 1
+    };
+  }
+  /**
+   * @inheritdoc
+   */
+  async release(resource) {
+    const activeKey = this.getActiveKey(resource);
+    const current = await this.broker.get(activeKey);
+    if (current !== null && current > 0) {
+      await this.broker.set(activeKey, current - 1);
+    }
+  }
+  /**
+   * @inheritdoc
+   */
+  async getStats(resource) {
+    const [minuteState, secondState, activeCount, cumulativeStats] = await Promise.all([
+      this.getWindowState(this.getMinuteKey(resource)),
+      this.getWindowState(this.getSecondKey(resource)),
+      this.broker.get(this.getActiveKey(resource)).then((v) => v ?? 0),
+      this.getCumulativeStats(resource)
+    ]);
+    return {
+      resource,
+      tokensThisMinute: minuteState.tokens,
+      requestsThisMinute: minuteState.requests,
+      requestsThisSecond: secondState.requests,
+      activeRequests: activeCount,
+      totalRequests: cumulativeStats.totalRequests,
+      totalTokens: cumulativeStats.totalTokens,
+      waitCount: cumulativeStats.waitCount,
+      totalWaitTime: cumulativeStats.totalWaitTime
+    };
+  }
+  /**
+   * @inheritdoc
+   */
+  async reset(resource) {
+    await Promise.all([
+      this.broker.clear(`ratelimit:${resource}:*`)
+    ]);
+  }
+};
+
+// src/wrappers/queued-llm.ts
+var QueuedLLM = class {
+  constructor(broker, realLLM) {
+    this.broker = broker;
+    this.realLLM = realLLM;
+  }
+  /**
+   * Generate a completion through the queue.
+   *
+   * @param prompt - Text prompt
+   * @param options - Optional generation options with priority
+   * @returns LLM response
+   * @throws Error if request fails after all retries
+   */
+  async complete(prompt, options) {
+    const priority = options?.priority ?? "normal";
+    const estimatedTokens = estimateTokens(prompt);
+    const resource = options?.metadata?.resource ?? "llm";
+    const response = await this.broker.enqueue({
+      resource,
+      operation: "complete",
+      args: [prompt, options],
+      priority,
+      estimatedTokens
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("LLM request failed");
+    }
+    return response.data;
+  }
+  async getProtocolCapabilities() {
+    if (!this.realLLM.getProtocolCapabilities) {
+      return {
+        cache: { supported: false },
+        stream: { supported: true }
+      };
+    }
+    return this.realLLM.getProtocolCapabilities();
+  }
+  /**
+   * Stream a completion (bypasses queue for real-time UX).
+   *
+   * Streaming is passed through directly to the underlying LLM
+   * because:
+   * 1. Real-time user experience requires immediate response
+   * 2. Token counting happens after streaming completes
+   * 3. Rate limits are still enforced by the underlying adapter
+   *
+   * @param prompt - Text prompt
+   * @param options - Optional generation options
+   * @returns Async iterable of text chunks
+   */
+  stream(prompt, options) {
+    return this.realLLM.stream(prompt, options);
+  }
+  /**
+   * Chat with native tool calling support (proxies to underlying LLM).
+   * Currently NOT queued - passes through directly for simplicity.
+   * TODO: Add queueing support when needed.
+   */
+  async chatWithTools(messages, options) {
+    if (!this.realLLM.chatWithTools) {
+      throw new Error("Underlying LLM does not support chatWithTools");
+    }
+    return this.realLLM.chatWithTools(messages, options);
+  }
+};
+function createQueuedLLM(broker, llm) {
+  return new QueuedLLM(broker, llm);
+}
+
+// src/wrappers/queued-embeddings.ts
+var QueuedEmbeddings = class {
+  constructor(broker, realEmbeddings) {
+    this.broker = broker;
+    this.realEmbeddings = realEmbeddings;
+  }
+  _priority = "normal";
+  /**
+   * Get embedding dimensions from the underlying implementation.
+   */
+  get dimensions() {
+    return this.realEmbeddings.dimensions;
+  }
+  /**
+   * Set default priority for subsequent operations.
+   *
+   * @param priority - Priority level
+   * @returns this for chaining
+   */
+  withPriority(priority) {
+    this._priority = priority;
+    return this;
+  }
+  /**
+   * Generate embedding vector for a single text through the queue.
+   *
+   * @param text - Input text
+   * @returns Embedding vector
+   * @throws Error if request fails after all retries
+   */
+  async embed(text) {
+    const estimatedTokens = estimateTokens(text);
+    const response = await this.broker.enqueue({
+      resource: "embeddings",
+      operation: "embed",
+      args: [text],
+      priority: this._priority,
+      estimatedTokens
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("Embeddings request failed");
+    }
+    return response.data;
+  }
+  /**
+   * Generate embedding vectors for multiple texts through the queue.
+   *
+   * @param texts - Array of input texts
+   * @returns Array of embedding vectors
+   * @throws Error if request fails after all retries
+   */
+  async embedBatch(texts) {
+    const estimatedTokens = estimateBatchTokens(texts);
+    const response = await this.broker.enqueue({
+      resource: "embeddings",
+      operation: "embedBatch",
+      args: [texts],
+      priority: this._priority,
+      estimatedTokens
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("Embeddings batch request failed");
+    }
+    return response.data;
+  }
+  /**
+   * Get the dimensions of the embeddings.
+   * This method is needed for IPC/Unix Socket transport to access the dimensions property.
+   */
+  async getDimensions() {
+    return this.realEmbeddings.dimensions;
+  }
+};
+function createQueuedEmbeddings(broker, embeddings) {
+  return new QueuedEmbeddings(broker, embeddings);
+}
+
+// src/wrappers/queued-vector-store.ts
+var QueuedVectorStore = class {
+  constructor(broker, realVectorStore) {
+    this.broker = broker;
+    this.realVectorStore = realVectorStore;
+  }
+  _priority = "normal";
+  /**
+   * Set default priority for subsequent operations.
+   *
+   * @param priority - Priority level
+   * @returns this for chaining
+   */
+  withPriority(priority) {
+    this._priority = priority;
+    return this;
+  }
+  /**
+   * Search for similar vectors through the queue.
+   *
+   * @param query - Query embedding vector
+   * @param limit - Maximum number of results
+   * @param filter - Optional metadata filter
+   * @returns Search results
+   * @throws Error if request fails after all retries
+   */
+  async search(query, limit, filter) {
+    const response = await this.broker.enqueue({
+      resource: "vectorStore",
+      operation: "search",
+      args: [query, limit, filter],
+      priority: this._priority
+      // No token estimation for vector operations
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("VectorStore search failed");
+    }
+    return response.data;
+  }
+  /**
+   * Upsert vectors through the queue.
+   *
+   * @param vectors - Array of vector records to upsert
+   * @throws Error if request fails after all retries
+   */
+  async upsert(vectors) {
+    const response = await this.broker.enqueue({
+      resource: "vectorStore",
+      operation: "upsert",
+      args: [vectors],
+      priority: this._priority
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("VectorStore upsert failed");
+    }
+  }
+  /**
+   * Delete vectors through the queue.
+   *
+   * @param ids - Array of vector IDs to delete
+   * @throws Error if request fails after all retries
+   */
+  async delete(ids) {
+    const response = await this.broker.enqueue({
+      resource: "vectorStore",
+      operation: "delete",
+      args: [ids],
+      priority: this._priority
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("VectorStore delete failed");
+    }
+  }
+  /**
+   * Get total count of vectors through the queue.
+   *
+   * @returns Vector count
+   * @throws Error if request fails after all retries
+   */
+  async count() {
+    const response = await this.broker.enqueue({
+      resource: "vectorStore",
+      operation: "count",
+      args: [],
+      priority: this._priority
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("VectorStore count failed");
+    }
+    return response.data;
+  }
+  /**
+   * Get vectors by IDs through the queue (if supported).
+   *
+   * @param ids - Array of vector IDs to retrieve
+   * @returns Array of vector records
+   * @throws Error if request fails or method not supported
+   */
+  async get(ids) {
+    if (!this.realVectorStore.get) {
+      throw new Error("VectorStore.get() not supported by underlying implementation");
+    }
+    const response = await this.broker.enqueue({
+      resource: "vectorStore",
+      operation: "get",
+      args: [ids],
+      priority: this._priority
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("VectorStore get failed");
+    }
+    return response.data;
+  }
+  /**
+   * Query vectors by filter through the queue (if supported).
+   *
+   * @param filter - Metadata filter to apply
+   * @returns Array of matching vector records
+   * @throws Error if request fails or method not supported
+   */
+  async query(filter) {
+    if (!this.realVectorStore.query) {
+      throw new Error("VectorStore.query() not supported by underlying implementation");
+    }
+    const response = await this.broker.enqueue({
+      resource: "vectorStore",
+      operation: "query",
+      args: [filter],
+      priority: this._priority
+    });
+    if (!response.success) {
+      throw response.error ?? new Error("VectorStore query failed");
+    }
+    return response.data;
+  }
+};
+function createQueuedVectorStore(broker, vectorStore) {
+  return new QueuedVectorStore(broker, vectorStore);
+}
+
+export { DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, InMemoryRateLimitBackend, PriorityQueue, QueuedEmbeddings, QueuedLLM, QueuedVectorStore, RATE_LIMIT_PRESETS, ResourceBroker, StateBrokerRateLimitBackend, calculateBackoffDelay, classifyError, createQueuedEmbeddings, createQueuedLLM, createQueuedVectorStore, createQuickRetryConfig, createRateLimitRetryConfig, estimateBatchTokens, estimateTokens, extractRetryAfter, getRateLimitConfig, isRateLimitError, isRetryableError, shouldRetry, sleep, withRetry };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map