/**
 * Turn lifecycle span helpers.
 *
 * Creates and manages spans that track the full turn lifecycle:
 * TURN_SUBMITTED → TURN_COMPLETED | TURN_ERROR | TURN_CANCEL
 *
 * The turn span is the root span for a conversation turn. Tool and LLM
 * spans are created as children of the turn span.
 */
import type { Span } from '../types.js';
import type { RuntimeTracer } from '../tracer.js';
/** Context supplied when starting a turn span. */
export interface TurnSpanContext {
    /** Turn ID from the event envelope. */
    readonly turnId: string;
    /** Session-level trace ID for correlation. */
    readonly traceId: string;
    /** Session ID. */
    readonly sessionId: string;
    /** User prompt (truncated to 256 chars for the attribute). */
    readonly prompt: string;
}
/** Result context supplied when ending a turn span. */
export interface TurnSpanEndContext {
    /** Final outcome of the turn. */
    readonly outcome: 'completed' | 'error' | 'cancelled';
    /** Error message if outcome is 'error'. */
    readonly error?: string | undefined;
    /** Cancel reason if outcome is 'cancelled'. */
    readonly cancelReason?: string | undefined;
    /** Token usage if available. */
    readonly tokens?: {
        readonly input: number;
        readonly output: number;
        readonly cacheRead?: number | undefined;
    };
}
/**
 * Start a turn lifecycle span.
 *
 * The returned Span should be stored and ended when the turn resolves
 * via `endTurnSpan`.
 *
 * @param tracer - RuntimeTracer instance.
 * @param ctx - Turn context from TURN_SUBMITTED event.
 */
export declare function startTurnSpan(tracer: RuntimeTracer, ctx: TurnSpanContext): Span;
/**
 * End a turn lifecycle span with outcome context.
 *
 * @param span - The span returned by `startTurnSpan`.
 * @param ctx - Turn end context.
 */
export declare function endTurnSpan(span: Span, ctx: TurnSpanEndContext): void;
//# sourceMappingURL=turn.d.ts.map