recursive-llm-ts 5.0.2 → 5.2.3

package/dist/esm/events.js

@@ -0,0 +1,73 @@
+/**
+ * Event system for recursive-llm-ts.
+ *
+ * Provides typed event emission for monitoring LLM operations,
+ * validation retries, recursion progress, and more.
+ */
+// ─── Event Emitter ───────────────────────────────────────────────────────────
+/**
+ * Typed event emitter for RLM operations.
+ *
+ * @example
+ * ```typescript
+ * const rlm = new RLM('gpt-4o-mini');
+ * rlm.on('llm_call', (event) => console.log('LLM call:', event.model));
+ * rlm.on('error', (event) => reportToSentry(event.error));
+ * ```
+ */
+export class RLMEventEmitter {
+    constructor() {
+        this.listeners = new Map();
+    }
+    /** Register an event listener */
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+        return this;
+    }
+    /** Register a one-time event listener */
+    once(event, listener) {
+        const wrapper = (e) => {
+            this.off(event, wrapper);
+            listener(e);
+        };
+        return this.on(event, wrapper);
+    }
+    /** Remove an event listener */
+    off(event, listener) {
+        var _a;
+        (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.delete(listener);
+        return this;
+    }
+    /** Remove all listeners for an event (or all events) */
+    removeAllListeners(event) {
+        if (event) {
+            this.listeners.delete(event);
+        }
+        else {
+            this.listeners.clear();
+        }
+        return this;
+    }
+    /** Emit an event to all registered listeners */
+    emit(event, data) {
+        const eventListeners = this.listeners.get(event);
+        if (eventListeners) {
+            for (const listener of eventListeners) {
+                try {
+                    listener(data);
+                }
+                catch (_a) {
+                    // Don't let listener errors break the emitter
+                }
+            }
+        }
+    }
+    /** Get the number of listeners for an event */
+    listenerCount(event) {
+        var _a, _b;
+        return (_b = (_a = this.listeners.get(event)) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0;
+    }
+}

package/dist/esm/file-storage.d.ts

@@ -0,0 +1,122 @@
+import { FileStorageConfig } from './bridge-interface';
+/**
+ * Custom error class for S3 storage operations.
+ * Provides actionable error messages for common failure modes.
+ */
+export declare class S3StorageError extends Error {
+    readonly code: string;
+    readonly bucket: string;
+    readonly key?: string;
+    readonly originalError?: Error;
+    constructor(opts: {
+        message: string;
+        code: string;
+        bucket: string;
+        key?: string;
+        originalError?: Error;
+    });
+}
+export { FileStorageConfig } from './bridge-interface';
+export interface FileEntry {
+    /** Relative path from the root of the storage source */
+    relativePath: string;
+    /** File content as a string */
+    content: string;
+    /** Size in bytes */
+    size: number;
+}
+export interface FileStorageResult {
+    /** The built context string containing all file contents */
+    context: string;
+    /** List of files that were included */
+    files: Array<{
+        relativePath: string;
+        size: number;
+    }>;
+    /** Total size of all file contents */
+    totalSize: number;
+    /** Files that were skipped and why */
+    skipped: Array<{
+        relativePath: string;
+        reason: string;
+    }>;
+}
+export interface FileStorageProvider {
+    listFiles(): Promise<string[]>;
+    readFile(relativePath: string): Promise<string>;
+    getFileSize(relativePath: string): Promise<number>;
+}
+export declare class LocalFileStorage implements FileStorageProvider {
+    private rootPath;
+    constructor(rootPath: string);
+    listFiles(): Promise<string[]>;
+    private walkDir;
+    readFile(relativePath: string): Promise<string>;
+    getFileSize(relativePath: string): Promise<number>;
+}
+/**
+ * S3FileStorage uses the AWS SDK v3 via dynamic import.
+ * If @aws-sdk/client-s3 is not installed, it throws a clear error.
+ *
+ * Supports:
+ * - AWS S3
+ * - MinIO (set endpoint to MinIO URL)
+ * - LocalStack (set endpoint to LocalStack URL, typically http://localhost:4566)
+ * - DigitalOcean Spaces, Backblaze B2, and other S3-compatible services
+ *
+ * Credential resolution order:
+ * 1. Explicit credentials in FileStorageConfig.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.)
+ */
+export declare class S3FileStorage implements FileStorageProvider {
+    private bucket;
+    private prefix;
+    private region;
+    private credentials?;
+    private endpoint?;
+    private forcePathStyle;
+    private s3Client;
+    constructor(config: FileStorageConfig);
+    /**
+     * Returns the credential source being used for debugging/logging.
+     */
+    getCredentialSource(): string;
+    private getClient;
+    private buildKey;
+    listFiles(): Promise<string[]>;
+    readFile(relativePath: string): Promise<string>;
+    getFileSize(relativePath: string): Promise<number>;
+}
+/**
+ * FileContextBuilder reads files from a storage provider, applies filters,
+ * and builds a structured context string for LLM consumption.
+ */
+export declare class FileContextBuilder {
+    private provider;
+    private config;
+    constructor(config: FileStorageConfig);
+    private createProvider;
+    /**
+     * Build a structured context string from all matching files.
+     * Files are formatted with clear delimiters so the LLM can reference them.
+     */
+    buildContext(): Promise<FileStorageResult>;
+    /**
+     * Build a file tree overview for the LLM to understand the folder structure.
+     */
+    private buildFileTree;
+    /**
+     * Format a single file's content with clear delimiters.
+     */
+    private formatFileBlock;
+    /**
+     * Get just the list of files without reading content.
+     * Useful for previewing what would be included.
+     */
+    listMatchingFiles(): Promise<string[]>;
+}
+/**
+ * Convenience function to build context from a file storage config.
+ */
+export declare function buildFileContext(config: FileStorageConfig): Promise<FileStorageResult>;