import type { RunAttributeValue, RunFeedback, RunKind, RunLink, RedactionPolicy, SamplingPolicy, TraceExporter, TraceStore } from '../types/tracing.js';
/** An event to record: its time defaults to now. */
export interface RunEventInput {
    /** What happened. */
    name: string;
    /** When, as ISO-8601 or a `Date`. Defaults to now. */
    time?: string | Date;
    /** What it carries. */
    attributes?: Record<string, RunAttributeValue>;
}
/** A run to link to: by its trace and id, or by a W3C `traceparent` header from another process. */
export type RunLinkInput = RunLink | {
    traceparent: string;
    attributes?: Record<string, RunAttributeValue>;
};
/** Configuration for a tracer. */
export interface TracerOptions {
    /** Where runs are written. */
    store: TraceStore;
    /** Which traces are kept. */
    sampling?: SamplingPolicy;
    /** What is removed from runs before they are stored or exported. */
    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>;
    /**
     * Writes each run when it starts and again when it ends, instead of a whole trace once its root
     * finishes.
     *
     * A trace written at the end is lost with the process that held it. Written as it runs, a crashed
     * run stays in the store with every run that finished, and a run in progress can be watched.
     * Sampling is then decided when the root starts. A trace not sampled is still held in memory and
     * written at the end when tail sampling keeps it, so `keepErrors` still shows every failure.
     * Defaults to true on a durable store, one whose `durable` is not `false`, and to false, which writes
     * at the end, on one in memory and under 2.x's defaults, `useDefaults('2.x')`.
     */
    incremental?: boolean;
    /**
     * Also hands every finished run that is kept to these exporters, after redaction, such as an
     * `OtlpTraceExporter` sending OpenTelemetry spans to a collector.
     */
    exporters?: TraceExporter[];
    /** 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;
    /** The events one run keeps; the rest are counted as `droppedEvents`. Defaults to 128. */
    maxEventsPerRun?: number;
}
/** 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;
    /**
     * Continues a trace another process started, from a W3C `traceparent` header such as the one
     * `RunHandle.traceparent()` returns or an OpenTelemetry service sends. The run joins that trace,
     * under the span the header names, and keeps its sampling decision.
     */
    traceparent?: string;
    /** The runs it came from beside its parent, such as the branches a joined step gathers. */
    links?: readonly RunLinkInput[];
}
/** 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;
    /** Events learned only as it ends, such as those a response reports, recorded at their own times. */
    events?: readonly RunEventInput[];
    /** Links learned only as it ends. */
    links?: readonly RunLinkInput[];
}
/** 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. By default the trace is written once its root finishes; with `incremental`,
     * this run is written now.
     */
    finish(options?: FinishRunOptions): Promise<void>;
    /** Starts a run beneath this one, without relying on the ambient context. */
    child(options: StartRunOptions): RunHandle;
    /**
     * This run as a W3C `traceparent` header, for work it hands to another process: an operation's
     * `traceContext`, a request to a remote graph, a call to any OpenTelemetry service. Pass it back
     * as `StartRunOptions.traceparent` there.
     */
    traceparent(): string;
    /** Records something that happened inside the run, now unless `time` says. Ignored once it finished. */
    event(name: string, attributes?: Record<string, RunAttributeValue>, time?: string | Date): void;
    /** A link to this run, for another run to say it came from it. */
    link(attributes?: Record<string, RunAttributeValue>): RunLink;
}
/**
 * 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;
    /** Each trace's writes, in order, so a run's end can never land before its start. */
    private readonly writes;
    /** What each handle puts in scope for `within()`. */
    private readonly scopes;
    /** Runs that finished, whose events are closed. Weak, so a run never finished is never held. */
    private readonly closed;
    private readonly now;
    /** Whether runs are written as they start and finish: as asked, or as the defaults in effect say. */
    private readonly writesAsItRuns;
    constructor(options: TracerOptions);
    /** Where runs are written. */
    get store(): TraceStore;
    /** Whether runs are written as they start and finish, as `incremental` asks, or 3.0's defaults do. */
    get incremental(): boolean;
    /** The run currently in scope, if any. */
    current(): {
        traceId: string;
        runId: string;
    } | undefined;
    /**
     * Records something that happened on the run in scope, such as a retry or a verdict, now unless
     * `time` says. Returns whether there was a run to record it on.
     */
    event(name: string, attributes?: Record<string, RunAttributeValue>, time?: string | Date): boolean;
    /**
     * 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>;
    /**
     * Runs `fn` with a run in scope, so every run started inside it, such as a model call through a
     * traced client, nests beneath that run. Unlike `trace()`, it neither starts nor finishes the run:
     * a run started with `startRun()` is finished by its handle, when its owner decides.
     */
    within<T>(handle: RunHandle, fn: () => T): 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>;
    /** Waits for every write and export handed over so far. */
    flush(): Promise<void>;
    /** Adds an event to a run still open, keeping at most `maxEventsPerRun` and counting the rest. */
    private record;
    private handle;
    private close;
    /** Chains a write behind the trace's earlier ones. A failed write is reported, never thrown. */
    private enqueue;
    private settle;
    private export;
    private keepByTail;
    private decideSampling;
    /** Applies the redaction policy. What a trace must not hold, it never holds. */
    private prepare;
}
/**
 * A trace id as the 32 hex digits W3C trace context and OpenTelemetry use. An id that already is one
 * is kept; a tracer's own `trace-…` id is padded, so every process derives the same one.
 */
export declare function w3cTraceId(traceId: string): string;
/** A run id as the 16 hex digits of a W3C span id. */
export declare function w3cSpanId(runId: string): string;
/** Removes fields by dot path, deeply, without mutating what the caller passed in. */
export declare function stripFields(value: unknown, fields: readonly string[]): unknown;