import type { GraphEvent, GraphResult } from '../types/graph.js';
import type { CompletionRequest } from '../types/messages.js';
import type { NexusResponse } from '../types/response.js';
import type { RunHandle, Tracer } from './tracer.js';
/** Options for `traceGraph()`. */
export interface GraphTracingOptions {
    /** Name of the root run. Defaults to `graph`. */
    name?: string;
    /** Labels for filtering. */
    tags?: string[];
    /** Metadata added to the root run. */
    metadata?: Record<string, unknown>;
    /** Inputs recorded on the root run. */
    inputs?: unknown;
    /** `graph` by default; an agent run is worth labelling as one. */
    kind?: 'graph' | 'agent';
}
/** Tracing for one graph run: a root run with one child per task. */
export interface GraphTracing {
    /** Spread into a run's options: `graph.invoke(input, { threadId, ...tracing.runOptions })`. */
    runOptions: {
        onEvent: (event: GraphEvent) => void;
    };
    /** The run every task hangs from. */
    root: RunHandle;
    /** The active run for a node, so a model call inside it nests where it belongs. */
    runFor(node: string): RunHandle | undefined;
    /** Finishes the root run, recording the result's status and state. */
    finish(result?: GraphResult<never> | {
        status?: string;
        state?: unknown;
    }): Promise<void>;
}
/**
 * Records a graph or agent run as a trace.
 *
 * The graph already reports every task starting, retrying, and finishing; tracing is that stream
 * written down as a tree. A retry is an event on its task's run, and a tool's progress an event on
 * the tool's. A task that follows a step of several tasks, such as the join after a fan-out, links to
 * each of them. Nothing inside the graph knows about tracing, and a run without it pays nothing.
 */
export declare function traceGraph(tracer: Tracer, options?: GraphTracingOptions): GraphTracing;
/** Any client with a `complete()` method. */
export interface ModelClientLike {
    /** Runs one completion. */
    complete(request: CompletionRequest): Promise<NexusResponse>;
}
/**
 * Wraps a model client so every call becomes a run, with its tokens and cost.
 *
 * `parent` decides where the call hangs: pass `() => tracing.runFor('model')` and a model call lands
 * inside the node that made it rather than beside it.
 *
 * What the response reports becomes the run's events: each attempt that failed before it, as `retry`
 * on the same provider or `failover` to another, at the time it failed; each guardrail applied, as
 * `guardrail`; the cache's answer, as `cache`; and each capability warning.
 */
export declare function traceModelClient<T extends ModelClientLike>(client: T, tracer: Tracer, options?: {
    parent?: () => RunHandle | undefined;
    name?: string;
}): T;
/** Anything with a `retrieve()` method, such as every retriever in `nexus-ai-pro/rag`. */
export interface RetrieverLike {
    /** The documents that best answer a query, best first. Its options are recorded, all but a `signal`. */
    retrieve(query: string, options?: object): Promise<readonly unknown[]>;
}
/**
 * Wraps a retriever so every retrieval becomes a run of kind `retriever`, holding the query and the
 * documents that came back, so an evaluator reading the trace sees what an answer rested on. Every
 * other member of the retriever is its own.
 *
 * `parent` decides where the retrieval hangs; without it, under the run in scope.
 */
export declare function traceRetriever<T extends RetrieverLike>(retriever: T, tracer: Tracer, options?: {
    parent?: () => RunHandle | undefined;
    name?: string;
}): T;