/**
 * Session Tracing -- OpenTelemetry Span Management
 *
 * Provides span creation/ending APIs for interactions, LLM requests, and tool
 * executions. Uses two independent AsyncLocalStorage contexts:
 * - interactionContext: holds the interaction span for the entire turn
 * - toolContext: holds the current tool span (cleared on end)
 *
 * LLM request spans do not enter any ALS; they are passed explicitly to
 * endLLMRequestSpan, aligning with Claude Code's approach.
 */
import type { Span } from "@opentelemetry/api";
import type { LLMRequestMetadata, LLMRequestInput, ToolMetadata } from "../types/telemetry.js";
/**
 * Creates an interaction span for a user turn.
 * The span is stored in interactionContext for the duration of the turn.
 */
export declare function startInteractionSpan(userPrompt: string, sequence: number): Span | undefined;
/**
 * Ends the current interaction span and clears the context.
 */
export declare function endInteractionSpan(): void;
/**
 * Resets incremental tracing state. Should be called after compaction to
 * prevent incorrect delta calculations.
 */
export declare function resetTracingState(): void;
/**
 * Creates an LLM request span as a child of the interaction span.
 * Does NOT enter any ALS — the span must be passed explicitly to endLLMRequestSpan.
 *
 * When logToolContent is enabled, captures:
 * - system_prompt_hash / system_prompt_preview / system_prompt_length
 * - new_context (incremental messages delta)
 * - tools (JSON array of {name, hash}) / tools_count
 */
export declare function startLLMRequestSpan(model: string, options?: LLMRequestInput): Span | undefined;
/**
 * Ends an LLM request span with response metadata.
 * The span is passed explicitly — no ALS is read or modified.
 *
 * When logToolContent is enabled, captures response.model_output.
 */
export declare function endLLMRequestSpan(span: Span | undefined, metadata: LLMRequestMetadata): void;
/**
 * Creates a tool execution span as a child of the interaction span.
 * Enters toolContext with the new span.
 */
export declare function startToolSpan(toolName: string, input?: unknown): Span | undefined;
/**
 * Ends the current tool span with execution metadata.
 * Reads the span from toolContext, then clears it.
 */
export declare function endToolSpan(metadata: ToolMetadata): void;