recursive-llm-ts 5.1.1 → 5.2.3

package/dist/{bridge-factory.js → cjs/bridge-factory.js}

@@ -45,15 +45,39 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.createBridge = createBridge;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const pkg_dir_1 = require("./pkg-dir");
 const DEFAULT_GO_BINARY = process.platform === 'win32' ? 'rlm-go.exe' : 'rlm-go';
 function resolveDefaultGoBinary() {
-    return path.join(__dirname, '..', 'bin', DEFAULT_GO_BINARY);
+    return path.join(pkg_dir_1.PKG_ROOT_DIR, 'bin', DEFAULT_GO_BINARY);
+}
+/** 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 isPlatformBinaryAvailable() {
+    const key = `${process.platform}-${process.arch}`;
+    const pkgName = PLATFORM_PACKAGES[key];
+    if (!pkgName)
+        return false;
+    try {
+        const pkgDir = path.dirname(require.resolve(`${pkgName}/package.json`));
+        return fs.existsSync(path.join(pkgDir, 'bin', DEFAULT_GO_BINARY));
+    }
+    catch (_a) {
+        return false;
+    }
 }
 function isGoBinaryAvailable() {
     const envPath = process.env.RLM_GO_BINARY;
     if (envPath && fs.existsSync(envPath)) {
         return true;
     }
+    if (isPlatformBinaryAvailable())
+        return true;
     return fs.existsSync(resolveDefaultGoBinary());
 }
 /**

package/dist/{go-bridge.js → cjs/go-bridge.js}

@@ -57,16 +57,48 @@ exports.GoBridge = void 0;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const child_process_1 = require("child_process");
+const pkg_dir_1 = require("./pkg-dir");
 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;
     }
-    // Try multiple locations
+    // 1. Try platform-specific npm package (pre-built binary)
+    const platformBin = resolvePlatformBinary();
+    if (platformBin)
+        return platformBin;
+    // 2. Try local locations
     const possiblePaths = [
-        path.join(__dirname, '..', 'bin', DEFAULT_BINARY_NAME), // NPM package (primary)
-        path.join(__dirname, '..', 'go', DEFAULT_BINARY_NAME), // Development fallback
+        path.join(pkg_dir_1.PKG_ROOT_DIR, 'bin', DEFAULT_BINARY_NAME), // NPM package (primary)
+        path.join(pkg_dir_1.PKG_ROOT_DIR, 'go', DEFAULT_BINARY_NAME), // Development fallback
     ];
     for (const p of possiblePaths) {
         if (fs.existsSync(p)) {

package/dist/cjs/package.json

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

package/dist/cjs/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/cjs/pkg-dir.js

@@ -0,0 +1,79 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PKG_ROOT_DIR = exports.PKG_DIST_DIR = void 0;
+/**
+ * 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).
+ */
+const path = __importStar(require("path"));
+const url_1 = require("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((0, url_1.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) */
+exports.PKG_DIST_DIR = resolveCurrentDir();
+/**
+ * Package root directory.
+ * Handles both flat (dist/) and nested (dist/cjs/, dist/esm/) layouts.
+ */
+exports.PKG_ROOT_DIR = (() => {
+    const parent = path.dirname(exports.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/bridge-factory.d.ts

@@ -0,0 +1,7 @@
+import { Bridge } from './bridge-interface';
+export type BridgeType = 'go';
+/**
+ * Create the Go bridge for RLM communication.
+ * Throws if the Go binary is not available.
+ */
+export declare function createBridge(bridgeType?: BridgeType): Promise<Bridge>;

package/dist/esm/bridge-factory.js

@@ -0,0 +1,60 @@
+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 * as fs from 'fs';
+import * as path from 'path';
+import { PKG_ROOT_DIR } from './pkg-dir.js';
+const DEFAULT_GO_BINARY = process.platform === 'win32' ? 'rlm-go.exe' : 'rlm-go';
+function resolveDefaultGoBinary() {
+    return path.join(PKG_ROOT_DIR, 'bin', DEFAULT_GO_BINARY);
+}
+/** 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 isPlatformBinaryAvailable() {
+    const key = `${process.platform}-${process.arch}`;
+    const pkgName = PLATFORM_PACKAGES[key];
+    if (!pkgName)
+        return false;
+    try {
+        const pkgDir = path.dirname(require.resolve(`${pkgName}/package.json`));
+        return fs.existsSync(path.join(pkgDir, 'bin', DEFAULT_GO_BINARY));
+    }
+    catch (_a) {
+        return false;
+    }
+}
+function isGoBinaryAvailable() {
+    const envPath = process.env.RLM_GO_BINARY;
+    if (envPath && fs.existsSync(envPath)) {
+        return true;
+    }
+    if (isPlatformBinaryAvailable())
+        return true;
+    return fs.existsSync(resolveDefaultGoBinary());
+}
+/**
+ * Create the Go bridge for RLM communication.
+ * Throws if the Go binary is not available.
+ */
+export function createBridge() {
+    return __awaiter(this, arguments, void 0, function* (bridgeType = 'go') {
+        if (!isGoBinaryAvailable()) {
+            throw new Error('Go RLM binary not found. Build it with: node scripts/build-go-binary.js\n' +
+                'Ensure Go 1.25+ is installed: https://go.dev/dl/');
+        }
+        const { GoBridge } = yield import('./go-bridge.js');
+        return new GoBridge();
+    });
+}

package/dist/esm/bridge-interface.d.ts

@@ -0,0 +1,269 @@
+export interface RLMStats {
+    llm_calls: number;
+    iterations: number;
+    depth: number;
+    parsing_retries?: number;
+    total_tokens?: number;
+    prompt_tokens?: number;
+    completion_tokens?: number;
+}
+export interface RLMResult {
+    result: string;
+    stats: RLMStats;
+    structured_result?: boolean;
+    trace_events?: TraceEvent[];
+}
+export interface MetaAgentConfig {
+    enabled: boolean;
+    model?: string;
+    max_optimize_len?: number;
+}
+export interface ObservabilityConfig {
+    debug?: boolean;
+    trace_enabled?: boolean;
+    trace_endpoint?: string;
+    service_name?: string;
+    log_output?: string;
+    langfuse_enabled?: boolean;
+    langfuse_public_key?: string;
+    langfuse_secret_key?: string;
+    langfuse_host?: string;
+}
+export interface TraceEvent {
+    timestamp: string;
+    type: string;
+    name: string;
+    attributes: Record<string, string>;
+    duration?: number;
+    trace_id?: string;
+    span_id?: string;
+    parent_id?: string;
+}
+export interface ContextOverflowConfig {
+    /** Enable automatic context overflow recovery (default: true) */
+    enabled?: boolean;
+    /** Override detected model token limit (0 = auto-detect from API errors) */
+    max_model_tokens?: number;
+    /** Strategy: 'mapreduce' (default), 'truncate', 'chunked', 'tfidf', 'textrank', or 'refine' */
+    strategy?: 'mapreduce' | 'truncate' | 'chunked' | 'tfidf' | 'textrank' | 'refine';
+    /** Fraction of token budget to reserve for prompts/overhead (default: 0.15) */
+    safety_margin?: number;
+    /** Maximum reduction attempts before giving up (default: 3) */
+    max_reduction_attempts?: number;
+}
+export interface LCMConfig {
+    /** Enable LCM context management (default: false for backward compat) */
+    enabled?: boolean;
+    /** Soft token threshold — async compaction begins above this (default: 70% of model limit) */
+    soft_threshold?: number;
+    /** Hard token threshold — blocking compaction above this (default: 90% of model limit) */
+    hard_threshold?: number;
+    /** Number of messages to compact at once (default: 10) */
+    compaction_block_size?: number;
+    /** Target tokens per summary node (default: 500) */
+    summary_target_tokens?: number;
+    /** Large file handling configuration */
+    file_handling?: LCMFileConfig;
+    /** Episode-based context grouping configuration */
+    episodes?: EpisodeConfig;
+    /** Persistence backend configuration (default: in-memory) */
+    store_backend?: StoreBackendConfig;
+}
+export interface LCMFileConfig {
+    /** Token count above which files are stored externally with exploration summaries (default: 25000) */
+    token_threshold?: number;
+}
+export interface EpisodeConfig {
+    /** Max tokens before auto-closing an episode (default: 2000) */
+    max_episode_tokens?: number;
+    /** Max messages before auto-closing an episode (default: 20) */
+    max_episode_messages?: number;
+    /** Topic change sensitivity 0-1 (reserved for future semantic detection) */
+    topic_change_threshold?: number;
+    /** Auto-generate summary when episode closes (default: true) */
+    auto_compact_after_close?: boolean;
+}
+export interface Episode {
+    id: string;
+    title: string;
+    message_ids: string[];
+    start_time: string;
+    end_time: string;
+    tokens: number;
+    summary?: string;
+    summary_tokens?: number;
+    status: 'active' | 'compacted' | 'archived';
+    tags?: string[];
+    parent_episode_id?: string;
+}
+export interface StoreBackendConfig {
+    /** Backend type: 'memory' (default) or 'sqlite' */
+    type?: 'memory' | 'sqlite';
+    /** Path for SQLite database file (required when type is 'sqlite', use ':memory:' for in-memory SQLite) */
+    path?: string;
+}
+export interface LLMMapConfig {
+    /** Path to JSONL input file */
+    input_path: string;
+    /** Path to JSONL output file */
+    output_path: string;
+    /** Prompt template — use {{item}} as placeholder for each item */
+    prompt: string;
+    /** JSON Schema for output validation */
+    output_schema?: Record<string, any>;
+    /** Worker pool concurrency (default: 16) */
+    concurrency?: number;
+    /** Per-item retry limit (default: 3) */
+    max_retries?: number;
+    /** Model to use (defaults to engine model) */
+    model?: string;
+}
+export interface LLMMapResult {
+    total_items: number;
+    completed: number;
+    failed: number;
+    output_path: string;
+    duration_ms: number;
+    tokens_used: number;
+}
+export interface AgenticMapConfig {
+    /** Path to JSONL input file */
+    input_path: string;
+    /** Path to JSONL output file */
+    output_path: string;
+    /** Prompt template — use {{item}} as placeholder for each item */
+    prompt: string;
+    /** JSON Schema for output validation */
+    output_schema?: Record<string, any>;
+    /** Worker pool concurrency (default: 8) */
+    concurrency?: number;
+    /** Per-item retry limit (default: 2) */
+    max_retries?: number;
+    /** Model for sub-agents (defaults to engine model) */
+    model?: string;
+    /** If true, sub-agents cannot modify filesystem */
+    read_only?: boolean;
+    /** Max recursion depth for sub-agents (default: 3) */
+    max_depth?: number;
+    /** Max iterations per sub-agent (default: 15) */
+    max_iterations?: number;
+}
+export interface AgenticMapResult {
+    total_items: number;
+    completed: number;
+    failed: number;
+    output_path: string;
+    duration_ms: number;
+    tokens_used: number;
+}
+export interface DelegationRequest {
+    /** Task description for the sub-agent */
+    prompt: string;
+    /** Specific slice of work being handed off (required for non-root) */
+    delegated_scope?: string;
+    /** Work the caller retains (required for non-root) */
+    kept_work?: string;
+    /** Read-only exploration agent (exempt from guard) */
+    read_only?: boolean;
+    /** Parallel decomposition (exempt from guard) */
+    parallel?: boolean;
+}
+export interface LCMStoreStats {
+    total_messages: number;
+    total_summaries: number;
+    active_context_items: number;
+    active_context_tokens: number;
+    immutable_store_tokens: number;
+    compression_ratio: number;
+}
+export interface LCMGrepResult {
+    message_id: string;
+    role: string;
+    content: string;
+    summary_id?: string;
+    match_line: string;
+}
+export interface LCMDescribeResult {
+    type: 'message' | 'summary';
+    id: string;
+    tokens: number;
+    role?: string;
+    kind?: 'leaf' | 'condensed';
+    level?: number;
+    covered_ids?: string[];
+    file_ids?: string[];
+    content?: string;
+}
+export interface EpisodeListResult {
+    episodes: Episode[];
+    active_episode_id?: string;
+    total_episodes: number;
+}
+export interface RLMConfig {
+    recursive_model?: string;
+    api_base?: string;
+    api_key?: string;
+    max_depth?: number;
+    max_iterations?: number;
+    go_binary_path?: string;
+    meta_agent?: MetaAgentConfig;
+    observability?: ObservabilityConfig;
+    context_overflow?: ContextOverflowConfig;
+    lcm?: LCMConfig;
+    debug?: boolean;
+    api_version?: string;
+    timeout?: number;
+    temperature?: number;
+    max_tokens?: number;
+    structured?: any;
+    [key: string]: any;
+}
+export interface FileStorageConfig {
+    /** Storage type: 'local' or 's3' */
+    type: 'local' | 's3';
+    /** For local: root directory path. For S3: bucket name */
+    path: string;
+    /** For S3: the prefix (folder path) within the bucket */
+    prefix?: string;
+    /** For S3: AWS region (falls back to AWS_REGION env var, then 'us-east-1') */
+    region?: string;
+    /**
+     * For S3: explicit credentials.
+     * Resolution order:
+     * 1. This field (explicit credentials)
+     * 2. Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
+     * 3. AWS SDK default credential chain (IAM role, ~/.aws/credentials, ECS task role, etc.)
+     */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+    /**
+     * For S3: custom endpoint URL.
+     * Use for S3-compatible services: MinIO, LocalStack, DigitalOcean Spaces, Backblaze B2.
+     * When set, forcePathStyle is automatically enabled.
+     */
+    endpoint?: string;
+    /**
+     * For S3: force path-style addressing (bucket in path, not subdomain).
+     * Automatically true when endpoint is set.
+     */
+    forcePathStyle?: boolean;
+    /** Glob patterns to include (e.g. ['*.ts', '*.md']) */
+    includePatterns?: string[];
+    /** Glob patterns to exclude (e.g. ['node_modules/**']) */
+    excludePatterns?: string[];
+    /** Maximum file size in bytes to include (default: 1MB) */
+    maxFileSize?: number;
+    /** Maximum total context size in bytes (default: 10MB) */
+    maxTotalSize?: number;
+    /** Maximum number of files to include (default: 1000) */
+    maxFiles?: number;
+    /** File extensions to include (e.g. ['.ts', '.md', '.txt']) */
+    extensions?: string[];
+}
+export interface Bridge {
+    completion(model: string, query: string, context: string, rlmConfig: RLMConfig): Promise<RLMResult>;
+    cleanup(): Promise<void>;
+}

package/dist/esm/bridge-interface.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/cache.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Caching layer for recursive-llm-ts completions.
+ *
+ * Provides exact-match caching to avoid redundant API calls for
+ * identical query+context pairs. Supports in-memory and file-based storage.
+ */
+export interface CacheConfig {
+    /** Enable/disable caching (default: false) */
+    enabled?: boolean;
+    /** Cache strategy (default: 'exact') */
+    strategy?: 'exact' | 'none';
+    /** Maximum number of cached entries (default: 1000) */
+    maxEntries?: number;
+    /** Time-to-live in seconds (default: 3600 = 1 hour) */
+    ttl?: number;
+    /** Storage backend (default: 'memory') */
+    storage?: 'memory' | 'file';
+    /** Directory for file-based cache (default: .rlm-cache) */
+    cacheDir?: string;
+}
+export interface CacheStats {
+    hits: number;
+    misses: number;
+    size: number;
+    hitRate: number;
+    evictions: number;
+}
+export interface CacheProvider {
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+}
+export declare class MemoryCache implements CacheProvider {
+    private store;
+    private maxEntries;
+    constructor(maxEntries?: number);
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+}
+export declare class FileCache implements CacheProvider {
+    private cacheDir;
+    private maxEntries;
+    constructor(cacheDir?: string, maxEntries?: number);
+    private filePath;
+    get<T>(key: string): T | undefined;
+    set<T>(key: string, value: T, ttl: number): void;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    clear(): void;
+    size(): number;
+}
+export declare class RLMCache {
+    private provider;
+    private config;
+    private stats;
+    constructor(config?: CacheConfig);
+    /** Check if caching is enabled */
+    get enabled(): boolean;
+    /** Look up a cached result */
+    lookup<T>(model: string, query: string, context: string, extra?: Record<string, unknown>): {
+        hit: boolean;
+        value?: T;
+    };
+    /** Store a result in the cache */
+    store<T>(model: string, query: string, context: string, value: T, extra?: Record<string, unknown>): void;
+    /** Get cache statistics */
+    getStats(): CacheStats;
+    /** Clear the cache */
+    clear(): void;
+    private updateHitRate;
+}