/**
 * TypeScript type definitions for MCP-AQL (MCP Agent Query Language)
 * These types match the GraphQL schema defined in schema.graphql
 */
/**
 * Element types supported by DollhouseMCP.
 * These correspond to the 6 core element types in the system.
 */
export declare enum ElementType {
    Persona = "persona",
    Skill = "skill",
    Template = "template",
    Agent = "agent",
    Memory = "memory",
    Ensemble = "ensemble"
}
export declare function normalizeMCPAQLElementType(value: string): ElementType | undefined;
/**
 * Input for all MCP-AQL operations.
 * The operation field determines which handler function is invoked.
 */
export interface OperationInput {
    /**
     * The operation to perform (e.g., 'create_element', 'list_elements')
     */
    operation: string;
    /**
     * Element type for element operations (snake_case, Issue #290)
     */
    element_type?: ElementType;
    /**
     * Element type for element operations (camelCase, legacy)
     * @deprecated Use element_type instead
     */
    elementType?: ElementType;
    /**
     * Operation-specific parameters as a JSON object
     */
    params?: Record<string, unknown>;
}
/**
 * Batch request containing multiple operations to execute in sequence.
 * Operations are executed in order, and failures do not stop execution.
 */
export interface BatchRequest {
    /**
     * Array of operations to execute in sequence
     */
    operations: Array<{
        operation: string;
        element_type?: ElementType;
        elementType?: ElementType;
        params?: Record<string, unknown>;
    }>;
}
/**
 * Individual result in a batch operation response
 */
export interface BatchOperationResult {
    /**
     * Index of the operation in the batch (0-based)
     */
    index: number;
    /**
     * Operation that was executed
     */
    operation: string;
    /**
     * Result of the operation
     */
    result: OperationResult;
}
/**
 * Result of a batch operation request.
 * success=false when the batch itself is rejected (e.g. exceeds size limit).
 */
export interface BatchResult {
    success: boolean;
    /**
     * Array of individual operation results
     */
    results: BatchOperationResult[];
    /**
     * Summary statistics
     */
    summary: {
        total: number;
        succeeded: number;
        failed: number;
    };
    /** Batch-level error message (present when success=false) */
    error?: string;
    /** Request correlation and timing metadata for the overall batch (Issue #301) */
    _meta: ResponseMeta;
}
/**
 * Successful operation result.
 * Data contains the operation-specific result payload.
 */
export interface OperationSuccess {
    success: true;
    /** Operation-specific result payload */
    data: unknown;
    /** Request correlation and timing metadata (Issue #301) */
    _meta: ResponseMeta;
    error?: never;
}
/**
 * Failed operation result.
 * Error contains a human-readable error message.
 */
export interface OperationFailure {
    success: false;
    /** Human-readable error message */
    error: string;
    /** Request correlation and timing metadata (Issue #301) */
    _meta: ResponseMeta;
    data?: never;
}
/**
 * Standard result type for all MCP-AQL operations.
 * Discriminated union ensures type safety:
 * - success: true → data is present, error is absent
 * - success: false → error is present, data is absent
 */
export type OperationResult = OperationSuccess | OperationFailure;
/**
 * Response metadata for request correlation and timing.
 * Included in every operation response to enable log correlation and performance monitoring.
 * Issue #301: Request IDs and distributed tracing support.
 */
export interface ResponseMeta {
    /** Correlation ID from ContextTracker (matches correlationId in log entries) */
    requestId: string;
    /** Wall-clock milliseconds for the operation */
    durationMs: number;
    /** ISO 8601 response timestamp */
    timestamp: string;
}
/**
 * Operation categories mapped to their safety annotations
 */
export interface OperationSafety {
    readOnly: boolean;
    destructive: boolean;
}
/**
 * Map of endpoint names to their safety annotations
 */
export declare const ENDPOINT_SAFETY: Record<string, OperationSafety>;
/**
 * Operation names grouped by endpoint
 */
export declare const ENDPOINT_OPERATIONS: {
    readonly create: readonly ["create_element", "import_element", "addEntry", "activate_element"];
    readonly read: readonly ["list_elements", "get_element", "search_elements", "query_elements", "get_active_elements", "validate_element", "render", "export_element", "deactivate_element", "introspect"];
    readonly update: readonly ["edit_element"];
    readonly delete: readonly ["delete_element", "execute_agent", "clear"];
};
/**
 * Type guard to check if a string is a valid ElementType.
 * Accepts both singular ("memory") and plural ("memories") forms.
 * Issue #433: Users and LLMs naturally use either form.
 */
export declare function isElementType(value: unknown): value is ElementType;
/**
 * Type guard to check if an object is a valid OperationInput
 * Issue #290: Accepts both element_type (snake_case) and elementType (camelCase)
 */
export declare function isOperationInput(value: unknown): value is OperationInput;
/**
 * Type guard to check if an object is a valid OperationResult
 */
export declare function isOperationResult(value: unknown): value is OperationResult;
/**
 * Type guard to check if an object is a valid BatchRequest
 */
export declare function isBatchRequest(value: unknown): value is BatchRequest;
/**
 * Legacy tool format that some LLMs might generate.
 * This is NOT documented but silently supported for resilience.
 *
 * NOTE: Only one of args/params should be used; if both are present,
 * args takes precedence.
 */
interface LegacyToolFormat {
    tool: string;
    /** Operation arguments (takes precedence over params) */
    args?: Record<string, unknown>;
    /** Operation parameters (used only if args not present) */
    params?: Record<string, unknown>;
}
/**
 * Type guard to check if input is in legacy tool format.
 * Supports: { tool: 'operation_name', args: {...} }
 *       or: { tool: 'operation_name', params: {...} }
 *
 * INTERNAL USE ONLY - Not documented to users.
 * Issue #205: Silent JSON fallback for edge cases.
 */
export declare function isLegacyToolFormat(value: unknown): value is LegacyToolFormat;
/**
 * Convert legacy tool format to proper OperationInput.
 *
 * PRECEDENCE RULES:
 * 1. If `args` is present (even if empty {}), use `args`
 * 2. Otherwise, if `params` is present, use `params`
 * 3. If neither present, use empty object {}
 *
 * EDGE CASE: { tool: 'x', args: { a: 1 }, params: { b: 2 } }
 * Result: { operation: 'x', params: { a: 1 } } (args wins, params ignored)
 *
 * INTERNAL USE ONLY - Not documented to users.
 * Issue #205: Silent JSON fallback for edge cases.
 */
export declare function convertLegacyToMCPAQL(legacy: LegacyToolFormat): OperationInput;
/**
 * Input format types for internal metrics tracking.
 * Issue #205: Silent JSON fallback for edge cases.
 */
export type InputFormat = 'proper' | 'legacy_converted' | 'permission_prompt_protocol' | 'invalid';
/**
 * Internal metrics for input format tracking.
 * Not exposed to users; for monitoring purposes only.
 *
 * High legacy_converted ratio might indicate:
 * - Documentation issues
 * - Model confusion
 * - Need for better prompt engineering
 */
export declare class InputFormatMetrics {
    private static counts;
    /**
     * Record an input format event
     */
    static record(format: InputFormat): void;
    /**
     * Get current metrics snapshot
     */
    static getMetrics(): Readonly<Record<InputFormat, number>>;
    /**
     * Reset metrics (mainly for testing)
     */
    static reset(): void;
}
/**
 * Parse and normalize operation input, handling multiple formats.
 *
 * Supports:
 * 1. Proper MCP-AQL format: { operation: 'x', params: {...} }
 * 2. Legacy tool format: { tool: 'x', args: {...} } (silent fallback)
 *
 * Issue #205: Silent JSON fallback for edge cases.
 *
 * @param input - Raw input to parse
 * @returns Normalized OperationInput or null if invalid
 */
export declare function parseOperationInput(input: unknown): OperationInput | null;
/**
 * Generate a diagnostic summary of invalid input for error messages.
 * Helps agents and developers understand what was actually received when
 * parsing fails — especially useful for debugging parallel-call issues (#1656).
 *
 * @param input - The raw input that failed to parse
 * @returns Human-readable diagnostic string describing what was received
 *
 * @example
 * describeInvalidInput(null)
 * // => 'Received: null'
 *
 * describeInvalidInput({ params: { element_name: 'x' } })
 * // => 'Received: { params } (missing "operation" field)'
 *
 * describeInvalidInput([{ operation: 'addEntry' }, { operation: 'addEntry' }])
 * // => 'Received: array with 2 items (use { operations: [...] } for batch calls)'
 *
 * describeInvalidInput({ operation: 123, params: {} })
 * // => 'Received: { operation, params } ("operation" is number, expected string)'
 */
export declare function describeInvalidInput(input: unknown): string;
export {};
//# sourceMappingURL=types.d.ts.map