/**
 * MCPAQLHandler - Unified handler for all MCP-AQL operations
 *
 * ARCHITECTURE:
 * - Thin resolver pattern: validates → routes → dispatches
 * - SOLID principles: depends on abstractions (HandlerRegistry interface)
 * - Defense in depth: Gatekeeper validates endpoint/operation matching and enforces policies
 * - Dispatch pattern: routes handler references to actual method calls
 *
 * OPERATION FLOW:
 * 1. Validate input structure (type guards)
 * 2. Validate permissions (Gatekeeper)
 * 3. Route operation (OperationRouter)
 * 4. Dispatch to handler (resolveHandlerReference)
 * 5. Return standardized result (OperationResult)
 *
 * ERROR HANDLING:
 * All errors are caught and returned as OperationFailure with:
 * - success: false
 * - error: human-readable message
 * - data: never (discriminated union enforces this)
 */
import { Gatekeeper } from './Gatekeeper.js';
import { OperationResult, BatchResult } from './types.js';
import type { DangerZoneEnforcer } from '../../security/DangerZoneEnforcer.js';
import type { VerificationStore } from '@dollhousemcp/safety';
import type { IVerificationNotifier } from '../../services/VerificationNotifier.js';
import type { ElementCRUDHandler } from '../ElementCRUDHandler.js';
import type { MemoryManager } from '../../elements/memories/MemoryManager.js';
import type { AgentManager } from '../../elements/agents/AgentManager.js';
import type { TemplateRenderer } from '../../utils/TemplateRenderer.js';
import type { ElementQueryService } from '../../services/query/ElementQueryService.js';
import type { CollectionHandler } from '../CollectionHandler.js';
import type { PortfolioHandler } from '../PortfolioHandler.js';
import type { GitHubAuthHandler } from '../GitHubAuthHandler.js';
import type { ConfigHandler } from '../ConfigHandler.js';
import type { EnhancedIndexHandler } from '../EnhancedIndexHandler.js';
import type { PersonaHandler } from '../PersonaHandler.js';
import type { SyncHandler } from '../SyncHandlerV2.js';
import type { BuildInfoService } from '../../services/BuildInfoService.js';
import type { MemoryLogSink } from '../../logging/sinks/MemoryLogSink.js';
import type { PerformanceMonitor } from '../../utils/PerformanceMonitor.js';
import type { OperationMetricsTracker } from '../../metrics/OperationMetricsTracker.js';
import type { GatekeeperMetricsTracker } from '../../metrics/GatekeeperMetricsTracker.js';
import type { AutonomyMetricsSnapshot } from '../../elements/agents/autonomyEvaluator.js';
/**
 * Verification metrics tracker following DangerZoneEnforcer.getMetrics() pattern.
 * Tracks success/failure/expiry rates and time-to-verify.
 */
export interface VerificationMetrics {
    /** Total verify_challenge calls since startup */
    totalAttempts: number;
    /** Successful verifications */
    totalSuccesses: number;
    /** Failed verifications (wrong code) */
    totalFailures: number;
    /** Expired challenge attempts */
    totalExpired: number;
    /** Invalid format attempts (rejected before store lookup) */
    totalInvalidFormat: number;
    /** Rate-limited attempts */
    totalRateLimited: number;
    /** Average time from challenge creation to successful verify (ms) */
    averageTimeToVerifyMs: number;
    /** Current failures in rate-limit window */
    failuresInCurrentWindow: number;
}
/**
 * Handler registry interface for dependency injection.
 * Abstracts the concrete handler types for better testability and decoupling.
 */
export interface HandlerRegistry {
    elementCRUD: ElementCRUDHandler;
    memoryManager: MemoryManager;
    agentManager: AgentManager;
    templateRenderer: TemplateRenderer;
    elementQueryService: ElementQueryService;
    collectionHandler?: CollectionHandler;
    portfolioHandler?: PortfolioHandler;
    authHandler?: GitHubAuthHandler;
    configHandler?: ConfigHandler;
    enhancedIndexHandler?: EnhancedIndexHandler;
    personaHandler?: PersonaHandler;
    syncHandler?: SyncHandler;
    buildInfoService?: BuildInfoService;
    cacheMemoryBudget?: import('../../cache/CacheMemoryBudget.js').CacheMemoryBudget;
    gatekeeper: Gatekeeper;
    dangerZoneEnforcer?: DangerZoneEnforcer;
    verificationStore?: VerificationStore;
    verificationNotifier?: IVerificationNotifier;
    memorySink?: MemoryLogSink;
    metricsSink?: import('../../metrics/sinks/MemoryMetricsSink.js').MemoryMetricsSink;
    performanceMonitor?: PerformanceMonitor;
    operationMetricsTracker?: OperationMetricsTracker;
    gatekeeperMetricsTracker?: GatekeeperMetricsTracker;
}
/**
 * MCPAQLHandler - Unified entry point for all MCP-AQL operations
 *
 * This handler implements the thin resolver pattern:
 * 1. Validates that operations are called via correct CRUD endpoints
 * 2. Routes operations to their handler references
 * 3. Dispatches to actual handler methods
 * 4. Returns standardized OperationResult
 *
 * DESIGN RATIONALE:
 * - Single Responsibility: Only orchestrates, delegates actual work
 * - Dependency Inversion: Depends on HandlerRegistry interface
 * - Interface Segregation: HandlerRegistry exposes only what's needed
 * - Open/Closed: New operations added to router, not this class
 */
/**
 * Minimal interface for correlation ID retrieval.
 * Keeps coupling loose — only requires what MCPAQLHandler actually needs.
 * Issue #301: Request correlation support.
 */
export interface CorrelationIdProvider {
    getCorrelationId(): string | undefined;
}
export declare class MCPAQLHandler {
    private readonly handlers;
    private readonly contextTracker?;
    private readonly gatekeeper;
    /**
     * Issue #656: Per-memory save debounce timers.
     * When addEntry is called rapidly, we coalesce saves — only the latest
     * state is written to disk after the debounce window expires.
     * Key: normalized memory name, Value: { timer, memory, manager }
     */
    private readonly pendingSaves;
    /** Issue #656: Debounce metrics — tracks saves coalesced vs actually written. */
    private readonly debounceMetrics;
    /**
     * Issue #657: Per-memory save frequency tracker.
     * Sliding window counter: tracks addEntry calls per memory within the monitor window.
     * Logs warnings at configurable thresholds to catch runaway loops early.
     */
    private readonly saveFrequencyCounters;
    /** Issue #625 Phase 4: Rate limiter for permission_prompt evaluations (configurable via env) */
    private readonly permissionPromptLimiter;
    /** Issue #625 Phase 4: Rate limiter for CLI approval record creation (configurable via env) */
    private readonly cliApprovalLimiter;
    /**
     * Build a standardized rate-limit deny response for permission_prompt.
     */
    private buildRateLimitDeny;
    /** Issue #142: Rate limiter for verify_challenge attempts (max 10 failures per 60s window) */
    private readonly verificationRateLimiter;
    /** Issue #142: Metrics tracker for verification operations */
    private readonly verificationMetrics;
    /**
     * Tracks agents currently in an execution loop for Gatekeeper policy enforcement.
     *
     * **Lifecycle:** Entries are added in `dispatchExecute()` on `execute_agent` and
     * removed on `complete_execution`. Only agents with a gatekeeper policy (explicit
     * or synthesized from `tools` config) are tracked.
     *
     * **Policy resolution:** Entries are included in `getActiveElements()` so the
     * Gatekeeper evaluates agent policies alongside persona/skill/ensemble policies.
     * The standard priority applies: deny > scope_restriction > confirm > allow.
     *
     * **Memory safety:** The Map is bounded by concurrently executing agents. If a
     * session ends without `complete_execution`, the Map is garbage collected with
     * the MCPAQLHandler instance.
     *
     * Issue #449
     */
    private readonly executingAgents;
    /**
     * Set of aborted goalIds. Once a goalId is aborted, all further execution
     * operations (record_execution_step, complete_execution, continue_execution)
     * for that goalId are rejected at the dispatch layer.
     *
     * Issue #249: Abort/cancellation infrastructure.
     */
    private readonly abortedGoals;
    constructor(handlers: HandlerRegistry, contextTracker?: CorrelationIdProvider | undefined);
    /**
     * Get verification metrics for monitoring/diagnostics.
     * Follows the same pattern as DangerZoneEnforcer.getMetrics().
     */
    getVerificationMetrics(): VerificationMetrics;
    /**
     * Get autonomy evaluation metrics for monitoring/diagnostics.
     * Issue #391: Follows the same pattern as getVerificationMetrics().
     */
    getAutonomyMetrics(): AutonomyMetricsSnapshot;
    /**
     * Gather currently active elements for Gatekeeper policy evaluation.
     *
     * Queries PersonaManager, SkillManager, and EnsembleManager for active elements,
     * then appends any currently executing agents with gatekeeper policies. All
     * elements are mapped to the {@link ActiveElement} interface expected by
     * `Gatekeeper.enforce()`.
     *
     * Issue #452: Provides element context for Layer 2 (element policy resolution).
     * Issue #449: Includes executing agents alongside personas/skills/ensembles.
     *
     * @returns Array of active elements with their gatekeeper policies, or empty
     *          array if gathering fails (fail-open: only route policies apply).
     */
    private getActiveElements;
    private getPolicyReportElements;
    private copyGatekeeperDiagnostics;
    /**
     * Handle CREATE operations (additive, non-destructive)
     *
     * CREATE endpoint operations:
     * - create_element: Create new elements
     * - import_element: Import elements from exported data
     * - addEntry: Add entries to memory elements
     *
     * Supports batch operations when input contains `operations` array.
     *
     * @param input - Operation input with operation name and params, or BatchRequest
     * @returns OperationResult with success/failure status, or BatchResult for batch operations
     */
    handleCreate(input: unknown): Promise<OperationResult | BatchResult>;
    /**
     * Handle READ operations (read-only, safe)
     *
     * READ endpoint operations:
     * - list_elements: List elements with filtering
     * - get_element: Get element by name
     * - get_element_details: Get detailed element information
     * - search_elements: Full-text search
     * - query_elements: Query with pagination
     * - get_active_elements: Get active elements
     * - validate_element: Validate element
     * - render: Render template
     * - export_element: Export element
     * - activate_element: Activate elements for use
     * - deactivate_element: Deactivate element
     *
     * Supports batch operations when input contains `operations` array.
     *
     * @param input - Operation input with operation name and params, or BatchRequest
     * @returns OperationResult with success/failure status, or BatchResult for batch operations
     */
    handleRead(input: unknown): Promise<OperationResult | BatchResult>;
    /**
     * Handle UPDATE operations (modifying existing state)
     *
     * UPDATE endpoint operations:
     * - edit_element: Modify existing elements
     *
     * Supports batch operations when input contains `operations` array.
     *
     * @param input - Operation input with operation name and params, or BatchRequest
     * @returns OperationResult with success/failure status, or BatchResult for batch operations
     */
    handleUpdate(input: unknown): Promise<OperationResult | BatchResult>;
    /**
     * Handle DELETE operations (destructive actions)
     *
     * DELETE endpoint operations:
     * - delete_element: Delete elements
     * - clear: Clear memory entries
     * - clear_github_auth: Remove GitHub authentication
     *
     * Supports batch operations when input contains `operations` array.
     *
     * @param input - Operation input with operation name and params, or BatchRequest
     * @returns OperationResult with success/failure status, or BatchResult for batch operations
     */
    handleDelete(input: unknown): Promise<OperationResult | BatchResult>;
    /**
     * Handle EXECUTE operations (runtime execution lifecycle)
     *
     * EXECUTE endpoint operations:
     * - execute_agent: Start execution of an agent or executable element
     * - get_execution_state: Query current execution state
     * - record_execution_step: Record execution progress or findings
     * - complete_execution: Signal execution finished successfully
     * - continue_execution: Resume execution from saved state
     * - abort_execution: Cancel an ongoing execution
     *
     * Unlike CRUD operations (which are idempotent), EXECUTE operations manage
     * runtime state and are inherently non-idempotent. Calling execute twice
     * creates two separate executions.
     *
     * Supports batch operations when input contains `operations` array.
     *
     * @param input - Operation input with operation name and params, or BatchRequest
     * @returns OperationResult with success/failure status, or BatchResult for batch operations
     */
    handleExecute(input: unknown): Promise<OperationResult | BatchResult>;
    /**
     * Core execution logic shared by all CRUD endpoints.
     * Implements the thin resolver pattern: validate → route → dispatch → return.
     *
     * OPERATION FLOW:
     * 1. Validate input structure
     * 2. Validate permissions (PermissionGuard)
     * 3. Route operation (OperationRouter)
     * 4. Dispatch to handler
     * 5. Return standardized result
     *
     * @param input - Raw input to validate and process
     * @param endpoint - CRUD endpoint being called
     * @returns Standardized OperationResult
     */
    private executeOperation;
    /**
     * Execute a batch of operations sequentially.
     * Operations are executed in order, and failures do not stop execution.
     *
     * EXECUTION SEMANTICS:
     * - Operations run sequentially (in order)
     * - Each operation is validated independently
     * - Failed operations don't stop the batch
     * - All results are collected and returned
     *
     * @param batch - BatchRequest with array of operations
     * @param endpoint - CRUD endpoint being called
     * @returns BatchResult with all operation results and summary
     */
    private executeBatch;
    /**
     * Dispatch a handler reference to the actual handler method.
     *
     * Handler reference format: "Module.method"
     * Examples:
     * - "ElementCRUD.create" → this.handlers.elementCRUD.createElement(...)
     * - "Memory.addEntry" → this.handlers.memoryManager.addEntry(...)
     * - "Agent.execute" → this.handlers.agentManager.executeAgent(...)
     *
     * DISPATCH STRATEGY (Issue #247):
     * 1. Check if operation is schema-driven → use SchemaDispatcher
     * 2. Otherwise fall through to legacy module-based dispatch
     *
     * Schema-driven operations benefit from:
     * - Declarative configuration (no switch statements)
     * - Auto-generated parameter validation
     * - Single source of truth for operation metadata
     *
     * @param handlerRef - Handler reference in "Module.method" format
     * @param input - Validated operation input
     * @returns Promise resolving to operation-specific data
     * @throws Error if handler reference is unknown or method fails
     */
    private dispatch;
    /**
     * Dispatch ElementCRUD operations to ElementCRUDHandler
     */
    private dispatchElementCRUD;
    /**
     * Handle element import operation.
     * Parses export package, deserializes element data, and creates the element.
     *
     * @param params - Operation parameters containing data and optional overwrite flag
     * @returns Promise resolving to created element
     * @throws Error if export package is invalid or element already exists (when overwrite is false)
     */
    private handleImportElement;
    /**
     * Export an element to JSON or YAML format
     *
     * @param name - Element name to export
     * @param type - Element type (persona, skill, template, agent, memory, ensemble)
     * @param format - Export format: 'json' or 'yaml' (default: 'json')
     * @returns ExportPackage with serialized element data
     */
    private handleExportElement;
    /**
     * Dispatch Memory operations to MemoryManager
     *
     * Memory operations work on individual Memory instances:
     * 1. Get the Memory by name from MemoryManager
     * 2. Call the operation on the Memory instance
     */
    /**
     * Issue #656: Debounce memory saves to prevent file descriptor exhaustion.
     * Coalesces rapid addEntry calls — only writes the latest state after the window expires.
     */
    private debouncedMemorySave;
    /**
     * Issue #657: Track addEntry call frequency per memory and log warnings at thresholds.
     *
     * Uses a sliding window counter to detect runaway save loops before they exhaust resources.
     * Counters are bounded: max 500 tracked memories, oldest-first eviction when exceeded.
     * Warning/critical flags auto-reset when frequency drops below thresholds.
     *
     * @param memoryName - Name of the memory being written to
     */
    private trackSaveFrequency;
    /**
     * Issue #656: Flush all pending debounced saves on shutdown.
     * Called by DI container dispose chain to ensure no data is lost.
     */
    dispose(): Promise<void>;
    /**
     * Issue #656: Flush all pending debounced saves immediately.
     */
    flushPendingSaves(): Promise<void>;
    private dispatchMemory;
    /**
     * Dispatch Agent operations to AgentManager
     */
    private dispatchAgent;
    /**
     * Dispatch Template operations to TemplateRenderer
     */
    private dispatchTemplate;
    /**
     * Dispatch Activation operations (cross-cutting concern)
     */
    private dispatchActivation;
    /**
     * Dispatch Search operations to ElementQueryService
     */
    private dispatchSearch;
    /**
     * Dispatch Introspection operations to IntrospectionResolver
     */
    private dispatchIntrospection;
    /**
     * Search elements across one or all element types
     *
     * Implements simple case-insensitive substring matching on:
     * - metadata.name
     * - metadata.description
     * - content (if available)
     *
     * @param input - Operation input with optional elementType and search params
     * @returns Search results with matched elements and relevance info
     */
    private handleSearchElements;
    /**
     * Dispatch Collection operations to CollectionHandler
     */
    private dispatchCollection;
    /**
     * Dispatch Portfolio operations to PortfolioHandler
     */
    private dispatchPortfolio;
    /**
     * Dispatch Auth operations to GitHubAuthHandler
     */
    private dispatchAuth;
    /**
     * Dispatch Config operations to ConfigHandler and BuildInfoService
     */
    private dispatchConfig;
    /**
     * Dispatch EnhancedIndex operations to EnhancedIndexHandler
     */
    private dispatchEnhancedIndex;
    /**
     * Dispatch Persona operations to PersonaHandler
     */
    private dispatchPersona;
    private challengeIsForDeadlockRelief;
    private issueDeadlockReliefChallenge;
    private completeDeadlockRelief;
    /**
     * Dispatch Gatekeeper operations for confirmation management.
     *
     * Issue #452: Handles the confirm_operation flow where users approve
     * operations that require confirmation per Gatekeeper policy.
     *
     * Flow:
     * 1. Gatekeeper.enforce() returns confirmationPending: true
     * 2. LLM calls confirm_operation with the operation name
     * 3. This method records the confirmation in the session
     * 4. LLM retries the original operation, which now passes via Layer 3
     */
    private dispatchGatekeeper;
    /**
     * Dispatch Logging operations (Issue #528 - CRUDE migration)
     *
     * Routes query_logs through the unified CRUDE pipeline instead of
     * a standalone MCP tool, providing operation routing, gatekeeper
     * policy enforcement, and structured response format.
     */
    private dispatchLogging;
    /**
     * Dispatch Metrics operations.
     *
     * Routes query_metrics through the unified CRUDE pipeline, providing
     * operation routing, gatekeeper policy enforcement, and structured response format.
     */
    private dispatchMetrics;
    /**
     * Dispatch Browser operations (Issue #774: open portfolio browser)
     */
    /**
     * Dispatch Browser operations.
     *
     * Starts the portfolio web server (if not running) and opens the
     * system browser. Returns the URL and any warnings if the browser
     * could not be opened automatically.
     *
     * @param method - The browser method to dispatch ('open')
     * @returns MCP response with URL and optional warning
     * @see Issue #774
     */
    /**
     * Extract URL query parameters from operation params.
     * Serializes all params except 'tab' as string key-value pairs.
     * @see Issue #1765 - URL parameter support for portfolio browser
     */
    private static extractUrlParams;
    /** Serialize a param value to a URL-safe string. */
    private static serializeParamValue;
    private dispatchBrowser;
    /**
     * Look up the CRUDE endpoint for a given operation name.
     * Used by dispatchGatekeeper to determine the correct endpoint context.
     */
    private getEndpointForOperation;
    /**
     * Build a human-readable summary of an operation for confirmation prompts.
     * Issue #748: Natural language confirmation summaries.
     *
     * Translates raw operation names and params into plain language so users
     * understand what they're approving without parsing machine-readable payloads.
     */
    private buildOperationSummary;
    /**
     * Score the risk of an MCP-AQL operation for auto-confirm audit trails.
     *
     * Returns a score from 0-100 based on operation characteristics:
     * - DELETE endpoint operations: base 80 (destructive, data loss)
     * - EXECUTE endpoint operations: base 60 (unpredictable side effects)
     * - UPDATE endpoint operations: base 40 (modifies existing data)
     * - CREATE endpoint operations: base 20 (additive, low risk)
     *
     * Modifiers:
     * - Operations with canBeElevated: false get +10 (structurally dangerous)
     * - Operations targeting gatekeeper fields get +10 (privilege escalation vector)
     *
     * @param operation - The operation name
     * @param endpoint - The CRUDE endpoint
     * @param params - Operation parameters (for field inspection)
     * @returns Risk score 0-100
     */
    private scoreOperationRisk;
    /**
     * Dispatch Execute operations for execution lifecycle management (Issue #244)
     *
     * Execute operations handle runtime state of executable elements:
     * - execute: Start a new execution
     * - getState: Query current execution state
     * - updateState: Record progress, findings, step completion
     * - complete: Signal successful completion
     * - continue: Resume from saved state
     * - abort: Cancel an ongoing execution
     *
     * These operations are non-idempotent by nature (unlike CRUD operations).
     * Currently routes to AgentManager, but designed for future extensibility
     * to workflows, pipelines, and other executable element types.
     */
    private dispatchExecute;
    /** Maximum recent blocks tracked per agent to prevent unbounded growth */
    private static readonly MAX_RECENT_BLOCKS;
    /**
     * Record a gatekeeper block against all currently executing agents.
     * Called when Gatekeeper.enforce() denies an operation, so that
     * record_execution_step can report it as a notification.
     *
     * @since v2.1.0 - Agent Notification System
     * @private
     */
    private recordGatekeeperBlockForAgents;
    /**
     * Collect notifications for an executing agent from all sources:
     * 1. Unreported gatekeeper blocks → permission_pending
     * 2. Autonomy pause (continue=false) → autonomy_pause
     * 3. DangerZone blocked agents (system-wide broadcast) → danger_zone
     *
     * Gatekeeper blocks are marked as "reported" after first collection
     * so they don't repeat on subsequent calls. DangerZone and autonomy
     * notifications are always emitted while the condition persists.
     *
     * @since v2.1.0 - Agent Notification System
     * @private
     */
    private collectNotifications;
    /**
     * Evaluate resilience policy after a step result and potentially override
     * the autonomy directive to enable auto-continuation or retry.
     *
     * Returns a modified step result if resilience kicks in, or null to use
     * the original result (default behavior).
     *
     * @since v2.1.0 - Agent Execution Resilience (Issue #526)
     * @private
     */
    private evaluateResilience;
    /**
     * Get active goal IDs for an agent (Issue #249).
     * Queries the agent's state to find in-progress goals.
     * @private
     */
    private getActiveGoalIds;
    /**
     * Get the current correlation ID from the underlying ContextTracker.
     * Exposed for use by UnifiedEndpoint and other wrappers.
     * Issue #301.
     */
    getCorrelationId(): string | undefined;
    /**
     * Build response metadata with correlation ID and timing.
     * Issue #301: Request IDs and distributed tracing support.
     */
    private buildMeta;
    /**
     * Create a successful operation result
     */
    private success;
    /**
     * Create a failed operation result
     */
    private failure;
    /**
     * Apply field selection and name transformation to handler response.
     *
     * Processes the `fields` parameter to filter response data:
     * - If fields is an array, filter to those fields only
     * - If fields is a preset string ('minimal', 'standard', 'full'), use preset
     * - If fields is not provided, transform names only (name → element_name)
     *
     * For responses with `results` or `items` arrays, field selection is applied
     * to each item in the array rather than filtering the container object.
     *
     * @param result - The raw handler result
     * @param params - Original params containing optional `fields`
     * @returns Transformed result with field selection applied
     */
    private applyFieldSelection;
    /**
     * Transform response with awareness of nested arrays.
     * Applies name transformation to items within `results` or `items` arrays.
     */
    private transformWithArrayAwareness;
    /**
     * Filter response with awareness of nested arrays.
     * Applies field filtering to items within `results` or `items` arrays.
     */
    private filterWithArrayAwareness;
    /**
     * Transform top-level fields of an object, excluding specified keys.
     * Used to preserve container metadata (total, query, etc.) while filtering nested arrays.
     */
    private transformTopLevel;
    /**
     * Check if result is an MCP response format (with content array).
     * These responses contain formatted text and shouldn't be transformed.
     */
    private isMCPResponse;
}
//# sourceMappingURL=MCPAQLHandler.d.ts.map