/**
 * Model Span Tracing
 *
 * Provides span tracking for Model generations, including:
 * - MODEL_STEP spans (one per Model API call - includes processors and tool executions)
 * - MODEL_INFERENCE spans (the provider call itself - model latency only)
 * - MODEL_CHUNK spans (individual streaming chunks within an inference)
 *
 * Hierarchy: MODEL_GENERATION -> MODEL_STEP -> MODEL_INFERENCE -> MODEL_CHUNK
 *
 * Processors and tool executions remain children of MODEL_STEP (siblings of
 * MODEL_INFERENCE), so MODEL_INFERENCE measures pure model time.
 */
import { SpanType } from '@mastra/core/observability';
import type { Span, EndGenerationOptions, ErrorSpanOptions, ModelInferenceContext, TracingContext, UpdateSpanOptions } from '@mastra/core/observability';
import type { StepStartPayload, StepFinishPayload } from '@mastra/core/stream';
/**
 * Manages MODEL_STEP and MODEL_CHUNK span tracking for streaming Model responses.
 *
 * Should be instantiated once per MODEL_GENERATION span and shared across
 * all streaming steps (including after tool calls).
 */
export declare class ModelSpanTracker {
    #private;
    constructor(modelSpan?: Span<SpanType.MODEL_GENERATION>);
    /**
     * Set request-side context applied to subsequent MODEL_INFERENCE spans.
     * No-op when paired with an older @mastra/core that lacks the feature flag.
     */
    setInferenceContext(context: ModelInferenceContext): void;
    /**
     * Get the tracing context for creating child spans.
     * Returns the current step span if active, otherwise the model span.
     */
    getTracingContext(): TracingContext;
    /**
     * Report an error on the generation span, also closing any still-open
     * MODEL_INFERENCE / MODEL_STEP children so a fatal error before step-finish
     * doesn't leave them dangling. No-op if they were already closed.
     */
    reportGenerationError(options: ErrorSpanOptions<SpanType.MODEL_GENERATION>): void;
    /**
     * End the generation span with optional raw usage data.
     * If usage is provided, it will be converted to UsageStats with cache token details.
     */
    endGeneration(options?: EndGenerationOptions): void;
    /**
     * Update the generation span
     */
    updateGeneration(options: UpdateSpanOptions<SpanType.MODEL_GENERATION>): void;
    /**
     * Enable or disable deferred step closing for durable execution.
     * When enabled, step-finish chunks won't automatically close the step span.
     * Use exportCurrentStep() to get the span data, then close it manually later.
     */
    setDeferStepClose(defer: boolean): void;
    /**
     * Export the current step span for later rebuilding (durable execution).
     * Returns undefined if no step span is active.
     */
    exportCurrentStep(): ReturnType<Span<SpanType.MODEL_STEP>['exportSpan']> | undefined;
    /**
     * Get the pending step finish payload (captured when defer mode is enabled).
     * This contains usage, finishReason, etc. for closing the step later.
     */
    getPendingStepFinishPayload(): StepFinishPayload<any, any> | undefined;
    /**
     * Set the starting step index for durable execution.
     * Used when resuming across agentic loop iterations to maintain step continuity.
     */
    setStepIndex(index: number): void;
    /**
     * Get the current step index.
     */
    getStepIndex(): number;
    /**
     * Start a new Model execution step.
     * This should be called at the beginning of LLM execution to capture accurate startTime.
     * The step-start chunk payload can be passed later via updateStep() if needed.
     *
     * Note: this only opens MODEL_STEP. The MODEL_INFERENCE child span is opened
     * separately via startInference() so its duration excludes input processor work.
     * Callers that don't call startInference() explicitly will get one auto-created
     * when the first model chunk arrives.
     */
    startStep(payload?: StepStartPayload): void;
    /**
     * Open the MODEL_INFERENCE span for the current step. Chunks (including tool-call
     * chunks emitted by the model) parent under this span so its duration reflects
     * pure model latency.
     *
     * Should be called immediately before invoking the model — after any input
     * processors / `prepareStep` work has completed — so the span's startTime
     * does not include processor time. The latest `#inferenceContext` (set via
     * setInferenceContext) is snapshotted onto the span at creation.
     *
     * No-ops when the installed @mastra/core lacks the `model-inference-span`
     * feature flag, or when called without an active step span. Auto-invoked from
     * chunk handlers as a safety net; explicit callers get the most accurate
     * start time.
     */
    startInference(payload?: StepStartPayload): void;
    /**
     * Update the current step span with additional payload data.
     * Called when step-start chunk arrives with request/warnings info.
     */
    updateStep(payload?: StepStartPayload): void;
    /**
     * Wraps a stream with model tracing transform to track MODEL_STEP and MODEL_CHUNK spans.
     *
     * This should be added to the stream pipeline to automatically
     * create MODEL_STEP and MODEL_CHUNK spans for each semantic unit in the stream.
     */
    wrapStream<T extends {
        pipeThrough: Function;
    }>(stream: T): T;
}
//# sourceMappingURL=model-tracing.d.ts.map