/**
 * telemetry-otel.ts — OpenTelemetry span export bridge.
 *
 * Provides no-op-safe OpenTelemetry span creation for agent lifecycle events.
 * Uses the global @opentelemetry/api tracer — if the host application hasn't
 * configured a TracerProvider, all operations are zero-cost no-ops.
 *
 * Architecture:
 *   - Only imports from @opentelemetry/api (the interface, not the SDK)
 *   - The host application is responsible for configuring the TracerProvider
 *     and exporters (Console, OTLP, Jaeger, etc.)
 *   - This module creates spans at meaningful lifecycle points with proper
 *     parent-child relationships via context propagation
 *
 * Span hierarchy (when a TracerProvider is configured):
 *   agent.run:Explore
 *   ├── agent.turn:1
 *   │   ├── tool.call:read
 *   │   └── tool.call:write
 *   ├── agent.turn:2
 *   │   └── tool.call:search
 *   └── agent.compaction (event, duration ~0)
 */
import { type Context, type Span, type Tracer } from "@opentelemetry/api";
import { setTracingEnabled } from "./agent-registry.js";
export { setTracingEnabled };
/** OpenTelemetry attribute name for the per-agent correlation id. */
export declare const CORRELATION_ID_ATTRIBUTE = "correlation.id";
/**
 * Generate a short correlation id (8 hex chars, derived from a v4 UUID).
 * Cheap (~one crypto call) and collision-resistant for one session — the
 * underlying UUID v4 is uniformly random, and the 32-bit prefix is plenty
 * to tie a subagent run + its spans + its log lines together in `/agents
 * health` and in the dashboard.
 *
 * The id is stable for the lifetime of an agent record (set at spawn,
 * preserved across `resumeAgent`), so re-running an agent keeps the same
 * correlation id and traces line up.
 */
export declare function generateCorrelationId(): string;
/** Library name for scoped tracer identification. */
export declare const TRACER_NAME = "pi-agent-orchestrator";
export declare const TRACER_VERSION = "0.14.1";
/** Get a tracer scoped to this library. No-op safe. */
export declare function getTracer(): Tracer;
/** Invalidate cached tracer (for testing after TracerProvider changes). */
export declare function resetTracer(): void;
/**
 * Start an agent lifecycle span and return both the span and an active
 * context so child spans (tool, turn, compaction) inherit the parent.
 *
 * If `options.correlationId` is provided it is attached as the OTel
 * `correlation.id` attribute (so the value is queryable through the OTel
 * SDK's normal `getSpanAttribute` / `attributes` accessors) and is also
 * echoed back on the result. The runner does not depend on this return
 * value — the agent record is the source of truth for correlation ids —
 * but tests and ad-hoc log helpers can read it without an extra import.
 */
export declare function startAgentSpan(agentId: string, type: string, options?: {
    description?: string;
    depth?: number;
    model?: string;
    correlationId?: string;
}): {
    span: Span;
    ctx: Context;
    correlationId?: string;
};
/**
 * End an agent span with completion status and metrics.
 */
export declare function endAgentSpan(span: Span, result: {
    status: "completed" | "error" | "aborted" | "steered";
    durationMs: number;
    turns: number;
    toolCalls: number;
    tokensIn: number;
    tokensOut: number;
    tokensCacheWrite?: number;
    validated?: boolean;
    error?: string;
}): void;
/**
 * Start a tool call sub-span as a child of the agent span context.
 */
export declare function startToolSpan(agentId: string, toolName: string, parentCtx?: Context): Span;
/**
 * End a tool call span with status.
 */
export declare function endToolSpan(span: Span, error?: string): void;
/**
 * Start a turn sub-span as a child of the agent span context.
 */
export declare function startTurnSpan(agentId: string, turnNumber: number, parentCtx?: Context): Span;
/**
 * End a turn span.
 */
export declare function endTurnSpan(span: Span): void;
/**
 * Add a compaction sub-span (event/duration ~0) as a child of the agent context.
 */
export declare function startCompactionSpan(agentId: string, reason: string, tokensBefore: number, parentCtx?: Context): Span;
/**
 * End a compaction span.
 */
export declare function endCompactionSpan(span: Span): void;