agent-inspect 1.2.0 → 1.4.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. */
@@ -457,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;
@@ -599,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). */
@@ -609,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>;
 /**
@@ -627,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;
 /**
@@ -705,6 +739,131 @@ interface TraceFilterOptions {
 }
 declare function filterTraces(traces: TraceMetadata[], options: TraceFilterOptions): TraceMetadata[];
 
+type TimelineFocus = "all" | "slow";
+interface TimelineEntry {
+    stepId: string;
+    name: string;
+    type: StepType;
+    status: StepStatus;
+    depth: number;
+    startedAt: number;
+    offsetMs: number;
+    durationMs?: number;
+    isError: boolean;
+    slow?: boolean;
+    streaming?: {
+        chunkCount?: number;
+        streamDurationMs?: number;
+        streamedCharCount?: number;
+    };
+}
+interface RunTimeline {
+    runId: string;
+    name?: string;
+    status: TraceMetadataStatus;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    correlation?: {
+        correlationId?: string;
+        requestId?: string;
+        decisionId?: string;
+        groupId?: string;
+    };
+    entries: TimelineEntry[];
+}
+interface TimelineOptions {
+    focus?: TimelineFocus;
+    slowTopN?: number;
+}
+declare function buildRunTimeline(events: TraceEvent[], options?: TimelineOptions): RunTimeline;
+interface RenderTimelineOptions {
+    focus?: TimelineFocus;
+}
+declare function renderTimeline(timeline: RunTimeline, options?: RenderTimelineOptions): string;
+
+interface DurationStats {
+    minMs?: number;
+    maxMs?: number;
+    avgMs?: number;
+    p50Ms?: number;
+    p95Ms?: number;
+}
+interface TraceStatsRankedRun {
+    runId: string;
+    name?: string;
+    durationMs?: number;
+    status: string;
+}
+interface TraceStatsRankedStep {
+    runId: string;
+    stepName: string;
+    stepType: string;
+    durationMs: number;
+}
+interface TraceStats {
+    traceDir: string;
+    since?: string;
+    correlationId?: string;
+    groupId?: string;
+    totalRuns: number;
+    successCount: number;
+    errorCount: number;
+    runningCount: number;
+    unknownCount: number;
+    errorRate: number;
+    duration: DurationStats;
+    totalSteps: number;
+    avgStepsPerRun: number;
+    totalLlmSteps: number;
+    totalToolSteps: number;
+    totalErrorSteps: number;
+    slowestRuns: TraceStatsRankedRun[];
+    slowestSteps: TraceStatsRankedStep[];
+}
+interface TraceStatsOptions {
+    traceDir: string;
+    since?: string;
+    correlationId?: string;
+    groupId?: string;
+    slowRunLimit?: number;
+    slowStepLimit?: number;
+}
+declare function buildTraceStats(metas: TraceMetadata[], options: TraceStatsOptions): Promise<TraceStats>;
+declare function renderTraceStats(stats: TraceStats): string;
+
+interface TraceSearchOptions {
+    traceDir: string;
+    since?: string;
+    status?: "success" | "error" | "running" | "unknown";
+    kind?: string;
+    type?: string;
+    name?: string;
+    tool?: string;
+    duration?: string;
+    limit?: number;
+}
+interface TraceSearchResult {
+    runId: string;
+    runName?: string;
+    runStatus: string;
+    stepId?: string;
+    stepName?: string;
+    stepType?: string;
+    timestamp?: number;
+    durationMs?: number;
+    matchReason: string;
+    matchedFields: string[];
+    filePath: string;
+}
+interface ParsedDurationFilter {
+    op: ">" | ">=" | "<" | "<=";
+    ms: number;
+}
+declare function parseDurationFilter(expr: string): ParsedDurationFilter;
+declare function searchTraces(metas: TraceMetadata[], options: TraceSearchOptions): Promise<TraceSearchResult[]>;
+declare function loadTraceMetadataList(_traceDir: string, fileNames: string[], getPath: (fileName: string) => string): Promise<TraceMetadata[]>;
+
 /**
  * Safety check for cleanup workflows: returns true only when the file appears to be an AgentInspect trace.
  * This should be conservative: false positives are more dangerous than false negatives.
@@ -887,6 +1046,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;
@@ -961,6 +1125,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.
@@ -969,4 +1142,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 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 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 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, 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, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, resolveTraceDir, resolveTraceSafetyOptions, runWithContext, runWithStepContext, safeString, serializeEvent, stableJson, step, summarizeTree, traceEventToPersistedInspectEvent, traceEventsToPersistedInspectEvents, traceEventsToPersistedRunTrees, 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, type DurationStats, 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 ParsedDurationFilter, 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 RenderTimelineOptions, type RenderTreeOptions, type ResolvedRedactionProfile, type Run, type RunComparable, type RunCompletedEvent, type RunDiffItem, type RunDiffResult, type RunDiffSummary, type RunStartedEvent, type RunStatus, type RunSummary, type RunTimeline, type Step, type StepComparable, type StepCompletedEvent, type StepMetadata, type StepOptions, type StepStartedEvent, type StepStatus, type StepType, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, 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, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, TreeBuilder, type TreeBuilderOptions, buildRunSummary, buildRunTimeline, buildTraceStats, 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, loadTraceMetadataList, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, maybeInspectRun, mergeExportDefaults, mergeLogIngestConfig, observe, parseDuration, parseDurationFilter, parseLogLine, parseLogsToTrees, persistedInspectEventToInspectEvent, persistedInspectEventsToInspectEvents, persistedInspectEventsToRunTrees, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, redactRunTreeForExport, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, resolveTraceSafetyOptions, runWithContext, runWithStepContext, safeString, searchTraces, 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. */
@@ -457,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;
@@ -599,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). */
@@ -609,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>;
 /**
@@ -627,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;
 /**
@@ -705,6 +739,131 @@ interface TraceFilterOptions {
 }
 declare function filterTraces(traces: TraceMetadata[], options: TraceFilterOptions): TraceMetadata[];
 
+type TimelineFocus = "all" | "slow";
+interface TimelineEntry {
+    stepId: string;
+    name: string;
+    type: StepType;
+    status: StepStatus;
+    depth: number;
+    startedAt: number;
+    offsetMs: number;
+    durationMs?: number;
+    isError: boolean;
+    slow?: boolean;
+    streaming?: {
+        chunkCount?: number;
+        streamDurationMs?: number;
+        streamedCharCount?: number;
+    };
+}
+interface RunTimeline {
+    runId: string;
+    name?: string;
+    status: TraceMetadataStatus;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    correlation?: {
+        correlationId?: string;
+        requestId?: string;
+        decisionId?: string;
+        groupId?: string;
+    };
+    entries: TimelineEntry[];
+}
+interface TimelineOptions {
+    focus?: TimelineFocus;
+    slowTopN?: number;
+}
+declare function buildRunTimeline(events: TraceEvent[], options?: TimelineOptions): RunTimeline;
+interface RenderTimelineOptions {
+    focus?: TimelineFocus;
+}
+declare function renderTimeline(timeline: RunTimeline, options?: RenderTimelineOptions): string;
+
+interface DurationStats {
+    minMs?: number;
+    maxMs?: number;
+    avgMs?: number;
+    p50Ms?: number;
+    p95Ms?: number;
+}
+interface TraceStatsRankedRun {
+    runId: string;
+    name?: string;
+    durationMs?: number;
+    status: string;
+}
+interface TraceStatsRankedStep {
+    runId: string;
+    stepName: string;
+    stepType: string;
+    durationMs: number;
+}
+interface TraceStats {
+    traceDir: string;
+    since?: string;
+    correlationId?: string;
+    groupId?: string;
+    totalRuns: number;
+    successCount: number;
+    errorCount: number;
+    runningCount: number;
+    unknownCount: number;
+    errorRate: number;
+    duration: DurationStats;
+    totalSteps: number;
+    avgStepsPerRun: number;
+    totalLlmSteps: number;
+    totalToolSteps: number;
+    totalErrorSteps: number;
+    slowestRuns: TraceStatsRankedRun[];
+    slowestSteps: TraceStatsRankedStep[];
+}
+interface TraceStatsOptions {
+    traceDir: string;
+    since?: string;
+    correlationId?: string;
+    groupId?: string;
+    slowRunLimit?: number;
+    slowStepLimit?: number;
+}
+declare function buildTraceStats(metas: TraceMetadata[], options: TraceStatsOptions): Promise<TraceStats>;
+declare function renderTraceStats(stats: TraceStats): string;
+
+interface TraceSearchOptions {
+    traceDir: string;
+    since?: string;
+    status?: "success" | "error" | "running" | "unknown";
+    kind?: string;
+    type?: string;
+    name?: string;
+    tool?: string;
+    duration?: string;
+    limit?: number;
+}
+interface TraceSearchResult {
+    runId: string;
+    runName?: string;
+    runStatus: string;
+    stepId?: string;
+    stepName?: string;
+    stepType?: string;
+    timestamp?: number;
+    durationMs?: number;
+    matchReason: string;
+    matchedFields: string[];
+    filePath: string;
+}
+interface ParsedDurationFilter {
+    op: ">" | ">=" | "<" | "<=";
+    ms: number;
+}
+declare function parseDurationFilter(expr: string): ParsedDurationFilter;
+declare function searchTraces(metas: TraceMetadata[], options: TraceSearchOptions): Promise<TraceSearchResult[]>;
+declare function loadTraceMetadataList(_traceDir: string, fileNames: string[], getPath: (fileName: string) => string): Promise<TraceMetadata[]>;
+
 /**
  * Safety check for cleanup workflows: returns true only when the file appears to be an AgentInspect trace.
  * This should be conservative: false positives are more dangerous than false negatives.
@@ -887,6 +1046,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;
@@ -961,6 +1125,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.
@@ -969,4 +1142,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 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 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 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, 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, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, resolveTraceDir, resolveTraceSafetyOptions, runWithContext, runWithStepContext, safeString, serializeEvent, stableJson, step, summarizeTree, traceEventToPersistedInspectEvent, traceEventsToPersistedInspectEvents, traceEventsToPersistedRunTrees, 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, type DurationStats, 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 ParsedDurationFilter, 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 RenderTimelineOptions, type RenderTreeOptions, type ResolvedRedactionProfile, type Run, type RunComparable, type RunCompletedEvent, type RunDiffItem, type RunDiffResult, type RunDiffSummary, type RunStartedEvent, type RunStatus, type RunSummary, type RunTimeline, type Step, type StepComparable, type StepCompletedEvent, type StepMetadata, type StepOptions, type StepStartedEvent, type StepStatus, type StepType, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, 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, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, TreeBuilder, type TreeBuilderOptions, buildRunSummary, buildRunTimeline, buildTraceStats, 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, loadTraceMetadataList, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, maybeInspectRun, mergeExportDefaults, mergeLogIngestConfig, observe, parseDuration, parseDurationFilter, parseLogLine, parseLogsToTrees, persistedInspectEventToInspectEvent, persistedInspectEventsToInspectEvents, persistedInspectEventsToRunTrees, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, redactRunTreeForExport, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, resolveTraceSafetyOptions, runWithContext, runWithStepContext, safeString, searchTraces, serializeEvent, stableJson, step, summarizeTree, traceEventToPersistedInspectEvent, traceEventsToPersistedInspectEvents, traceEventsToPersistedRunTrees, truncateName, validateEvent, validateExport, validateExportContent, warn, wildcardMatch, writeTraceEvent };