agent-inspect 1.9.0 → 2.0.0

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

@@ -1,8 +1,50 @@
-import { E as ErrorInfo, e as RedactionProfile, n as StepMetadata, T as TraceEvent, I as InspectRunOptions, g as ExecutionContext, d as TraceCorrelationMetadata, S as StepType, k as RunStatus, c as StepStatus } from './types-B2-BU5CS.cjs';
-import { R as RedactionRule } from './log-config-DanPV3P9.cjs';
-import { P as PersistedInspectEvent } from './persisted-inspect-event-DHPfzUd8.cjs';
-import { TraceWriterStats, TraceWriter } from './writers.cjs';
-import './inspect-event-CevRYp58.cjs';
+export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-CSKnzpXR.cjs';
+import { R as RedactionProfile, E as ErrorInfo, b as RunStatus, e as StepStatus, h as TraceEvent, j as RunSummary, k as TraceMetadata, l as TraceMetadataStatus, f as StepType, g as TraceCorrelationMetadata } from './types-DgMN3qow.cjs';
+export { A as ActiveStepContext, i as ExecutionContext, I as InspectRunOptions, O as ObserveOptions, a as Run, m as RunCompletedEvent, n as RunStartedEvent, c as Step, o as StepCompletedEvent, d as StepMetadata, S as StepOptions, p as StepStartedEvent, T as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-DgMN3qow.cjs';
+import { a as InspectRunTree } from './inspect-event-CevRYp58.cjs';
+export { A as AttributionConfidence, E as EventSource, c as InspectEvent, I as InspectKind, b as InspectNode } from './inspect-event-CevRYp58.cjs';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-DHcHPUKv.cjs';
+import { Stats } from 'node:fs';
+import './writers.cjs';
+import './log-config-8aE5Kxtr.cjs';
+
+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;
+
+/** Two spaces per nesting level in terminal output. */
+declare const TERMINAL_INDENT = "  ";
+/** Max display length for names in terminal output. */
+declare const MAX_TERMINAL_NAME_LENGTH = 80;
+/** Max nesting depth used for indentation (prevents huge indents). */
+declare const MAX_TERMINAL_DEPTH = 10;
+/** Indentation string for a nesting depth (capped, never negative). */
+declare function getIndent(depth: number): string;
+/** Truncates a display name for terminal use; invalid input becomes `"unnamed"`. */
+declare function formatTerminalName(name: string): string;
+/** Renders a single step line (colored); does not consult silent mode. */
+declare function renderStepLine(name: string, durationMs: number | undefined, status: StepStatus, depth?: number): string;
+/** Renders an error summary line (no stack in MVP). */
+declare function renderErrorLine(error: ErrorInfo, depth?: number): string;
+/** Plain-text run summary lines (no chalk) for stable testing and CLI reuse. */
+declare function renderRunSummary(durationMs: number, status: RunStatus, traceFilePath?: string): string[];
+/** Prints run header with icon and dim run id. */
+declare function printRunStart(runId: string, name: string): void;
+/** Prints a running step line. */
+declare function printStepStart(name: string, depth?: number): void;
+/** Prints a completed step line with duration and status icon. */
+declare function printStepComplete(name: string, durationMs: number, status: StepStatus, depth?: number): void;
+/** Prints a structured error line (message only, no stack). */
+declare function printError(error: ErrorInfo, depth?: number): void;
+/** Prints run completion summary and optional trace path. */
+declare function printRunComplete(_name: string, _runId: string, durationMs: number, status: RunStatus, traceFilePath?: string): void;
+/** Prints which step failed. */
+declare function printFailedAt(stepName: string): void;
 
 /** Default folder under the user home for AgentInspect data. */
 declare const DEFAULT_TRACE_DIR_NAME = ".agent-inspect";
@@ -55,200 +97,308 @@ 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;
+/**
+ * Strict MVP validation before writing JSONL. Rejects empty ids, non-finite times, and malformed payloads.
+ */
+declare function validateEvent(event: unknown): event is TraceEvent;
+/** Serializes a trace line as compact JSON without a trailing newline. */
+declare function serializeEvent(event: TraceEvent): string;
+/**
+ * Creates (or truncates) an empty JSONL file for a run. Uses {@link ensureTraceDir} then {@link getTraceFilePath}.
+ * On failure, retries once under {@link FALLBACK_TRACE_DIR}.
+ */
+declare function initializeTraceFile(runId: string, traceDir: string): Promise<string | undefined>;
+declare function writeTraceEvent(event: TraceEvent, traceDir: string): Promise<void>;
+/**
+ * Reads raw JSONL file contents for a run, or `undefined` if missing or unreadable.
+ */
+declare function readTraceFile(runId: string, traceDir: string): Promise<string | undefined>;
+/**
+ * Parses JSONL into validated {@link TraceEvent} rows (v0.1 native or v0.2 normalized).
+ * Invalid lines are skipped with a warning.
+ */
+declare function readTraceEvents(runId: string, traceDir: string): Promise<TraceEvent[]>;
+/**
+ * Lists `.jsonl` file names in `traceDir`, newest by mtime first (name sort as tie-breaker).
+ */
+declare function listTraceFiles(traceDir: string): Promise<string[]>;
+/** Maps a `.jsonl` file name to its run id (basename only; no traversal). */
+declare function getRunIdFromTraceFileName(fileName: string): string | undefined;
+
+type TraceJsonlFormat = "0.1" | "0.2" | "1.0" | "mixed" | "empty";
+type ParsedTraceJsonlRow = {
+    format: "0.1";
+    event: TraceEvent;
+    sourceLine: number;
+} | {
+    format: "0.2";
+    event: PersistedInspectEvent;
+    sourceLine: number;
+} | {
+    format: "1.0";
+    event: PersistedInspectEvent;
+    sourceLine: number;
+};
+interface ParseTraceJsonlResult {
+    format: TraceJsonlFormat;
+    /** Count of valid source JSONL rows before any one-to-many normalization. */
+    sourceEventCount: number;
+    events: TraceEvent[];
+    persisted: PersistedInspectEvent[];
+    /** Valid source rows in JSONL order, before cross-version normalization. */
+    rows: ParsedTraceJsonlRow[];
+}
+interface ParseTraceJsonlOptions {
+    validate?: (value: unknown) => value is TraceEvent;
+    /** Emit parse warnings through the standard AgentInspect warning channel (default true). */
+    warnings?: boolean;
+}
+/**
+ * Parses JSONL content into normalized v0.1 {@link TraceEvent} rows.
+ * Accepts homogenous v0.1, v0.2, or v1.0 files; mixed files are converted with a warning.
+ */
+declare function parseTraceJsonl(raw: string, options?: ParseTraceJsonlOptions): ParseTraceJsonlResult;
+/**
+ * Returns a user-facing message when a trace file uses an unsupported schema version.
+ */
+declare function unknownTraceFormatMessage(): string;
+
+interface TraceDirectoryOptions {
+    dir?: string;
+}
+declare function resolveTraceDir(options?: TraceDirectoryOptions): string;
+declare class TraceDirectory {
+    #private;
+    constructor(options?: TraceDirectoryOptions);
+    getPath(filename?: string): string;
+    list(): Promise<string[]>;
+    getFileStats(filename: string): Promise<Stats>;
 }
-/** 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). */
-declare const DEFAULT_MAX_PREVIEW_LENGTH = 500;
-/** Default max serialized JSONL line size in bytes (UTF-8). */
-declare const DEFAULT_MAX_EVENT_BYTES = 65536;
-/** Resolved trace safety settings used at write time. */
-interface TraceSafetyOptions {
-    redactEnabled: boolean;
-    redactionRules?: RedactionRule[];
+declare function extractMetadata(filePath: string, _quickScan?: boolean): Promise<TraceMetadata>;
+declare function buildRunSummary(events: TraceEvent[]): RunSummary;
+
+interface TraceFilterOptions {
+    status?: TraceMetadataStatus;
+    name?: string;
+    since?: string;
+    limit?: number;
+}
+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 RunWhatSummary {
+    runId: string;
+    name?: string;
+    status: TraceMetadataStatus;
+    durationMs?: number;
+    totalSteps: number;
+    llmSteps: number;
+    toolSteps: number;
+    logicSteps: number;
+    errorSteps: number;
+    maxDepth: number;
+    longestStep?: {
+        name: string;
+        durationMs: number;
+        type: string;
+    };
+    totalTokens?: {
+        input: number;
+        output: number;
+        total?: number;
+        cached?: number;
+    };
+    correlation?: TraceCorrelationMetadata;
+    failedStepNames: string[];
+    runErrorMessage?: string;
+}
+/**
+ * Build a concise inspection summary for `what` / report workflows.
+ * Read-only over in-memory v0.1 {@link TraceEvent} rows.
+ */
+declare function buildRunWhatSummary(events: TraceEvent[]): RunWhatSummary;
+interface RenderWhatOptions {
+    /** Include correlation ids when present (default true). */
+    correlation?: boolean;
+}
+/**
+ * Render a human-readable `what` summary (plain text, no ANSI).
+ */
+declare function renderRunWhat(summary: RunWhatSummary, options?: RenderWhatOptions): string;
+
+type ExplainMode = "dry-run" | "local";
+interface ExplainFact {
+    id: string;
+    label: string;
+    value: unknown;
+    source: "trace";
+    confidence: "observed";
+}
+interface ExplainInference {
+    id: string;
+    label: string;
+    text: string;
+    evidence: string[];
+    confidence: "deterministic";
+}
+interface ExplainResult {
+    mode: ExplainMode;
+    runId: string;
+    name?: string;
+    status?: string;
     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" | "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>;
-/**
- * Applies redaction, metadata truncation, and final serialized size bounds.
- * Never throws; returns a schema-valid event or a minimally truncated variant.
- */
-declare function prepareTraceEventForDisk(event: TraceEvent, opts: TraceSafetyOptions): TraceEvent;
-
-/** Returns the active run context, without internal step fields. */
-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;
-/**
- * Active step id in this async scope (parent for nested `step()` calls).
- * `undefined` at run root or outside any run.
- */
-declare function getCurrentStepId(): string | undefined;
-/** Alias of {@link getCurrentStepId} for readability in step instrumentation. */
-declare function getParentStepId(): string | undefined;
-/**
- * Nesting depth: `0` at run root, increments by one per nested `runWithStepContext`.
- * Returns `0` outside any run.
- */
-declare function getCurrentDepth(): number;
-declare function hasActiveContext(): boolean;
-declare function getTraceDirFromContext(): string | undefined;
-declare function isSilentContext(): boolean;
-/** Resolved trace safety settings for the active run (redaction + size bounds). */
-declare function getTraceSafetyFromContext(): TraceSafetyOptions | undefined;
-/**
- * Runs `fn` with a fresh AgentInspect run context (depth 0, no active step).
- * Propagates sync/async results and rejections; does not swallow user errors.
- */
-declare function runWithContext<T>(context: ExecutionContext, fn: () => Promise<T> | T, traceSafety?: TraceSafetyOptions): Promise<T>;
-/**
- * Runs `fn` with `stepId` as the active step (incremented depth).
- * If no run is active, runs `fn` without altering async context.
- */
-declare function runWithStepContext<T>(stepId: string, fn: () => Promise<T> | T): Promise<T>;
-
-interface InspectorRuntimeOptions {
-    enabled?: boolean;
-    writer?: TraceWriter;
-    traceSafety?: TraceSafetyOptions;
-}
-interface InspectorRuntimeContext extends ExecutionContext {
-    runtimeId: string;
-}
-interface InspectorRuntimeDiagnostics {
-    instrumentationErrors: number;
-    lastInstrumentationError?: string;
-    writerStats?: TraceWriterStats;
-}
-interface InspectorRuntime {
-    readonly runtimeId: string;
-    readonly enabled: boolean;
-    runWithContext<T>(context: ExecutionContext, fn: () => Promise<T> | T): Promise<T>;
-    runWithStepContext<T>(stepId: string, fn: () => Promise<T> | T): Promise<T>;
-    getCurrentContext(): InspectorRuntimeContext | undefined;
-    getCurrentCorrelationMetadata(): TraceCorrelationMetadata | undefined;
-    getCurrentStepId(): string | undefined;
-    getCurrentDepth(): number;
-    getTraceSafety(): TraceSafetyOptions;
-    write(event: PersistedInspectEvent): Promise<void>;
-    flush(): Promise<void>;
-    close(): Promise<void>;
-    getDiagnostics(): InspectorRuntimeDiagnostics;
-}
-declare function createInspectorRuntime(options?: InspectorRuntimeOptions): InspectorRuntime;
-
-interface InspectorCaptureOptions {
-    onSuccess?: "none" | "metadata-only";
-    onError?: "none" | "metadata-only";
-}
-interface CreateInspectorOptions {
-    enabled?: boolean;
-    writer?: TraceWriter;
-    /**
-     * Context metadata only. Does not configure writer output; use
-     * `fileWriter({ dir })` or another explicit writer for persistence paths.
-     *
-     * @experimental
-     */
-    traceDir?: string;
-    /**
-     * Context metadata only for compatibility with existing terminal helpers.
-     * `createInspector()` does not print lifecycle output.
-     *
-     * @experimental
-     */
-    silent?: boolean;
-    metadata?: Record<string, unknown>;
+    facts: ExplainFact[];
+    inferences: ExplainInference[];
+    notes: string[];
+}
+interface ExplainOptions {
+    mode?: ExplainMode;
     redactionProfile?: RedactionProfile;
-    /**
-     * Metadata-only summaries for persisted run/step completion rows.
-     * This never stores raw return values, prompts, outputs, or thrown objects.
-     *
-     * @experimental
-     */
-    capture?: InspectorCaptureOptions;
-    traceSafety?: TraceSafetyOptions;
-}
-interface InspectorRunOptions {
-    runId?: string;
-    traceDir?: string;
-    silent?: boolean;
-    metadata?: Record<string, unknown>;
-}
-interface InspectorStepOptions {
-    type?: StepType;
-    metadata?: StepMetadata;
-}
-type InspectorObserveOptions = InspectorStepOptions;
-interface Inspector {
-    /**
-     * Low-level runtime access is retained for v1.6 compatibility. Prefer
-     * `getDiagnostics()` unless you need advanced runtime context primitives.
-     *
-     * @experimental
-     */
-    readonly runtime: InspectorRuntime;
-    run<T>(name: string, fn: () => T | Promise<T>, options?: InspectorRunOptions): Promise<T>;
-    step<T>(name: string, fn: () => T | Promise<T>, options?: InspectorStepOptions): Promise<T>;
-    tool<T>(name: string, fn: () => T | Promise<T>, options?: InspectorStepOptions): Promise<T>;
-    llm<T>(name: string, fn: () => T | Promise<T>, options?: InspectorStepOptions): Promise<T>;
-    observe<TFunction extends (...args: any[]) => any>(name: string, fn: TFunction, options?: InspectorObserveOptions): (...args: Parameters<TFunction>) => Promise<Awaited<ReturnType<TFunction>>>;
-    getDiagnostics(): ReturnType<InspectorRuntime["getDiagnostics"]>;
-    flush(): Promise<void>;
-    close(): Promise<void>;
-}
-declare function createInspector(options?: CreateInspectorOptions): Inspector;
+}
+/**
+ * Build a local, deterministic explanation payload from a reader-selected run.
+ *
+ * This helper performs no network I/O and does not call a model provider.
+ */
+declare function buildLocalExplanation(run: InspectRunTree, options?: ExplainOptions): ExplainResult;
 
-/** Two spaces per nesting level in terminal output. */
-declare const TERMINAL_INDENT = "  ";
-/** Max display length for names in terminal output. */
-declare const MAX_TERMINAL_NAME_LENGTH = 80;
-/** Max nesting depth used for indentation (prevents huge indents). */
-declare const MAX_TERMINAL_DEPTH = 10;
-/** Indentation string for a nesting depth (capped, never negative). */
-declare function getIndent(depth: number): string;
-/** Truncates a display name for terminal use; invalid input becomes `"unnamed"`. */
-declare function formatTerminalName(name: string): string;
-/** Renders a single step line (colored); does not consult silent mode. */
-declare function renderStepLine(name: string, durationMs: number | undefined, status: StepStatus, depth?: number): string;
-/** Renders an error summary line (no stack in MVP). */
-declare function renderErrorLine(error: ErrorInfo, depth?: number): string;
-/** Plain-text run summary lines (no chalk) for stable testing and CLI reuse. */
-declare function renderRunSummary(durationMs: number, status: RunStatus, traceFilePath?: string): string[];
-/** Prints run header with icon and dim run id. */
-declare function printRunStart(runId: string, name: string): void;
-/** Prints a running step line. */
-declare function printStepStart(name: string, depth?: number): void;
-/** Prints a completed step line with duration and status icon. */
-declare function printStepComplete(name: string, durationMs: number, status: StepStatus, depth?: number): void;
-/** Prints a structured error line (message only, no stack). */
-declare function printError(error: ErrorInfo, depth?: number): void;
-/** Prints run completion summary and optional trace path. */
-declare function printRunComplete(_name: string, _runId: string, durationMs: number, status: RunStatus, traceFilePath?: string): void;
-/** Prints which step failed. */
-declare function printFailedAt(stepName: string): void;
+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.
+ */
+declare function isAgentInspectTrace(filePath: string): Promise<boolean>;
+
+/**
+ * v0.2 shared duration utilities.
+ *
+ * `parseDuration` is used for filters such as "since" / "older-than".
+ * `formatDuration` is used for compact display in CLI and summaries.
+ */
+declare function parseDuration(duration: string): number;
 
-export { type CreateInspectorOptions, DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, DEFAULT_TRACE_DIR_NAME, FALLBACK_TRACE_DIR, type Inspector, type InspectorCaptureOptions, type InspectorObserveOptions, type InspectorRunOptions, type InspectorRuntime, type InspectorRuntimeContext, type InspectorRuntimeDiagnostics, type InspectorRuntimeOptions, type InspectorStepOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, RUNS_DIR_NAME, type ResolvedRedactionProfile, TERMINAL_INDENT, type TraceSafetyOptions, createInspector, createInspectorRuntime, createRunId, createStepId, ensureTraceDir, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getTraceDirFromContext, getTraceFilePath, getTraceSafetyFromContext, hasActiveContext, isSilentContext, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, renderErrorLine, renderRunSummary, renderStepLine, resolveRedactionProfile, resolveTraceSafetyOptions, runWithContext, runWithStepContext, truncateName, warn };
+export { DEFAULT_TRACE_DIR_NAME, type DurationStats, ErrorInfo, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, InspectRunTree, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedRedactionProfile, RunStatus, RunSummary, type RunTimeline, type RunWhatSummary, StepStatus, StepType, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, buildLocalExplanation, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, createRunId, createStepId, ensureTraceDir, extractMetadata, filterTraces, formatDuration, formatError, formatTerminalName, formatTimestamp, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getTraceFilePath, initializeTraceFile, isAgentInspectTrace, listTraceFiles, loadTraceMetadataList, parseDuration, parseDurationFilter, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunSummary, renderRunWhat, renderStepLine, renderTimeline, renderTraceStats, resolveRedactionProfile, resolveTraceDir, searchTraces, serializeEvent, truncateName, unknownTraceFormatMessage, validateEvent, warn, writeTraceEvent };