recursive-llm-ts 5.0.2 → 5.2.3

package/dist/esm/go-bridge.js

@@ -0,0 +1,133 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import * as fs from 'fs';
+import * as path from 'path';
+import { spawn } from 'child_process';
+import { PKG_ROOT_DIR } from './pkg-dir.js';
+const DEFAULT_BINARY_NAME = process.platform === 'win32' ? 'rlm-go.exe' : 'rlm-go';
+/** Platform-specific npm package names for pre-built binaries */
+const PLATFORM_PACKAGES = {
+    'darwin-arm64': '@recursive-llm/darwin-arm64',
+    'darwin-x64': '@recursive-llm/darwin-x64',
+    'linux-x64': '@recursive-llm/linux-x64',
+    'linux-arm64': '@recursive-llm/linux-arm64',
+    'win32-x64': '@recursive-llm/win32-x64',
+};
+function resolvePlatformBinary() {
+    const platform = process.platform;
+    const arch = process.arch;
+    const key = `${platform}-${arch}`;
+    const pkgName = PLATFORM_PACKAGES[key];
+    if (!pkgName)
+        return null;
+    try {
+        // require.resolve works in both CJS and ESM (via createRequire)
+        const pkgDir = path.dirname(require.resolve(`${pkgName}/package.json`));
+        const binPath = path.join(pkgDir, 'bin', DEFAULT_BINARY_NAME);
+        if (fs.existsSync(binPath))
+            return binPath;
+    }
+    catch (_a) {
+        // Package not installed — fall through
+    }
+    return null;
+}
+function resolveBinaryPath(rlmConfig) {
+    const configuredPath = rlmConfig.go_binary_path || process.env.RLM_GO_BINARY;
+    if (configuredPath) {
+        return configuredPath;
+    }
+    // 1. Try platform-specific npm package (pre-built binary)
+    const platformBin = resolvePlatformBinary();
+    if (platformBin)
+        return platformBin;
+    // 2. Try local locations
+    const possiblePaths = [
+        path.join(PKG_ROOT_DIR, 'bin', DEFAULT_BINARY_NAME), // NPM package (primary)
+        path.join(PKG_ROOT_DIR, 'go', DEFAULT_BINARY_NAME), // Development fallback
+    ];
+    for (const p of possiblePaths) {
+        if (fs.existsSync(p)) {
+            return p;
+        }
+    }
+    return possiblePaths[0]; // Return first path, error will be caught later
+}
+function assertBinaryExists(binaryPath) {
+    if (!fs.existsSync(binaryPath)) {
+        throw new Error(`Go RLM binary not found at ${binaryPath}.\n` +
+            'Build it with: node scripts/build-go-binary.js');
+    }
+}
+function sanitizeConfig(config) {
+    const { go_binary_path, structured } = config, sanitized = __rest(config, ["go_binary_path", "structured"]);
+    return { config: sanitized, structured };
+}
+export class GoBridge {
+    completion(model_1, query_1, context_1) {
+        return __awaiter(this, arguments, void 0, function* (model, query, context, rlmConfig = {}) {
+            const binaryPath = resolveBinaryPath(rlmConfig);
+            assertBinaryExists(binaryPath);
+            const { config, structured } = sanitizeConfig(rlmConfig);
+            const payload = JSON.stringify({
+                model,
+                query,
+                context,
+                config,
+                structured
+            });
+            return new Promise((resolve, reject) => {
+                const child = spawn(binaryPath, [], { stdio: ['pipe', 'pipe', 'pipe'] });
+                let stdout = '';
+                let stderr = '';
+                child.stdout.on('data', (data) => {
+                    stdout += data.toString();
+                });
+                child.stderr.on('data', (data) => {
+                    stderr += data.toString();
+                });
+                child.on('error', (error) => {
+                    reject(new Error(`Failed to start Go binary: ${error.message}`));
+                });
+                child.on('close', (code) => {
+                    if (code !== 0) {
+                        reject(new Error(stderr || `Go binary exited with code ${code}`));
+                        return;
+                    }
+                    try {
+                        const parsed = JSON.parse(stdout);
+                        resolve(parsed);
+                    }
+                    catch (error) {
+                        reject(new Error(`Failed to parse Go response: ${error.message || error}`));
+                    }
+                });
+                child.stdin.write(payload);
+                child.stdin.end();
+            });
+        });
+    }
+    cleanup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            // No persistent processes to clean up.
+        });
+    }
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,12 @@
+export { RLM, RLMBuilder, RLMCompletionResult, RLMResultFormatter } from './rlm';
+export { RLMConfig, RLMResult, RLMStats, MetaAgentConfig, ObservabilityConfig, TraceEvent, FileStorageConfig, ContextOverflowConfig } from './bridge-interface';
+export { BridgeType } from './bridge-factory';
+export { StructuredRLMResult, SubTask, CoordinatorConfig, SchemaDecomposition } from './structured-types';
+export { RLMExtendedConfig, ValidationResult, ValidationIssue, ValidationLevel, validateConfig, assertValidConfig } from './config';
+export { RLMError, RLMValidationError, RLMRateLimitError, RLMTimeoutError, RLMProviderError, RLMBinaryError, RLMConfigError, RLMSchemaError, RLMContextOverflowError, RLMAbortError, classifyError, } from './errors';
+export { RLMStream, StreamOptions, StreamChunk, StreamChunkType, TextStreamChunk, PartialObjectStreamChunk, UsageStreamChunk, ErrorStreamChunk, DoneStreamChunk, createSimulatedStream, } from './streaming';
+export { RLMCache, CacheConfig, CacheStats, CacheProvider, MemoryCache, FileCache } from './cache';
+export { RetryConfig, FallbackConfig, withRetry, withFallback } from './retry';
+export { RLMEventEmitter, RLMEventMap, RLMEventType, LLMCallEvent, LLMResponseEvent, ValidationRetryEvent, RecursionEvent, MetaAgentEvent, ErrorEvent, CompletionStartEvent, CompletionEndEvent, CacheEvent, RetryEvent, } from './events';
+export { RLMAgentCoordinator } from './coordinator';
+export { FileContextBuilder, FileStorageProvider, FileStorageResult, FileEntry, LocalFileStorage, S3FileStorage, S3StorageError, buildFileContext, } from './file-storage';

package/dist/esm/index.js

@@ -0,0 +1,17 @@
+// ─── Core ────────────────────────────────────────────────────────────────────
+export { RLM, RLMBuilder, RLMResultFormatter } from './rlm.js';
+export { validateConfig, assertValidConfig } from './config.js';
+// ─── Errors ──────────────────────────────────────────────────────────────────
+export { RLMError, RLMValidationError, RLMRateLimitError, RLMTimeoutError, RLMProviderError, RLMBinaryError, RLMConfigError, RLMSchemaError, RLMContextOverflowError, RLMAbortError, classifyError, } from './errors.js';
+// ─── Streaming ───────────────────────────────────────────────────────────────
+export { RLMStream, createSimulatedStream, } from './streaming.js';
+// ─── Cache ───────────────────────────────────────────────────────────────────
+export { RLMCache, MemoryCache, FileCache } from './cache.js';
+// ─── Retry / Resilience ──────────────────────────────────────────────────────
+export { withRetry, withFallback } from './retry.js';
+// ─── Events ──────────────────────────────────────────────────────────────────
+export { RLMEventEmitter, } from './events.js';
+// ─── Coordinator ─────────────────────────────────────────────────────────────
+export { RLMAgentCoordinator } from './coordinator.js';
+// ─── File Storage ────────────────────────────────────────────────────────────
+export { FileContextBuilder, LocalFileStorage, S3FileStorage, S3StorageError, buildFileContext, } from './file-storage.js';

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/pkg-dir.d.ts

@@ -0,0 +1,7 @@
+/** Directory containing the compiled JS file (dist/cjs or dist/esm or dist) */
+export declare const PKG_DIST_DIR: string;
+/**
+ * Package root directory.
+ * Handles both flat (dist/) and nested (dist/cjs/, dist/esm/) layouts.
+ */
+export declare const PKG_ROOT_DIR: string;

package/dist/esm/pkg-dir.js

@@ -0,0 +1,43 @@
+/**
+ * Portable package directory resolution.
+ *
+ * Works in both CommonJS and ESM contexts by detecting the available
+ * globals and falling back gracefully. The resolved path always points
+ * to the package root (parent of the dist/cjs or dist/esm directory).
+ */
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+function resolveCurrentDir() {
+    // CJS — __dirname is defined natively by Node
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    // ESM — derive from import.meta.url via indirect eval to avoid CJS parse errors.
+    // This branch only runs in ESM where import.meta is valid syntax.
+    try {
+        const meta = new Function('return import.meta')();
+        if (meta && typeof meta.url === 'string') {
+            return path.dirname(fileURLToPath(meta.url));
+        }
+    }
+    catch (_a) {
+        // Not in ESM or import.meta not supported
+    }
+    // Last resort: use process.cwd()
+    return process.cwd();
+}
+/** Directory containing the compiled JS file (dist/cjs or dist/esm or dist) */
+export const PKG_DIST_DIR = resolveCurrentDir();
+/**
+ * Package root directory.
+ * Handles both flat (dist/) and nested (dist/cjs/, dist/esm/) layouts.
+ */
+export const PKG_ROOT_DIR = (() => {
+    const parent = path.dirname(PKG_DIST_DIR);
+    const parentBase = path.basename(parent);
+    // If parent is 'dist', we're in dist/cjs or dist/esm — go up one more
+    if (parentBase === 'dist') {
+        return path.dirname(parent);
+    }
+    return parent;
+})();

package/dist/esm/retry.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Retry and resilience layer for recursive-llm-ts.
+ *
+ * Provides configurable retry with exponential backoff, jitter,
+ * and provider fallback chains.
+ */
+export interface RetryConfig {
+    /** Maximum number of retries (default: 3) */
+    maxRetries?: number;
+    /** Backoff strategy (default: 'exponential') */
+    backoff?: 'exponential' | 'linear' | 'fixed';
+    /** Base delay in milliseconds (default: 1000) */
+    baseDelay?: number;
+    /** Maximum delay in milliseconds (default: 30000) */
+    maxDelay?: number;
+    /** Add jitter to delays (default: true) */
+    jitter?: boolean;
+    /** Error types that should be retried */
+    retryableErrors?: string[];
+    /** Called before each retry with retry info */
+    onRetry?: (attempt: number, error: Error, delay: number) => void;
+}
+/** Fallback model configuration */
+export interface FallbackConfig {
+    /** Ordered list of fallback models to try */
+    models?: string[];
+    /** Strategy for fallback selection */
+    strategy?: 'sequential' | 'round-robin';
+}
+/**
+ * Execute a function with retry logic.
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => rlm.completion(query, context),
+ *   { maxRetries: 3, backoff: 'exponential' }
+ * );
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, config?: RetryConfig, signal?: AbortSignal): Promise<T>;
+/**
+ * Execute a function with fallback models.
+ * Tries each model in order until one succeeds.
+ *
+ * @example
+ * ```typescript
+ * const result = await withFallback(
+ *   (model) => rlm.completion(query, context, model),
+ *   { models: ['gpt-4o', 'claude-sonnet-4-20250514', 'gemini-2.0-flash'] }
+ * );
+ * ```
+ */
+export declare function withFallback<T>(fn: (model: string) => Promise<T>, fallbackConfig: FallbackConfig, retryConfig?: RetryConfig, signal?: AbortSignal): Promise<T & {
+    _usedModel?: string;
+}>;

package/dist/esm/retry.js

@@ -0,0 +1,181 @@
+/**
+ * Retry and resilience layer for recursive-llm-ts.
+ *
+ * Provides configurable retry with exponential backoff, jitter,
+ * and provider fallback chains.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { RLMError, RLMRateLimitError, RLMAbortError } from './errors.js';
+const DEFAULT_RETRYABLE_ERRORS = new Set([
+    'RATE_LIMIT',
+    'TIMEOUT',
+    'PROVIDER',
+    'UNKNOWN',
+]);
+function resolveConfig(config = {}) {
+    var _a, _b, _c, _d, _e;
+    return {
+        maxRetries: (_a = config.maxRetries) !== null && _a !== void 0 ? _a : 3,
+        backoff: (_b = config.backoff) !== null && _b !== void 0 ? _b : 'exponential',
+        baseDelay: (_c = config.baseDelay) !== null && _c !== void 0 ? _c : 1000,
+        maxDelay: (_d = config.maxDelay) !== null && _d !== void 0 ? _d : 30000,
+        jitter: (_e = config.jitter) !== null && _e !== void 0 ? _e : true,
+        retryableErrors: config.retryableErrors
+            ? new Set(config.retryableErrors)
+            : DEFAULT_RETRYABLE_ERRORS,
+        onRetry: config.onRetry,
+    };
+}
+// ─── Delay Calculation ───────────────────────────────────────────────────────
+function calculateDelay(attempt, config) {
+    let delay;
+    switch (config.backoff) {
+        case 'exponential':
+            delay = config.baseDelay * Math.pow(2, attempt);
+            break;
+        case 'linear':
+            delay = config.baseDelay * (attempt + 1);
+            break;
+        case 'fixed':
+            delay = config.baseDelay;
+            break;
+        default:
+            delay = config.baseDelay;
+    }
+    // Cap at max
+    delay = Math.min(delay, config.maxDelay);
+    // Add jitter (0.5x to 1.5x)
+    if (config.jitter) {
+        delay = delay * (0.5 + Math.random());
+    }
+    return Math.round(delay);
+}
+// ─── Retryable Check ─────────────────────────────────────────────────────────
+function isRetryable(error, config) {
+    // Never retry abort errors
+    if (error instanceof RLMAbortError)
+        return false;
+    // Check explicit retryable flag
+    if (error instanceof RLMError) {
+        if (!error.retryable)
+            return false;
+        return config.retryableErrors.has(error.code);
+    }
+    // For non-RLM errors, check message heuristics
+    const msg = error.message.toLowerCase();
+    if (msg.includes('rate limit') || msg.includes('429'))
+        return true;
+    if (msg.includes('timeout') || msg.includes('etimedout'))
+        return true;
+    if (msg.includes('econnreset') || msg.includes('econnrefused'))
+        return true;
+    if (msg.includes('500') || msg.includes('502') || msg.includes('503') || msg.includes('504'))
+        return true;
+    return false;
+}
+// ─── Sleep Helper ────────────────────────────────────────────────────────────
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+            reject(new RLMAbortError());
+            return;
+        }
+        const timer = setTimeout(resolve, ms);
+        if (signal) {
+            const onAbort = () => {
+                clearTimeout(timer);
+                reject(new RLMAbortError());
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+// ─── Retry Executor ──────────────────────────────────────────────────────────
+/**
+ * Execute a function with retry logic.
+ *
+ * @example
+ * ```typescript
+ * const result = await withRetry(
+ *   () => rlm.completion(query, context),
+ *   { maxRetries: 3, backoff: 'exponential' }
+ * );
+ * ```
+ */
+export function withRetry(fn, config, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const resolved = resolveConfig(config);
+        let lastError;
+        for (let attempt = 0; attempt <= resolved.maxRetries; attempt++) {
+            try {
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                    throw new RLMAbortError();
+                return yield fn();
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                lastError = error;
+                // Check if we should retry
+                if (attempt >= resolved.maxRetries || !isRetryable(error, resolved)) {
+                    throw error;
+                }
+                // Special handling for rate limit with retry-after
+                let delay;
+                if (error instanceof RLMRateLimitError && error.retryAfter) {
+                    delay = error.retryAfter * 1000;
+                }
+                else {
+                    delay = calculateDelay(attempt, resolved);
+                }
+                // Notify callback
+                (_a = resolved.onRetry) === null || _a === void 0 ? void 0 : _a.call(resolved, attempt + 1, error, delay);
+                // Wait before retrying
+                yield sleep(delay, signal);
+            }
+        }
+        throw lastError || new Error('Retry failed');
+    });
+}
+/**
+ * Execute a function with fallback models.
+ * Tries each model in order until one succeeds.
+ *
+ * @example
+ * ```typescript
+ * const result = await withFallback(
+ *   (model) => rlm.completion(query, context, model),
+ *   { models: ['gpt-4o', 'claude-sonnet-4-20250514', 'gemini-2.0-flash'] }
+ * );
+ * ```
+ */
+export function withFallback(fn, fallbackConfig, retryConfig, signal) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const models = fallbackConfig.models || [];
+        if (models.length === 0) {
+            throw new RLMError('No models configured for fallback', { code: 'CONFIG', retryable: false });
+        }
+        let lastError;
+        for (const model of models) {
+            try {
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                    throw new RLMAbortError();
+                const result = yield withRetry(() => fn(model), retryConfig, signal);
+                return Object.assign(Object.assign({}, result), { _usedModel: model });
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+                // Continue to next model
+            }
+        }
+        throw lastError || new Error('All fallback models failed');
+    });
+}