export type TraceLevel = "ERROR" | "WARN" | "INFO" | "DEBUG";
/**
 * Derive an 8-char trace ID from a message ID (or random fallback).
 */
export declare function deriveTraceId(messageId?: string | null): string;
/**
 * Append a trace event for a chat message lifecycle stage (agent scope).
 * Best-effort, never throws or blocks.
 */
export declare function traceChatEvent(params: {
    agentId: string;
    traceId: string;
    level: TraceLevel;
    stage: string;
    data?: Record<string, unknown>;
}): void;
/**
 * Append a trace event to the gateway-level log (unified view across all agents).
 * Best-effort, never throws or blocks.
 */
export declare function traceGatewayEvent(params: {
    traceId: string;
    level: TraceLevel;
    stage: string;
    data?: Record<string, unknown>;
}): void;
/**
 * Append a trace event to the channels-level log (transport/delivery events).
 * Best-effort, never throws or blocks.
 */
export declare function traceChannelEvent(params: {
    traceId: string;
    level: TraceLevel;
    stage: string;
    data?: Record<string, unknown>;
}): void;
/**
 * Remove trace files older than maxAgeDays. Call on gateway startup.
 */
export declare function pruneOldTraceFiles(maxAgeDays?: number): void;
