@trenchwork/erosolar 1.1.16

package/dist/core/toolRuntime.d.ts

@@ -0,0 +1,192 @@
+import { type JSONSchemaObject, type ProviderId, type ProviderToolDefinition, type ToolCallRequest } from './types.js';
+import { ContextManager } from './contextManager.js';
+import { type PreflightWarning } from './toolPreconditions.js';
+/**
+ * Execution context for tool operations with strict TypeScript typing
+ */
+export interface ToolExecutionContext {
+    readonly profileName: string;
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly workspaceContext?: string | null;
+}
+/**
+ * Type-safe tool observer with generic parameter inference for AI flow monitoring
+ */
+export interface ToolRuntimeObserver<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** Called when tool execution begins */
+    onToolStart?(call: ToolCallRequest & {
+        args: T;
+    }): void;
+    /** Called when tool execution completes successfully */
+    onToolResult?(call: ToolCallRequest & {
+        args: T;
+    }, output: string): void;
+    /** Called when tool execution fails */
+    onToolError?(call: ToolCallRequest & {
+        args: T;
+    }, error: string): void;
+    /** Called when cached result is used instead of execution */
+    onCacheHit?(call: ToolCallRequest & {
+        args: T;
+    }): void;
+    /** Called for progress updates during long-running operations */
+    onToolProgress?(call: ToolCallRequest & {
+        args: T;
+    }, progress: ToolProgressUpdate): void;
+    /** Called for pre-flight warnings before tool execution */
+    onToolWarning?(call: ToolCallRequest & {
+        args: T;
+    }, warning: PreflightWarning | string): void;
+}
+interface ToolRuntimeOptions {
+    readonly observer?: ToolRuntimeObserver;
+    readonly contextManager?: ContextManager;
+    readonly enableCache?: boolean;
+    readonly cacheTTLMs?: number;
+    /**
+     * Working directory used to load `.erosolar/settings.json` hooks.
+     * If unset, hooks are loaded from `~/.erosolar/settings.json`
+     * only (user-global) and the project-local file is skipped.
+     */
+    readonly workingDir?: string;
+}
+/**
+ * Generic tool handler with parameter type inference for AI flow execution
+ */
+type ToolHandler<T extends Record<string, unknown> = Record<string, unknown>> = (args: T) => Promise<string> | string;
+/**
+ * Enhanced tool definition with parameter type safety for AI software engineering
+ */
+export interface ToolDefinition<T extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique identifier for the tool */
+    readonly name: string;
+    /** Human-readable description for AI understanding */
+    readonly description: string;
+    /** JSON Schema defining the tool's parameter structure */
+    readonly parameters?: JSONSchemaObject;
+    /** Function that implements the tool's behavior */
+    readonly handler: ToolHandler<T>;
+    /** Whether results can be cached for performance optimization */
+    readonly cacheable?: boolean;
+    /** Optional per-tool cache TTL in milliseconds (falls back to runtime default) */
+    readonly cacheTtlMs?: number;
+}
+/**
+ * Collection of related tools grouped by functionality
+ */
+export interface ToolSuite {
+    /** Unique identifier for the tool suite */
+    readonly id: string;
+    /** Human-readable description of the suite's purpose */
+    readonly description?: string;
+    /** Array of tool definitions in this suite */
+    readonly tools: readonly ToolDefinition[];
+}
+export interface ToolHistoryEntry {
+    toolName: string;
+    args: Record<string, unknown>;
+    timestamp: number;
+    success: boolean;
+    hasOutput: boolean;
+    error?: string;
+}
+export interface DiffSnapshotRecord {
+    command: string;
+    output: string;
+    timestamp: number;
+}
+export interface ToolProgressUpdate {
+    current: number;
+    total?: number;
+    message?: string;
+}
+/**
+ * Report incremental progress for the currently executing tool.
+ * Tools can call this to surface live status updates (e.g., indexing files).
+ */
+export declare function reportToolProgress(progress: ToolProgressUpdate): void;
+/**
+ * Type-safe utility functions for tool runtime operations
+ */
+export declare namespace ToolRuntimeUtils {
+    /**
+     * Creates a type-safe tool definition with inferred parameter types
+     */
+    function createToolDefinition<T extends Record<string, unknown>>(definition: ToolDefinition<T>): ToolDefinition<T>;
+    /**
+     * Creates a type-safe tool suite with inferred tool types
+     */
+    function createToolSuite(suite: ToolSuite): ToolSuite;
+    /**
+     * Type guard to check if a tool definition matches expected parameter schema
+     */
+    function isToolDefinition(__tool: ToolDefinition, expectedSchema?: JSONSchemaObject): boolean;
+}
+/**
+ * Interface describing the public API of ToolRuntime.
+ * Used by wrapper implementations like RestrictedToolRuntime.
+ */
+export interface IToolRuntime {
+    listProviderTools(): ProviderToolDefinition[];
+    execute(call: ToolCallRequest, context?: {
+        profileName?: string;
+        provider?: string;
+        model?: string;
+    }): Promise<string>;
+    registerSuite(suite: ToolSuite): void;
+    unregisterSuite(id: string): void;
+    clearCache(): void;
+    getCacheStats(): {
+        size: number;
+        entries: number;
+    };
+    clearToolHistory(): void;
+    getToolHistory(): readonly ToolHistoryEntry[];
+    clearDiffSnapshots(): void;
+    getDiffSnapshots(): readonly DiffSnapshotRecord[];
+}
+export declare class ToolRuntime implements IToolRuntime {
+    private readonly registry;
+    private readonly registrationOrder;
+    private readonly observer;
+    private readonly contextManager;
+    private readonly cache;
+    private readonly enableCache;
+    private readonly cacheTTLMs;
+    private readonly toolHistory;
+    private readonly maxHistorySize;
+    private readonly diffSnapshots;
+    private readonly maxDiffSnapshots;
+    private readonly maxDiffSnapshotLength;
+    private readonly hooks;
+    constructor(baseTools?: ToolDefinition[], options?: ToolRuntimeOptions);
+    registerSuite(suite: ToolSuite): void;
+    unregisterSuite(id: string): void;
+    listProviderTools(): ProviderToolDefinition[];
+    execute(call: ToolCallRequest, _context?: {
+        profileName?: string;
+        provider?: string;
+        model?: string;
+    }): Promise<string>;
+    private getCacheKey;
+    clearCache(): void;
+    getCacheStats(): {
+        size: number;
+        entries: number;
+    };
+    clearToolHistory(): void;
+    getToolHistory(): readonly ToolHistoryEntry[];
+    private recordToolHistory;
+    clearDiffSnapshots(): void;
+    getDiffSnapshots(): readonly DiffSnapshotRecord[];
+    private addTool;
+    private removeFromOrder;
+    private recordDiffSnapshot;
+    private findGitDiffCommand;
+    private extractCommands;
+    private isGitDiffCommand;
+}
+export declare function createDefaultToolRuntime(context: ToolExecutionContext, toolSuites?: ToolSuite[], options?: ToolRuntimeOptions): ToolRuntime;
+export {};
+//# sourceMappingURL=toolRuntime.d.ts.map

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

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

package/dist/core/toolRuntime.js

@@ -0,0 +1,460 @@
+/* eslint-disable @typescript-eslint/no-namespace */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ToolArgumentValidationError, coerceToolArguments, validateToolArguments, } from './schemaValidator.js';
+import { validateToolPreconditions, validateAIFlowPatterns, EDIT_WITHOUT_READ } from './toolPreconditions.js';
+import { safeTruncate } from './resultVerification.js';
+import { logDebug } from '../utils/debugLogger.js';
+import { loadHooksConfig, runPreToolUseHooks, runPostToolUseHooks } from './hooks.js';
+const toolExecutionContext = new AsyncLocalStorage();
+/**
+ * Report incremental progress for the currently executing tool.
+ * Tools can call this to surface live status updates (e.g., indexing files).
+ */
+export function reportToolProgress(progress) {
+    const context = toolExecutionContext.getStore();
+    if (!context?.observer?.onToolProgress) {
+        return;
+    }
+    const current = Number.isFinite(progress.current) ? Math.max(0, progress.current) : 0;
+    const total = progress.total !== undefined ? Math.max(current, progress.total) : current;
+    try {
+        context.observer.onToolProgress(context.call, {
+            current,
+            total,
+            message: progress.message,
+        });
+    }
+    catch {
+        // Swallow observer errors so they don't break tool execution
+    }
+}
+// Idempotent tools that can be safely cached
+const CACHEABLE_TOOLS = new Set([
+    'Read',
+    'read_file',
+    'Glob',
+    'glob_search',
+    'Grep',
+    'grep_search',
+    'find_definition',
+    'analyze_code_quality',
+    'extract_exports',
+]);
+function buildOptimizationHint(warning) {
+    const code = warning.code;
+    const suggestion = warning.suggestion || warning.message;
+    switch (code) {
+        case 'SEARCH_BROAD_PATTERN':
+        case 'SEARCH_CONTEXT_OVERFLOW_RISK':
+            return (`\n\n<optimization-hint>\n` +
+                `⚡ SEARCH: ${suggestion}\n` +
+                `</optimization-hint>`);
+        case EDIT_WITHOUT_READ:
+        case 'EDIT_PLACEHOLDER':
+            return (`\n\n<optimization-hint>\n` +
+                `⚡ EDIT: Read the file first to copy exact whitespace. ${suggestion}\n` +
+                `</optimization-hint>`);
+        case 'NPM_INCOMPLETE_WORKFLOW':
+            return (`\n\n<optimization-hint>\n` +
+                `⚡ PUBLISH: ${suggestion}\n` +
+                `</optimization-hint>`);
+        default:
+            return null;
+    }
+}
+/**
+ * Type-safe utility functions for tool runtime operations
+ */
+export var ToolRuntimeUtils;
+(function (ToolRuntimeUtils) {
+    /**
+     * Creates a type-safe tool definition with inferred parameter types
+     */
+    function createToolDefinition(definition) {
+        return definition;
+    }
+    ToolRuntimeUtils.createToolDefinition = createToolDefinition;
+    /**
+     * Creates a type-safe tool suite with inferred tool types
+     */
+    function createToolSuite(suite) {
+        return suite;
+    }
+    ToolRuntimeUtils.createToolSuite = createToolSuite;
+    /**
+     * Type guard to check if a tool definition matches expected parameter schema
+     */
+    function isToolDefinition(__tool, expectedSchema) {
+        if (!expectedSchema)
+            return true;
+        // In a real implementation, this would validate against the schema
+        return true;
+    }
+    ToolRuntimeUtils.isToolDefinition = isToolDefinition;
+})(ToolRuntimeUtils || (ToolRuntimeUtils = {}));
+export class ToolRuntime {
+    registry = new Map();
+    registrationOrder = [];
+    observer;
+    contextManager;
+    cache = new Map();
+    enableCache;
+    cacheTTLMs;
+    toolHistory = [];
+    maxHistorySize = 50; // Keep last 50 tool calls for AI flow pattern detection
+    diffSnapshots = [];
+    maxDiffSnapshots = 5; // Keep only the most recent git diff outputs
+    maxDiffSnapshotLength = 4000;
+    hooks;
+    constructor(baseTools = [], options = {}) {
+        this.observer = options.observer ?? null;
+        this.contextManager = options.contextManager ?? null;
+        this.enableCache = options.enableCache ?? true;
+        this.cacheTTLMs = options.cacheTTLMs ?? 5 * 60 * 1000; // 5 minutes default
+        // Load hook config eagerly. Hot-reloading on every tool call would
+        // give the user faster feedback but at the cost of file I/O on
+        // every step — we accept "edit settings → restart CLI" as the
+        // tradeoff (matches Claude Code).
+        try {
+            this.hooks = loadHooksConfig(options.workingDir ?? process.cwd());
+        }
+        catch (err) {
+            logDebug('[hooks] config load failed: ' + err.message);
+            this.hooks = {};
+        }
+        if (baseTools.length) {
+            this.registerSuite({
+                id: 'runtime.core',
+                description: 'Core runtime metadata tools',
+                tools: baseTools,
+            });
+        }
+    }
+    registerSuite(suite) {
+        if (!suite?.id?.trim()) {
+            throw new Error('Tool suite id cannot be blank.');
+        }
+        this.unregisterSuite(suite.id);
+        for (const definition of suite.tools ?? []) {
+            this.addTool(definition, suite.id);
+        }
+    }
+    unregisterSuite(id) {
+        if (!id?.trim()) {
+            return;
+        }
+        for (const [name, record] of this.registry.entries()) {
+            if (record.suiteId === id) {
+                this.registry.delete(name);
+                this.removeFromOrder(name);
+            }
+        }
+    }
+    listProviderTools() {
+        return this.registrationOrder
+            .map((name) => this.registry.get(name))
+            .filter((record) => Boolean(record))
+            .map(({ definition }) => ({
+            name: definition.name,
+            description: definition.description,
+            ...(definition.parameters && { parameters: definition.parameters }),
+        }));
+    }
+    async execute(call, _context) {
+        const record = this.registry.get(call.name);
+        const rawArgs = normalizeToolArguments(call.arguments);
+        const args = coerceToolArguments(record?.definition.parameters, rawArgs);
+        const augmentedCall = { ...call, args };
+        if (!record) {
+            const message = `Tool "${call.name}" is not available.`;
+            this.observer?.onToolError?.(augmentedCall, message);
+            // Performance monitoring removed - no legacy components
+            return message;
+        }
+        // Check if tool is cacheable
+        const isCacheable = record.definition.cacheable ?? CACHEABLE_TOOLS.has(call.name);
+        const cacheTtl = typeof record.definition.cacheTtlMs === 'number' && Number.isFinite(record.definition.cacheTtlMs)
+            ? Math.max(0, Math.floor(record.definition.cacheTtlMs))
+            : this.cacheTTLMs;
+        const canUseCache = this.enableCache && isCacheable && cacheTtl > 0;
+        // Try to get from cache
+        if (canUseCache) {
+            const cacheKey = this.getCacheKey({ ...call, arguments: args });
+            const cached = this.cache.get(cacheKey);
+            if (cached && Date.now() - cached.timestamp < cacheTtl) {
+                this.observer?.onCacheHit?.(augmentedCall);
+                this.observer?.onToolResult?.(augmentedCall, cached.result);
+                // Record cache hit as successful execution with 0ms time
+                // Performance monitoring removed - no legacy components
+                this.recordToolHistory({
+                    toolName: call.name,
+                    args,
+                    timestamp: Date.now(),
+                    success: true,
+                    hasOutput: hasNonEmptyOutput(cached.result),
+                });
+                return cached.result;
+            }
+        }
+        this.observer?.onToolStart?.(augmentedCall);
+        // Performance monitoring removed - no legacy components
+        try {
+            validateToolArguments(record.definition.name, record.definition.parameters, args);
+            // Pre-flight AI flow validation - catch common tool usage failures
+            const preflightWarnings = validateToolPreconditions(call.name, args);
+            for (const warning of preflightWarnings) {
+                this.observer?.onToolWarning?.(augmentedCall, warning);
+            }
+            // Advanced AI flow pattern validation using tool history
+            const aiFlowWarnings = validateAIFlowPatterns(call.name, args, this.toolHistory);
+            for (const warning of aiFlowWarnings) {
+                this.observer?.onToolWarning?.(augmentedCall, warning);
+            }
+            // Collect optimization hints to inject into result
+            const optimizationHints = [];
+            const seenOptimizationCodes = new Set();
+            for (const warning of [...preflightWarnings, ...aiFlowWarnings]) {
+                if (warning.code && seenOptimizationCodes.has(warning.code)) {
+                    continue;
+                }
+                const hint = buildOptimizationHint(warning);
+                if (hint) {
+                    if (warning.code) {
+                        seenOptimizationCodes.add(warning.code);
+                    }
+                    optimizationHints.push(hint);
+                }
+            }
+            // PreToolUse hooks: run user-configured shell commands that
+            // can block this tool call. Best-effort — if the hook errors,
+            // times out, or returns malformed output, we pass through.
+            try {
+                const blocked = await runPreToolUseHooks(this.hooks, call.name, args);
+                if (blocked) {
+                    const reason = blocked.reason || 'Blocked by hook';
+                    const message = `Error: ${call.name} blocked by user hook: ${reason}`;
+                    this.observer?.onToolError?.(augmentedCall, message);
+                    this.recordToolHistory({
+                        toolName: call.name,
+                        args,
+                        timestamp: Date.now(),
+                        success: false,
+                        hasOutput: false,
+                    });
+                    return message;
+                }
+            }
+            catch (err) {
+                // A buggy hook should never crash the agent. Log + continue.
+                logDebug('[hooks] PreToolUse error: ' + err.message);
+            }
+            const result = await toolExecutionContext.run({ call: augmentedCall, observer: this.observer ?? undefined }, async () => record.definition.handler(args));
+            let output = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+            // PostToolUse hooks: append text from each matching hook so
+            // the model sees the augmentation. Useful for "lint after every
+            // edit" / "echo every Bash command to a log" patterns.
+            try {
+                const post = await runPostToolUseHooks(this.hooks, call.name, args, output);
+                if (post?.appendToResult) {
+                    output = `${output}\n\n[hook] ${post.appendToResult}`;
+                }
+            }
+            catch (err) {
+                logDebug('[hooks] PostToolUse error: ' + err.message);
+            }
+            let snapshotCandidate = output;
+            // Truncate output if context manager is available
+            if (this.contextManager) {
+                const truncated = this.contextManager.truncateToolOutput(output, call.name);
+                if (truncated.wasTruncated) {
+                    output = truncated.content;
+                    // Log truncation for debugging
+                    if (process.env['DEBUG_CONTEXT']) {
+                        logDebug(`[Context Manager] Truncated ${call.name} output: ${truncated.originalLength} -> ${truncated.truncatedLength} chars`);
+                    }
+                }
+                snapshotCandidate = output;
+            }
+            this.recordDiffSnapshot(args, snapshotCandidate);
+            // Cache the result if cacheable
+            if (canUseCache) {
+                const cacheKey = this.getCacheKey({ ...call, arguments: args });
+                this.cache.set(cacheKey, {
+                    result: output,
+                    timestamp: Date.now(),
+                });
+            }
+            // Append optimization hints to guide future LLM behavior
+            if (optimizationHints.length > 0) {
+                output = output + optimizationHints.join('');
+            }
+            this.observer?.onToolResult?.(augmentedCall, output);
+            this.recordToolHistory({
+                toolName: call.name,
+                args,
+                timestamp: Date.now(),
+                success: true,
+                hasOutput: hasNonEmptyOutput(output),
+            });
+            // Record successful execution
+            // Performance monitoring removed - no legacy components
+            return output;
+        }
+        catch (error) {
+            let formatted;
+            if (error instanceof ToolArgumentValidationError) {
+                formatted = error.message;
+            }
+            else {
+                const message = error instanceof Error ? error.message : String(error);
+                formatted = `Failed to run "${call.name}": ${message}`;
+            }
+            this.observer?.onToolError?.(augmentedCall, formatted);
+            this.recordToolHistory({
+                toolName: call.name,
+                args,
+                timestamp: Date.now(),
+                success: false,
+                hasOutput: hasNonEmptyOutput(formatted),
+                error: formatted,
+            });
+            // Record failed execution - no legacy performance monitoring
+            return formatted;
+        }
+    }
+    getCacheKey(call) {
+        return `${call.name}:${JSON.stringify(call.arguments)}`;
+    }
+    clearCache() {
+        this.cache.clear();
+    }
+    getCacheStats() {
+        let totalSize = 0;
+        for (const entry of this.cache.values()) {
+            totalSize += entry.result.length;
+        }
+        return {
+            size: totalSize,
+            entries: this.cache.size,
+        };
+    }
+    clearToolHistory() {
+        this.toolHistory.length = 0;
+    }
+    getToolHistory() {
+        return this.toolHistory;
+    }
+    recordToolHistory(entry) {
+        this.toolHistory.push(entry);
+        if (this.toolHistory.length > this.maxHistorySize) {
+            this.toolHistory.shift();
+        }
+    }
+    clearDiffSnapshots() {
+        this.diffSnapshots.length = 0;
+    }
+    getDiffSnapshots() {
+        return this.diffSnapshots;
+    }
+    addTool(definition, suiteId) {
+        if (!definition?.name?.trim()) {
+            throw new Error(`Tool names cannot be blank (suite "${suiteId}").`);
+        }
+        if (this.registry.has(definition.name)) {
+            const owner = this.registry.get(definition.name)?.suiteId ?? 'unknown';
+            throw new Error(`Tool "${definition.name}" already registered by suite "${owner}".`);
+        }
+        this.registry.set(definition.name, {
+            suiteId,
+            definition,
+        });
+        this.registrationOrder.push(definition.name);
+    }
+    removeFromOrder(name) {
+        const index = this.registrationOrder.indexOf(name);
+        if (index >= 0) {
+            this.registrationOrder.splice(index, 1);
+        }
+    }
+    recordDiffSnapshot(args, output) {
+        const command = this.findGitDiffCommand(args);
+        if (!command || !output) {
+            return;
+        }
+        this.diffSnapshots.push({
+            command,
+            output: safeTruncate(output, this.maxDiffSnapshotLength, 'git-diff'),
+            timestamp: Date.now(),
+        });
+        if (this.diffSnapshots.length > this.maxDiffSnapshots) {
+            this.diffSnapshots.shift();
+        }
+    }
+    findGitDiffCommand(args) {
+        for (const command of this.extractCommands(args)) {
+            if (this.isGitDiffCommand(command)) {
+                return command;
+            }
+        }
+        return null;
+    }
+    extractCommands(args) {
+        const commands = [];
+        const command = args['command'];
+        if (typeof command === 'string' && command.trim()) {
+            commands.push(command.trim());
+        }
+        const commandList = args['commands'];
+        if (Array.isArray(commandList)) {
+            for (const value of commandList) {
+                if (typeof value === 'string' && value.trim()) {
+                    commands.push(value.trim());
+                }
+            }
+        }
+        return commands;
+    }
+    isGitDiffCommand(command) {
+        return /\bgit\s+(?:--no-pager\s+)?(?:diff|show)\b/i.test(command);
+    }
+}
+export function createDefaultToolRuntime(context, toolSuites = [], options = {}) {
+    // Start with no default introspection tools - they waste tokens
+    // Model knows its capabilities from tool definitions
+    const runtime = new ToolRuntime([], options);
+    for (const suite of toolSuites) {
+        runtime.registerSuite(suite);
+    }
+    return runtime;
+}
+// Removed unused introspection tools (context_snapshot, capabilities_overview, profile_details)
+// Model already knows capabilities from tool definitions; these just wasted tokens
+function hasNonEmptyOutput(output) {
+    return typeof output === 'string' && output.trim().length > 0;
+}
+function normalizeToolArguments(value) {
+    if (value instanceof Map) {
+        return Object.fromEntries(value.entries());
+    }
+    if (isRecord(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            return {};
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            return isRecord(parsed) ? parsed : {};
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=toolRuntime.js.map