agent-inspect 1.1.0 → 1.3.0

package/packages/core/dist/index.d.cts

@@ -220,8 +220,17 @@ interface StepCompletedEvent extends TraceEventBase {
 }
 /** Discriminated union of all MVP trace events written as JSONL lines. */
 type TraceEvent = RunStartedEvent | RunCompletedEvent | StepStartedEvent | StepCompletedEvent;
+/** Named redaction presets for trace writing and share-safe exports (v1.3.0+). */
+type RedactionProfile = "local" | "share" | "strict";
+/** Optional correlation fields for grouping and cross-run tracing (v1.3.0+). */
+interface TraceCorrelationMetadata {
+    correlationId?: string;
+    requestId?: string;
+    decisionId?: string;
+    groupId?: string;
+}
 /** Options for `inspectRun()` and `maybeInspectRun()`. */
-interface InspectRunOptions {
+interface InspectRunOptions extends TraceCorrelationMetadata {
     traceDir?: string;
     silent?: boolean;
     metadata?: Record<string, unknown>;
@@ -237,6 +246,12 @@ interface InspectRunOptions {
     redact?: boolean | {
         rules?: RedactionRule[];
     };
+    /**
+     * Redaction preset for trace metadata. Default `local` (same keys as default redaction).
+     * `share` and `strict` add extra key-based redaction and tighter string bounds.
+     * Ignored when `redact: false`.
+     */
+    redactionProfile?: RedactionProfile;
     /** Max UTF-8 bytes for a serialized trace event line. Default 65536. */
     maxEventBytes?: number;
     /** Max length for string metadata values (non-preview keys). Default 2000. */
@@ -278,6 +293,145 @@ declare function isStepStatus(value: unknown): value is StepStatus;
  */
 declare function isTraceEvent(value: unknown): value is TraceEvent;
 
+type PersistedSchemaVersion = "0.2";
+type PersistedEventSourceType = "manual" | "json-log" | "log4js" | "adapter" | "ai-sdk" | "otel";
+interface PersistedEventSource {
+    type: PersistedEventSourceType;
+    name?: string;
+    version?: string;
+}
+type PersistedEventStatus = "running" | "ok" | "error" | "unknown";
+interface PersistedInspectError {
+    name?: string;
+    message: string;
+    code?: string;
+}
+interface PersistedTokenUsage {
+    input?: number;
+    output?: number;
+    total?: number;
+}
+interface PersistedTraceContext {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+}
+interface PersistedInspectEvent {
+    schemaVersion: PersistedSchemaVersion;
+    eventId: string;
+    runId: string;
+    parentId?: string;
+    kind: InspectKind;
+    name: string;
+    status?: PersistedEventStatus;
+    timestamp: string;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    confidence: AttributionConfidence;
+    source: PersistedEventSource;
+    attributes?: Record<string, unknown>;
+    inputSummary?: unknown;
+    outputSummary?: unknown;
+    error?: PersistedInspectError;
+    tokenUsage?: PersistedTokenUsage;
+    trace?: PersistedTraceContext;
+}
+/**
+ * Runtime guard for a v0.2 {@link PersistedInspectEvent} JSON object.
+ *
+ * Timestamp fields (`timestamp`, `startedAt`, `endedAt`) are validated as
+ * non-empty strings only — stricter ISO-8601 parsing may be added later.
+ */
+declare function isPersistedInspectEvent(value: unknown): value is PersistedInspectEvent;
+
+interface TraceEventToPersistedOptions {
+    /**
+     * Stable index within the source event list.
+     * Used only to make synthetic eventId deterministic when v0.1 has no eventId.
+     */
+    eventIndex?: number;
+    /**
+     * Optional source name override.
+     * Default: "trace-event"
+     */
+    sourceName?: string;
+    /**
+     * Optional source version override.
+     * Default: "0.1"
+     */
+    sourceVersion?: string;
+}
+/**
+ * Maps one v0.1 {@link TraceEvent} to a v0.2 {@link PersistedInspectEvent}.
+ * Does not mutate `event`.
+ */
+declare function traceEventToPersistedInspectEvent(event: TraceEvent, options?: TraceEventToPersistedOptions): PersistedInspectEvent;
+/**
+ * Maps a v0.1 trace event list to persisted v0.2 events (one output per input).
+ */
+declare function traceEventsToPersistedInspectEvents(events: readonly TraceEvent[], options?: Omit<TraceEventToPersistedOptions, "eventIndex">): PersistedInspectEvent[];
+
+interface InspectEventToPersistedOptions {
+    /**
+     * Optional source name override.
+     * If omitted, derived from event.source.type.
+     */
+    sourceName?: string;
+    /**
+     * Optional source version override.
+     */
+    sourceVersion?: string;
+    /**
+     * Stable index for deterministic fallback IDs if needed.
+     */
+    eventIndex?: number;
+}
+/**
+ * Maps one in-memory {@link InspectEvent} to a v0.2 {@link PersistedInspectEvent}.
+ * Does not mutate `event`.
+ */
+declare function inspectEventToPersistedInspectEvent(event: InspectEvent, options?: InspectEventToPersistedOptions): PersistedInspectEvent;
+/**
+ * Maps in-memory {@link InspectEvent} rows to persisted v0.2 events.
+ */
+declare function inspectEventsToPersistedInspectEvents(events: readonly InspectEvent[], options?: Omit<InspectEventToPersistedOptions, "eventIndex">): PersistedInspectEvent[];
+
+interface PersistedToInspectEventOptions {
+    /**
+     * If true, invalid persisted events are skipped by batch conversion.
+     * If false or omitted, invalid events throw.
+     */
+    skipInvalid?: boolean;
+}
+/**
+ * Maps one v0.2 {@link PersistedInspectEvent} to in-memory {@link InspectEvent}.
+ * Throws if `event` fails {@link isPersistedInspectEvent}.
+ */
+declare function persistedInspectEventToInspectEvent(event: PersistedInspectEvent): InspectEvent;
+/**
+ * Maps persisted v0.2 events to in-memory {@link InspectEvent} rows.
+ */
+declare function persistedInspectEventsToInspectEvents(events: readonly PersistedInspectEvent[], options?: PersistedToInspectEventOptions): InspectEvent[];
+
+interface PersistedTreeBridgeOptions {
+    /**
+     * If true, invalid persisted events are skipped.
+     * If false or omitted, invalid persisted events throw.
+     */
+    skipInvalid?: boolean;
+}
+/**
+ * Builds {@link InspectRunTree} rows from v0.2 {@link PersistedInspectEvent} input.
+ * Uses {@link TreeBuilder} as the canonical tree builder. Does not mutate `events`.
+ */
+declare function persistedInspectEventsToRunTrees(events: readonly PersistedInspectEvent[], options?: PersistedTreeBridgeOptions): InspectRunTree[];
+/**
+ * Builds {@link InspectRunTree} rows from legacy v0.1 {@link TraceEvent} input
+ * via the persisted-event model. Does not mutate `events`.
+ */
+declare function traceEventsToPersistedRunTrees(events: readonly TraceEvent[]): InspectRunTree[];
+
 type ParserWarningCode = "MALFORMED_JSON" | "MISSING_RUN_ID" | "MISSING_EVENT" | "MISSING_TIMESTAMP" | "UNSUPPORTED_LOG4JS_PAYLOAD" | "CONFIG_ERROR" | "UNKNOWN";
 interface ParserWarning {
     code: ParserWarningCode;
@@ -318,6 +472,8 @@ declare function matchMapping(eventName: string, mappings?: Record<string, LogEv
 declare const DEFAULT_REDACT_KEYS: readonly ["authorization", "cookie", "token", "apiKey", "password", "secret", "email"];
 interface RedactorOptions {
     rules?: RedactionRule[];
+    /** Additional exact keys (case-insensitive) to redact in addition to defaults. */
+    extraKeys?: readonly string[];
 }
 declare class Redactor {
     #private;
@@ -460,6 +616,15 @@ declare function truncateName(name: string, maxLength?: number): string;
  */
 declare function warn(message: string, error?: unknown): void;
 
+interface ResolvedRedactionProfile {
+    profile: RedactionProfile;
+    extraKeys: readonly string[];
+    maxMetadataValueLengthCap?: number;
+    maxPreviewLengthCap?: number;
+}
+/** Resolves named profile behavior (keys + metadata string caps). */
+declare function resolveRedactionProfile(profile?: RedactionProfile): ResolvedRedactionProfile;
+
 /** Default max length for string metadata values (non-preview keys). */
 declare const DEFAULT_MAX_METADATA_VALUE_LENGTH = 2000;
 /** Default max length for preview-like metadata keys (contains `preview`, case-insensitive). */
@@ -470,12 +635,15 @@ declare const DEFAULT_MAX_EVENT_BYTES = 65536;
 interface TraceSafetyOptions {
     redactEnabled: boolean;
     redactionRules?: RedactionRule[];
+    redactionProfile: RedactionProfile;
+    profileExtraKeys: readonly string[];
     maxMetadataValueLength: number;
     maxPreviewLength: number;
     maxEventBytes: number;
 }
+
 /** Resolves {@link InspectRunOptions} trace safety fields with safe defaults. */
-declare function resolveTraceSafetyOptions(options?: Pick<InspectRunOptions, "redact" | "maxEventBytes" | "maxMetadataValueLength" | "maxPreviewLength">): TraceSafetyOptions;
+declare function resolveTraceSafetyOptions(options?: Pick<InspectRunOptions, "redact" | "redactionProfile" | "maxEventBytes" | "maxMetadataValueLength" | "maxPreviewLength">): TraceSafetyOptions;
 /** Redacts (when enabled) and truncates metadata values for disk persistence. */
 declare function prepareMetadataForDisk(metadata: Record<string, unknown> | StepMetadata, opts: TraceSafetyOptions): Record<string, unknown>;
 /**
@@ -488,6 +656,11 @@ declare function prepareTraceEventForDisk(event: TraceEvent, opts: TraceSafetyOp
 declare function getCurrentContext(): ExecutionContext | undefined;
 /** Active `runId` when inside `runWithContext`, else `undefined`. */
 declare function getCurrentRunId(): string | undefined;
+/**
+ * Correlation metadata for the active run (`correlationId`, `requestId`, `decisionId`, `groupId`).
+ * `undefined` outside `inspectRun` / `maybeInspectRun` or when no correlation fields were set.
+ */
+declare function getCurrentCorrelationMetadata(): TraceCorrelationMetadata | undefined;
 /** Active `runName` when inside `runWithContext`, else `undefined`. */
 declare function getCurrentRunName(): string | undefined;
 /**
@@ -748,6 +921,11 @@ interface ExportOptions {
     pretty?: boolean;
     redacted?: boolean;
     maxAttributeLength?: number;
+    /**
+     * Redaction preset for exported copies. Default `local`.
+     * `share` and `strict` apply stronger key-based redaction before rendering.
+     */
+    redactionProfile?: RedactionProfile;
 }
 interface ExportResult {
     format: ExportFormat;
@@ -822,6 +1000,15 @@ declare function exportOtlpJson(tree: InspectRunTree, options?: Partial<ExportOp
 
 declare function validateExportContent(format: ExportFormat, content: string): ExportValidationResult;
 
+interface RedactRunTreeForExportOptions {
+    redactionProfile?: RedactionProfile;
+}
+/**
+ * Returns a deep copy of `tree` with profile-based redaction applied to event attributes.
+ * Does not mutate the input tree.
+ */
+declare function redactRunTreeForExport(tree: InspectRunTree, options?: RedactRunTreeForExportOptions): InspectRunTree;
+
 declare function mergeExportDefaults(options: ExportOptions): ExportOptions;
 /**
  * @experimental Compatibility-oriented export API. Exports are local-only and do not upload anywhere.
@@ -830,4 +1017,4 @@ declare function mergeExportDefaults(options: ExportOptions): ExportOptions;
 declare function exportRunTree(tree: InspectRunTree, options: ExportOptions): ExportResult;
 declare function validateExport(result: ExportResult): ExportValidationResult;
 
-export { type ActiveStepContext, type AttributionConfidence, DEFAULT_LOG_INGEST_CONFIG, DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, DEFAULT_REDACT_KEYS, DEFAULT_TRACE_DIR_NAME, type DiffKind, type DiffOptions, type DiffPath, type DiffPathSegment, type DiffSeverity, EXPORT_PAYLOAD_VERSION, type ErrorInfo, EventNormalizer, type EventSource, type ExecutionContext, type ExportFormat, type ExportOptions, type ExportResult, type ExportValidationResult, FALLBACK_TRACE_DIR, type InspectEvent, type InspectKind, type InspectNode, type InspectRunOptions, type InspectRunTree, JsonLogParser, LiveLogAccumulator, type LiveLogAccumulatorOptions, type LiveLogUpdate, Log4jsParser, type LogEventMapping, type LogIngestConfig, type LogSourceFormat, type LogToTreeResult, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type NormalizeOptions, type ObserveOptions, type OpenInferenceExport, type OpenInferenceSpan, type ParseLogLineOptions, type ParseLogsOptions, type ParseResult, type ParserWarning, type ParserWarningCode, RUNS_DIR_NAME, type RawLogRecord, type RedactionRule, type RedactionStrategy, Redactor, type RedactorOptions, type RenderDiffOptions, type RenderTreeOptions, type Run, type RunComparable, type RunCompletedEvent, type RunDiffItem, type RunDiffResult, type RunDiffSummary, type RunStartedEvent, type RunStatus, type RunSummary, type Step, type StepComparable, type StepCompletedEvent, type StepMetadata, type StepOptions, type StepStartedEvent, type StepStatus, type StepType, TERMINAL_INDENT, type TokenMetadata, TraceDirectory, type TraceDirectoryOptions, type TraceEvent, type TraceEventBase, type TraceExporter, type TraceFilterOptions, type TraceMetadata, type TraceMetadataStatus, type TraceSafetyOptions, type TraceSchemaVersion, TreeBuilder, type TreeBuilderOptions, buildRunSummary, compactAttributes, createRunId, createStepId, diffRuns, diffTraceEvents, ensureTraceDir, escapeHtml, escapeMarkdown, exportHtml, exportMarkdown, exportOpenInference, exportOtlpJson, exportRunTree, extractMetadata, filterTraces, flattenTree, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getRunIdFromTraceFileName, getTraceDirFromContext, getTraceFilePath, getTraceSafetyFromContext, hasActiveContext, initializeTraceFile, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, loadLogIngestConfig, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, maybeInspectRun, mergeExportDefaults, mergeLogIngestConfig, observe, parseDuration, parseLogLine, parseLogsToTrees, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, resolveTraceDir, resolveTraceSafetyOptions, runWithContext, runWithStepContext, safeString, serializeEvent, stableJson, step, summarizeTree, truncateName, validateEvent, validateExport, validateExportContent, warn, wildcardMatch, writeTraceEvent };
+export { type ActiveStepContext, type AttributionConfidence, DEFAULT_LOG_INGEST_CONFIG, DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, DEFAULT_REDACT_KEYS, DEFAULT_TRACE_DIR_NAME, type DiffKind, type DiffOptions, type DiffPath, type DiffPathSegment, type DiffSeverity, EXPORT_PAYLOAD_VERSION, type ErrorInfo, EventNormalizer, type EventSource, type ExecutionContext, type ExportFormat, type ExportOptions, type ExportResult, type ExportValidationResult, FALLBACK_TRACE_DIR, type InspectEvent, type InspectEventToPersistedOptions, type InspectKind, type InspectNode, type InspectRunOptions, type InspectRunTree, JsonLogParser, LiveLogAccumulator, type LiveLogAccumulatorOptions, type LiveLogUpdate, Log4jsParser, type LogEventMapping, type LogIngestConfig, type LogSourceFormat, type LogToTreeResult, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type NormalizeOptions, type ObserveOptions, type OpenInferenceExport, type OpenInferenceSpan, type ParseLogLineOptions, type ParseLogsOptions, type ParseResult, type ParserWarning, type ParserWarningCode, type PersistedEventSource, type PersistedEventSourceType, type PersistedEventStatus, type PersistedInspectError, type PersistedInspectEvent, type PersistedSchemaVersion, type PersistedToInspectEventOptions, type PersistedTokenUsage, type PersistedTraceContext, type PersistedTreeBridgeOptions, RUNS_DIR_NAME, type RawLogRecord, type RedactionProfile, type RedactionRule, type RedactionStrategy, Redactor, type RedactorOptions, type RenderDiffOptions, type RenderTreeOptions, type ResolvedRedactionProfile, type Run, type RunComparable, type RunCompletedEvent, type RunDiffItem, type RunDiffResult, type RunDiffSummary, type RunStartedEvent, type RunStatus, type RunSummary, type Step, type StepComparable, type StepCompletedEvent, type StepMetadata, type StepOptions, type StepStartedEvent, type StepStatus, type StepType, TERMINAL_INDENT, type TokenMetadata, type TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, type TraceEvent, type TraceEventBase, type TraceEventToPersistedOptions, type TraceExporter, type TraceFilterOptions, type TraceMetadata, type TraceMetadataStatus, type TraceSafetyOptions, type TraceSchemaVersion, TreeBuilder, type TreeBuilderOptions, buildRunSummary, compactAttributes, createRunId, createStepId, diffRuns, diffTraceEvents, ensureTraceDir, escapeHtml, escapeMarkdown, exportHtml, exportMarkdown, exportOpenInference, exportOtlpJson, exportRunTree, extractMetadata, filterTraces, flattenTree, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getRunIdFromTraceFileName, getTraceDirFromContext, getTraceFilePath, getTraceSafetyFromContext, hasActiveContext, initializeTraceFile, inspectEventToPersistedInspectEvent, inspectEventsToPersistedInspectEvents, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, isPersistedInspectEvent, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, loadLogIngestConfig, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, maybeInspectRun, mergeExportDefaults, mergeLogIngestConfig, observe, parseDuration, parseLogLine, parseLogsToTrees, persistedInspectEventToInspectEvent, persistedInspectEventsToInspectEvents, persistedInspectEventsToRunTrees, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, redactRunTreeForExport, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, resolveRedactionProfile, resolveTraceDir, resolveTraceSafetyOptions, runWithContext, runWithStepContext, safeString, serializeEvent, stableJson, step, summarizeTree, traceEventToPersistedInspectEvent, traceEventsToPersistedInspectEvents, traceEventsToPersistedRunTrees, truncateName, validateEvent, validateExport, validateExportContent, warn, wildcardMatch, writeTraceEvent };

package/packages/core/dist/index.d.ts

@@ -220,8 +220,17 @@ interface StepCompletedEvent extends TraceEventBase {
 }
 /** Discriminated union of all MVP trace events written as JSONL lines. */
 type TraceEvent = RunStartedEvent | RunCompletedEvent | StepStartedEvent | StepCompletedEvent;
+/** Named redaction presets for trace writing and share-safe exports (v1.3.0+). */
+type RedactionProfile = "local" | "share" | "strict";
+/** Optional correlation fields for grouping and cross-run tracing (v1.3.0+). */
+interface TraceCorrelationMetadata {
+    correlationId?: string;
+    requestId?: string;
+    decisionId?: string;
+    groupId?: string;
+}
 /** Options for `inspectRun()` and `maybeInspectRun()`. */
-interface InspectRunOptions {
+interface InspectRunOptions extends TraceCorrelationMetadata {
     traceDir?: string;
     silent?: boolean;
     metadata?: Record<string, unknown>;
@@ -237,6 +246,12 @@ interface InspectRunOptions {
     redact?: boolean | {
         rules?: RedactionRule[];
     };
+    /**
+     * Redaction preset for trace metadata. Default `local` (same keys as default redaction).
+     * `share` and `strict` add extra key-based redaction and tighter string bounds.
+     * Ignored when `redact: false`.
+     */
+    redactionProfile?: RedactionProfile;
     /** Max UTF-8 bytes for a serialized trace event line. Default 65536. */
     maxEventBytes?: number;
     /** Max length for string metadata values (non-preview keys). Default 2000. */
@@ -278,6 +293,145 @@ declare function isStepStatus(value: unknown): value is StepStatus;
  */
 declare function isTraceEvent(value: unknown): value is TraceEvent;
 
+type PersistedSchemaVersion = "0.2";
+type PersistedEventSourceType = "manual" | "json-log" | "log4js" | "adapter" | "ai-sdk" | "otel";
+interface PersistedEventSource {
+    type: PersistedEventSourceType;
+    name?: string;
+    version?: string;
+}
+type PersistedEventStatus = "running" | "ok" | "error" | "unknown";
+interface PersistedInspectError {
+    name?: string;
+    message: string;
+    code?: string;
+}
+interface PersistedTokenUsage {
+    input?: number;
+    output?: number;
+    total?: number;
+}
+interface PersistedTraceContext {
+    traceId?: string;
+    spanId?: string;
+    parentSpanId?: string;
+}
+interface PersistedInspectEvent {
+    schemaVersion: PersistedSchemaVersion;
+    eventId: string;
+    runId: string;
+    parentId?: string;
+    kind: InspectKind;
+    name: string;
+    status?: PersistedEventStatus;
+    timestamp: string;
+    startedAt?: string;
+    endedAt?: string;
+    durationMs?: number;
+    confidence: AttributionConfidence;
+    source: PersistedEventSource;
+    attributes?: Record<string, unknown>;
+    inputSummary?: unknown;
+    outputSummary?: unknown;
+    error?: PersistedInspectError;
+    tokenUsage?: PersistedTokenUsage;
+    trace?: PersistedTraceContext;
+}
+/**
+ * Runtime guard for a v0.2 {@link PersistedInspectEvent} JSON object.
+ *
+ * Timestamp fields (`timestamp`, `startedAt`, `endedAt`) are validated as
+ * non-empty strings only — stricter ISO-8601 parsing may be added later.
+ */
+declare function isPersistedInspectEvent(value: unknown): value is PersistedInspectEvent;
+
+interface TraceEventToPersistedOptions {
+    /**
+     * Stable index within the source event list.
+     * Used only to make synthetic eventId deterministic when v0.1 has no eventId.
+     */
+    eventIndex?: number;
+    /**
+     * Optional source name override.
+     * Default: "trace-event"
+     */
+    sourceName?: string;
+    /**
+     * Optional source version override.
+     * Default: "0.1"
+     */
+    sourceVersion?: string;
+}
+/**
+ * Maps one v0.1 {@link TraceEvent} to a v0.2 {@link PersistedInspectEvent}.
+ * Does not mutate `event`.
+ */
+declare function traceEventToPersistedInspectEvent(event: TraceEvent, options?: TraceEventToPersistedOptions): PersistedInspectEvent;
+/**
+ * Maps a v0.1 trace event list to persisted v0.2 events (one output per input).
+ */
+declare function traceEventsToPersistedInspectEvents(events: readonly TraceEvent[], options?: Omit<TraceEventToPersistedOptions, "eventIndex">): PersistedInspectEvent[];
+
+interface InspectEventToPersistedOptions {
+    /**
+     * Optional source name override.
+     * If omitted, derived from event.source.type.
+     */
+    sourceName?: string;
+    /**
+     * Optional source version override.
+     */
+    sourceVersion?: string;
+    /**
+     * Stable index for deterministic fallback IDs if needed.
+     */
+    eventIndex?: number;
+}
+/**
+ * Maps one in-memory {@link InspectEvent} to a v0.2 {@link PersistedInspectEvent}.
+ * Does not mutate `event`.
+ */
+declare function inspectEventToPersistedInspectEvent(event: InspectEvent, options?: InspectEventToPersistedOptions): PersistedInspectEvent;
+/**
+ * Maps in-memory {@link InspectEvent} rows to persisted v0.2 events.
+ */
+declare function inspectEventsToPersistedInspectEvents(events: readonly InspectEvent[], options?: Omit<InspectEventToPersistedOptions, "eventIndex">): PersistedInspectEvent[];
+
+interface PersistedToInspectEventOptions {
+    /**
+     * If true, invalid persisted events are skipped by batch conversion.
+     * If false or omitted, invalid events throw.
+     */
+    skipInvalid?: boolean;
+}
+/**
+ * Maps one v0.2 {@link PersistedInspectEvent} to in-memory {@link InspectEvent}.
+ * Throws if `event` fails {@link isPersistedInspectEvent}.
+ */
+declare function persistedInspectEventToInspectEvent(event: PersistedInspectEvent): InspectEvent;
+/**
+ * Maps persisted v0.2 events to in-memory {@link InspectEvent} rows.
+ */
+declare function persistedInspectEventsToInspectEvents(events: readonly PersistedInspectEvent[], options?: PersistedToInspectEventOptions): InspectEvent[];
+
+interface PersistedTreeBridgeOptions {
+    /**
+     * If true, invalid persisted events are skipped.
+     * If false or omitted, invalid persisted events throw.
+     */
+    skipInvalid?: boolean;
+}
+/**
+ * Builds {@link InspectRunTree} rows from v0.2 {@link PersistedInspectEvent} input.
+ * Uses {@link TreeBuilder} as the canonical tree builder. Does not mutate `events`.
+ */
+declare function persistedInspectEventsToRunTrees(events: readonly PersistedInspectEvent[], options?: PersistedTreeBridgeOptions): InspectRunTree[];
+/**
+ * Builds {@link InspectRunTree} rows from legacy v0.1 {@link TraceEvent} input
+ * via the persisted-event model. Does not mutate `events`.
+ */
+declare function traceEventsToPersistedRunTrees(events: readonly TraceEvent[]): InspectRunTree[];
+
 type ParserWarningCode = "MALFORMED_JSON" | "MISSING_RUN_ID" | "MISSING_EVENT" | "MISSING_TIMESTAMP" | "UNSUPPORTED_LOG4JS_PAYLOAD" | "CONFIG_ERROR" | "UNKNOWN";
 interface ParserWarning {
     code: ParserWarningCode;
@@ -318,6 +472,8 @@ declare function matchMapping(eventName: string, mappings?: Record<string, LogEv
 declare const DEFAULT_REDACT_KEYS: readonly ["authorization", "cookie", "token", "apiKey", "password", "secret", "email"];
 interface RedactorOptions {
     rules?: RedactionRule[];
+    /** Additional exact keys (case-insensitive) to redact in addition to defaults. */
+    extraKeys?: readonly string[];
 }
 declare class Redactor {
     #private;
@@ -460,6 +616,15 @@ declare function truncateName(name: string, maxLength?: number): string;
  */
 declare function warn(message: string, error?: unknown): void;
 
+interface ResolvedRedactionProfile {
+    profile: RedactionProfile;
+    extraKeys: readonly string[];
+    maxMetadataValueLengthCap?: number;
+    maxPreviewLengthCap?: number;
+}
+/** Resolves named profile behavior (keys + metadata string caps). */
+declare function resolveRedactionProfile(profile?: RedactionProfile): ResolvedRedactionProfile;
+
 /** Default max length for string metadata values (non-preview keys). */
 declare const DEFAULT_MAX_METADATA_VALUE_LENGTH = 2000;
 /** Default max length for preview-like metadata keys (contains `preview`, case-insensitive). */
@@ -470,12 +635,15 @@ declare const DEFAULT_MAX_EVENT_BYTES = 65536;
 interface TraceSafetyOptions {
     redactEnabled: boolean;
     redactionRules?: RedactionRule[];
+    redactionProfile: RedactionProfile;
+    profileExtraKeys: readonly string[];
     maxMetadataValueLength: number;
     maxPreviewLength: number;
     maxEventBytes: number;
 }
+
 /** Resolves {@link InspectRunOptions} trace safety fields with safe defaults. */
-declare function resolveTraceSafetyOptions(options?: Pick<InspectRunOptions, "redact" | "maxEventBytes" | "maxMetadataValueLength" | "maxPreviewLength">): TraceSafetyOptions;
+declare function resolveTraceSafetyOptions(options?: Pick<InspectRunOptions, "redact" | "redactionProfile" | "maxEventBytes" | "maxMetadataValueLength" | "maxPreviewLength">): TraceSafetyOptions;
 /** Redacts (when enabled) and truncates metadata values for disk persistence. */
 declare function prepareMetadataForDisk(metadata: Record<string, unknown> | StepMetadata, opts: TraceSafetyOptions): Record<string, unknown>;
 /**
@@ -488,6 +656,11 @@ declare function prepareTraceEventForDisk(event: TraceEvent, opts: TraceSafetyOp
 declare function getCurrentContext(): ExecutionContext | undefined;
 /** Active `runId` when inside `runWithContext`, else `undefined`. */
 declare function getCurrentRunId(): string | undefined;
+/**
+ * Correlation metadata for the active run (`correlationId`, `requestId`, `decisionId`, `groupId`).
+ * `undefined` outside `inspectRun` / `maybeInspectRun` or when no correlation fields were set.
+ */
+declare function getCurrentCorrelationMetadata(): TraceCorrelationMetadata | undefined;
 /** Active `runName` when inside `runWithContext`, else `undefined`. */
 declare function getCurrentRunName(): string | undefined;
 /**
@@ -748,6 +921,11 @@ interface ExportOptions {
     pretty?: boolean;
     redacted?: boolean;
     maxAttributeLength?: number;
+    /**
+     * Redaction preset for exported copies. Default `local`.
+     * `share` and `strict` apply stronger key-based redaction before rendering.
+     */
+    redactionProfile?: RedactionProfile;
 }
 interface ExportResult {
     format: ExportFormat;
@@ -822,6 +1000,15 @@ declare function exportOtlpJson(tree: InspectRunTree, options?: Partial<ExportOp
 
 declare function validateExportContent(format: ExportFormat, content: string): ExportValidationResult;
 
+interface RedactRunTreeForExportOptions {
+    redactionProfile?: RedactionProfile;
+}
+/**
+ * Returns a deep copy of `tree` with profile-based redaction applied to event attributes.
+ * Does not mutate the input tree.
+ */
+declare function redactRunTreeForExport(tree: InspectRunTree, options?: RedactRunTreeForExportOptions): InspectRunTree;
+
 declare function mergeExportDefaults(options: ExportOptions): ExportOptions;
 /**
  * @experimental Compatibility-oriented export API. Exports are local-only and do not upload anywhere.
@@ -830,4 +1017,4 @@ declare function mergeExportDefaults(options: ExportOptions): ExportOptions;
 declare function exportRunTree(tree: InspectRunTree, options: ExportOptions): ExportResult;
 declare function validateExport(result: ExportResult): ExportValidationResult;
 
-export { type ActiveStepContext, type AttributionConfidence, DEFAULT_LOG_INGEST_CONFIG, DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, DEFAULT_REDACT_KEYS, DEFAULT_TRACE_DIR_NAME, type DiffKind, type DiffOptions, type DiffPath, type DiffPathSegment, type DiffSeverity, EXPORT_PAYLOAD_VERSION, type ErrorInfo, EventNormalizer, type EventSource, type ExecutionContext, type ExportFormat, type ExportOptions, type ExportResult, type ExportValidationResult, FALLBACK_TRACE_DIR, type InspectEvent, type InspectKind, type InspectNode, type InspectRunOptions, type InspectRunTree, JsonLogParser, LiveLogAccumulator, type LiveLogAccumulatorOptions, type LiveLogUpdate, Log4jsParser, type LogEventMapping, type LogIngestConfig, type LogSourceFormat, type LogToTreeResult, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type NormalizeOptions, type ObserveOptions, type OpenInferenceExport, type OpenInferenceSpan, type ParseLogLineOptions, type ParseLogsOptions, type ParseResult, type ParserWarning, type ParserWarningCode, RUNS_DIR_NAME, type RawLogRecord, type RedactionRule, type RedactionStrategy, Redactor, type RedactorOptions, type RenderDiffOptions, type RenderTreeOptions, type Run, type RunComparable, type RunCompletedEvent, type RunDiffItem, type RunDiffResult, type RunDiffSummary, type RunStartedEvent, type RunStatus, type RunSummary, type Step, type StepComparable, type StepCompletedEvent, type StepMetadata, type StepOptions, type StepStartedEvent, type StepStatus, type StepType, TERMINAL_INDENT, type TokenMetadata, TraceDirectory, type TraceDirectoryOptions, type TraceEvent, type TraceEventBase, type TraceExporter, type TraceFilterOptions, type TraceMetadata, type TraceMetadataStatus, type TraceSafetyOptions, type TraceSchemaVersion, TreeBuilder, type TreeBuilderOptions, buildRunSummary, compactAttributes, createRunId, createStepId, diffRuns, diffTraceEvents, ensureTraceDir, escapeHtml, escapeMarkdown, exportHtml, exportMarkdown, exportOpenInference, exportOtlpJson, exportRunTree, extractMetadata, filterTraces, flattenTree, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getRunIdFromTraceFileName, getTraceDirFromContext, getTraceFilePath, getTraceSafetyFromContext, hasActiveContext, initializeTraceFile, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, loadLogIngestConfig, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, maybeInspectRun, mergeExportDefaults, mergeLogIngestConfig, observe, parseDuration, parseLogLine, parseLogsToTrees, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, resolveTraceDir, resolveTraceSafetyOptions, runWithContext, runWithStepContext, safeString, serializeEvent, stableJson, step, summarizeTree, truncateName, validateEvent, validateExport, validateExportContent, warn, wildcardMatch, writeTraceEvent };
+export { type ActiveStepContext, type AttributionConfidence, DEFAULT_LOG_INGEST_CONFIG, DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, DEFAULT_REDACT_KEYS, DEFAULT_TRACE_DIR_NAME, type DiffKind, type DiffOptions, type DiffPath, type DiffPathSegment, type DiffSeverity, EXPORT_PAYLOAD_VERSION, type ErrorInfo, EventNormalizer, type EventSource, type ExecutionContext, type ExportFormat, type ExportOptions, type ExportResult, type ExportValidationResult, FALLBACK_TRACE_DIR, type InspectEvent, type InspectEventToPersistedOptions, type InspectKind, type InspectNode, type InspectRunOptions, type InspectRunTree, JsonLogParser, LiveLogAccumulator, type LiveLogAccumulatorOptions, type LiveLogUpdate, Log4jsParser, type LogEventMapping, type LogIngestConfig, type LogSourceFormat, type LogToTreeResult, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type NormalizeOptions, type ObserveOptions, type OpenInferenceExport, type OpenInferenceSpan, type ParseLogLineOptions, type ParseLogsOptions, type ParseResult, type ParserWarning, type ParserWarningCode, type PersistedEventSource, type PersistedEventSourceType, type PersistedEventStatus, type PersistedInspectError, type PersistedInspectEvent, type PersistedSchemaVersion, type PersistedToInspectEventOptions, type PersistedTokenUsage, type PersistedTraceContext, type PersistedTreeBridgeOptions, RUNS_DIR_NAME, type RawLogRecord, type RedactionProfile, type RedactionRule, type RedactionStrategy, Redactor, type RedactorOptions, type RenderDiffOptions, type RenderTreeOptions, type ResolvedRedactionProfile, type Run, type RunComparable, type RunCompletedEvent, type RunDiffItem, type RunDiffResult, type RunDiffSummary, type RunStartedEvent, type RunStatus, type RunSummary, type Step, type StepComparable, type StepCompletedEvent, type StepMetadata, type StepOptions, type StepStartedEvent, type StepStatus, type StepType, TERMINAL_INDENT, type TokenMetadata, type TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, type TraceEvent, type TraceEventBase, type TraceEventToPersistedOptions, type TraceExporter, type TraceFilterOptions, type TraceMetadata, type TraceMetadataStatus, type TraceSafetyOptions, type TraceSchemaVersion, TreeBuilder, type TreeBuilderOptions, buildRunSummary, compactAttributes, createRunId, createStepId, diffRuns, diffTraceEvents, ensureTraceDir, escapeHtml, escapeMarkdown, exportHtml, exportMarkdown, exportOpenInference, exportOtlpJson, exportRunTree, extractMetadata, filterTraces, flattenTree, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getRunIdFromTraceFileName, getTraceDirFromContext, getTraceFilePath, getTraceSafetyFromContext, hasActiveContext, initializeTraceFile, inspectEventToPersistedInspectEvent, inspectEventsToPersistedInspectEvents, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, isPersistedInspectEvent, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, loadLogIngestConfig, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, maybeInspectRun, mergeExportDefaults, mergeLogIngestConfig, observe, parseDuration, parseLogLine, parseLogsToTrees, persistedInspectEventToInspectEvent, persistedInspectEventsToInspectEvents, persistedInspectEventsToRunTrees, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, redactRunTreeForExport, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, resolveRedactionProfile, resolveTraceDir, resolveTraceSafetyOptions, runWithContext, runWithStepContext, safeString, serializeEvent, stableJson, step, summarizeTree, traceEventToPersistedInspectEvent, traceEventsToPersistedInspectEvents, traceEventsToPersistedRunTrees, truncateName, validateEvent, validateExport, validateExportContent, warn, wildcardMatch, writeTraceEvent };