import { voice } from '@livekit/agents';
import type { Mastra } from '@mastra/core/mastra';
import { SpanType } from '@mastra/core/observability';
import type { Span, TracingContext } from '@mastra/core/observability';
import type { RequestContext } from '@mastra/core/request-context';
import type { LiveKitSessionMetadata } from './metadata.js';
import type { VoiceTurnMetrics } from './turn-metrics.js';
export interface VoiceCallObservabilityOptions {
    /** The Mastra instance whose observability config receives the spans. */
    mastra: Mastra;
    /** Resolved Mastra agent id/key answering the call (for span attribution). */
    agentId: string;
    /** LiveKit room name for this session. */
    roomName: string;
    /** Dispatch metadata for the session. */
    metadata: LiveKitSessionMetadata;
    /** Request context forwarded to span sampling. */
    requestContext?: RequestContext;
}
export interface VoiceCallObservability {
    /** The root `voice call` span. Each turn's agent run and every pipeline metric nests under it. */
    readonly span: Span<SpanType.GENERIC>;
    /** Thread into the bridge's `streamOptions` so each turn's agent run nests under the call. */
    readonly tracingContext: TracingContext;
    /** Subscribe to the session's `metrics_collected` events. Call once, before `session.start()`. */
    attach(session: voice.AgentSession): void;
    /** Record a generation or playback measurement with its correlation IDs. */
    recordTurn(metric: VoiceTurnMetrics): void;
    /** Close the call span with the usage roll-up. Idempotent; safe to call from a shutdown hook. */
    finalize(options?: {
        error?: unknown;
    }): void;
}
/**
 * Opens a `voice call` trace for one LiveKit session and bridges LiveKit's voice-pipeline
 * metrics into Mastra observability.
 *
 * The returned root span groups everything about the call: each conversation turn's Mastra
 * agent run (nested via {@link VoiceCallObservability.tracingContext}) plus an event span for
 * every STT, TTS, end-of-utterance, VAD, and LLM-latency metric LiveKit emits. Metrics are
 * point-in-time, so they're recorded as event spans (no duration) with the value in the name.
 * The root closes on the session `close` event with a per-model usage roll-up (token, character,
 * and audio totals for the whole call) from a `ModelUsageCollector`.
 *
 * Returns `undefined` when the Mastra instance has no observability configured, so callers
 * can treat instrumentation as a no-op without branching on config.
 */
export declare function startVoiceCallObservability(options: VoiceCallObservabilityOptions): VoiceCallObservability | undefined;
//# sourceMappingURL=observability.d.ts.map