/**
 * Optional OpenTelemetry layer for the agent loop.
 *
 * The framework's primary trace store is the in-house `agent_trace_spans` /
 * `agent_trace_summaries` tables (see `traces.ts`). This module adds an
 * OPTIONAL, no-op-unless-configured OpenTelemetry export on top of that, so a
 * host that already runs an OTel collector can see agent runs, model calls, and
 * tool calls alongside the rest of their distributed traces.
 *
 * Design constraints:
 *   - `@opentelemetry/api` is an OPTIONAL dependency. If it isn't installed the
 *     helpers degrade to silent no-ops — nothing here ever throws into the agent
 *     loop.
 *   - The API package ships a default NO-OP tracer. Until a host registers a
 *     real `TracerProvider` (via `@opentelemetry/sdk-node` or similar, which
 *     core deliberately does NOT depend on), `tracer.startSpan(...)` returns a
 *     no-op span and the cost is a couple of property reads. We never register a
 *     provider ourselves — instrumentation is opt-in by the embedding app.
 *   - Heavy SDK packages (`@opentelemetry/sdk-*`, exporters) are NOT added to
 *     core. The host owns the provider/exporter wiring; core only emits spans.
 */
/**
 * Minimal structural subset of the OpenTelemetry `Span` we use. Declared
 * locally so this module type-checks even when `@opentelemetry/api` isn't
 * installed (it's an optional dependency).
 */
export interface AgentSpan {
    setAttribute(key: string, value: string | number | boolean): void;
    setAttributes(attributes: Record<string, string | number | boolean>): void;
    /** OTel `SpanStatusCode`: 1 = OK, 2 = ERROR. */
    setStatus(status: {
        code: number;
        message?: string;
    }): void;
    recordException(exception: {
        name?: string;
        message: string;
    }): void;
    end(): void;
}
/** OTel `SpanStatusCode` values, inlined so we don't need the api types here. */
export declare const SPAN_STATUS_OK = 1;
export declare const SPAN_STATUS_ERROR = 2;
interface AgentTracer {
    startSpan(name: string, options?: {
        attributes?: Record<string, string | number | boolean>;
    }): AgentSpan;
}
/**
 * Start a span. When OTel isn't installed (or no provider is registered) this
 * returns `null` and the caller simply skips span bookkeeping — there is no
 * runtime cost beyond the cached null check.
 */
export declare function startAgentSpan(name: string, attributes?: Record<string, string | number | boolean | null | undefined>): Promise<AgentSpan | null>;
/**
 * Finish a span, setting OK/ERROR status and recording the error message when
 * present. Safe to call with `null` (no-op) and never throws.
 */
export declare function endAgentSpan(span: AgentSpan | null, result?: {
    status?: "success" | "error";
    errorMessage?: string | null;
    attributes?: Record<string, string | number | boolean | null | undefined>;
}): void;
/** For tests — reset the cached tracer so a fresh provider can be detected. */
export declare function __resetAgentTracerCache(): void;
/**
 * For tests — inject a tracer directly (e.g. an in-memory test provider's
 * tracer) without going through the `@opentelemetry/api` global. Pass `null`
 * to simulate "no tracer available".
 */
export declare function __setAgentTracerForTests(tracer: AgentTracer | null): void;
export {};
//# sourceMappingURL=tracing.d.ts.map