import { type RequestContext } from '../../utils/internal/requestContext.js';
/**
 * RFC 5424 severity levels supported by the MCP logger, ordered from least to most severe.
 * These map internally to Pino levels for transport compatibility:
 * - `debug` → pino `debug`
 * - `info` / `notice` → pino `info`
 * - `warning` → pino `warn`
 * - `error` / `crit` → pino `error`
 * - `alert` / `emerg` → pino `fatal`
 */
export type McpLogLevel = 'debug' | 'info' | 'notice' | 'warning' | 'error' | 'crit' | 'alert' | 'emerg';
/**
 * Pino `formatters.log` hook. Strips values that break pino-redact's wildcard
 * traversal on Node 25+ — notably `AbortSignal` (via `ctx.signal`) and the
 * method-bearing handles on the framework `Context` (`log`, `state`, `elicit`,
 * `sample`, `notifyResource*`, `progress`). Acts as a safety net for every log
 * call regardless of how callers shaped their bindings.
 *
 * @internal Exported only for unit testing. Not part of the public API.
 */
export declare function sanitizeLogBindings(obj: Record<string, unknown>): Record<string, unknown>;
/**
 * Singleton structured logger backed by Pino with RFC 5424 level semantics.
 *
 * Features:
 * - Environment-adaptive output: pretty-printed (pino-pretty) in HTTP development mode,
 *   JSON to stderr in stdio/production mode (MCP spec requires clean stdout).
 * - Optional file sinks: `combined.log` at the configured log level, `error.log` for
 *   errors and above, and `interactions.log` for structured interaction records.
 * - Sensitive field redaction via Pino's `redact` option.
 * - Per-message rate limiting to suppress log storms; suppressed counts are flushed
 *   at the end of each rate-limit window.
 * - OpenTelemetry trace context is auto-injected via {@link RequestContext} fields.
 * - Serverless-safe: when `IS_SERVERLESS=true` or `process` is unavailable, falls
 *   back to minimal Pino config without file transports or Node.js APIs.
 *
 * Obtain the singleton via {@link logger} or `Logger.getInstance()`.
 */
export declare class Logger {
    private static readonly instance;
    private pinoLogger?;
    private interactionLogger?;
    private initialized;
    private currentMcpLevel;
    private transportType;
    private rateLimitThreshold;
    private rateLimitWindow;
    private messageCounts;
    private suppressedMessages;
    private cleanupTimer?;
    private constructor();
    /**
     * Returns the singleton `Logger` instance.
     *
     * Prefer importing the pre-resolved {@link logger} export rather than calling this directly.
     *
     * @returns The singleton `Logger` instance.
     * @example
     * ```ts
     * import { Logger } from '../../utils/internal/logger.js';
     * const log = Logger.getInstance();
     * ```
     */
    static getInstance(): Logger;
    private createPinoLogger;
    private createInteractionLogger;
    /**
     * Initializes the logger, constructing Pino transports appropriate for the environment.
     *
     * Must be called once at server startup before any log methods are used. Subsequent calls
     * are no-ops (a warning is emitted instead). After initialization, a startup `info` entry
     * is written confirming the active level.
     *
     * @param level - MCP log level to apply. Defaults to `'info'`.
     * @param transportType - Active transport (`'stdio'` or `'http'`). Determines whether
     *   colored pretty-print output is enabled. In `'stdio'` mode, logs are always written
     *   to stderr (fd 2) to preserve stdout for MCP JSON-RPC.
     * @returns Promise that resolves when Pino transports and file sinks are ready.
     * @example
     * ```ts
     * await logger.initialize('debug', 'http');
     * ```
     */
    initialize(level?: McpLogLevel, transportType?: 'stdio' | 'http'): Promise<void>;
    /**
     * Changes the active log level at runtime without restarting transports.
     *
     * Has no effect if the logger has not been initialized; a console error is emitted
     * to stderr when running in a TTY. After the level is updated, an `info` entry is
     * written to confirm the change.
     *
     * @param newLevel - The new MCP log level to apply.
     * @example
     * ```ts
     * logger.setLevel('debug');
     * ```
     */
    setLevel(newLevel: McpLogLevel): void;
    /**
     * Implements the `AsyncDisposable` protocol (`await using logger`).
     *
     * Delegates to {@link close}. Allows the logger to be used with `await using` in
     * TypeScript 5.2+ explicit resource management contexts.
     *
     * @returns Promise that resolves when all transports have been flushed and closed.
     */
    [Symbol.asyncDispose](): Promise<void>;
    /**
     * Flushes all pending log entries and shuts down transports gracefully.
     *
     * Clears the rate-limit cleanup timer, flushes any suppressed message counts,
     * and waits for both the main Pino logger and the interaction logger to drain
     * before resolving. Safe to call multiple times — subsequent calls on an
     * already-closed logger resolve immediately.
     *
     * @returns Promise that resolves when all writes have completed.
     * @example
     * ```ts
     * process.on('SIGTERM', () => logger.close());
     * ```
     */
    close(): Promise<void>;
    /**
     * Returns whether the logger has been successfully initialized.
     *
     * Use this to guard code that should only run after {@link initialize} has resolved,
     * or to skip logging in contexts where initialization may not have occurred.
     *
     * @returns `true` if {@link initialize} has completed and {@link close} has not yet been called.
     * @example
     * ```ts
     * if (logger.isInitialized()) {
     *   logger.info('Server ready', ctx);
     * }
     * ```
     */
    isInitialized(): boolean;
    private isRateLimited;
    private flushSuppressedMessages;
    private log;
    private logWithError;
    /**
     * Logs a diagnostic message at `debug` severity (RFC 5424 level 7).
     *
     * Suppressed unless the active log level is `'debug'`. Use for verbose tracing,
     * internal state dumps, and low-level request/response details.
     *
     * @param msg - Human-readable log message.
     * @param context - Optional request context providing `requestId`, `traceId`, and related fields.
     * @example
     * ```ts
     * logger.debug('Cache miss', ctx);
     * ```
     */
    debug(msg: string, context?: RequestContext): void;
    /**
     * Logs an informational message at `info` severity (RFC 5424 level 6).
     *
     * Use for normal operational events: server startup, request completions, configuration loaded.
     *
     * @param msg - Human-readable log message.
     * @param context - Optional request context.
     * @example
     * ```ts
     * logger.info('Server listening on :3000', ctx);
     * ```
     */
    info(msg: string, context?: RequestContext): void;
    /**
     * Logs a notice-level message at `notice` severity (RFC 5424 level 5).
     *
     * Use for significant but non-error conditions: configuration changes, deprecation notices,
     * expected state transitions worth tracking. Maps to pino `info` level internally.
     *
     * @param msg - Human-readable log message.
     * @param context - Optional request context.
     * @example
     * ```ts
     * logger.notice('Feature flag toggled', ctx);
     * ```
     */
    notice(msg: string, context?: RequestContext): void;
    /**
     * Logs a warning message at `warning` severity (RFC 5424 level 4).
     *
     * Use for recoverable abnormal conditions: deprecated API usage, retried operations,
     * non-fatal misconfigurations. Maps to pino `warn` level internally.
     *
     * @param msg - Human-readable log message.
     * @param context - Optional request context.
     * @example
     * ```ts
     * logger.warning('Rate limit approaching', ctx);
     * ```
     */
    warning(msg: string, context?: RequestContext): void;
    /**
     * Logs an error-level message at `error` severity (RFC 5424 level 3).
     *
     * Use when an operation fails but the server can continue. The `errorOrContext`
     * parameter accepts either an `Error` (serialized via `pino.stdSerializers.err`) or a
     * `RequestContext` when no error object is available. Maps to pino `error` level.
     *
     * @param msg - Human-readable description of the failure.
     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
     * @param context - Request context; required when `errorOrContext` is an `Error`.
     * @example
     * ```ts
     * logger.error('Failed to fetch resource', err, ctx);
     * logger.error('Invalid state encountered', ctx);
     * ```
     */
    error(msg: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
    /**
     * Logs a critical error at `crit` severity (RFC 5424 level 2).
     *
     * Use for serious failures that impair a subsystem but do not crash the process —
     * for example, a storage provider going offline. Maps to pino `error` level.
     *
     * @param msg - Human-readable description of the critical condition.
     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
     * @param context - Request context; required when `errorOrContext` is an `Error`.
     * @example
     * ```ts
     * logger.crit('Database connection pool exhausted', err, ctx);
     * ```
     */
    crit(msg: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
    /**
     * Logs an alert-level message at `alert` severity (RFC 5424 level 1).
     *
     * Use when immediate human intervention is required — for example, a security breach
     * detected or critical data loss imminent. Maps to pino `fatal` level.
     *
     * @param msg - Human-readable description of the alert condition.
     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
     * @param context - Request context; required when `errorOrContext` is an `Error`.
     * @example
     * ```ts
     * logger.alert('Unauthorized admin access detected', err, ctx);
     * ```
     */
    alert(msg: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
    /**
     * Logs an emergency-level message at `emerg` severity (RFC 5424 level 0).
     *
     * Use for conditions that render the system completely unusable — process about to exit,
     * unrecoverable internal state. Maps to pino `fatal` level.
     *
     * @param msg - Human-readable description of the emergency.
     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
     * @param context - Request context; required when `errorOrContext` is an `Error`.
     * @example
     * ```ts
     * logger.emerg('Unrecoverable state — shutting down', err, ctx);
     * ```
     */
    emerg(msg: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
    /**
     * Alias for {@link emerg}. Provided for callers familiar with the pino/winston `fatal` level.
     *
     * Maps to RFC 5424 `emerg` (level 0) and pino `fatal` internally.
     *
     * @param msg - Human-readable description of the fatal condition.
     * @param errorOrContext - The `Error` to serialize, or a `RequestContext` if no error object exists.
     * @param context - Request context; required when `errorOrContext` is an `Error`.
     * @example
     * ```ts
     * logger.fatal('Process terminating due to unhandled exception', err, ctx);
     * ```
     */
    fatal(msg: string, errorOrContext: Error | RequestContext, context?: RequestContext): void;
    /**
     * Writes a structured interaction record to the dedicated `interactions.log` file sink.
     *
     * Interaction logs capture high-level semantic events (tool invocations, resource reads,
     * prompt renders) as structured JSON, separate from the main operational log stream.
     * This sink is only available when `config.logsPath` is set and the runtime is not serverless;
     * a `warning` is emitted if the logger is called before the sink is ready.
     *
     * @param interactionName - Identifier for the interaction type (e.g., `'tool:my_tool'`).
     * @param data - Arbitrary structured data to include alongside `interactionName` in the log record.
     * @example
     * ```ts
     * logger.logInteraction('tool:echo_message', { requestId: ctx.requestId, input });
     * ```
     */
    logInteraction(interactionName: string, data: Record<string, unknown>): void;
}
/**
 * Pre-resolved singleton logger instance. Import this directly rather than calling
 * `Logger.getInstance()` in most contexts.
 *
 * Must be initialized once at startup via `logger.initialize()` before any log methods
 * will produce output. Log calls made before initialization are silently dropped.
 *
 * @example
 * ```ts
 * import { logger } from '../../utils/internal/logger.js';
 *
 * // At startup:
 * await logger.initialize('debug', 'http');
 *
 * // In application code:
 * logger.info('Request received', ctx);
 * logger.error('Upstream failure', err, ctx);
 * ```
 */
export declare const logger: Logger;
//# sourceMappingURL=logger.d.ts.map