/**
 * MCP Auto Mode
 *
 * Automatically defers tool descriptions when they would exceed a configurable
 * percentage of the context window. This prevents context overflow in long
 * sessions with many tools.
 *
 * Based on Claude Code v2.1.7's MCP Auto Mode feature.
 *
 * Key features:
 * - Configurable percentage threshold for tool descriptions
 * - Priority-based tool selection
 * - Always-include and always-defer lists
 * - On-demand fetching of deferred tool descriptions
 * - Force-include override for user requests
 */
import type { Logger } from '../observability/logger.js';
import type { ContextManager, ContextState } from '../router/context-manager.js';
/**
 * Configuration for MCP Auto Mode
 */
export interface MCPAutoModeConfig {
    /** Enable auto mode (default: true) */
    enabled: boolean;
    /** Maximum percentage of context for tool descriptions (default: 10) */
    maxToolDescriptionPercent: number;
    /** Tools that should never be deferred */
    alwaysInclude?: string[];
    /** Tools that should always be deferred */
    alwaysDefer?: string[];
    /** Minimum tools to include even when deferring (default: 5) */
    minToolsToInclude: number;
}
/**
 * Tool with its description metadata
 */
export interface ToolDescriptor {
    /** Unique tool name */
    name: string;
    /** Tool description text */
    description: string;
    /** Estimated tokens for this tool's schema */
    estimatedTokens: number;
    /** Priority (higher = more important, default: 0) */
    priority?: number;
    /** Is this tool currently deferred? */
    deferred?: boolean;
    /** Timestamp of last use (for recency-based prioritization) */
    lastUsedAt?: number;
}
/**
 * Result of auto mode processing
 */
export interface AutoModeResult {
    /** Tools to include in this request */
    includedTools: string[];
    /** Tools that were deferred */
    deferredTools: string[];
    /** Total tokens saved by deferring */
    tokensSaved: number;
    /** Was any tool deferred? */
    hadDeferrals: boolean;
    /** Message to show user if tools were deferred */
    deferralMessage?: string;
}
/**
 * MCP Auto Mode - Intelligent tool description management
 *
 * Automatically defers tool descriptions that would exceed context limits.
 * This is based on Claude Code v2.1.7's MCP Auto Mode feature.
 *
 * @example
 * ```typescript
 * const autoMode = new MCPAutoMode(
 *   { maxToolDescriptionPercent: 15 },
 *   contextManager,
 *   logger
 * );
 *
 * // Register tools
 * autoMode.registerTool({
 *   name: 'invoke_agent',
 *   description: 'Invoke a specialized agent...',
 *   estimatedTokens: 150,
 *   priority: 10,
 * });
 *
 * // Before each request, process tools
 * const contextState = contextManager.getState('openai', 'gpt-4o', messages);
 * const result = autoMode.processForRequest(contextState);
 *
 * // Use result.includedTools for this request
 * if (result.hadDeferrals) {
 *   console.log(result.deferralMessage);
 * }
 * ```
 */
export declare class MCPAutoMode {
    private config;
    private readonly contextManager;
    private readonly logger;
    private toolRegistry;
    private forcedIncludes;
    /**
     * Create a new MCPAutoMode instance.
     *
     * @param config - Partial configuration (merged with defaults)
     * @param contextManager - ContextManager for token estimation
     * @param logger - Logger instance for observability
     */
    constructor(config: Partial<MCPAutoModeConfig>, contextManager: ContextManager, logger: Logger);
    /**
     * Register a tool with its description.
     *
     * @param tool - Tool descriptor to register
     */
    registerTool(tool: ToolDescriptor): void;
    /**
     * Unregister a tool.
     *
     * @param name - Name of tool to unregister
     */
    unregisterTool(name: string): void;
    /**
     * Get all registered tools.
     *
     * @returns Array of all tool descriptors
     */
    getAllTools(): ToolDescriptor[];
    /**
     * Calculate total tokens for all tool descriptions.
     *
     * @returns Total estimated tokens
     */
    getTotalToolTokens(): number;
    /**
     * Process tools for a request given current context state.
     * Returns which tools to include and which to defer.
     *
     * @param contextState - Current context state from ContextManager
     * @param requestedTools - Optional list of specifically requested tool names
     * @returns AutoModeResult with included/deferred tools
     */
    processForRequest(contextState: ContextState, requestedTools?: string[]): AutoModeResult;
    /**
     * Get deferred tool description on demand.
     * (When user explicitly requests a deferred tool)
     *
     * @param name - Name of deferred tool
     * @returns Tool descriptor if found, undefined otherwise
     */
    getDeferredToolDescription(name: string): ToolDescriptor | undefined;
    /**
     * Check if a specific tool is currently deferred.
     *
     * @param name - Tool name to check
     * @returns True if tool is deferred
     */
    isDeferred(name: string): boolean;
    /**
     * Force include a deferred tool (user override).
     * This tool will be included in subsequent requests until reset.
     *
     * @param name - Tool name to force include
     */
    forceInclude(name: string): void;
    /**
     * Reset all deferrals and force-includes.
     */
    resetDeferrals(): void;
    /**
     * Mark a tool as recently used (for recency-based prioritization).
     *
     * @param name - Tool name that was used
     */
    markToolUsed(name: string): void;
    /**
     * Get current configuration.
     *
     * @returns Current MCPAutoModeConfig
     */
    getConfig(): MCPAutoModeConfig;
    /**
     * Update configuration.
     *
     * @param config - Partial configuration to merge
     */
    updateConfig(config: Partial<MCPAutoModeConfig>): void;
    /**
     * Sort tools by priority for inclusion decisions.
     *
     * Priority order:
     * 1. Tools in alwaysInclude
     * 2. Tools explicitly requested for this call
     * 3. Tools that were force-included by user
     * 4. Recently used tools
     * 5. Tools with higher priority scores
     * 6. Other tools
     * 7. Tools in alwaysDefer (lowest priority)
     */
    private getSortedTools;
    /**
     * Calculate total tokens saved by deferring tools.
     */
    private calculateTokensSaved;
    /**
     * Estimate token count for a tool based on its description.
     * Uses the context manager's estimation logic.
     */
    private estimateToolTokens;
}
/**
 * Create an MCPAutoMode instance.
 *
 * @param config - Partial configuration (merged with defaults)
 * @param contextManager - ContextManager instance
 * @param logger - Logger instance
 * @returns Configured MCPAutoMode instance
 */
export declare function createMCPAutoMode(config: Partial<MCPAutoModeConfig>, contextManager: ContextManager, logger: Logger): MCPAutoMode;
//# sourceMappingURL=auto-mode.d.ts.map