bigtool-ts 0.1.0

package/dist/loader/index.d.ts

@@ -0,0 +1,172 @@
+/**
+ * ToolLoader module.
+ *
+ * Provides lazy loading of tool implementations with LRU caching.
+ * The loader bridges the gap between tool metadata (catalog) and
+ * actual tool implementations (sources).
+ *
+ * @module loader
+ */
+import type { StructuredTool } from '@langchain/core/tools';
+import type { ToolLoader, ToolCatalog } from '../types.js';
+/**
+ * Configuration options for DefaultToolLoader.
+ *
+ * @example
+ * ```typescript
+ * const options: ToolLoaderOptions = {
+ *   maxSize: 50,    // Cache up to 50 tools
+ *   ttl: 300000,    // Expire after 5 minutes
+ * };
+ * ```
+ */
+export interface ToolLoaderOptions {
+    /**
+     * Maximum number of tools to cache.
+     *
+     * When the limit is reached, least recently used tools are evicted.
+     *
+     * @default 100
+     */
+    maxSize?: number;
+    /**
+     * Time-to-live for cached tools in milliseconds.
+     *
+     * After this time, tools are evicted from cache and reloaded
+     * from source on next access.
+     *
+     * @default undefined (no expiry)
+     */
+    ttl?: number;
+}
+/**
+ * Default tool loader with LRU caching.
+ *
+ * Caches loaded tools to avoid repeated loading from sources.
+ * Uses an LRU (Least Recently Used) eviction policy when the
+ * cache is full.
+ *
+ * The loader:
+ * 1. Checks cache for existing tool
+ * 2. If not cached, looks up metadata in catalog
+ * 3. Gets the source from the catalog
+ * 4. Loads the tool from the source
+ * 5. Caches and returns the tool
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { DefaultToolLoader } from '@repo/bigtool-ts';
+ *
+ * const loader = new DefaultToolLoader(catalog, { maxSize: 50 });
+ *
+ * // Load a tool
+ * const tool = await loader.load('github:create_pr');
+ *
+ * // Tool is now cached - subsequent loads are instant
+ * const sameTool = await loader.load('github:create_pr');
+ * ```
+ *
+ * @example With TTL
+ * ```typescript
+ * const loader = new DefaultToolLoader(catalog, {
+ *   maxSize: 100,
+ *   ttl: 5 * 60 * 1000, // 5 minutes
+ * });
+ * ```
+ */
+export declare class DefaultToolLoader implements ToolLoader {
+    /** @internal The tool catalog for metadata lookup */
+    private catalog;
+    /** @internal LRU cache for loaded tools */
+    private cache;
+    /**
+     * Creates a new DefaultToolLoader.
+     *
+     * @param catalog - The tool catalog for metadata and source lookup
+     * @param options - Cache configuration options
+     *
+     * @example
+     * ```typescript
+     * const loader = new DefaultToolLoader(catalog);
+     * const loaderWithOptions = new DefaultToolLoader(catalog, { maxSize: 50 });
+     * ```
+     */
+    constructor(catalog: ToolCatalog, options?: ToolLoaderOptions);
+    /**
+     * Load a tool by ID.
+     *
+     * Returns cached tool if available, otherwise loads from source.
+     *
+     * @param id - The tool ID to load
+     * @returns Promise resolving to the loaded tool
+     * @throws Error if tool not found in catalog or source returns null
+     *
+     * @example
+     * ```typescript
+     * const tool = await loader.load('github:create_pr');
+     * const result = await tool.invoke({ title: 'My PR' });
+     * ```
+     */
+    load(id: string): Promise<StructuredTool>;
+    /**
+     * Pre-load multiple tools in parallel.
+     *
+     * Useful for warming up the cache before a batch of operations.
+     * Errors are silently ignored—use load() for error handling.
+     *
+     * @param ids - Array of tool IDs to pre-load
+     *
+     * @example
+     * ```typescript
+     * // Warm up cache with expected tools
+     * await loader.warmup([
+     *   'github:create_pr',
+     *   'github:list_repos',
+     *   'github:get_issues',
+     * ]);
+     * ```
+     */
+    warmup(ids: string[]): Promise<void>;
+    /**
+     * Remove a tool from the cache.
+     *
+     * The tool will be reloaded from source on next access.
+     *
+     * @param id - The tool ID to evict
+     *
+     * @example
+     * ```typescript
+     * // Invalidate after tool update
+     * loader.evict('github:create_pr');
+     * ```
+     */
+    evict(id: string): void;
+    /**
+     * Clear the entire cache.
+     *
+     * All tools will be reloaded from source on next access.
+     *
+     * @example
+     * ```typescript
+     * // Clear cache after major changes
+     * loader.clear();
+     * ```
+     */
+    clear(): void;
+    /**
+     * Get cache statistics for monitoring.
+     *
+     * @returns Object with current size and max size
+     *
+     * @example
+     * ```typescript
+     * const stats = loader.getStats();
+     * console.log(`Cache: ${stats.size}/${stats.maxSize}`);
+     * ```
+     */
+    getStats(): {
+        size: number;
+        maxSize: number;
+    };
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/loader/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/loader/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAG3D;;;;;;;;;;GAUG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBAAa,iBAAkB,YAAW,UAAU;IAClD,qDAAqD;IACrD,OAAO,CAAC,OAAO,CAAc;IAE7B,2CAA2C;IAC3C,OAAO,CAAC,KAAK,CAAmC;IAEhD;;;;;;;;;;;OAWG;gBACS,OAAO,EAAE,WAAW,EAAE,OAAO,GAAE,iBAAsB;IAQjE;;;;;;;;;;;;;;OAcG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA8B/C;;;;;;;;;;;;;;;;;OAiBG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIvB;;;;;;;;;;OAUG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;OAUG;IACH,QAAQ,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;CAM9C"}

package/dist/loader/index.js

@@ -0,0 +1,179 @@
+/**
+ * ToolLoader module.
+ *
+ * Provides lazy loading of tool implementations with LRU caching.
+ * The loader bridges the gap between tool metadata (catalog) and
+ * actual tool implementations (sources).
+ *
+ * @module loader
+ */
+import { LRUCache } from 'lru-cache';
+/**
+ * Default tool loader with LRU caching.
+ *
+ * Caches loaded tools to avoid repeated loading from sources.
+ * Uses an LRU (Least Recently Used) eviction policy when the
+ * cache is full.
+ *
+ * The loader:
+ * 1. Checks cache for existing tool
+ * 2. If not cached, looks up metadata in catalog
+ * 3. Gets the source from the catalog
+ * 4. Loads the tool from the source
+ * 5. Caches and returns the tool
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { DefaultToolLoader } from '@repo/bigtool-ts';
+ *
+ * const loader = new DefaultToolLoader(catalog, { maxSize: 50 });
+ *
+ * // Load a tool
+ * const tool = await loader.load('github:create_pr');
+ *
+ * // Tool is now cached - subsequent loads are instant
+ * const sameTool = await loader.load('github:create_pr');
+ * ```
+ *
+ * @example With TTL
+ * ```typescript
+ * const loader = new DefaultToolLoader(catalog, {
+ *   maxSize: 100,
+ *   ttl: 5 * 60 * 1000, // 5 minutes
+ * });
+ * ```
+ */
+export class DefaultToolLoader {
+    /** @internal The tool catalog for metadata lookup */
+    catalog;
+    /** @internal LRU cache for loaded tools */
+    cache;
+    /**
+     * Creates a new DefaultToolLoader.
+     *
+     * @param catalog - The tool catalog for metadata and source lookup
+     * @param options - Cache configuration options
+     *
+     * @example
+     * ```typescript
+     * const loader = new DefaultToolLoader(catalog);
+     * const loaderWithOptions = new DefaultToolLoader(catalog, { maxSize: 50 });
+     * ```
+     */
+    constructor(catalog, options = {}) {
+        this.catalog = catalog;
+        this.cache = new LRUCache({
+            max: options.maxSize ?? 100,
+            ttl: options.ttl,
+        });
+    }
+    /**
+     * Load a tool by ID.
+     *
+     * Returns cached tool if available, otherwise loads from source.
+     *
+     * @param id - The tool ID to load
+     * @returns Promise resolving to the loaded tool
+     * @throws Error if tool not found in catalog or source returns null
+     *
+     * @example
+     * ```typescript
+     * const tool = await loader.load('github:create_pr');
+     * const result = await tool.invoke({ title: 'My PR' });
+     * ```
+     */
+    async load(id) {
+        // Check cache first
+        const cached = this.cache.get(id);
+        if (cached) {
+            return cached;
+        }
+        // Get metadata to find the source
+        const metadata = this.catalog.getMetadata(id);
+        if (!metadata) {
+            throw new Error(`ToolLoader: Unknown tool '${id}'`);
+        }
+        // Get the source
+        const source = this.catalog.getSource(metadata.sourceId);
+        if (!source) {
+            throw new Error(`ToolLoader: No source found for tool '${id}'`);
+        }
+        // Load from source
+        const tool = await source.getTool(id);
+        if (!tool) {
+            throw new Error(`ToolLoader: Source returned null for tool '${id}'`);
+        }
+        // Cache and return
+        this.cache.set(id, tool);
+        return tool;
+    }
+    /**
+     * Pre-load multiple tools in parallel.
+     *
+     * Useful for warming up the cache before a batch of operations.
+     * Errors are silently ignored—use load() for error handling.
+     *
+     * @param ids - Array of tool IDs to pre-load
+     *
+     * @example
+     * ```typescript
+     * // Warm up cache with expected tools
+     * await loader.warmup([
+     *   'github:create_pr',
+     *   'github:list_repos',
+     *   'github:get_issues',
+     * ]);
+     * ```
+     */
+    async warmup(ids) {
+        await Promise.all(ids.map(id => this.load(id).catch(() => null)));
+    }
+    /**
+     * Remove a tool from the cache.
+     *
+     * The tool will be reloaded from source on next access.
+     *
+     * @param id - The tool ID to evict
+     *
+     * @example
+     * ```typescript
+     * // Invalidate after tool update
+     * loader.evict('github:create_pr');
+     * ```
+     */
+    evict(id) {
+        this.cache.delete(id);
+    }
+    /**
+     * Clear the entire cache.
+     *
+     * All tools will be reloaded from source on next access.
+     *
+     * @example
+     * ```typescript
+     * // Clear cache after major changes
+     * loader.clear();
+     * ```
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get cache statistics for monitoring.
+     *
+     * @returns Object with current size and max size
+     *
+     * @example
+     * ```typescript
+     * const stats = loader.getStats();
+     * console.log(`Cache: ${stats.size}/${stats.maxSize}`);
+     * ```
+     */
+    getStats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.cache.max,
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/loader/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/loader/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAkCrC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAO,iBAAiB;IAC5B,qDAAqD;IAC7C,OAAO,CAAc;IAE7B,2CAA2C;IACnC,KAAK,CAAmC;IAEhD;;;;;;;;;;;OAWG;IACH,YAAY,OAAoB,EAAE,UAA6B,EAAE;QAC/D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QACvB,IAAI,CAAC,KAAK,GAAG,IAAI,QAAQ,CAAC;YACxB,GAAG,EAAE,OAAO,CAAC,OAAO,IAAI,GAAG;YAC3B,GAAG,EAAE,OAAO,CAAC,GAAG;SACjB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,IAAI,CAAC,EAAU;QACnB,oBAAoB;QACpB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,MAAM,CAAC;QAChB,CAAC;QAED,kCAAkC;QAClC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QAC9C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,6BAA6B,EAAE,GAAG,CAAC,CAAC;QACtD,CAAC;QAED,iBAAiB;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,IAAI,KAAK,CAAC,yCAAyC,EAAE,GAAG,CAAC,CAAC;QAClE,CAAC;QAED,mBAAmB;QACnB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CAAC,8CAA8C,EAAE,GAAG,CAAC,CAAC;QACvE,CAAC;QAED,mBAAmB;QACnB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,MAAM,CAAC,GAAa;QACxB,MAAM,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAU;QACd,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED;;;;;;;;;;OAUG;IACH,QAAQ;QACN,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI;YACrB,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG;SACxB,CAAC;IACJ,CAAC;CACF"}

package/dist/loader/loader.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ToolLoader - Lazy loading of tool implementations with LRU caching.
+ *
+ * Handles the "last mile" of tool loading:
+ * - LocalSource: Tool already in memory, just return it
+ * - MCPSource: May need to prepare the tool wrapper
+ * - DynamicSource: Actually load/import the tool on demand
+ */
+import type { StructuredTool } from "@langchain/core/tools";
+import type { ToolCatalog, ToolSource, ToolLoader } from "../types.js";
+/**
+ * Configuration for ToolLoader.
+ */
+export interface ToolLoaderConfig {
+    /** Maximum number of tools to cache (default: 100) */
+    maxCacheSize?: number;
+    /** Time-to-live for cached tools in milliseconds (default: 5 minutes) */
+    ttl?: number;
+    /** The tool catalog to use for metadata */
+    catalog: ToolCatalog;
+    /** Map of source ID to source implementation */
+    sources: Map<string, ToolSource>;
+}
+/**
+ * Error thrown when a tool cannot be found.
+ */
+export declare class ToolNotFoundError extends Error {
+    readonly toolId: string;
+    constructor(toolId: string, message?: string);
+}
+/**
+ * Error thrown when a source cannot be found.
+ */
+export declare class SourceNotFoundError extends Error {
+    readonly sourceId: string;
+    readonly toolId: string;
+    constructor(sourceId: string, toolId: string);
+}
+/**
+ * ToolLoader implementation with LRU caching and concurrent load deduplication.
+ */
+export declare class ToolLoaderImpl implements ToolLoader {
+    private readonly cache;
+    private readonly catalog;
+    private readonly sources;
+    private readonly loading;
+    private unsubscribe?;
+    constructor(config: ToolLoaderConfig);
+    /**
+     * Load a tool by ID.
+     *
+     * Uses LRU cache for performance. Concurrent requests for the same
+     * tool are deduplicated to prevent multiple loads.
+     *
+     * @param id - The tool ID to load
+     * @returns The loaded StructuredTool
+     * @throws ToolNotFoundError if the tool doesn't exist
+     * @throws SourceNotFoundError if the tool's source isn't registered
+     */
+    load(id: string): Promise<StructuredTool>;
+    /**
+     * Load a tool from its source.
+     *
+     * @param id - The tool ID to load
+     * @returns The loaded StructuredTool
+     * @throws ToolNotFoundError if the tool doesn't exist
+     * @throws SourceNotFoundError if the tool's source isn't registered
+     */
+    private loadFromSource;
+    /**
+     * Pre-load multiple tools in parallel.
+     *
+     * This is useful for warming up the cache before a batch of operations.
+     * Errors are silently ignored - check individual tools with load() if
+     * you need error handling.
+     *
+     * @param ids - Array of tool IDs to pre-load
+     */
+    warmup(ids: string[]): Promise<void>;
+    /**
+     * Remove a tool from the cache.
+     *
+     * The tool will be reloaded from source on next access.
+     *
+     * @param id - The tool ID to evict
+     */
+    evict(id: string): void;
+    /**
+     * Clear the entire cache.
+     *
+     * All tools will be reloaded from source on next access.
+     */
+    clear(): void;
+    /**
+     * Get cache statistics for monitoring.
+     */
+    get stats(): {
+        size: number;
+        maxSize: number;
+        loading: number;
+    };
+    /**
+     * Dispose of the loader and clean up resources.
+     */
+    dispose(): void;
+}
+/**
+ * Create a new ToolLoader instance.
+ *
+ * @param config - Loader configuration
+ * @returns A new ToolLoader instance
+ */
+export declare function createToolLoader(config: ToolLoaderConfig): ToolLoader;
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../src/loader/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEvE;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,OAAO,EAAE,WAAW,CAAC;IACrB,gDAAgD;IAChD,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;aAExB,MAAM,EAAE,MAAM;gBAAd,MAAM,EAAE,MAAM,EAC9B,OAAO,CAAC,EAAE,MAAM;CAKnB;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAKjC;AAUD;;GAEG;AACH,qBAAa,cAAe,YAAW,UAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IACtE,OAAO,CAAC,WAAW,CAAC,CAAa;gBAErB,MAAM,EAAE,gBAAgB;IAgBpC;;;;;;;;;;OAUG;IACG,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA0B/C;;;;;;;OAOG;YACW,cAAc;IAyB5B;;;;;;;;OAQG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAK1C;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAMvB;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,KAAK,IAAI;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAM9D;IAED;;OAEG;IACH,OAAO,IAAI,IAAI;CAIhB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,GAAG,UAAU,CAErE"}

package/dist/loader/loader.js

@@ -0,0 +1,185 @@
+/**
+ * ToolLoader - Lazy loading of tool implementations with LRU caching.
+ *
+ * Handles the "last mile" of tool loading:
+ * - LocalSource: Tool already in memory, just return it
+ * - MCPSource: May need to prepare the tool wrapper
+ * - DynamicSource: Actually load/import the tool on demand
+ */
+import { LRUCache } from "lru-cache";
+/**
+ * Error thrown when a tool cannot be found.
+ */
+export class ToolNotFoundError extends Error {
+    toolId;
+    constructor(toolId, message) {
+        super(message ?? `Tool not found: ${toolId}`);
+        this.toolId = toolId;
+        this.name = "ToolNotFoundError";
+    }
+}
+/**
+ * Error thrown when a source cannot be found.
+ */
+export class SourceNotFoundError extends Error {
+    sourceId;
+    toolId;
+    constructor(sourceId, toolId) {
+        super(`Source not found for tool: ${toolId} (expected source: ${sourceId})`);
+        this.sourceId = sourceId;
+        this.toolId = toolId;
+        this.name = "SourceNotFoundError";
+    }
+}
+/**
+ * Default configuration values.
+ */
+const DEFAULTS = {
+    maxCacheSize: 100,
+    ttl: 5 * 60 * 1000, // 5 minutes
+};
+/**
+ * ToolLoader implementation with LRU caching and concurrent load deduplication.
+ */
+export class ToolLoaderImpl {
+    cache;
+    catalog;
+    sources;
+    loading = new Map();
+    unsubscribe;
+    constructor(config) {
+        this.cache = new LRUCache({
+            max: config.maxCacheSize ?? DEFAULTS.maxCacheSize,
+            ttl: config.ttl ?? DEFAULTS.ttl,
+        });
+        this.catalog = config.catalog;
+        this.sources = config.sources;
+        // Listen for catalog changes to invalidate cache
+        this.unsubscribe = this.catalog.onToolsChanged.subscribe(({ removed }) => {
+            for (const id of removed) {
+                this.evict(id);
+            }
+        });
+    }
+    /**
+     * Load a tool by ID.
+     *
+     * Uses LRU cache for performance. Concurrent requests for the same
+     * tool are deduplicated to prevent multiple loads.
+     *
+     * @param id - The tool ID to load
+     * @returns The loaded StructuredTool
+     * @throws ToolNotFoundError if the tool doesn't exist
+     * @throws SourceNotFoundError if the tool's source isn't registered
+     */
+    async load(id) {
+        // 1. Check cache first
+        const cached = this.cache.get(id);
+        if (cached) {
+            return cached;
+        }
+        // 2. Check if already loading (dedup concurrent requests)
+        const existing = this.loading.get(id);
+        if (existing) {
+            return existing;
+        }
+        // 3. Load from source
+        const loadPromise = this.loadFromSource(id);
+        this.loading.set(id, loadPromise);
+        try {
+            const tool = await loadPromise;
+            this.cache.set(id, tool);
+            return tool;
+        }
+        finally {
+            this.loading.delete(id);
+        }
+    }
+    /**
+     * Load a tool from its source.
+     *
+     * @param id - The tool ID to load
+     * @returns The loaded StructuredTool
+     * @throws ToolNotFoundError if the tool doesn't exist
+     * @throws SourceNotFoundError if the tool's source isn't registered
+     */
+    async loadFromSource(id) {
+        // Get metadata to find the source
+        const metadata = this.catalog.getMetadata(id);
+        if (!metadata) {
+            throw new ToolNotFoundError(id);
+        }
+        // Get the source
+        const source = this.sources.get(metadata.sourceId);
+        if (!source) {
+            throw new SourceNotFoundError(metadata.sourceId, id);
+        }
+        // Load from source
+        const tool = await source.getTool(id);
+        if (!tool) {
+            throw new ToolNotFoundError(id, `Tool ${id} exists in catalog but source returned null`);
+        }
+        return tool;
+    }
+    /**
+     * Pre-load multiple tools in parallel.
+     *
+     * This is useful for warming up the cache before a batch of operations.
+     * Errors are silently ignored - check individual tools with load() if
+     * you need error handling.
+     *
+     * @param ids - Array of tool IDs to pre-load
+     */
+    async warmup(ids) {
+        // Load all tools in parallel, ignoring failures
+        await Promise.allSettled(ids.map((id) => this.load(id)));
+    }
+    /**
+     * Remove a tool from the cache.
+     *
+     * The tool will be reloaded from source on next access.
+     *
+     * @param id - The tool ID to evict
+     */
+    evict(id) {
+        this.cache.delete(id);
+        // Also clear any in-progress loading (will be restarted on next load)
+        this.loading.delete(id);
+    }
+    /**
+     * Clear the entire cache.
+     *
+     * All tools will be reloaded from source on next access.
+     */
+    clear() {
+        this.cache.clear();
+        this.loading.clear();
+    }
+    /**
+     * Get cache statistics for monitoring.
+     */
+    get stats() {
+        return {
+            size: this.cache.size,
+            maxSize: this.cache.max,
+            loading: this.loading.size,
+        };
+    }
+    /**
+     * Dispose of the loader and clean up resources.
+     */
+    dispose() {
+        this.unsubscribe?.();
+        this.clear();
+    }
+}
+/**
+ * Create a new ToolLoader instance.
+ *
+ * @param config - Loader configuration
+ * @returns A new ToolLoader instance
+ */
+export function createToolLoader(config) {
+    return new ToolLoaderImpl(config);
+}
+//# sourceMappingURL=loader.js.map

package/dist/loader/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/loader/loader.ts"],"names":[],"mappings":"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"}