/**
 * Core telemetry types for the Skaile agent framework.
 *
 * The TelemetryProvider interface is the sole contract between framework
 * instrumentation code and any observability backend (OTEL, Langfuse, etc.).
 */
/**
 * W3C-compatible trace context for cross-process propagation.
 * Carry this across service boundaries to correlate distributed spans
 * into a single trace.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export interface TraceContext {
    traceId: string;
    spanId: string;
    baggage?: Record<string, string>;
}
/**
 * Discriminator for the top-level unit of work being traced.
 * Used as the `kind` field in {@link TraceOptions} and stored on the root span
 * as the `skaile.trace.kind` attribute.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export type TraceKind = "flow_run" | "chat_session" | "skill_test" | "serve_session";
/**
 * Options passed to {@link TelemetryProvider.startTrace}.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export interface TraceOptions {
    name: string;
    kind: TraceKind;
    attributes?: Attributes;
    parentContext?: TraceContext;
}
/**
 * A root-level unit of work. Contains the trace identifier and its root span.
 * Pass a `Trace` as the first argument to {@link TelemetryProvider.startSpan}
 * to create a direct child of the root span.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export interface Trace {
    readonly traceId: string;
    readonly rootSpan: Span;
}
/**
 * Discriminator for the type of operation a span represents.
 * Stored as the `skaile.span.kind` attribute on every span.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export type SpanKind = "agent_turn" | "llm_generation" | "tool_call" | "flow_node" | "connector_op" | "mount_op" | "session_setup" | "manifest_load" | "resource_init" | "internal";
/**
 * Options passed to {@link TelemetryProvider.startSpan}.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export interface SpanOptions {
    name: string;
    kind: SpanKind;
    attributes?: Attributes;
}
/**
 * A single unit of instrumented work within a trace.
 * Spans are lightweight value objects — they carry only IDs.
 * The backing OTEL span is held inside the provider's internal span map.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export interface Span {
    readonly spanId: string;
    readonly traceId: string;
}
/**
 * Terminal state reported when ending a span via {@link TelemetryProvider.endSpan}
 * or {@link TelemetryProvider.endTrace}. Setting `status: "error"` marks the span
 * as failed in the backend UI.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export interface SpanResult {
    status: "ok" | "error";
    error?: string;
    attributes?: Attributes;
}
/**
 * Payload for {@link TelemetryProvider.logGeneration}. Carries the fields
 * required to render an LLM generation in Langfuse or any GenAI-convention-aware
 * OTLP backend.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export interface GenerationEvent {
    model: string;
    provider: string;
    inputTokens?: number;
    outputTokens?: number;
    totalTokens?: number;
    costUsd?: number;
    durationMs: number;
    promptPreview?: string;
    stopReason?: string;
}
/**
 * A scalar value that can be attached to a span or event as an attribute.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export type AttributeValue = string | number | boolean;
/**
 * A flat key-value map of {@link AttributeValue} scalars attached to spans and events.
 *
 * @docLink packages/telemetry/concepts#core-types
 */
export type Attributes = Record<string, AttributeValue>;
/**
 * The pluggable telemetry backend contract. Framework instrumentation code
 * depends only on this interface — never on a concrete implementation.
 *
 * The two built-in implementations are {@link NoopTelemetryProvider} (zero-cost
 * default) and `OtelTelemetryProvider` (OTLP/HTTP backend). Custom backends can
 * be injected via constructor injection at entry points.
 *
 * @docLink packages/telemetry/concepts#telemetry-provider
 */
export interface TelemetryProvider {
    /** Start a new trace (root-level unit of work). */
    startTrace(opts: TraceOptions): Trace;
    /** End a trace. */
    endTrace(trace: Trace, result?: SpanResult): void;
    /** Start a span. Pass a Trace for a root-level child, or a parent Span for nesting. */
    startSpan(parent: Trace | Span, opts: SpanOptions): Span;
    /** End a span with an optional result. */
    endSpan(span: Span, result?: SpanResult): void;
    /** Record a named event on a span. */
    addEvent(span: Span, name: string, attrs?: Attributes): void;
    /** Record an LLM generation event on a span (uses GenAI conventions). */
    logGeneration(span: Span, generation: GenerationEvent): void;
    /** Record a numeric metric (counter or histogram value). */
    recordMetric(name: string, value: number, tags?: Record<string, string>): void;
    /** Flush buffered telemetry data. */
    flush(): Promise<void>;
    /** Shut down the provider and release resources. */
    shutdown(): Promise<void>;
}
/**
 * Fine-grained flags that control which framework events are recorded.
 * Maps to the `telemetry.capture` block in `skaile.yaml`.
 * `prompt_content` defaults to `false` to avoid sending sensitive data to the
 * collector unless explicitly enabled.
 *
 * @docLink packages/telemetry/concepts#configuration
 */
export interface TelemetryCaptureConfig {
    llm_generations: boolean;
    tool_calls: boolean;
    connector_ops: boolean;
    mount_ops: boolean;
    flow_state_changes: boolean;
    prompt_content: boolean;
}
/**
 * Fully-resolved telemetry configuration produced by {@link resolveTelemetryConfig}.
 * All fields are present and concrete — no `undefined` except for optional OTLP
 * connection fields (`endpoint`, `auth`, `secretKey`).
 *
 * @docLink packages/telemetry/concepts#configuration
 */
export interface TelemetryConfig {
    provider: "otel" | "none";
    endpoint?: string;
    auth?: string;
    secretKey?: string;
    samplingRate: number;
    batchSize: number;
    exportIntervalMs: number;
    capture: TelemetryCaptureConfig;
}
//# sourceMappingURL=types.d.ts.map