/**
 * xrayObservability — AWS X-Ray distributed-tracing adapter.
 *
 * Maps agentfootprint's event taxonomy onto AWS X-Ray segment trees:
 *
 *     agent.turn_start          ↦  root segment (one trace per turn)
 *     agent.turn_end            ↦  close root segment + flush
 *     agent.iteration_start     ↦  push subsegment under root
 *     agent.iteration_end       ↦  close iteration subsegment
 *     stream.llm_start          ↦  push leaf subsegment (model call)
 *     stream.llm_end            ↦  close llm subsegment
 *     stream.tool_start         ↦  push leaf subsegment (tool call)
 *     stream.tool_end           ↦  close tool subsegment (correlated
 *                                  by toolCallId — parallel-safe)
 *     error.fatal               ↦  fault on root + close the whole
 *                                  tree (turn_end never arrives)
 *
 * Events are anchored on `meta.runId` (the dispatcher envelope),
 * with a `payload.runId` fallback for hand-built events.
 *
 * The result in the X-Ray Trace Map: a hierarchical timeline of every
 * agent run — turn → iteration → llm-call/tool-call — queryable in
 * X-Ray Insights, joinable with the rest of your AWS distributed
 * trace via `AWSTraceHeader` propagation (consumer's responsibility
 * to wire upstream/downstream IDs).
 *
 * Subpath:  `agentfootprint/observability-providers`
 * Peer dep: `@aws-sdk/client-xray` (OPTIONAL — installed only when
 *           this adapter is used).
 *
 * Sampling:
 *   By default every turn produces one trace. Pass `sampleRate: 0.1`
 *   to sample 10% of turns — sampling decisions are made at
 *   `turn_start` and persist for the whole turn (so partial traces
 *   never reach X-Ray).
 *
 * @example
 * ```ts
 * import { xrayObservability } from 'agentfootprint/observability-providers';
 * import { microtaskBatchDriver } from 'footprintjs/detach';
 *
 * agent.enable.observability({
 *   strategy: xrayObservability({
 *     region: 'us-east-1',
 *     serviceName: 'my-agent',
 *     sampleRate: 0.1,                    // 10% sampling
 *   }),
 *   detach: { driver: microtaskBatchDriver, mode: 'forget' },
 * });
 * ```
 *
 * @example Test injection
 * ```ts
 * xrayObservability({
 *   serviceName: 'test',
 *   _client: {
 *     putTraceSegments: async (input) => { capturedDocs.push(input); },
 *   },
 * });
 * ```
 */
import type { ObservabilityStrategy } from '../../strategies/types.js';
export interface XrayObservabilityOptions {
    /** AWS region. Falls back to AWS_REGION / AWS_DEFAULT_REGION env. */
    readonly region?: string;
    /** Service name on every emitted segment. Surfaces in X-Ray's
     *  service map. Required. */
    readonly serviceName: string;
    /** 0..1 — fraction of turns to sample. Default `1.0` (every turn).
     *  Decisions are made at `turn_start` and persist for the whole
     *  turn so partial traces never reach X-Ray. */
    readonly sampleRate?: number;
    /** Max segments buffered before forced flush. X-Ray's
     *  `PutTraceSegments` API accepts up to 50 segments per call;
     *  default 25 keeps latency tight. */
    readonly maxBatchSegments?: number;
    /** Forced flush window for low-traffic agents. Default 1000ms.
     *  `0` disables time-based flush. */
    readonly flushIntervalMs?: number;
    /** Test injection — bypasses SDK lazy-require entirely. */
    readonly _client?: XRayLikeClient;
}
export interface XRayLikeClient {
    putTraceSegments(input: {
        TraceSegmentDocuments: ReadonlyArray<string>;
    }): Promise<unknown>;
}
export declare function xrayObservability(opts: XrayObservabilityOptions): ObservabilityStrategy;
//# sourceMappingURL=xray.d.ts.map