/**
 * @module discovery
 * Tool discovery functionality for xRegistry
 *
 * Provides capability-based search, trust-ranked results, and auto-discovery
 * for AI agents to find and use tools without hardcoded endpoints.
 */
import type { Result } from '@private.me/shared';
import type { ToolMetadata, TrustLevel } from './types.js';
import { ToolNotFoundError, RegistryError } from './errors.js';
import { ToolRegistry } from './registry.js';
/**
 * Discovery result with ranked matches and alternatives.
 */
export interface DiscoveryResult {
    /** Primary match (highest-ranked tool) */
    primary: ToolMetadata | null;
    /** All matching tools, ranked by trust level (verified first) */
    matches: readonly ToolMetadata[];
    /** Suggested alternatives if no exact match */
    alternatives: readonly ToolMetadata[];
}
/**
 * Discovery options for customizing search behavior.
 */
export interface DiscoveryOptions {
    /** Minimum trust level required (filters out lower levels) */
    minTrustLevel?: TrustLevel;
    /** Maximum number of results to return */
    limit?: number;
    /** Include alternatives even if exact match found */
    includeAlternatives?: boolean;
}
/**
 * Discover tools by capability.
 *
 * Searches the registry for tools matching the given capability,
 * ranks results by trust level (verified > community > experimental),
 * and provides alternatives if no exact match is found.
 *
 * @param capability - Capability keyword to search for (e.g., "payment", "github", "charge")
 * @param registry - Tool registry instance to search
 * @param options - Optional discovery configuration
 * @returns Discovery result with ranked matches and alternatives
 *
 * @example
 * ```typescript
 * import { discover, ToolRegistry } from '@private.me/xregistry';
 *
 * const registry = new ToolRegistry();
 * const result = discover('payment', registry);
 *
 * if (result.primary) {
 *   console.log('Best match:', result.primary.name);
 *   console.log('Trust level:', result.primary.trustLevel);
 *   console.log('Endpoint:', result.primary.endpoint);
 * } else {
 *   console.log('No exact match, alternatives:', result.alternatives);
 * }
 * ```
 *
 * @example
 * ```typescript
 * // With options
 * const result = discover('payment', registry, {
 *   minTrustLevel: 'verified',  // Only verified tools
 *   limit: 5,                    // Max 5 results
 *   includeAlternatives: true    // Show alternatives even if match found
 * });
 * ```
 */
export declare function discover(capability: string, registry: ToolRegistry, options?: DiscoveryOptions): DiscoveryResult;
/**
 * Resolve tool alias to endpoint via registry.
 *
 * This is the integration point for agent-call.ts to replace hardcoded endpoints
 * with dynamic registry lookups.
 *
 * @param toolAlias - Tool identifier (e.g., "stripe:createCharge")
 * @param registry - Tool registry instance
 * @returns Result with tool metadata or error
 *
 * @example
 * ```typescript
 * import { resolveToolEndpoint } from '@private.me/xregistry';
 *
 * const result = resolveToolEndpoint('stripe:createCharge', registry);
 *
 * if (result.ok) {
 *   const tool = result.value;
 *   console.log('Endpoint:', tool.endpoint);
 *   console.log('Schema:', tool.schema);
 *   console.log('Trust level:', tool.trustLevel);
 * } else {
 *   console.error('Tool not found:', result.error.message);
 * }
 * ```
 */
export declare function resolveToolEndpoint(toolAlias: string, registry: ToolRegistry): Result<ToolMetadata, ToolNotFoundError>;
/**
 * Auto-discover tool by capability if not found by name.
 *
 * First tries exact name lookup. If not found, searches by capability
 * and suggests alternatives.
 *
 * @param nameOrCapability - Tool name or capability keyword
 * @param registry - Tool registry instance
 * @param options - Optional discovery configuration
 * @returns Result with tool metadata or discovery suggestions
 *
 * @example
 * ```typescript
 * import { autoDiscover } from '@private.me/xregistry';
 *
 * // Try exact name first, fallback to capability search
 * const result = autoDiscover('stripe:createCharge', registry);
 *
 * if (result.ok) {
 *   console.log('Found tool:', result.value.primary?.name);
 * } else {
 *   console.error('Discovery failed:', result.error.message);
 * }
 * ```
 */
export declare function autoDiscover(nameOrCapability: string, registry: ToolRegistry, options?: DiscoveryOptions): Result<DiscoveryResult, RegistryError>;
//# sourceMappingURL=discovery.d.ts.map