import type { RunFeedback, RunKind, RedactionPolicy, SamplingPolicy, TraceStore } from '../types/tracing.js';
/** Configuration for a tracer. */
export interface TracerOptions {
    /** Where finished traces are written. */
    store: TraceStore;
    /** Which traces are kept. */
    sampling?: SamplingPolicy;
    /** What is removed from runs before they are stored. */
    redaction?: RedactionPolicy;
    /** Tags added to every run, such as the deployment or the release. */
    tags?: string[];
    /** Metadata added to every run. */
    metadata?: Record<string, unknown>;
    /** Replaces the system clock, for tests. */
    now?: () => Date;
    /** Errors from the store are swallowed by default; a hook lets an application notice them. */
    onError?: (error: unknown) => void;
}
/** Options for starting a run. */
export interface StartRunOptions {
    /** What the run is, such as a node or a tool name. */
    name: string;
    /** What kind of work it is. Defaults to `chain`. */
    kind?: RunKind;
    /** What it received. */
    inputs?: unknown;
    /** Labels for filtering. */
    tags?: string[];
    /** Application data, queryable by dot path. */
    metadata?: Record<string, unknown>;
    /** The model it calls, for a model run. */
    model?: string;
    /** The provider it calls, for a model run. */
    provider?: string;
    /** Overrides the parent taken from the surrounding context. */
    parentId?: string;
    /** Joins an existing trace instead of starting a new one. */
    traceId?: string;
}
/** Options for finishing a run. */
export interface FinishRunOptions {
    /** What it produced. */
    outputs?: unknown;
    /** Why it failed. Its presence marks the run as an error. */
    error?: unknown;
    /** Token counts and other units reported. */
    usage?: Record<string, number>;
    /** What it cost. */
    cost?: number;
    /** Metadata merged into the run's. */
    metadata?: Record<string, unknown>;
    /** The model that actually ran, replacing the one the run started with, such as `auto` after routing. */
    model?: string;
    /** The provider that actually ran. */
    provider?: string;
}
/** A run in progress. Finishing it writes it to the store. */
export interface RunHandle {
    /** The run's id. */
    readonly id: string;
    /** The trace it belongs to. */
    readonly traceId: string;
    /** Finishes the run. The trace is written once its root finishes. */
    finish(options?: FinishRunOptions): Promise<void>;
    /** Starts a run beneath this one, without relying on the ambient context. */
    child(options: StartRunOptions): RunHandle;
}
/**
 * Records run trees.
 *
 * The context is carried through `AsyncLocalStorage`, which is created only when a tracer exists, so
 * an application that never traces pays nothing: no storage, no wrapper objects, no per-call work.
 */
export declare class Tracer {
    private readonly options;
    private readonly context;
    private readonly pending;
    private readonly now;
    constructor(options: TracerOptions);
    /** The run currently in scope, if any. */
    current(): {
        traceId: string;
        runId: string;
    } | undefined;
    /**
     * Starts a run beneath the run in scope, or a new trace when there is none. Finish it with the
     * handle.
     */
    startRun(options: StartRunOptions): RunHandle;
    /** Runs `fn` inside a new run, finishing it with the result or the error. */
    trace<T>(options: StartRunOptions, fn: (handle: RunHandle) => Promise<T> | T): Promise<T>;
    /** Wraps any function so every call to it becomes a run. */
    traceable<A extends unknown[], R>(options: StartRunOptions | ((...args: A) => StartRunOptions), fn: (...args: A) => Promise<R> | R): (...args: A) => Promise<R>;
    /** Attaches feedback to a run, through the store's `addFeedback` when it has one. */
    recordFeedback(runId: string, feedback: Omit<RunFeedback, 'createdAt'> & {
        createdAt?: string;
    }): Promise<void>;
    private handle;
    private close;
    private keepByTail;
    private decideSampling;
    /** Applies the redaction policy. What a trace must not hold, it never holds. */
    private prepare;
}
/** Removes fields by dot path, deeply, without mutating what the caller passed in. */
export declare function stripFields(value: unknown, fields: readonly string[]): unknown;