erosolar-cli 1.7.195 → 1.7.196

package/dist/core/unified/toolRuntime.d.ts

@@ -0,0 +1,179 @@
+/**
+ * Unified Tool Runtime
+ *
+ * Core tool execution engine with caching, validation, and lifecycle management.
+ * Combines the best features from both TypeScript and Python implementations.
+ *
+ * Principal Investigator: Bo Shang
+ * Framework: erosolar-cli
+ */
+import type { ToolDefinition, ToolSuite, ToolRecord, ToolCallRequest, ToolCallResult, ProviderToolDefinition } from './types.js';
+import { ToolArgumentValidationError } from './schema.js';
+import { validateToolPreconditions, type PreflightWarning } from '../toolPreconditions.js';
+/**
+ * Tools that can be safely cached based on their arguments
+ */
+export declare const CACHEABLE_TOOLS: Set<string>;
+export interface ToolRuntimeConfig {
+    enableCache: boolean;
+    cacheTtlMs: number;
+    maxCacheSize: number;
+    defaultTimeoutMs: number;
+    networkTimeoutMs: number;
+    maxOutputLength: number;
+    verbose: boolean;
+}
+export interface CacheEntry {
+    output: string;
+    timestamp: number;
+    ttl: number;
+    hitCount: number;
+}
+/**
+ * Observer interface for tool lifecycle events
+ */
+export interface ToolRuntimeObserver {
+    onToolStart?(call: ToolCallRequest): void;
+    onToolResult?(call: ToolCallRequest, result: ToolCallResult): void;
+    onToolError?(call: ToolCallRequest, error: Error): void;
+    onToolWarning?(call: ToolCallRequest, warning: PreflightWarning | string): void;
+    onCacheHit?(call: ToolCallRequest, entry: CacheEntry): void;
+    onCacheMiss?(call: ToolCallRequest): void;
+    onValidationError?(call: ToolCallRequest, error: ToolArgumentValidationError): void;
+}
+/**
+ * Unified Tool Runtime
+ *
+ * Manages tool registration, execution, caching, and validation.
+ */
+export declare class ToolRuntime {
+    private registry;
+    private cache;
+    private config;
+    private observers;
+    private executionStats;
+    constructor(config?: Partial<ToolRuntimeConfig>);
+    /**
+     * Register a tool suite
+     */
+    registerSuite(suite: ToolSuite): void;
+    /**
+     * Register a single tool
+     */
+    registerTool(tool: ToolDefinition, suiteName?: string): void;
+    /**
+     * Unregister a tool
+     */
+    unregisterTool(name: string): boolean;
+    /**
+     * Get a tool by name
+     */
+    getTool(name: string): ToolRecord | undefined;
+    /**
+     * Check if a tool exists
+     */
+    hasTool(name: string): boolean;
+    /**
+     * Enable or disable a tool
+     */
+    setToolEnabled(name: string, enabled: boolean): boolean;
+    /**
+     * Execute a tool call
+     */
+    execute(call: ToolCallRequest): Promise<ToolCallResult>;
+    /**
+     * Execute with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Create an error result
+     */
+    private createErrorResult;
+    /**
+     * Check if a tool's results can be cached
+     */
+    private isCacheable;
+    /**
+     * Generate cache key for a tool call
+     */
+    private getCacheKey;
+    /**
+     * Check if a cache entry has expired
+     */
+    private isCacheExpired;
+    /**
+     * Cache a result
+     */
+    private cacheResult;
+    /**
+     * Evict oldest cache entries
+     */
+    private evictOldestCacheEntries;
+    /**
+     * Clear all cache entries
+     */
+    clearCache(): void;
+    /**
+     * Clear expired cache entries
+     */
+    clearExpiredCache(): number;
+    /**
+     * Truncate output if too long
+     *
+     * PERF: Uses efficient slicing - O(1) for length check, O(n) for truncation only when needed.
+     * Binary search not applicable here as we need character boundaries, not search.
+     */
+    private truncateOutput;
+    /**
+     * Add an observer
+     */
+    addObserver(observer: ToolRuntimeObserver): void;
+    /**
+     * Remove an observer
+     */
+    removeObserver(observer: ToolRuntimeObserver): boolean;
+    /**
+     * Notify observers of an event
+     */
+    private notifyObservers;
+    /**
+     * Get tools in provider format
+     */
+    listProviderTools(): ProviderToolDefinition[];
+    /**
+     * Get tools for a specific category
+     */
+    getToolsByCategory(category: string): ToolRecord[];
+    /**
+     * Get execution statistics
+     */
+    getStats(): {
+        totalCalls: number;
+        cacheHits: number;
+        cacheHitRate: number;
+        errors: number;
+        errorRate: number;
+        avgExecutionTimeMs: number;
+        registeredTools: number;
+        cacheSize: number;
+    };
+    /**
+     * Reset statistics
+     */
+    resetStats(): void;
+    /**
+     * Get tool execution counts
+     */
+    getToolExecutionCounts(): Map<string, number>;
+}
+/**
+ * Create a tool runtime with default configuration
+ */
+export declare function createToolRuntime(config?: Partial<ToolRuntimeConfig>): ToolRuntime;
+/**
+ * Create a tool suite from definitions
+ */
+export declare function createToolSuite(name: string, version: string, tools: ToolDefinition[], description?: string): ToolSuite;
+export { validateToolPreconditions };
+export type { PreflightWarning };
+//# sourceMappingURL=toolRuntime.d.ts.map

package/dist/core/unified/toolRuntime.d.ts.map

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

package/dist/core/unified/toolRuntime.js

@@ -0,0 +1,517 @@
+/**
+ * Unified Tool Runtime
+ *
+ * Core tool execution engine with caching, validation, and lifecycle management.
+ * Combines the best features from both TypeScript and Python implementations.
+ *
+ * Principal Investigator: Bo Shang
+ * Framework: erosolar-cli
+ */
+import { validateToolArguments, ToolArgumentValidationError } from './schema.js';
+import { validateToolPreconditions } from '../toolPreconditions.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Tools that can be safely cached based on their arguments
+ */
+export const CACHEABLE_TOOLS = new Set([
+    'Read',
+    'read',
+    'read_file',
+    'Glob',
+    'glob',
+    'glob_search',
+    'Grep',
+    'grep',
+    'grep_search',
+    'WebSearch',
+    'web_search',
+    'WebFetch',
+    'web_fetch',
+    'find_definition',
+    'analyze_code_quality',
+    'analyze_complexity',
+    'find_dependencies',
+]);
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG = {
+    enableCache: true,
+    cacheTtlMs: 5 * 60 * 1000, // 5 minutes
+    maxCacheSize: 1000,
+    defaultTimeoutMs: 120_000, // 2 minutes
+    networkTimeoutMs: 30_000, // 30 seconds
+    maxOutputLength: 100_000, // 100k chars
+    verbose: false,
+};
+// ============================================================================
+// Tool Runtime
+// ============================================================================
+/**
+ * Unified Tool Runtime
+ *
+ * Manages tool registration, execution, caching, and validation.
+ */
+export class ToolRuntime {
+    registry = new Map();
+    cache = new Map();
+    config;
+    observers = [];
+    executionStats = {
+        totalCalls: 0,
+        cacheHits: 0,
+        errors: 0,
+        totalTimeMs: 0,
+    };
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // ==========================================================================
+    // Registration
+    // ==========================================================================
+    /**
+     * Register a tool suite
+     */
+    registerSuite(suite) {
+        for (const tool of suite.tools) {
+            this.registerTool(tool, suite.name);
+        }
+        if (this.config.verbose) {
+            console.log(`[ToolRuntime] Registered suite: ${suite.name} (${suite.tools.length} tools)`);
+        }
+    }
+    /**
+     * Register a single tool
+     */
+    registerTool(tool, suiteName = 'default') {
+        const record = {
+            definition: tool,
+            suite: suiteName,
+            enabled: true,
+            executionCount: 0,
+        };
+        this.registry.set(tool.name, record);
+        // Also register lowercase version for case-insensitive lookup
+        if (tool.name !== tool.name.toLowerCase()) {
+            this.registry.set(tool.name.toLowerCase(), record);
+        }
+    }
+    /**
+     * Unregister a tool
+     */
+    unregisterTool(name) {
+        const record = this.registry.get(name);
+        if (!record)
+            return false;
+        this.registry.delete(name);
+        this.registry.delete(name.toLowerCase());
+        return true;
+    }
+    /**
+     * Get a tool by name
+     */
+    getTool(name) {
+        return this.registry.get(name) || this.registry.get(name.toLowerCase());
+    }
+    /**
+     * Check if a tool exists
+     */
+    hasTool(name) {
+        return this.registry.has(name) || this.registry.has(name.toLowerCase());
+    }
+    /**
+     * Enable or disable a tool
+     */
+    setToolEnabled(name, enabled) {
+        const record = this.getTool(name);
+        if (!record)
+            return false;
+        record.enabled = enabled;
+        return true;
+    }
+    // ==========================================================================
+    // Execution
+    // ==========================================================================
+    /**
+     * Execute a tool call
+     */
+    async execute(call) {
+        const startTime = Date.now();
+        this.executionStats.totalCalls++;
+        // Look up tool
+        const record = this.getTool(call.name);
+        if (!record) {
+            return this.createErrorResult(call, startTime, `Unknown tool: ${call.name}`);
+        }
+        if (!record.enabled) {
+            return this.createErrorResult(call, startTime, `Tool is disabled: ${call.name}`);
+        }
+        const tool = record.definition;
+        // Notify observers
+        this.notifyObservers('onToolStart', call);
+        // Check cache
+        if (this.config.enableCache && this.isCacheable(tool)) {
+            const cacheKey = this.getCacheKey(call);
+            const cached = this.cache.get(cacheKey);
+            if (cached && !this.isCacheExpired(cached)) {
+                cached.hitCount++;
+                this.executionStats.cacheHits++;
+                this.notifyObservers('onCacheHit', call, cached);
+                return {
+                    toolCallId: call.id,
+                    output: cached.output,
+                    success: true,
+                    cached: true,
+                    durationMs: Date.now() - startTime,
+                };
+            }
+            this.notifyObservers('onCacheMiss', call);
+        }
+        // Validate arguments
+        try {
+            validateToolArguments(call.name, tool.parameters, call.arguments);
+        }
+        catch (error) {
+            if (error instanceof ToolArgumentValidationError) {
+                this.notifyObservers('onValidationError', call, error);
+                return this.createErrorResult(call, startTime, error.message);
+            }
+            throw error;
+        }
+        // Pre-flight AI flow validation - catch common tool usage failures
+        const preflightWarnings = validateToolPreconditions(call.name, call.arguments);
+        for (const warning of preflightWarnings) {
+            this.notifyObservers('onToolWarning', call, warning);
+        }
+        // Execute tool
+        try {
+            const output = await this.executeWithTimeout(tool, call.arguments);
+            const truncatedOutput = this.truncateOutput(output, call.name);
+            const durationMs = Date.now() - startTime;
+            // Update stats
+            record.executionCount++;
+            record.lastExecuted = Date.now();
+            this.executionStats.totalTimeMs += durationMs;
+            // Cache result if cacheable
+            if (this.config.enableCache && this.isCacheable(tool)) {
+                this.cacheResult(call, truncatedOutput);
+            }
+            const result = {
+                toolCallId: call.id,
+                output: truncatedOutput,
+                success: true,
+                cached: false,
+                durationMs,
+            };
+            this.notifyObservers('onToolResult', call, result);
+            return result;
+        }
+        catch (error) {
+            this.executionStats.errors++;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.notifyObservers('onToolError', call, error);
+            return this.createErrorResult(call, startTime, errorMessage);
+        }
+    }
+    /**
+     * Execute with timeout
+     */
+    async executeWithTimeout(tool, args) {
+        const timeoutMs = this.config.defaultTimeoutMs;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                reject(new Error(`Tool execution timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            tool
+                .execute(args)
+                .then((result) => {
+                clearTimeout(timer);
+                resolve(result);
+            })
+                .catch((error) => {
+                clearTimeout(timer);
+                reject(error);
+            });
+        });
+    }
+    /**
+     * Create an error result
+     */
+    createErrorResult(call, startTime, error) {
+        return {
+            toolCallId: call.id,
+            output: `Error: ${error}`,
+            success: false,
+            cached: false,
+            durationMs: Date.now() - startTime,
+            error,
+        };
+    }
+    // ==========================================================================
+    // Caching
+    // ==========================================================================
+    /**
+     * Check if a tool's results can be cached
+     */
+    isCacheable(tool) {
+        if (tool.cacheable !== undefined) {
+            return tool.cacheable;
+        }
+        return CACHEABLE_TOOLS.has(tool.name);
+    }
+    /**
+     * Generate cache key for a tool call
+     */
+    getCacheKey(call) {
+        const argsStr = JSON.stringify(call.arguments, Object.keys(call.arguments).sort());
+        return `${call.name}:${argsStr}`;
+    }
+    /**
+     * Check if a cache entry has expired
+     */
+    isCacheExpired(entry) {
+        return Date.now() - entry.timestamp > entry.ttl;
+    }
+    /**
+     * Cache a result
+     */
+    cacheResult(call, output) {
+        // Enforce max cache size
+        if (this.cache.size >= this.config.maxCacheSize) {
+            this.evictOldestCacheEntries(Math.floor(this.config.maxCacheSize * 0.2));
+        }
+        const cacheKey = this.getCacheKey(call);
+        this.cache.set(cacheKey, {
+            output,
+            timestamp: Date.now(),
+            ttl: this.config.cacheTtlMs,
+            hitCount: 0,
+        });
+    }
+    /**
+     * Evict oldest cache entries
+     */
+    evictOldestCacheEntries(count) {
+        const entries = Array.from(this.cache.entries());
+        entries.sort(([, a], [, b]) => a.timestamp - b.timestamp);
+        for (let i = 0; i < Math.min(count, entries.length); i++) {
+            const entry = entries[i];
+            if (entry) {
+                this.cache.delete(entry[0]);
+            }
+        }
+    }
+    /**
+     * Clear all cache entries
+     */
+    clearCache() {
+        this.cache.clear();
+    }
+    /**
+     * Clear expired cache entries
+     */
+    clearExpiredCache() {
+        let cleared = 0;
+        for (const [key, entry] of Array.from(this.cache.entries())) {
+            if (this.isCacheExpired(entry)) {
+                this.cache.delete(key);
+                cleared++;
+            }
+        }
+        return cleared;
+    }
+    // ==========================================================================
+    // Output Handling
+    // ==========================================================================
+    /**
+     * Truncate output if too long
+     *
+     * PERF: Uses efficient slicing - O(1) for length check, O(n) for truncation only when needed.
+     * Binary search not applicable here as we need character boundaries, not search.
+     */
+    truncateOutput(output, toolName) {
+        const maxLength = this.config.maxOutputLength;
+        const len = output.length;
+        // Fast path: no truncation needed
+        if (len <= maxLength) {
+            return output;
+        }
+        const truncatedCount = len - maxLength;
+        const toolLower = toolName.toLowerCase();
+        // For file reads, keep head and tail for better context
+        if (toolLower.includes('read') || toolLower === 'glob' || toolLower === 'grep') {
+            // Keep 70% head, 30% tail (minus notice overhead)
+            const noticeLen = 50;
+            const usableLen = maxLength - noticeLen;
+            const headSize = Math.floor(usableLen * 0.7);
+            const tailSize = usableLen - headSize;
+            return (output.slice(0, headSize) +
+                `\n\n... [truncated ${truncatedCount} characters] ...\n\n` +
+                output.slice(-tailSize));
+        }
+        // For bash/command output, keep more of the tail (errors usually at end)
+        if (toolLower.includes('bash') || toolLower === 'execute') {
+            const noticeLen = 50;
+            const usableLen = maxLength - noticeLen;
+            const tailSize = Math.floor(usableLen * 0.8);
+            const headSize = usableLen - tailSize;
+            return (output.slice(0, headSize) +
+                `\n\n... [truncated ${truncatedCount} characters] ...\n\n` +
+                output.slice(-tailSize));
+        }
+        // Default: keep head only (fastest)
+        return output.slice(0, maxLength - 50) + `\n... [truncated ${truncatedCount} characters]`;
+    }
+    // ==========================================================================
+    // Observers
+    // ==========================================================================
+    /**
+     * Add an observer
+     */
+    addObserver(observer) {
+        this.observers.push(observer);
+    }
+    /**
+     * Remove an observer
+     */
+    removeObserver(observer) {
+        const index = this.observers.indexOf(observer);
+        if (index === -1)
+            return false;
+        this.observers.splice(index, 1);
+        return true;
+    }
+    /**
+     * Notify observers of an event
+     */
+    notifyObservers(event, ...args) {
+        for (const observer of this.observers) {
+            const handler = observer[event];
+            if (handler) {
+                try {
+                    handler.apply(observer, args);
+                }
+                catch (error) {
+                    if (this.config.verbose) {
+                        console.error(`[ToolRuntime] Observer error:`, error);
+                    }
+                }
+            }
+        }
+    }
+    // ==========================================================================
+    // Provider Integration
+    // ==========================================================================
+    /**
+     * Get tools in provider format
+     */
+    listProviderTools() {
+        const tools = [];
+        const seen = new Set();
+        for (const [, record] of Array.from(this.registry.entries())) {
+            if (!record.enabled || seen.has(record.definition.name)) {
+                continue;
+            }
+            seen.add(record.definition.name);
+            const tool = record.definition;
+            tools.push({
+                type: 'function',
+                function: {
+                    name: tool.name,
+                    description: tool.description,
+                    parameters: tool.parameters,
+                },
+            });
+        }
+        return tools;
+    }
+    /**
+     * Get tools for a specific category
+     */
+    getToolsByCategory(category) {
+        const tools = [];
+        const seen = new Set();
+        for (const record of Array.from(this.registry.values())) {
+            if (record.definition.category === category &&
+                record.enabled &&
+                !seen.has(record.definition.name)) {
+                seen.add(record.definition.name);
+                tools.push(record);
+            }
+        }
+        return tools;
+    }
+    // ==========================================================================
+    // Statistics
+    // ==========================================================================
+    /**
+     * Get execution statistics
+     */
+    getStats() {
+        const totalCalls = this.executionStats.totalCalls;
+        return {
+            totalCalls,
+            cacheHits: this.executionStats.cacheHits,
+            cacheHitRate: totalCalls > 0 ? this.executionStats.cacheHits / totalCalls : 0,
+            errors: this.executionStats.errors,
+            errorRate: totalCalls > 0 ? this.executionStats.errors / totalCalls : 0,
+            avgExecutionTimeMs: totalCalls > 0 ? this.executionStats.totalTimeMs / totalCalls : 0,
+            registeredTools: new Set(Array.from(this.registry.values()).map((r) => r.definition.name))
+                .size,
+            cacheSize: this.cache.size,
+        };
+    }
+    /**
+     * Reset statistics
+     */
+    resetStats() {
+        this.executionStats = {
+            totalCalls: 0,
+            cacheHits: 0,
+            errors: 0,
+            totalTimeMs: 0,
+        };
+    }
+    /**
+     * Get tool execution counts
+     */
+    getToolExecutionCounts() {
+        const counts = new Map();
+        const seen = new Set();
+        for (const record of Array.from(this.registry.values())) {
+            if (!seen.has(record.definition.name)) {
+                seen.add(record.definition.name);
+                counts.set(record.definition.name, record.executionCount);
+            }
+        }
+        return counts;
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create a tool runtime with default configuration
+ */
+export function createToolRuntime(config) {
+    return new ToolRuntime(config);
+}
+/**
+ * Create a tool suite from definitions
+ */
+export function createToolSuite(name, version, tools, description) {
+    return {
+        name,
+        version,
+        description,
+        tools,
+    };
+}
+// ============================================================================
+// AI Flow Pre-Flight Validation
+// ============================================================================
+// Re-export shared preflight validation to maintain unified runtime parity.
+export { validateToolPreconditions };
+//# sourceMappingURL=toolRuntime.js.map