import type { ToolCallStatus, ToolCallStatusSource, TraceIngestionSummary, TraceSourceMetadata } from '../types/index.js';
import type { TraceSourceKind } from '../types/trace.js';
import type { NormalizedToolIdentity } from '../shared/tool-identity.js';
export type { TraceSourceKind } from '../types/trace.js';
export type TraceRole = 'standalone' | 'main' | 'subagent';
export type TraceMessageRole = 'user' | 'assistant' | 'system';
export type TraceMessageOrigin = 'human' | 'runtime' | 'skill-context' | 'synthetic';
export type TraceToolStatus = ToolCallStatus;
export type TraceToolStatusSource = ToolCallStatusSource;
/** Source-neutral tool identity, including provider namespaces when present. */
export type TraceToolRef = NormalizedToolIdentity;
interface TraceEventBase {
    eventId: string;
    /** Source-native record/message id, when the source exposes one. */
    sourceEventId?: string;
    sourceIndex: number;
    sourceType: string;
    timestamp?: string;
    turnId?: string;
}
export interface TraceMessageEvent extends TraceEventBase {
    eventKind: 'message';
    role: TraceMessageRole;
    origin: TraceMessageOrigin;
    text: string;
    model?: string;
    attributionSkill?: string;
}
export interface TraceToolCallEvent extends TraceEventBase {
    eventKind: 'tool_call';
    callId: string;
    callInstanceId?: string;
    tool: TraceToolRef;
    input: Record<string, unknown>;
    model?: string;
}
export interface TraceToolResultEvent extends TraceEventBase {
    eventKind: 'tool_result';
    callId: string;
    callInstanceId?: string;
    output: string;
    status: TraceToolStatus;
    statusSource: TraceToolStatusSource;
}
export interface TraceUsageEvent extends TraceEventBase {
    eventKind: 'usage';
    model?: string;
    inputTokens: number;
    outputTokens: number;
    cacheReadTokens: number;
    cacheCreationTokens: number;
    reasoningTokens?: number;
}
export interface TraceLifecycleEvent extends TraceEventBase {
    eventKind: 'lifecycle';
    phase: 'session_started' | 'session_ended' | 'turn_started' | 'turn_completed' | 'turn_aborted' | 'turn_interrupted';
    reason?: string;
    durationMs?: number;
}
export interface TraceUnknownEvent extends TraceEventBase {
    eventKind: 'unknown';
    raw?: unknown;
}
export type TraceEvent = TraceMessageEvent | TraceToolCallEvent | TraceToolResultEvent | TraceUsageEvent | TraceLifecycleEvent | TraceUnknownEvent;
export interface TraceSession {
    /** Concrete source run/thread identifier. */
    runId: string;
    /** Root run shared by a main trace and its descendants. */
    rootRunId: string;
    parentRunId?: string;
    /** Unique evidence stream identifier. */
    traceId: string;
    groupPath: string;
    role: TraceRole;
    label: string;
    sourcePath: string;
    sourceKind: TraceSourceKind;
    events: TraceEvent[];
    cwd?: string;
    gitBranch?: string;
    entrypoint?: string;
    sourceMetadata?: TraceSourceMetadata;
    startTimestamp?: string;
    endTimestamp?: string;
}
export interface TraceCorpus {
    sessions: TraceSession[];
    ingestion: TraceIngestionSummary;
}
/**
 * Build a deterministic, transport-safe identity for one physical evidence
 * stream. Source paths remain available as provenance; the identifier itself
 * stays opaque so it can safely cross JSON, HTML, URLs, and review-state keys.
 */
export declare function createTraceId(input: {
    sourceKind: TraceSourceKind;
    runId: string;
    sourcePath: string;
    streamId?: string;
}): string;
export declare function traceEventTimestamp(event: TraceEvent): string | undefined;
export declare function normalizeTraceTimestamp(value: unknown): string | undefined;
export declare function traceTimestampBounds(values: Iterable<unknown>): {
    startTimestamp?: string;
    endTimestamp?: string;
};
export declare function traceToolDisplayName(tool: TraceToolRef): string;
/**
 * Correlate one concrete call occurrence with its result without treating a
 * source-native callId as globally unique. FIFO is the only source-neutral
 * assumption available when a runtime reuses call IDs.
 */
export declare function correlateTraceToolEvents(events: TraceEvent[]): TraceEvent[];