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. 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.
 */
export declare function traceModelClient<T extends ModelClientLike>(client: T, tracer: Tracer, options?: {
    parent?: () => RunHandle | undefined;
    name?: string;
}): T;