/**
 * Tracing System Types
 *
 * Provides types for distributed tracing, structured logging, and observability.
 */
/**
 * Span status indicating success, error, or unset
 */
export type SpanStatus = 'unset' | 'ok' | 'error';
/**
 * Span kind indicating the type of operation
 */
export type SpanKind = 'internal' | 'client' | 'server' | 'producer' | 'consumer';
/**
 * Attribute value types (compatible with OpenTelemetry)
 */
export type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
/**
 * Span attributes map
 */
export type SpanAttributes = Record<string, AttributeValue>;
/**
 * A trace span representing a unit of work
 */
export interface Span {
    /** Unique span identifier */
    spanId: string;
    /** Trace ID this span belongs to */
    traceId: string;
    /** Parent span ID (undefined for root spans) */
    parentSpanId?: string;
    /** Human-readable span name */
    name: string;
    /** Span kind */
    kind: SpanKind;
    /** Start time in milliseconds since epoch */
    startTime: number;
    /** End time in milliseconds since epoch (undefined if still active) */
    endTime?: number;
    /** Duration in milliseconds (undefined if still active) */
    durationMs?: number;
    /** Span status */
    status: SpanStatus;
    /** Status message (typically for errors) */
    statusMessage?: string;
    /** Span attributes */
    attributes: SpanAttributes;
    /** Span events (timestamped annotations) */
    events: SpanEvent[];
}
/**
 * Event within a span (timestamped annotation)
 */
export interface SpanEvent {
    /** Event name */
    name: string;
    /** Timestamp in milliseconds since epoch */
    timestamp: number;
    /** Event attributes */
    attributes?: SpanAttributes;
}
/**
 * Context for creating a new span
 */
export interface SpanContext {
    /** Trace ID */
    traceId: string;
    /** Parent span ID */
    parentSpanId?: string;
}
/**
 * A complete trace containing multiple spans
 */
export interface Trace {
    /** Unique trace identifier */
    traceId: string;
    /** Root span ID */
    rootSpanId: string;
    /** All spans in this trace */
    spans: Span[];
    /** Trace start time */
    startTime: number;
    /** Trace end time (undefined if still active) */
    endTime?: number;
    /** Total duration in milliseconds */
    durationMs?: number;
    /** Trace-level attributes */
    attributes: SpanAttributes;
}
/**
 * Standard attribute names following OpenTelemetry semantic conventions
 */
export declare const SemanticAttributes: {
    readonly AGENT_SESSION_ID: "agent.session_id";
    readonly AGENT_ITERATION: "agent.iteration";
    readonly AGENT_MAX_ITERATIONS: "agent.max_iterations";
    readonly LLM_PROVIDER: "llm.provider";
    readonly LLM_MODEL: "llm.model";
    readonly LLM_INPUT_TOKENS: "llm.input_tokens";
    readonly LLM_OUTPUT_TOKENS: "llm.output_tokens";
    readonly LLM_TOTAL_TOKENS: "llm.total_tokens";
    readonly LLM_CACHE_READ_TOKENS: "llm.cache_read_tokens";
    readonly LLM_CACHE_CREATION_TOKENS: "llm.cache_creation_tokens";
    readonly TOOL_NAME: "tool.name";
    readonly TOOL_INPUT: "tool.input";
    readonly TOOL_SUCCESS: "tool.success";
    readonly TOOL_ERROR: "tool.error";
    readonly TOOL_RESULT: "tool.result";
    readonly MESSAGE_ROLE: "message.role";
    readonly MESSAGE_COUNT: "message.count";
    readonly ERROR_TYPE: "error.type";
    readonly ERROR_MESSAGE: "error.message";
    readonly ERROR_STACK: "error.stack";
};
/**
 * Options for creating a TracingManager
 */
export interface TracingManagerOptions {
    /** Service name for traces */
    serviceName?: string;
    /** Service version */
    serviceVersion?: string;
    /** Default attributes added to all spans */
    defaultAttributes?: SpanAttributes;
    /** Maximum spans per trace (prevents memory issues) */
    maxSpansPerTrace?: number;
    /** Whether to auto-generate trace IDs */
    autoGenerateTraceId?: boolean;
    /** Event handler for tracing events */
    onEvent?: TracingEventHandler;
    /** Optional OpenTelemetry exporter */
    otelExporter?: OTelExporter;
}
/**
 * Options for starting a span
 */
export interface StartSpanOptions {
    /** Span name */
    name: string;
    /** Span kind (default: internal) */
    kind?: SpanKind;
    /** Parent span context (if not provided, uses current context) */
    parentContext?: SpanContext;
    /** Initial attributes */
    attributes?: SpanAttributes;
    /** Start time override (default: now) */
    startTime?: number;
}
/**
 * Options for ending a span
 */
export interface EndSpanOptions {
    /** End time override (default: now) */
    endTime?: number;
    /** Final status */
    status?: SpanStatus;
    /** Status message */
    statusMessage?: string;
    /** Additional attributes to add */
    attributes?: SpanAttributes;
}
/**
 * Events emitted by TracingManager
 */
export type TracingEvent = {
    type: 'trace:started';
    traceId: string;
    timestamp: number;
} | {
    type: 'trace:ended';
    traceId: string;
    durationMs: number;
    spanCount: number;
} | {
    type: 'span:started';
    spanId: string;
    traceId: string;
    name: string;
    parentSpanId?: string;
} | {
    type: 'span:ended';
    spanId: string;
    traceId: string;
    durationMs: number;
    status: SpanStatus;
} | {
    type: 'span:event';
    spanId: string;
    traceId: string;
    eventName: string;
} | {
    type: 'span:error';
    spanId: string;
    traceId: string;
    error: Error;
} | {
    type: 'export:success';
    traceId: string;
    exporter: string;
} | {
    type: 'export:error';
    traceId: string;
    exporter: string;
    error: Error;
};
/**
 * Handler for tracing events
 */
export type TracingEventHandler = (event: TracingEvent) => void;
/**
 * OpenTelemetry exporter interface (simplified)
 * Allows integration with any OTel-compatible backend
 */
export interface OTelExporter {
    /** Exporter name for logging */
    name: string;
    /** Export spans */
    export(spans: Span[]): Promise<void>;
    /** Shutdown the exporter */
    shutdown?(): Promise<void>;
}
/**
 * OpenTelemetry SDK types (defined here to avoid importing optional dependency)
 */
export type OTelSDK = {
    trace: {
        getTracer(name: string, version?: string): OTelTracer;
    };
};
export type OTelTracer = {
    startSpan(name: string, options?: unknown): OTelSpan;
};
export type OTelSpan = {
    setAttribute(key: string, value: AttributeValue): void;
    setStatus(status: {
        code: number;
        message?: string;
    }): void;
    addEvent(name: string, attributes?: Record<string, unknown>): void;
    end(endTime?: number): void;
    spanContext(): {
        traceId: string;
        spanId: string;
    };
};
/**
 * Log levels
 */
export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
/**
 * Structured log entry
 */
export interface LogEntry {
    /** Log level */
    level: LogLevel;
    /** Log message */
    message: string;
    /** Timestamp in ISO format */
    timestamp: string;
    /** Trace ID for correlation */
    traceId?: string;
    /** Span ID for correlation */
    spanId?: string;
    /** Session ID */
    sessionId?: string;
    /** Additional structured data */
    data?: Record<string, unknown>;
    /** Error information */
    error?: {
        name: string;
        message: string;
        stack?: string;
    };
}
/**
 * Logger interface for structured logging
 */
export interface StructuredLogger {
    debug(message: string, data?: Record<string, unknown>): void;
    info(message: string, data?: Record<string, unknown>): void;
    warn(message: string, data?: Record<string, unknown>): void;
    error(message: string, error?: Error, data?: Record<string, unknown>): void;
    /** Create a child logger with additional context */
    child(context: Record<string, unknown>): StructuredLogger;
    /** Set correlation IDs */
    setCorrelation(traceId?: string, spanId?: string, sessionId?: string): void;
}
/**
 * Options for creating a structured logger
 */
export interface StructuredLoggerOptions {
    /** Minimum log level */
    level?: LogLevel;
    /** Service name */
    serviceName?: string;
    /** Pretty print JSON (default: false for production) */
    prettyPrint?: boolean;
    /** Output function (default: console.log) */
    output?: (entry: LogEntry) => void;
    /** Initial context */
    context?: Record<string, unknown>;
}
/**
 * Configuration for built-in tracing hooks
 */
export interface TracingHooksConfig {
    /** Trace LLM calls */
    traceLLM?: boolean;
    /** Trace tool executions */
    traceTools?: boolean;
    /** Trace iterations */
    traceIterations?: boolean;
    /** Include input/output in attributes (may be verbose) */
    includeIO?: boolean;
    /** Truncate long values at this length */
    truncateAt?: number;
    /** Custom attribute mapper */
    attributeMapper?: (phase: 'llm' | 'tool' | 'iteration', data: Record<string, unknown>) => SpanAttributes;
}
/**
 * Context passed to tracing hooks
 */
export interface TracingHookContext {
    /** Tracing manager instance */
    manager: TracingManagerInterface;
    /** Current trace ID */
    traceId: string;
    /** Current span context */
    spanContext?: SpanContext;
    /** Session ID */
    sessionId: string;
}
/**
 * Interface for TracingManager (for type references without circular deps)
 */
export interface TracingManagerInterface {
    startTrace(attributes?: SpanAttributes): string;
    endTrace(traceId: string): Trace | undefined;
    startSpan(options: StartSpanOptions): Span;
    endSpan(spanId: string, options?: EndSpanOptions): Span | undefined;
    addSpanEvent(spanId: string, name: string, attributes?: SpanAttributes): void;
    setSpanAttributes(spanId: string, attributes: SpanAttributes): void;
    setSpanStatus(spanId: string, status: SpanStatus, message?: string): void;
    getCurrentSpan(): Span | undefined;
    getTrace(traceId: string): Trace | undefined;
}