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;
}
/**
 * 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;
    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