/**
 * Context-aware configuration resolution with automatic fallbacks.
 *
 * Provides 3-level fallback resolution for entity configuration:
 * 1. Entity-specific: `{entityType}.{entityName}.{key}`
 * 2. Entity-type default: `{entityType}.{key}`
 * 3. Global default: `{key}`
 *
 * @example
 * ```typescript
 * // For agent 'research-agent' looking for 'openaiKey':
 * // Tries: agents.research-agent.openaiKey → agents.openaiKey → openaiKey
 *
 * const resolver = createContextResolver(configService, {
 *   entityType: 'agents',
 *   entityName: 'research-agent',
 * });
 *
 * const apiKey = resolver.get('openaiKey');
 * ```
 *
 * @packageDocumentation
 */
import type { ConfigService } from './providers/config.service';
/**
 * Entity types that support context-aware config resolution.
 */
export type ConfigEntityType = 'agents' | 'plugins' | 'adapters';
/**
 * Context for resolving configuration with fallbacks.
 */
export interface ConfigResolutionContext {
    /**
     * Type of entity (agents, plugins, adapters).
     */
    entityType: ConfigEntityType;
    /**
     * Name of the specific entity.
     */
    entityName: string;
}
/**
 * Interface for resolving configuration values.
 * Used by adapter factory and other components that need config access.
 */
export interface ConfigResolver {
    /**
     * Get a configuration value by path.
     * Throws if not found.
     *
     * @param path - Dot-notation path (e.g., 'openaiKey')
     * @returns The resolved value
     * @throws Error if config key not found
     */
    get<T = unknown>(path: string): T;
    /**
     * Try to get a configuration value, returning undefined if not found.
     *
     * @param path - Dot-notation path
     * @returns The resolved value or undefined
     */
    tryGet<T = unknown>(path: string): T | undefined;
}
/**
 * Normalize an entity name for environment variable lookup.
 * Converts to uppercase and replaces non-alphanumeric characters with underscores.
 *
 * @example
 * ```typescript
 * normalizeNameForEnv('research-agent') // 'RESEARCH_AGENT'
 * normalizeNameForEnv('my agent')       // 'MY_AGENT'
 * normalizeNameForEnv('plugin.name')    // 'PLUGIN_NAME'
 * ```
 */
export declare function normalizeNameForEnv(name: string): string;
/**
 * Normalize a config path for nested object lookup.
 * Replaces non-alphanumeric characters (except dots) with underscores in each segment.
 *
 * @example
 * ```typescript
 * normalizePathSegment('research-agent') // 'research_agent'
 * ```
 */
export declare function normalizePathSegment(segment: string): string;
/**
 * Generate fallback paths for a config key based on entity context.
 *
 * Creates a 3-level fallback chain:
 * 1. `{entityType}.{entityName}.{key}` - Entity-specific
 * 2. `{entityType}.{key}` - Entity-type default
 * 3. `{key}` - Global default
 *
 * @param key - The config key to look up
 * @param context - Entity context (type and name)
 * @returns Array of paths to try in order
 *
 * @example
 * ```typescript
 * generateFallbacks('openaiKey', { entityType: 'agents', entityName: 'research-agent' })
 * // Returns: ['agents.research_agent.openaiKey', 'agents.openaiKey', 'openaiKey']
 * ```
 */
export declare function generateFallbacks(key: string, context: ConfigResolutionContext): string[];
/**
 * Generate environment variable names for fallback lookup.
 *
 * Creates environment variable names matching the fallback paths:
 * 1. `{ENTITY_TYPE}_{ENTITY_NAME}_{KEY}` - Entity-specific
 * 2. `{ENTITY_TYPE}_{KEY}` - Entity-type default
 * 3. `{KEY}` - Global default
 *
 * Note: Keys are converted to uppercase with non-alphanumeric chars replaced by underscores.
 * CamelCase keys like 'openaiKey' become 'OPENAIKEY' (no word-boundary detection).
 *
 * @param key - The config key
 * @param context - Entity context
 * @returns Array of env var names to try
 *
 * @example
 * ```typescript
 * generateEnvFallbacks('openaiKey', { entityType: 'agents', entityName: 'research-agent' })
 * // Returns: ['AGENTS_RESEARCH_AGENT_OPENAIKEY', 'AGENTS_OPENAIKEY', 'OPENAIKEY']
 * ```
 */
export declare function generateEnvFallbacks(key: string, context: ConfigResolutionContext): string[];
/**
 * Resolve a config value with fallbacks.
 * Tries each path in order until a value is found.
 *
 * @param config - ConfigService instance
 * @param paths - Paths to try in order
 * @returns The first found value, or undefined if none found
 */
export declare function resolveWithFallbacks<T>(config: ConfigService<Record<string, unknown>>, paths: string[]): T | undefined;
/**
 * Create a ConfigResolver that uses entity context for auto-fallbacks.
 *
 * @param config - ConfigService instance
 * @param context - Entity context for generating fallbacks
 * @returns ConfigResolver with fallback support
 *
 * @example
 * ```typescript
 * const resolver = createContextResolver(configService, {
 *   entityType: 'agents',
 *   entityName: 'research-agent',
 * });
 *
 * // Tries: agents.research_agent.openaiKey → agents.openaiKey → openaiKey
 * const apiKey = resolver.get('openaiKey');
 * ```
 */
export declare function createContextResolver(config: ConfigService<Record<string, unknown>>, context: ConfigResolutionContext): ConfigResolver;
/**
 * Create a simple ConfigResolver without fallbacks (direct lookup only).
 *
 * @param config - ConfigService instance
 * @returns ConfigResolver with direct lookup
 */
export declare function createDirectResolver(config: ConfigService<Record<string, unknown>>): ConfigResolver;
//# sourceMappingURL=config-resolver.d.ts.map