/**
 * Logger Module
 *
 * Pino-based structured logging for AgentRouter.
 * Provides a Logger class with support for:
 * - Log levels (trace, debug, info, warn, error, fatal)
 * - Structured logging with context
 * - Child loggers with bound context
 * - Pretty printing in development mode
 * - Correlation IDs and timestamps
 */
import { type Logger as PinoLogger } from 'pino';
/**
 * Log context that can be bound to a logger or passed per-call.
 */
export interface LogContext {
    /** Trace ID for request correlation */
    traceId?: string;
    /** Agent role being invoked */
    role?: string;
    /** Provider handling the request */
    provider?: string;
    /** Model being used */
    model?: string;
    /** Duration in milliseconds */
    durationMs?: number;
    /** Additional arbitrary context */
    [key: string]: unknown;
}
/**
 * Options for creating a Logger instance.
 */
export interface LoggerOptions {
    /** Logger name (appears in logs) */
    name?: string;
    /** Log level (default: info, or debug in development) */
    level?: LogLevel;
    /** Context to bind to all log entries */
    context?: LogContext;
    /** Whether to enable pretty printing (default: auto-detect from NODE_ENV) */
    pretty?: boolean;
}
/**
 * Supported log levels.
 */
export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
/**
 * Logger class wrapping pino with structured logging support.
 *
 * @example
 * ```typescript
 * const logger = new Logger({ name: 'agent-router' });
 * logger.info('Request received', { traceId, role: 'coder' });
 *
 * const childLogger = logger.child({ traceId: '123' });
 * childLogger.debug('Processing', { step: 1 });
 * ```
 */
export declare class Logger {
    private readonly pino;
    private readonly boundContext;
    constructor(options?: LoggerOptions);
    /**
     * Create a child logger with additional bound context.
     * The child logger inherits all parent context plus new bindings.
     */
    child(context: LogContext): Logger;
    /**
     * Log at trace level (most verbose).
     */
    trace(message: string, context?: LogContext): void;
    /**
     * Log at debug level.
     */
    debug(message: string, context?: LogContext): void;
    /**
     * Log at info level.
     */
    info(message: string, context?: LogContext): void;
    /**
     * Log at warn level.
     */
    warn(message: string, context?: LogContext): void;
    /**
     * Log at error level.
     */
    error(message: string, context?: LogContext & {
        error?: Error;
    }): void;
    /**
     * Log at fatal level (most severe).
     */
    fatal(message: string, context?: LogContext & {
        error?: Error;
    }): void;
    /**
     * Get the current log level.
     */
    get level(): LogLevel;
    /**
     * Set the log level dynamically.
     */
    set level(level: LogLevel);
    /**
     * Check if a log level is enabled.
     */
    isLevelEnabled(level: LogLevel): boolean;
    /**
     * Get the underlying pino instance (for advanced use cases).
     */
    get pinoInstance(): PinoLogger;
}
/**
 * Generate a unique trace ID for request correlation.
 * Uses UUID v4 format.
 */
export declare function generateTraceId(): string;
/**
 * Create a log context with a trace ID.
 * Useful for starting a new traced operation.
 */
export declare function createTracedContext(additionalContext?: LogContext): LogContext;
/**
 * Default logger instance for the agent-router package.
 * Pre-configured with the package name.
 */
export declare const logger: Logger;
/**
 * Factory function to create a Logger instance.
 * Convenience wrapper around new Logger().
 */
export declare function createLogger(options?: LoggerOptions): Logger;
/**
 * Data for logging a tool call attempt.
 */
export interface ToolCallData {
    /** Tool name being called */
    tool: string;
    /** Tool input parameters */
    input: Record<string, unknown>;
    /** Task ID if applicable */
    taskId?: string;
    /** Worktree ID if applicable */
    worktreeId?: string;
}
/**
 * Data for logging a tool call success.
 */
export interface ToolSuccessData {
    /** Tool name */
    tool: string;
    /** Duration in milliseconds */
    durationMs: number;
    /** Size of output in bytes */
    outputSize?: number;
    /** Task ID if applicable */
    taskId?: string;
}
/**
 * Data for logging a tool call failure.
 */
export interface ToolFailureData {
    /** Tool name */
    tool: string;
    /** Error that occurred */
    error: Error;
    /** Duration in milliseconds */
    durationMs: number;
    /** Task ID if applicable */
    taskId?: string;
    /** Whether the tool was denied by a hook */
    denied?: boolean;
    /** Reason for denial if denied */
    denyReason?: string;
}
/**
 * Data for logging a tool call denial.
 */
export interface ToolDenialData {
    /** Tool name */
    tool: string;
    /** Reason for denial */
    reason: string;
    /** Hook name that denied if applicable */
    hookName?: string;
    /** Task ID if applicable */
    taskId?: string;
}
/**
 * Data for logging a provider failover event.
 */
export interface FailoverData {
    /** Provider being switched from */
    fromProvider: string;
    /** Provider being switched to */
    toProvider: string;
    /** Reason for failover */
    reason: string;
    /** Error code if applicable */
    errorCode?: number;
    /** Error message if applicable */
    errorMessage?: string;
    /** Role being invoked */
    role?: string;
    /** Current attempt number */
    attemptNumber: number;
    /** Total allowed attempts */
    totalAttempts: number;
}
/**
 * Data for logging provider health changes.
 */
export interface HealthChangeData {
    /** Provider name */
    provider: string;
    /** Previous health status */
    previousStatus: string;
    /** New health status */
    newStatus: string;
    /** Reason for status change */
    reason: string;
    /** Cooldown end time if applicable */
    cooldownUntil?: Date;
}
/**
 * Data for logging rate limit warnings.
 */
export interface RateLimitWarningData {
    /** Provider name */
    provider: string;
    /** Remaining requests */
    remaining: number;
    /** Request limit */
    limit: number;
    /** Percentage of limit used */
    usedPercentage: number;
    /** When the rate limit resets */
    resetsAt: Date;
}
/**
 * Category for structured errors.
 */
export type ErrorCategory = 'provider' | 'tool' | 'worktree' | 'pipeline' | 'config' | 'system';
/**
 * Data for logging a structured error.
 */
export interface StructuredErrorData {
    /** Error category */
    category: ErrorCategory;
    /** Error code (e.g., 'PROVIDER_TIMEOUT', 'TOOL_DENIED') */
    code: string;
    /** Human-readable error message */
    message: string;
    /** Additional context */
    context: Record<string, unknown>;
    /** Stack trace if available */
    stack?: string;
    /** Whether the error is recoverable */
    recoverable: boolean;
    /** Suggested action for recovery */
    suggestedAction?: string;
}
/**
 * Extended Logger class with specialized logging methods for Hari Seldon.
 */
export declare class ExtendedLogger extends Logger {
    /**
     * Log a tool call attempt.
     */
    logToolCall(data: ToolCallData): void;
    /**
     * Log a tool call success.
     */
    logToolSuccess(data: ToolSuccessData): void;
    /**
     * Log a tool call failure.
     */
    logToolFailure(data: ToolFailureData): void;
    /**
     * Log a tool call denial by hook or policy.
     */
    logToolDenial(data: ToolDenialData): void;
    /**
     * Log a provider failover event.
     */
    logFailover(data: FailoverData): void;
    /**
     * Log a provider health change.
     */
    logHealthChange(data: HealthChangeData): void;
    /**
     * Log a rate limit warning.
     */
    logRateLimitWarning(data: RateLimitWarningData): void;
    /**
     * Log a structured error with full context.
     */
    logStructuredError(data: StructuredErrorData): void;
    /**
     * Create a child logger with additional bound context.
     * Returns an ExtendedLogger instead of Logger.
     */
    child(context: LogContext): ExtendedLogger;
}
/**
 * Factory function to create an ExtendedLogger instance.
 */
export declare function createExtendedLogger(options?: LoggerOptions): ExtendedLogger;
/**
 * Default extended logger instance for the hari-seldon package.
 */
export declare const extendedLogger: ExtendedLogger;
/**
 * Re-export for convenience.
 */
export default logger;
//# sourceMappingURL=logger.d.ts.map