toolpack-sdk 0.1.0-SNAPSHOT

package/dist/tools/registry.js

@@ -0,0 +1,217 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRegistry = void 0;
+const types_js_1 = require("./types.js");
+/**
+ * Central registry for all tools (built-in + custom).
+ * Handles registration, lookup, filtering by category, schema extraction,
+ * and loading tool projects.
+ */
+class ToolRegistry {
+    tools = new Map();
+    projects = new Map();
+    config = types_js_1.DEFAULT_TOOLS_CONFIG;
+    /**
+     * Register a tool (built-in or custom).
+     */
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    /**
+     * Register a custom tool provided by the consumer.
+     * Identical to register() but semantically distinct for clarity.
+     */
+    registerCustom(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    /**
+     * Get a tool by name.
+     */
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Check if a tool exists.
+     */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /**
+     * Get all registered tool names.
+     */
+    getNames() {
+        return Array.from(this.tools.keys());
+    }
+    /**
+     * Get all tools in a specific category.
+     */
+    getByCategory(category) {
+        return Array.from(this.tools.values()).filter(t => t.category === category);
+    }
+    /**
+     * Get all enabled tools based on config.
+     * If enabledTools and enabledToolCategories are both empty, returns all registered tools.
+     * Otherwise, returns only tools from enabledTools[] + enabledToolCategories[].
+     */
+    getEnabled() {
+        if (this.config.enabledTools.length === 0 && this.config.enabledToolCategories.length === 0) {
+            return Array.from(this.tools.values());
+        }
+        // Build filtered list from explicit tools + categories
+        const fromNames = this.getByNames(this.config.enabledTools);
+        const fromCategories = this.getByCategories(this.config.enabledToolCategories);
+        // Deduplicate by name
+        const seen = new Set();
+        const result = [];
+        for (const tool of [...fromNames, ...fromCategories]) {
+            if (!seen.has(tool.name)) {
+                seen.add(tool.name);
+                result.push(tool);
+            }
+        }
+        return result;
+    }
+    /**
+     * Get tool schemas suitable for sending to AI providers.
+     * If toolNames is provided, only return schemas for those tools.
+     * Otherwise, return schemas for all enabled tools.
+     */
+    getSchemas(toolNames) {
+        const tools = toolNames
+            ? toolNames.map(n => this.tools.get(n)).filter(Boolean)
+            : this.getEnabled();
+        return tools.map(t => ({
+            name: t.name,
+            displayName: t.displayName,
+            description: t.description,
+            parameters: t.parameters,
+            category: t.category,
+        }));
+    }
+    /**
+     * Get all tools matching a list of names.
+     */
+    getByNames(names) {
+        return names.map(n => this.tools.get(n)).filter(Boolean);
+    }
+    /**
+     * Get all tools matching a list of categories.
+     */
+    getByCategories(categories) {
+        const categorySet = new Set(categories);
+        return Array.from(this.tools.values()).filter(t => categorySet.has(t.category));
+    }
+    /**
+     * Get all registered categories (derived from tools).
+     */
+    getCategories() {
+        const cats = new Set();
+        for (const tool of this.tools.values()) {
+            cats.add(tool.category);
+        }
+        return Array.from(cats);
+    }
+    /**
+     * Get all registered tools.
+     * Used by BM25SearchEngine for indexing.
+     */
+    getAll() {
+        return Array.from(this.tools.values());
+    }
+    /**
+     * Update the config (called by config loader).
+     */
+    setConfig(config) {
+        this.config = config;
+    }
+    /**
+     * Get the current config.
+     */
+    getConfig() {
+        return this.config;
+    }
+    /**
+     * Get the total number of registered tools.
+     */
+    get size() {
+        return this.tools.size;
+    }
+    /**
+     * Validate that a tool project's declared dependencies are resolvable.
+     * Returns an array of missing package names (empty = all good).
+     */
+    async validateDependencies(project) {
+        const deps = project.dependencies;
+        if (!deps || Object.keys(deps).length === 0)
+            return [];
+        const missing = [];
+        for (const packageName of Object.keys(deps)) {
+            try {
+                await import(packageName);
+            }
+            catch {
+                missing.push(packageName);
+            }
+        }
+        return missing;
+    }
+    /**
+     * Load a single tool project into the registry.
+     * Validates dependencies before loading — throws if any are missing.
+     */
+    async loadProject(project) {
+        const missing = await this.validateDependencies(project);
+        if (missing.length > 0) {
+            throw new Error(`Tool project "${project.manifest.name}" has missing dependencies: ${missing.join(', ')}. ` +
+                `Install them with: npm install ${missing.join(' ')}`);
+        }
+        this.projects.set(project.manifest.name, project);
+        for (const tool of project.tools) {
+            this.register(tool);
+        }
+    }
+    /**
+     * Load multiple tool projects.
+     */
+    async loadProjects(projects) {
+        for (const project of projects) {
+            await this.loadProject(project);
+        }
+    }
+    /**
+     * Get a loaded project by name.
+     */
+    getProject(name) {
+        return this.projects.get(name);
+    }
+    /**
+     * Get all loaded projects.
+     */
+    getProjects() {
+        return Array.from(this.projects.values());
+    }
+    /**
+     * Get all loaded project names.
+     */
+    getProjectNames() {
+        return Array.from(this.projects.keys());
+    }
+    /**
+     * Load all built-in tool projects.
+     */
+    async loadBuiltIn() {
+        const { fsToolsProject } = await import('./fs-tools/index.js');
+        const { execToolsProject } = await import('./exec-tools/index.js');
+        const { systemToolsProject } = await import('./system-tools/index.js');
+        const { httpToolsProject } = await import('./http-tools/index.js');
+        const { webToolsProject } = await import('./web-tools/index.js');
+        const { codingToolsProject } = await import('./coding-tools/index.js');
+        const { gitToolsProject } = await import('./git-tools/index.js');
+        const { diffToolsProject } = await import('./diff-tools/index.js');
+        const { dbToolsProject } = await import('./db-tools/index.js');
+        const { cloudToolsProject } = await import('./cloud-tools/index.js');
+        await this.loadProjects([fsToolsProject, execToolsProject, systemToolsProject, httpToolsProject, webToolsProject, codingToolsProject, gitToolsProject, diffToolsProject, dbToolsProject, cloudToolsProject]);
+    }
+}
+exports.ToolRegistry = ToolRegistry;
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

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

package/dist/tools/router.d.ts

@@ -0,0 +1,40 @@
+import { ToolSchema, ToolsConfig } from './types.js';
+import { ToolRegistry } from './registry.js';
+import { Message } from '../types/index.js';
+import { ToolDiscoveryCache } from './search/index.js';
+/**
+ * Resolves which tools to send to the AI based on the tools config.
+ *
+ * Modes:
+ * 1. Tool Search Mode (toolSearch.enabled = true):
+ *    - Send only tool.search + alwaysLoadedTools + discovered tools
+ *    - AI discovers tools on-demand via tool.search
+ *    - 85%+ token savings for large tool libraries
+ *
+ * 2. Legacy Mode (toolSearch.enabled = false):
+ *    - Send all enabled tools upfront
+ *    - Use enabledTools/enabledToolCategories for filtering
+ */
+export declare class ToolRouter {
+    private discoveryCache;
+    /**
+     * Resolve the final list of tool schemas to send to the main AI model.
+     *
+     * @param messages  The conversation messages (used for extracting discovered tools)
+     * @param registry  The tool registry containing all registered tools
+     * @param config    The tools config from toolpack.config.tools.json
+     */
+    resolve(messages: Message[], registry: ToolRegistry, config: ToolsConfig): Promise<ToolSchema[]>;
+    /**
+     * Get the discovery cache (for AIClient to record discoveries).
+     */
+    getDiscoveryCache(): ToolDiscoveryCache;
+    /**
+     * Clear the discovery cache (call when starting a new conversation).
+     */
+    clearDiscoveryCache(): void;
+    private resolveWithToolSearch;
+    private resolveLegacy;
+    private toSchema;
+}
+//# sourceMappingURL=router.d.ts.map

package/dist/tools/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/tools/router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAyC,MAAM,mBAAmB,CAAC;AAE9F;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU;IACnB,OAAO,CAAC,cAAc,CAAgD;IAEtE;;;;;;OAMG;IACG,OAAO,CACT,QAAQ,EAAE,OAAO,EAAE,EACnB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,WAAW,GACpB,OAAO,CAAC,UAAU,EAAE,CAAC;IAcxB;;OAEG;IACH,iBAAiB,IAAI,kBAAkB;IAIvC;;OAEG;IACH,mBAAmB,IAAI,IAAI;IAM3B,OAAO,CAAC,qBAAqB;IAuD7B,OAAO,CAAC,aAAa;IA8BrB,OAAO,CAAC,QAAQ;CASnB"}

package/dist/tools/router.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolRouter = void 0;
+const index_js_1 = require("./search/index.js");
+/**
+ * Resolves which tools to send to the AI based on the tools config.
+ *
+ * Modes:
+ * 1. Tool Search Mode (toolSearch.enabled = true):
+ *    - Send only tool.search + alwaysLoadedTools + discovered tools
+ *    - AI discovers tools on-demand via tool.search
+ *    - 85%+ token savings for large tool libraries
+ *
+ * 2. Legacy Mode (toolSearch.enabled = false):
+ *    - Send all enabled tools upfront
+ *    - Use enabledTools/enabledToolCategories for filtering
+ */
+class ToolRouter {
+    discoveryCache = new index_js_1.ToolDiscoveryCache();
+    /**
+     * Resolve the final list of tool schemas to send to the main AI model.
+     *
+     * @param messages  The conversation messages (used for extracting discovered tools)
+     * @param registry  The tool registry containing all registered tools
+     * @param config    The tools config from toolpack.config.tools.json
+     */
+    async resolve(messages, registry, config) {
+        if (!config.enabled) {
+            return [];
+        }
+        // Tool Search Mode (Industry-Standard)
+        if (config.toolSearch?.enabled) {
+            return this.resolveWithToolSearch(messages, registry, config);
+        }
+        // Legacy Mode (all tools upfront)
+        return this.resolveLegacy(registry, config);
+    }
+    /**
+     * Get the discovery cache (for AIClient to record discoveries).
+     */
+    getDiscoveryCache() {
+        return this.discoveryCache;
+    }
+    /**
+     * Clear the discovery cache (call when starting a new conversation).
+     */
+    clearDiscoveryCache() {
+        this.discoveryCache.clear();
+    }
+    // ── Tool Search Mode ─────────────────────────────────────────────────────
+    resolveWithToolSearch(messages, registry, config) {
+        const schemas = [];
+        const seen = new Set();
+        // 1. Always include tool.search itself
+        schemas.push((0, index_js_1.getToolSearchSchema)());
+        seen.add(index_js_1.TOOL_SEARCH_NAME);
+        // 2. Always-loaded tools (user's top 3-5)
+        const alwaysLoadedTools = config.toolSearch?.alwaysLoadedTools ?? [];
+        for (const name of alwaysLoadedTools) {
+            const tool = registry.get(name);
+            if (tool && !seen.has(name)) {
+                schemas.push(this.toSchema(tool));
+                seen.add(name);
+            }
+        }
+        // 3. Always-loaded categories
+        const alwaysLoadedCategories = config.toolSearch?.alwaysLoadedCategories ?? [];
+        for (const category of alwaysLoadedCategories) {
+            for (const tool of registry.getByCategory(category)) {
+                if (!seen.has(tool.name)) {
+                    schemas.push(this.toSchema(tool));
+                    seen.add(tool.name);
+                }
+            }
+        }
+        // 4. Previously discovered tools (auto-cached)
+        if (config.toolSearch?.cacheDiscoveredTools !== false) {
+            // Merge any discoveries from messages into existing cache (don't overwrite)
+            const messageCache = index_js_1.ToolDiscoveryCache.fromMessages(messages);
+            this.discoveryCache.merge(messageCache);
+            const discovered = this.discoveryCache.getDiscoveredTools();
+            for (const name of discovered) {
+                const tool = registry.get(name);
+                if (tool && !seen.has(name)) {
+                    schemas.push(this.toSchema(tool));
+                    seen.add(name);
+                }
+            }
+        }
+        return schemas;
+    }
+    // ── Legacy Mode ──────────────────────────────────────────────────────────
+    resolveLegacy(registry, config) {
+        let candidates;
+        if (config.enabledTools.length === 0 && config.enabledToolCategories.length === 0) {
+            // Empty arrays = all tools enabled
+            candidates = registry.getEnabled();
+        }
+        else {
+            // Non-empty = only specified tools/categories
+            const fromNames = registry.getByNames(config.enabledTools);
+            const fromCategories = registry.getByCategories(config.enabledToolCategories);
+            // Deduplicate by name
+            const seen = new Set();
+            candidates = [];
+            for (const tool of [...fromNames, ...fromCategories]) {
+                if (!seen.has(tool.name)) {
+                    seen.add(tool.name);
+                    candidates.push(tool);
+                }
+            }
+        }
+        return candidates.map(t => this.toSchema(t));
+    }
+    // ── Helpers ──────────────────────────────────────────────────────────────
+    toSchema(tool) {
+        return {
+            name: tool.name,
+            displayName: tool.displayName,
+            description: tool.description,
+            parameters: tool.parameters,
+            category: tool.category,
+        };
+    }
+}
+exports.ToolRouter = ToolRouter;
+//# sourceMappingURL=router.js.map

package/dist/tools/router.js.map

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

package/dist/tools/search/bm25-engine.d.ts

@@ -0,0 +1,65 @@
+/**
+ * BM25 Search Engine for Tool Discovery
+ *
+ * BM25 (Best Matching 25) is the industry-standard ranking algorithm used by:
+ * - Elasticsearch
+ * - Anthropic's Tool Search
+ * - Apache Lucene/Solr
+ *
+ * Searches across: name, displayName, description, category, parameter names
+ * Returns: Top N tools ranked by relevance score
+ */
+import { ToolDefinition, ToolSchema } from '../types.js';
+export interface ToolDocument {
+    toolName: string;
+    tool: ToolDefinition;
+    text: string;
+    tokens: string[];
+    length: number;
+    termFrequencies: Map<string, number>;
+}
+export interface SearchOptions {
+    limit?: number;
+    category?: string;
+    minScore?: number;
+}
+export interface SearchResult {
+    toolName: string;
+    score: number;
+    tool: ToolSchema;
+}
+export declare class BM25SearchEngine {
+    private documents;
+    private avgDocLength;
+    private idf;
+    private totalDocs;
+    private docFrequencies;
+    private k1;
+    private b;
+    /**
+     * Index all tools for search.
+     * Call this once after loading all tools.
+     */
+    index(tools: ToolDefinition[]): void;
+    /**
+     * Search for tools matching the query.
+     * Returns top N results sorted by relevance score.
+     */
+    search(query: string, options?: SearchOptions): SearchResult[];
+    /**
+     * Get the number of indexed tools.
+     */
+    getIndexedCount(): number;
+    /**
+     * Check if a tool is indexed.
+     */
+    isIndexed(toolName: string): boolean;
+    private createDocument;
+    private tokenize;
+    private computeTermFrequencies;
+    private computeIDF;
+    private computeAvgDocLength;
+    private computeBM25Score;
+    private toSchema;
+}
+//# sourceMappingURL=bm25-engine.d.ts.map

package/dist/tools/search/bm25-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bm25-engine.d.ts","sourceRoot":"","sources":["../../../src/tools/search/bm25-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzD,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,cAAc,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,aAAa;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,UAAU,CAAC;CACpB;AAcD,qBAAa,gBAAgB;IACzB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,GAAG,CAAkC;IAC7C,OAAO,CAAC,SAAS,CAAa;IAC9B,OAAO,CAAC,cAAc,CAAkC;IAGxD,OAAO,CAAC,EAAE,CAAO;IACjB,OAAO,CAAC,CAAC,CAAQ;IAEjB;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,cAAc,EAAE,GAAG,IAAI;IAsBpC;;;OAGG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,YAAY,EAAE;IAuC9D;;OAEG;IACH,eAAe,IAAI,MAAM;IAIzB;;OAEG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAMpC,OAAO,CAAC,cAAc;IAoDtB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,gBAAgB;IAmBxB,OAAO,CAAC,QAAQ;CASnB"}