/**
 * Tracing and OpenTelemetry instrumentation for the execution engine.
 *
 * Extracted from ExecutionTree.ts — Phase 1 of the refactor.
 * See docs/execution-tree-refactor.md
 */
import type { Span } from "@opentelemetry/api";
import type { BatchToolMetadata } from "@stackables/bridge-types";
import type { Logger } from "./tree-types.ts";
export declare const otelTracer: import("@opentelemetry/api").Tracer;
export declare function isOtelActive(): boolean;
export declare const toolCallCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
export declare const toolDurationHistogram: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
export declare const toolErrorCounter: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
export { SpanStatusCode as SpanStatusCodeEnum } from "@opentelemetry/api";
/** Trace verbosity level.
 *  - `"off"` (default) — no collection, zero overhead
 *  - `"basic"` — tool, fn, timing, errors; no input/output
 *  - `"full"` — everything including input and output */
export type TraceLevel = "basic" | "full" | "off";
/** A single recorded tool invocation. */
export type ToolTrace = {
    /** Tool name as resolved (e.g. "hereGeo", "std.str.toUpperCase") */
    tool: string;
    /** The function that was called (e.g. "httpCall", "upperCase") */
    fn: string;
    /** Input object passed to the tool function (only in "full" level) */
    input?: Record<string, any>;
    /** Resolved output (only in "full" level, on success) */
    output?: any;
    /** Error message (present when the tool threw) */
    error?: string;
    /** Wall-clock duration in milliseconds */
    durationMs: number;
    /** Monotonic timestamp (ms) relative to the first trace in the request */
    startedAt: number;
};
/**
 * Bounded clone utility — replaces `structuredClone` for trace data.
 * Truncates arrays, strings, and deep objects to prevent OOM when
 * tracing large payloads.
 */
export declare function boundedClone(value: unknown, maxArrayItems?: number, maxStringLength?: number, depth?: number): unknown;
/** Shared trace collector — one per request, passed through the tree. */
export declare class TraceCollector {
    readonly traces: ToolTrace[];
    readonly level: "basic" | "full";
    private readonly epoch;
    /** Max array items to keep in bounded clone (configurable). */
    readonly maxArrayItems: number;
    /** Max string length to keep in bounded clone (configurable). */
    readonly maxStringLength: number;
    /** Max object depth to keep in bounded clone (configurable). */
    readonly cloneDepth: number;
    constructor(level?: "basic" | "full", options?: {
        maxArrayItems?: number;
        maxStringLength?: number;
        cloneDepth?: number;
    });
    /** Returns ms since the collector was created */
    now(): number;
    record(trace: ToolTrace): void;
    /** Build a trace entry, omitting input/output for basic level. */
    entry(base: {
        tool: string;
        fn: string;
        startedAt: number;
        durationMs: number;
        input?: Record<string, any>;
        output?: any;
        error?: string;
    }): ToolTrace;
}
/**
 * Resolved logging behaviour derived from a tool's `.bridge` metadata.
 * A fixed shape so call sites never branch on `undefined`.
 */
export type EffectiveToolLog = {
    /** Logger level for successful invocations, or `false` to suppress. */
    execution: false | "debug" | "info";
    /** Logger level for thrown errors, or `false` to suppress. */
    errors: false | "warn" | "error";
};
/** Normalised metadata resolved from the optional `.bridge` property. */
export type ResolvedToolMeta = {
    /** Whether the tool declares synchronous execution. */
    sync: boolean;
    /** Batch mode contract, when declared. */
    batch?: BatchToolMetadata;
    /** Emit an OTel span for this call. Default: `true`. */
    doTrace: boolean;
    log: EffectiveToolLog;
};
/** Read and normalise the `.bridge` metadata from a tool function. */
export declare function resolveToolMeta(fn: (...args: any[]) => any): ResolvedToolMeta;
/** Log a successful tool invocation. No-ops when `level` is `false`. */
export declare function logToolSuccess(logger: Logger | undefined, level: EffectiveToolLog["execution"], toolName: string, fnName: string, durationMs: number): void;
/** Log a tool error. No-ops when `level` is `false`. */
export declare function logToolError(logger: Logger | undefined, level: EffectiveToolLog["errors"], toolName: string, fnName: string, err: Error): void;
/** Record an exception on a span and mark it as errored. */
export declare function recordSpanError(span: Span | undefined, err: Error): void;
/**
 * Run `fn` inside an OTel span when `doTrace` is true;
 * otherwise call it directly with `undefined` as the span argument.
 */
export declare function withSpan<T>(doTrace: boolean, name: string, attrs: Record<string, string>, fn: (span: Span | undefined) => Promise<T>): Promise<T>;
/**
 * Synchronous variant of `withSpan` — runs `fn` inside an OTel span
 * without introducing a Promise.  Used by the sync-tool instrumented
 * path so that `{sync: true, trace: true}` tools still produce spans.
 */
export declare function withSyncSpan<T>(doTrace: boolean, name: string, attrs: Record<string, string>, fn: (span: Span | undefined) => T): T;
//# sourceMappingURL=tracing.d.ts.map