/**
 * OpenTelemetry GenAI Semantic Conventions for Photon
 *
 * Provides tracing spans following CNCF GenAI semantic conventions.
 * Zero required dependencies — dynamically imports @opentelemetry/api
 * and falls back to no-op spans when the SDK is not installed.
 */
export interface PhotonSpan {
    setAttribute(key: string, value: string | number | boolean): void;
    addEvent(name: string, attributes?: Record<string, string | number | boolean>): void;
    setStatus(code: 'OK' | 'ERROR', message?: string): void;
    recordException(error: unknown): void;
    end(): void;
}
/**
 * Parse a W3C traceparent header into its components.
 * Format: `{version}-{traceId}-{parentSpanId}-{flags}` (e.g. `00-abc...-def...-01`).
 * Returns null if the header is malformed.
 */
export declare function parseTraceparent(traceparent: string | undefined | null): {
    version: string;
    traceId: string;
    spanId: string;
    flags: string;
} | null;
/**
 * Start a span for tool execution following GenAI semantic conventions.
 * @param traceId - Optional W3C-compatible trace ID (32 hex chars) for async executions.
 *   When provided, set as `photon.trace_id` on the span so async executions are
 *   correlated with the execution ID returned to the caller.
 * @param stateful - When true, sets `photon.stateful=true` on the span.
 * @param parentTraceparent - Optional W3C traceparent header. When provided, the new
 *   span is created as a child of that remote span context so distributed traces
 *   chain across client → photon → downstream calls.
 */
export declare function startToolSpan(photon: string, tool: string, params?: Record<string, unknown>, traceId?: string, stateful?: boolean, parentTraceparent?: string): PhotonSpan;
/**
 * Start a span for agent-level invocation following GenAI semantic conventions.
 */
export declare function startAgentSpan(photon: string, description?: string): PhotonSpan;
/**
 * Returns true if OpenTelemetry tracing is available and configured.
 */
export declare function isTracingEnabled(): boolean;
/**
 * Wait for the initial OTel API probe to complete.
 * Useful in tests to ensure the cached state is resolved.
 */
export declare function waitForOtelProbe(): Promise<void>;
/**
 * Reset the cached OTel API reference. For testing only.
 */
export declare function _resetOtelCache(): void;
//# sourceMappingURL=otel.d.ts.map