@trenchwork/erosolar 1.1.30 → 1.1.32

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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"}