/**
 * LLM provider call span helpers.
 *
 * Creates child spans under a turn span to track provider API calls.
 * These spans capture model, token usage, latency, and error context.
 */
import type { Span } from '../types.js';
import type { RuntimeTracer } from '../tracer.js';
/** Context supplied when starting an LLM span. */
export interface LlmSpanContext {
    /** Turn ID this LLM call belongs to. */
    readonly turnId: string;
    /** Provider name (e.g. 'anthropic', 'openai'). */
    readonly provider: string;
    /** Model ID (e.g. 'claude-sonnet-4-6'). */
    readonly model: string;
    /** Trace ID from the parent turn span. */
    readonly traceId: string;
    /** Parent span ID (the turn span's spanId). */
    readonly parentSpanId: string;
    /** Whether this is a streaming call. */
    readonly streaming?: boolean | undefined;
    /** Number of messages in the request context. */
    readonly messageCount?: number | undefined;
}
/** Token usage recorded when ending an LLM span. */
export interface LlmTokenUsage {
    readonly inputTokens: number;
    readonly outputTokens: number;
    readonly cacheReadTokens?: number | undefined;
    readonly cacheWriteTokens?: number | undefined;
}
/** Result context supplied when ending an LLM span. */
export interface LlmSpanEndContext {
    /** Whether the call succeeded. */
    readonly success: boolean;
    /** Stop reason from the provider (e.g. 'end_turn', 'tool_use', 'max_tokens'). */
    readonly stopReason?: string | undefined;
    /** Token usage if available. */
    readonly tokens?: LlmTokenUsage | undefined;
    /** Error message if success is false. */
    readonly error?: string | undefined;
    /** HTTP status code if available (for remote provider calls). */
    readonly httpStatus?: number | undefined;
}
/**
 * Start an LLM provider call span as a child of the turn span.
 *
 * @param tracer - RuntimeTracer instance.
 * @param ctx - LLM span context.
 */
export declare function startLlmSpan(tracer: RuntimeTracer, ctx: LlmSpanContext): Span;
/**
 * Record that the LLM stream has started (first token received).
 *
 * @param span - The active LLM span.
 * @param firstTokenMs - Epoch ms when the first token arrived (optional override).
 */
export declare function recordLlmStreamStart(span: Span, firstTokenMs?: number): void;
/**
 * End an LLM provider call span.
 *
 * @param span - The span returned by `startLlmSpan`.
 * @param ctx - LLM end context.
 */
export declare function endLlmSpan(span: Span, ctx: LlmSpanEndContext): void;
//# sourceMappingURL=llm.d.ts.map