@kb-labs/core-resource-broker 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,1217 @@
+import { StateBroker } from '@kb-labs/core-state-broker';
+import { ILLM, LLMOptions, LLMResponse, LLMProtocolCapabilities, LLMMessage, LLMToolCallOptions, LLMToolCallResponse, IEmbeddings, IVectorStore, VectorFilter, VectorSearchResult, VectorRecord } from '@kb-labs/core-platform';
+
+/**
+ * @module @kb-labs/core-resource-broker/types
+ * Type definitions for the Resource Broker system.
+ *
+ * The Resource Broker provides centralized queue management, rate limiting,
+ * and retry logic for heavy platform resources (LLM, Embeddings, VectorStore).
+ */
+/**
+ * Rate limiting configuration for a resource.
+ * Supports multiple rate limiting strategies (TPM, RPM, RPS, concurrent).
+ */
+interface RateLimitConfig {
+    /**
+     * Tokens per minute limit (e.g., OpenAI TPM)
+     * If undefined, no token-based rate limiting is applied
+     */
+    tokensPerMinute?: number;
+    /**
+     * Requests per minute limit (e.g., OpenAI RPM)
+     * If undefined, no request-per-minute rate limiting is applied
+     */
+    requestsPerMinute?: number;
+    /**
+     * Requests per second limit
+     * Some APIs (like Sber) use RPS instead of RPM
+     */
+    requestsPerSecond?: number;
+    /**
+     * Maximum tokens per single request
+     * Provider-specific limit
+     */
+    maxTokensPerRequest?: number;
+    /**
+     * Maximum concurrent requests
+     * For local models - GPU/CPU concurrency limit
+     */
+    maxConcurrentRequests?: number;
+    /**
+     * Safety margin (0-1, default 0.9)
+     * Use only X% of the limit to avoid hitting exact boundaries
+     */
+    safetyMargin?: number;
+}
+/**
+ * Result of attempting to acquire rate limit capacity.
+ */
+interface AcquireResult {
+    /** Whether the request is allowed to proceed */
+    allowed: boolean;
+    /** Milliseconds to wait if not allowed */
+    waitTimeMs?: number;
+    /** Remaining tokens in current window */
+    tokensRemaining?: number;
+    /** Remaining requests in current window */
+    requestsRemaining?: number;
+    /** Current active concurrent requests */
+    activeRequests?: number;
+}
+/**
+ * Statistics for a rate-limited resource.
+ */
+interface RateLimitStats {
+    /** Resource identifier */
+    resource: string;
+    /** Tokens used in current minute window */
+    tokensThisMinute: number;
+    /** Requests made in current minute window */
+    requestsThisMinute: number;
+    /** Requests made in current second window */
+    requestsThisSecond: number;
+    /** Currently active requests */
+    activeRequests: number;
+    /** Total requests made since start */
+    totalRequests: number;
+    /** Total tokens used since start */
+    totalTokens: number;
+    /** Number of times capacity was unavailable */
+    waitCount: number;
+    /** Total time spent waiting (ms) */
+    totalWaitTime: number;
+}
+/**
+ * Backend abstraction for rate limit state storage.
+ * Allows swapping between in-memory and distributed storage.
+ */
+interface RateLimitBackend {
+    /**
+     * Atomically check limit and reserve capacity.
+     *
+     * @param resource - Resource identifier (e.g., 'llm', 'embeddings')
+     * @param tokens - Estimated tokens for this request
+     * @param config - Rate limit configuration
+     * @returns Acquire result with allowed/waitTime
+     */
+    acquire(resource: string, tokens: number, config: RateLimitConfig): Promise<AcquireResult>;
+    /**
+     * Release a concurrent request slot.
+     *
+     * @param resource - Resource identifier
+     */
+    release(resource: string): Promise<void>;
+    /**
+     * Get current statistics for a resource.
+     *
+     * @param resource - Resource identifier
+     */
+    getStats(resource: string): Promise<RateLimitStats>;
+    /**
+     * Reset statistics for a resource.
+     *
+     * @param resource - Resource identifier
+     */
+    reset(resource: string): Promise<void>;
+}
+/**
+ * Priority levels for resource requests.
+ * - high: User-facing operations (commit, interactive queries)
+ * - normal: Background operations with reasonable latency expectations
+ * - low: Analytics, batch processing, non-urgent tasks
+ */
+type ResourcePriority = 'high' | 'normal' | 'low';
+/**
+ * Request to execute a resource operation.
+ */
+interface ResourceRequest {
+    /** Unique request identifier */
+    id: string;
+    /** Resource type ('llm', 'embeddings', 'vectorStore') */
+    resource: string;
+    /** Operation name ('complete', 'embed', 'search') */
+    operation: string;
+    /** Arguments to pass to the operation */
+    args: unknown[];
+    /** Request priority */
+    priority: ResourcePriority;
+    /** Estimated tokens for rate limiting (optional) */
+    estimatedTokens?: number;
+    /** Request timeout in ms (optional, default: 60000) */
+    timeout?: number;
+    /** Max retry attempts (optional, default: 3) */
+    maxRetries?: number;
+    /** Timestamp when request was created */
+    createdAt: number;
+}
+/**
+ * Response from a resource operation.
+ */
+interface ResourceResponse<T = unknown> {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** Result data if successful */
+    data?: T;
+    /** Error if failed */
+    error?: Error;
+    /** Number of retry attempts made */
+    retries: number;
+    /** Time spent waiting in queue (ms) */
+    waitTime: number;
+    /** Time spent executing the operation (ms) */
+    processingTime: number;
+    /** Total time from request to response (ms) */
+    totalTime: number;
+}
+/**
+ * Queue item wrapping a request with execution context.
+ */
+interface QueueItem {
+    /** The resource request */
+    request: ResourceRequest;
+    /** Resolve function to complete the promise */
+    resolve: (response: ResourceResponse) => void;
+    /** Reject function to fail the promise */
+    reject: (error: Error) => void;
+    /** Timestamp when added to queue */
+    enqueuedAt: number;
+}
+/**
+ * Configuration for a registered resource.
+ */
+interface ResourceConfig {
+    /** Rate limit configuration or preset name */
+    rateLimits?: RateLimitConfig | string;
+    /** Maximum retry attempts */
+    maxRetries?: number;
+    /** Base delay for exponential backoff (ms) */
+    baseDelay?: number;
+    /** Maximum delay between retries (ms) */
+    maxDelay?: number;
+    /** Request timeout (ms) */
+    timeout?: number;
+    /** The actual executor function */
+    executor: ResourceExecutor;
+}
+/**
+ * Function that executes a resource operation.
+ */
+type ResourceExecutor = (operation: string, args: unknown[]) => Promise<unknown>;
+/**
+ * Statistics for the resource broker.
+ */
+interface ResourceBrokerStats {
+    /** Stats per resource */
+    resources: Record<string, ResourceStats>;
+    /** Total requests processed */
+    totalRequests: number;
+    /** Total successful requests */
+    totalSuccess: number;
+    /** Total failed requests */
+    totalErrors: number;
+    /** Current queue size */
+    queueSize: number;
+    /** Uptime in milliseconds */
+    uptime: number;
+}
+/**
+ * Statistics for a single resource.
+ */
+interface ResourceStats {
+    /** Rate limit stats */
+    rateLimits: RateLimitStats;
+    /** Queue size for this resource */
+    queueSize: number;
+    /** Requests by priority */
+    queueByPriority: {
+        high: number;
+        normal: number;
+        low: number;
+    };
+    /** Total requests processed */
+    totalRequests: number;
+    /** Total successful requests */
+    totalSuccess: number;
+    /** Total failed requests */
+    totalErrors: number;
+    /** Average wait time (ms) */
+    avgWaitTime: number;
+    /** Average processing time (ms) */
+    avgProcessingTime: number;
+}
+/**
+ * Main resource broker interface.
+ * Coordinates queues, rate limiting, and execution for all resources.
+ */
+interface IResourceBroker {
+    /**
+     * Register a resource with its configuration.
+     *
+     * @param resource - Resource identifier
+     * @param config - Resource configuration
+     */
+    register(resource: string, config: ResourceConfig): void;
+    /**
+     * Enqueue a request for execution.
+     * Returns a promise that resolves when the request completes.
+     *
+     * @param request - Resource request (without id and createdAt)
+     * @returns Response with result or error
+     */
+    enqueue<T>(request: Omit<ResourceRequest, 'id' | 'createdAt'>): Promise<ResourceResponse<T>>;
+    /**
+     * Get broker statistics.
+     */
+    getStats(): ResourceBrokerStats;
+    /**
+     * Graceful shutdown - drain queues and stop processing.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Check if broker is shutting down.
+     */
+    isShuttingDown(): boolean;
+}
+/**
+ * Error classification for retry logic.
+ */
+type ErrorType = 'rate_limit' | 'server_error' | 'timeout' | 'client_error' | 'network' | 'unknown';
+/**
+ * Configuration for retry strategy.
+ */
+interface RetryConfig {
+    /** Maximum number of retry attempts */
+    maxRetries: number;
+    /** Base delay in ms (default: 1000) */
+    baseDelay: number;
+    /** Maximum delay in ms (default: 30000) */
+    maxDelay: number;
+    /** Jitter factor (0-1, default: 0.1) */
+    jitter: number;
+    /** Which error types to retry */
+    retryableErrors: ErrorType[];
+}
+/**
+ * Default retry configuration.
+ */
+declare const DEFAULT_RETRY_CONFIG: RetryConfig;
+/**
+ * Default rate limit config (no limits).
+ */
+declare const DEFAULT_RATE_LIMIT_CONFIG: RateLimitConfig;
+
+/**
+ * @module @kb-labs/core-resource-broker/broker/resource-broker
+ * Main ResourceBroker implementation - coordinates queues, rate limiting, and execution.
+ */
+
+/**
+ * ResourceBroker - Centralized coordinator for heavy platform resources.
+ *
+ * Features:
+ * - Priority queue (high/normal/low)
+ * - Rate limiting with configurable backend (in-memory or distributed)
+ * - Automatic retry with exponential backoff
+ * - Graceful shutdown
+ * - Per-resource statistics
+ *
+ * The platform doesn't know about plugins - only manages resources.
+ * Any caller can enqueue requests with appropriate priority.
+ *
+ * @example
+ * ```typescript
+ * const backend = new InMemoryRateLimitBackend();
+ * const broker = new ResourceBroker(backend);
+ *
+ * // Register resources
+ * broker.register('llm', {
+ *   rateLimits: 'openai-tier-2',
+ *   executor: (op, args) => llmAdapter[op](...args),
+ * });
+ *
+ * // Enqueue request
+ * const response = await broker.enqueue({
+ *   resource: 'llm',
+ *   operation: 'complete',
+ *   args: [prompt, options],
+ *   priority: 'high',
+ *   estimatedTokens: 1000,
+ * });
+ * ```
+ */
+declare class ResourceBroker implements IResourceBroker {
+    private rateLimitBackend;
+    private resources;
+    private queue;
+    private processing;
+    private shuttingDown;
+    private startTime;
+    /**
+     * Active processing count per resource (for concurrent limit tracking).
+     */
+    private activeProcessing;
+    constructor(rateLimitBackend: RateLimitBackend);
+    /**
+     * Register a resource with its configuration.
+     *
+     * @param resource - Resource identifier ('llm', 'embeddings', 'vectorStore')
+     * @param config - Resource configuration including executor
+     */
+    register(resource: string, config: ResourceConfig): void;
+    /**
+     * Enqueue a request for execution.
+     *
+     * @param request - Resource request (without id and createdAt)
+     * @returns Promise that resolves with response when execution completes
+     */
+    enqueue<T>(request: Omit<ResourceRequest, 'id' | 'createdAt'>): Promise<ResourceResponse<T>>;
+    /**
+     * Process queue items continuously.
+     */
+    private processQueue;
+    /**
+     * Execute a single queue item with retry logic.
+     */
+    private executeItem;
+    /**
+     * Get broker statistics.
+     */
+    getStats(): ResourceBrokerStats;
+    /**
+     * Graceful shutdown - drain queues and stop processing.
+     *
+     * @param timeoutMs - Maximum time to wait for drain (default: 30000)
+     */
+    shutdown(timeoutMs?: number): Promise<void>;
+    /**
+     * Check if broker is shutting down.
+     */
+    isShuttingDown(): boolean;
+    /**
+     * Get registered resource names.
+     */
+    getRegisteredResources(): string[];
+    /**
+     * Check if a resource is registered.
+     */
+    hasResource(resource: string): boolean;
+    /**
+     * Unregister a resource.
+     * Note: Pending requests for this resource will fail.
+     */
+    unregister(resource: string): void;
+}
+
+/**
+ * @module @kb-labs/core-resource-broker/queue/priority-queue
+ * Priority queue implementation with three levels: high, normal, low.
+ */
+
+/**
+ * Priority queue with three priority levels.
+ *
+ * - High priority items are always dequeued first
+ * - Within the same priority, items are dequeued FIFO
+ * - Supports peeking without removing
+ *
+ * @example
+ * ```typescript
+ * const queue = new PriorityQueue();
+ *
+ * queue.enqueue(item1); // normal priority
+ * queue.enqueue(item2); // high priority
+ *
+ * const next = queue.dequeue(); // returns item2 (high priority)
+ * ```
+ */
+declare class PriorityQueue {
+    private high;
+    private normal;
+    private low;
+    /**
+     * Add an item to the queue.
+     *
+     * @param item - Queue item to add
+     */
+    enqueue(item: QueueItem): void;
+    /**
+     * Remove and return the highest priority item.
+     *
+     * @returns The next item or undefined if queue is empty
+     */
+    dequeue(): QueueItem | undefined;
+    /**
+     * Peek at the highest priority item without removing it.
+     *
+     * @returns The next item or undefined if queue is empty
+     */
+    peek(): QueueItem | undefined;
+    /**
+     * Get total queue size.
+     */
+    size(): number;
+    /**
+     * Get queue size by priority.
+     */
+    sizeByPriority(): {
+        high: number;
+        normal: number;
+        low: number;
+    };
+    /**
+     * Check if queue is empty.
+     */
+    isEmpty(): boolean;
+    /**
+     * Clear all items from the queue.
+     *
+     * @returns All removed items (for cleanup/rejection)
+     */
+    clear(): QueueItem[];
+    /**
+     * 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: string): QueueItem | undefined;
+    /**
+     * Get all items for a specific resource.
+     *
+     * @param resource - Resource identifier
+     * @returns Items matching the resource
+     */
+    getByResource(resource: string): QueueItem[];
+    /**
+     * Get queue size for a specific resource.
+     *
+     * @param resource - Resource identifier
+     */
+    sizeByResource(resource: string): number;
+    /**
+     * Iterate over all items (for inspection, not removal).
+     */
+    [Symbol.iterator](): Iterator<QueueItem>;
+}
+
+/**
+ * @module @kb-labs/core-resource-broker/rate-limit/in-memory-backend
+ * In-memory implementation of RateLimitBackend for single-process deployments.
+ */
+
+/**
+ * In-memory rate limit backend.
+ *
+ * Uses sliding window approach for TPM/RPM/RPS tracking.
+ * Suitable for single-process deployments.
+ *
+ * @example
+ * ```typescript
+ * const backend = new InMemoryRateLimitBackend();
+ *
+ * const result = await backend.acquire('llm', 1000, {
+ *   tokensPerMinute: 100000,
+ *   requestsPerMinute: 1000,
+ * });
+ *
+ * if (result.allowed) {
+ *   // Execute request
+ *   await backend.release('llm');
+ * } else {
+ *   // Wait and retry
+ *   await sleep(result.waitTimeMs);
+ * }
+ * ```
+ */
+declare class InMemoryRateLimitBackend implements RateLimitBackend {
+    private states;
+    /**
+     * Get or create state for a resource.
+     */
+    private getState;
+    /**
+     * Reset windows if time has passed.
+     */
+    private resetWindowsIfNeeded;
+    /**
+     * Check if all limits allow proceeding.
+     */
+    private checkLimits;
+    /**
+     * @inheritdoc
+     */
+    acquire(resource: string, tokens: number, config: RateLimitConfig): Promise<AcquireResult>;
+    /**
+     * @inheritdoc
+     */
+    release(resource: string): Promise<void>;
+    /**
+     * @inheritdoc
+     */
+    getStats(resource: string): Promise<RateLimitStats>;
+    /**
+     * @inheritdoc
+     */
+    reset(resource: string): Promise<void>;
+    /**
+     * Reset all resources.
+     */
+    resetAll(): void;
+}
+
+/**
+ * @module @kb-labs/core-resource-broker/rate-limit/state-broker-backend
+ * Distributed rate limit backend using StateBroker.
+ *
+ * Enables horizontal scaling by storing rate counters in a shared StateBroker
+ * (HTTP daemon or future Redis backend).
+ */
+
+/**
+ * Distributed rate limit backend using StateBroker.
+ *
+ * Key patterns:
+ * - `ratelimit:{resource}:minute:{YYYY-MM-DDTHH:MM}` - Minute window counters
+ * - `ratelimit:{resource}:second:{YYYY-MM-DDTHH:MM:SS}` - Second window counters
+ * - `ratelimit:{resource}:active` - Active concurrent requests
+ * - `ratelimit:{resource}:stats` - Cumulative statistics
+ *
+ * TTL strategy:
+ * - Minute windows: 120s TTL (allows for clock skew)
+ * - Second windows: 10s TTL
+ * - Active counter: No TTL (managed explicitly)
+ * - Stats: No TTL (persisted)
+ *
+ * @example
+ * ```typescript
+ * import { createStateBroker } from '@kb-labs/core-state-broker';
+ *
+ * const broker = createStateBroker({ backend: 'http', url: 'http://localhost:7777' });
+ * const backend = new StateBrokerRateLimitBackend(broker);
+ *
+ * // Now rate limits are coordinated across all processes using the same daemon
+ * ```
+ */
+declare class StateBrokerRateLimitBackend implements RateLimitBackend {
+    private broker;
+    constructor(broker: StateBroker);
+    /**
+     * Get current minute window key.
+     */
+    private getMinuteKey;
+    /**
+     * Get current second window key.
+     */
+    private getSecondKey;
+    /**
+     * Get active requests key.
+     */
+    private getActiveKey;
+    /**
+     * Get stats key.
+     */
+    private getStatsKey;
+    /**
+     * Get or initialize window state.
+     */
+    private getWindowState;
+    /**
+     * Get or initialize stats.
+     */
+    private getCumulativeStats;
+    /**
+     * @inheritdoc
+     */
+    acquire(resource: string, tokens: number, config: RateLimitConfig): Promise<AcquireResult>;
+    /**
+     * @inheritdoc
+     */
+    release(resource: string): Promise<void>;
+    /**
+     * @inheritdoc
+     */
+    getStats(resource: string): Promise<RateLimitStats>;
+    /**
+     * @inheritdoc
+     */
+    reset(resource: string): Promise<void>;
+}
+
+/**
+ * @module @kb-labs/core-resource-broker/rate-limit/presets
+ * Pre-configured rate limits for common providers.
+ */
+
+/**
+ * Pre-configured rate limits for common providers.
+ */
+declare const RATE_LIMIT_PRESETS: {
+    /**
+     * OpenAI Tier 1 (paid accounts, entry level)
+     * Updated Nov 2024: Tier 1 now has 1M TPM for embeddings
+     */
+    readonly 'openai-tier-1': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * OpenAI Tier 2 (after $50+ spent)
+     */
+    readonly 'openai-tier-2': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * OpenAI Tier 3
+     */
+    readonly 'openai-tier-3': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * OpenAI Tier 4
+     */
+    readonly 'openai-tier-4': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * OpenAI Tier 5 (enterprise)
+     */
+    readonly 'openai-tier-5': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * OpenAI GPT-4 specific limits (more restrictive)
+     */
+    readonly 'openai-gpt4': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * Anthropic Tier 1 (default)
+     */
+    readonly 'anthropic-tier-1': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * Anthropic Tier 2
+     */
+    readonly 'anthropic-tier-2': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * Anthropic Tier 3
+     */
+    readonly 'anthropic-tier-3': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * Anthropic Tier 4
+     */
+    readonly 'anthropic-tier-4': {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxTokensPerRequest: number;
+        safetyMargin: number;
+    };
+    /**
+     * Sber GigaChat API
+     * Conservative limits for typical access
+     */
+    readonly 'sber-gigachat': {
+        requestsPerMinute: number;
+        requestsPerSecond: number;
+        safetyMargin: number;
+    };
+    /**
+     * Yandex GPT API
+     */
+    readonly 'yandex-gpt': {
+        requestsPerMinute: number;
+        requestsPerSecond: number;
+        safetyMargin: number;
+    };
+    /**
+     * Local Ollama
+     * No external rate limits, only GPU concurrency
+     */
+    readonly 'ollama-local': {
+        maxConcurrentRequests: number;
+    };
+    /**
+     * Self-hosted vLLM
+     */
+    readonly 'vllm-local': {
+        maxConcurrentRequests: number;
+        requestsPerSecond: number;
+    };
+    /**
+     * Self-hosted text-embeddings-inference
+     */
+    readonly 'tei-local': {
+        maxConcurrentRequests: number;
+    };
+    /**
+     * No rate limiting (for testing or unlimited APIs)
+     */
+    readonly unlimited: {};
+    /**
+     * Very conservative (for debugging rate limit issues)
+     */
+    readonly debug: {
+        tokensPerMinute: number;
+        requestsPerMinute: number;
+        maxConcurrentRequests: number;
+        safetyMargin: number;
+    };
+};
+type RateLimitPreset = keyof typeof RATE_LIMIT_PRESETS;
+/**
+ * Get rate limit config from preset name or custom config.
+ *
+ * @param configOrPreset - Config object or preset name
+ * @returns Resolved rate limit configuration
+ *
+ * @example
+ * ```typescript
+ * // Use preset
+ * const config = getRateLimitConfig('openai-tier-2');
+ *
+ * // Use custom config
+ * const config = getRateLimitConfig({ tokensPerMinute: 100000 });
+ *
+ * // Default (openai-tier-2)
+ * const config = getRateLimitConfig();
+ * ```
+ */
+declare function getRateLimitConfig(configOrPreset?: RateLimitConfig | RateLimitPreset | string): RateLimitConfig;
+/**
+ * Estimate tokens for a text (rough approximation).
+ * Uses ~4 characters per token as a conservative estimate.
+ *
+ * @param text - Text to estimate
+ * @returns Estimated token count
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Estimate tokens for multiple texts.
+ *
+ * @param texts - Array of texts
+ * @returns Total estimated token count
+ */
+declare function estimateBatchTokens(texts: string[]): number;
+
+/**
+ * @module @kb-labs/core-resource-broker/retry/error-classifier
+ * Error classification for retry logic.
+ */
+
+/**
+ * Classify an error for retry decision.
+ *
+ * @param error - Error to classify
+ * @returns Error type classification
+ */
+declare function classifyError(error: unknown): ErrorType;
+/**
+ * Check if an error is a rate limit error (429).
+ */
+declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Check if an error is retryable.
+ *
+ * @param error - Error to check
+ * @param retryableTypes - Types that should be retried
+ */
+declare function isRetryableError(error: unknown, retryableTypes?: ErrorType[]): boolean;
+/**
+ * Extract retry-after hint from error if available.
+ *
+ * @param error - Error to extract hint from
+ * @returns Milliseconds to wait, or undefined
+ */
+declare function extractRetryAfter(error: unknown): number | undefined;
+
+/**
+ * @module @kb-labs/core-resource-broker/retry/retry-strategy
+ * Exponential backoff retry strategy with jitter.
+ */
+
+/**
+ * Result of a retry decision.
+ */
+interface RetryDecision {
+    /** Whether to retry */
+    shouldRetry: boolean;
+    /** Delay before retry (ms) */
+    delayMs: number;
+    /** Error classification */
+    errorType: ErrorType;
+    /** Current attempt number (0-indexed) */
+    attempt: number;
+    /** Maximum attempts allowed */
+    maxAttempts: number;
+}
+/**
+ * Calculate delay with exponential backoff and jitter.
+ *
+ * Formula: min(maxDelay, baseDelay * 2^attempt) * (1 + random * jitter)
+ *
+ * @param attempt - Current attempt (0-indexed)
+ * @param config - Retry configuration
+ * @param retryAfterHint - Optional retry-after hint from error (ms)
+ * @returns Delay in milliseconds
+ */
+declare function calculateBackoffDelay(attempt: number, config: RetryConfig, retryAfterHint?: number): number;
+/**
+ * Decide whether to retry based on error and attempt count.
+ *
+ * @param error - The error that occurred
+ * @param attempt - Current attempt (0-indexed)
+ * @param config - Retry configuration
+ * @returns Retry decision with delay
+ *
+ * @example
+ * ```typescript
+ * const decision = shouldRetry(error, 0, config);
+ *
+ * if (decision.shouldRetry) {
+ *   await sleep(decision.delayMs);
+ *   // retry...
+ * } else {
+ *   throw error;
+ * }
+ * ```
+ */
+declare function shouldRetry(error: unknown, attempt: number, config?: Partial<RetryConfig>): RetryDecision;
+/**
+ * Execute a function with retry logic.
+ *
+ * @param fn - Function to execute
+ * @param config - Retry configuration
+ * @returns Result of the function
+ * @throws Last error if all retries exhausted
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   async () => {
+ *     return await llm.complete(prompt);
+ *   },
+ *   { maxRetries: 3, baseDelay: 1000 }
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, config?: Partial<RetryConfig>): Promise<{
+    result: T;
+    attempts: number;
+}>;
+/**
+ * Sleep for a specified duration.
+ *
+ * @param ms - Milliseconds to sleep
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Create a retry configuration for rate-limited APIs.
+ *
+ * @param maxRetries - Maximum retry attempts (default: 5)
+ * @returns Retry config optimized for rate limits
+ */
+declare function createRateLimitRetryConfig(maxRetries?: number): RetryConfig;
+/**
+ * Create a retry configuration for quick operations.
+ *
+ * @param maxRetries - Maximum retry attempts (default: 3)
+ * @returns Retry config with fast retries
+ */
+declare function createQuickRetryConfig(maxRetries?: number): RetryConfig;
+
+/**
+ * @module @kb-labs/core-resource-broker/wrappers/queued-llm
+ * QueuedLLM - ILLM wrapper that routes requests through ResourceBroker.
+ */
+
+/**
+ * Extended LLM options with priority.
+ */
+interface QueuedLLMOptions extends LLMOptions {
+    /** Request priority (default: 'normal') */
+    priority?: ResourcePriority;
+}
+/**
+ * ILLM wrapper that routes requests through ResourceBroker.
+ *
+ * Features:
+ * - Transparent integration (implements ILLM interface)
+ * - Automatic token estimation for rate limiting
+ * - Priority support for different use cases
+ * - Retry and rate limiting handled by broker
+ *
+ * Note: stream() bypasses the queue for real-time UX.
+ *
+ * @example
+ * ```typescript
+ * const queuedLLM = new QueuedLLM(broker, realLLM);
+ *
+ * // Normal request (goes through queue)
+ * const response = await queuedLLM.complete(prompt);
+ *
+ * // High priority request
+ * const response = await queuedLLM.complete(prompt, { priority: 'high' });
+ *
+ * // Stream (bypasses queue for real-time)
+ * for await (const chunk of queuedLLM.stream(prompt)) {
+ *   process.stdout.write(chunk);
+ * }
+ * ```
+ */
+declare class QueuedLLM implements ILLM {
+    private broker;
+    private realLLM;
+    constructor(broker: IResourceBroker, realLLM: ILLM);
+    /**
+     * 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
+     */
+    complete(prompt: string, options?: QueuedLLMOptions): Promise<LLMResponse>;
+    getProtocolCapabilities(): Promise<LLMProtocolCapabilities>;
+    /**
+     * 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: string, options?: LLMOptions): AsyncIterable<string>;
+    /**
+     * Chat with native tool calling support (proxies to underlying LLM).
+     * Currently NOT queued - passes through directly for simplicity.
+     * TODO: Add queueing support when needed.
+     */
+    chatWithTools(messages: LLMMessage[], options: LLMToolCallOptions): Promise<LLMToolCallResponse>;
+}
+/**
+ * Create a QueuedLLM wrapper.
+ *
+ * @param broker - ResourceBroker instance
+ * @param llm - Real ILLM implementation
+ * @returns Wrapped ILLM that routes through broker
+ */
+declare function createQueuedLLM(broker: IResourceBroker, llm: ILLM): QueuedLLM;
+
+/**
+ * @module @kb-labs/core-resource-broker/wrappers/queued-embeddings
+ * QueuedEmbeddings - IEmbeddings wrapper that routes requests through ResourceBroker.
+ */
+
+/**
+ * Options for queued embeddings operations.
+ */
+interface QueuedEmbeddingsOptions {
+    /** Request priority (default: 'normal') */
+    priority?: ResourcePriority;
+}
+/**
+ * IEmbeddings wrapper that routes requests through ResourceBroker.
+ *
+ * Features:
+ * - Transparent integration (implements IEmbeddings interface)
+ * - Automatic token estimation for rate limiting
+ * - Batch operations with proper token accounting
+ * - Priority support for different use cases
+ *
+ * @example
+ * ```typescript
+ * const queuedEmbeddings = new QueuedEmbeddings(broker, realEmbeddings);
+ *
+ * // Single embedding
+ * const vector = await queuedEmbeddings.embed("Hello world");
+ *
+ * // Batch embedding
+ * const vectors = await queuedEmbeddings.embedBatch(["Hello", "World"]);
+ * ```
+ */
+declare class QueuedEmbeddings implements IEmbeddings {
+    private broker;
+    private realEmbeddings;
+    private _priority;
+    constructor(broker: IResourceBroker, realEmbeddings: IEmbeddings);
+    /**
+     * Get embedding dimensions from the underlying implementation.
+     */
+    get dimensions(): number;
+    /**
+     * Set default priority for subsequent operations.
+     *
+     * @param priority - Priority level
+     * @returns this for chaining
+     */
+    withPriority(priority: ResourcePriority): 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
+     */
+    embed(text: string): Promise<number[]>;
+    /**
+     * 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
+     */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Get the dimensions of the embeddings.
+     * This method is needed for IPC/Unix Socket transport to access the dimensions property.
+     */
+    getDimensions(): Promise<number>;
+}
+/**
+ * Create a QueuedEmbeddings wrapper.
+ *
+ * @param broker - ResourceBroker instance
+ * @param embeddings - Real IEmbeddings implementation
+ * @returns Wrapped IEmbeddings that routes through broker
+ */
+declare function createQueuedEmbeddings(broker: IResourceBroker, embeddings: IEmbeddings): QueuedEmbeddings;
+
+/**
+ * @module @kb-labs/core-resource-broker/wrappers/queued-vector-store
+ * QueuedVectorStore - IVectorStore wrapper that routes requests through ResourceBroker.
+ */
+
+/**
+ * Options for queued vector store operations.
+ */
+interface QueuedVectorStoreOptions {
+    /** Request priority (default: 'normal') */
+    priority?: ResourcePriority;
+}
+/**
+ * IVectorStore wrapper that routes requests through ResourceBroker.
+ *
+ * Features:
+ * - Transparent integration (implements IVectorStore interface)
+ * - Rate limiting for batch operations
+ * - Priority support for different use cases
+ * - Search operations prioritized over bulk upserts
+ *
+ * @example
+ * ```typescript
+ * const queuedVectorStore = new QueuedVectorStore(broker, realVectorStore);
+ *
+ * // Search (typically high priority)
+ * const results = await queuedVectorStore.search(queryVector, 10);
+ *
+ * // Bulk upsert (typically normal/low priority)
+ * await queuedVectorStore.upsert(vectors);
+ * ```
+ */
+declare class QueuedVectorStore implements IVectorStore {
+    private broker;
+    private realVectorStore;
+    private _priority;
+    constructor(broker: IResourceBroker, realVectorStore: IVectorStore);
+    /**
+     * Set default priority for subsequent operations.
+     *
+     * @param priority - Priority level
+     * @returns this for chaining
+     */
+    withPriority(priority: ResourcePriority): 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
+     */
+    search(query: number[], limit: number, filter?: VectorFilter): Promise<VectorSearchResult[]>;
+    /**
+     * Upsert vectors through the queue.
+     *
+     * @param vectors - Array of vector records to upsert
+     * @throws Error if request fails after all retries
+     */
+    upsert(vectors: VectorRecord[]): Promise<void>;
+    /**
+     * Delete vectors through the queue.
+     *
+     * @param ids - Array of vector IDs to delete
+     * @throws Error if request fails after all retries
+     */
+    delete(ids: string[]): Promise<void>;
+    /**
+     * Get total count of vectors through the queue.
+     *
+     * @returns Vector count
+     * @throws Error if request fails after all retries
+     */
+    count(): Promise<number>;
+    /**
+     * 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
+     */
+    get(ids: string[]): Promise<VectorRecord[]>;
+    /**
+     * 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
+     */
+    query(filter: VectorFilter): Promise<VectorRecord[]>;
+}
+/**
+ * Create a QueuedVectorStore wrapper.
+ *
+ * @param broker - ResourceBroker instance
+ * @param vectorStore - Real IVectorStore implementation
+ * @returns Wrapped IVectorStore that routes through broker
+ */
+declare function createQueuedVectorStore(broker: IResourceBroker, vectorStore: IVectorStore): QueuedVectorStore;
+
+export { type AcquireResult, DEFAULT_RATE_LIMIT_CONFIG, DEFAULT_RETRY_CONFIG, type ErrorType, type IResourceBroker, InMemoryRateLimitBackend, PriorityQueue, type QueueItem, QueuedEmbeddings, type QueuedEmbeddingsOptions, QueuedLLM, type QueuedLLMOptions, QueuedVectorStore, type QueuedVectorStoreOptions, RATE_LIMIT_PRESETS, type RateLimitBackend, type RateLimitConfig, type RateLimitPreset, type RateLimitStats, ResourceBroker, type ResourceBrokerStats, type ResourceConfig, type ResourceExecutor, type ResourcePriority, type ResourceRequest, type ResourceResponse, type ResourceStats, type RetryConfig, type RetryDecision, StateBrokerRateLimitBackend, calculateBackoffDelay, classifyError, createQueuedEmbeddings, createQueuedLLM, createQueuedVectorStore, createQuickRetryConfig, createRateLimitRetryConfig, estimateBatchTokens, estimateTokens, extractRetryAfter, getRateLimitConfig, isRateLimitError, isRetryableError, shouldRetry, sleep, withRetry };