agent-inspect 1.0.3 → 1.2.0

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

@@ -1,5 +1,75 @@
 import { Stats } from 'node:fs';
 
+type AttributionConfidence = "explicit" | "correlated" | "heuristic" | "unknown";
+type InspectKind = "RUN" | "AGENT" | "LLM" | "TOOL" | "CHAIN" | "RETRIEVER" | "DECISION" | "RESULT" | "ERROR" | "LOGIC" | "LOG";
+interface EventSource {
+    type: "manual" | "json-log" | "log4js" | "pino" | "winston" | "adapter";
+    file?: string;
+    line?: number;
+}
+interface InspectEvent {
+    eventId: string;
+    runId: string;
+    parentId?: string;
+    name: string;
+    kind: InspectKind;
+    timestamp: number;
+    status?: "running" | "ok" | "error";
+    durationMs?: number;
+    attributes?: Record<string, unknown>;
+    confidence: AttributionConfidence;
+    source: EventSource;
+}
+interface InspectNode {
+    event: InspectEvent;
+    children: InspectNode[];
+    depth: number;
+}
+interface InspectRunTree {
+    runId: string;
+    name?: string;
+    status?: "running" | "ok" | "error";
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    children: InspectNode[];
+    metadata: {
+        totalEvents: number;
+        confidenceBreakdown: Record<AttributionConfidence, number>;
+        kinds: Record<InspectKind, number>;
+    };
+}
+
+interface LogEventMapping {
+    kind?: InspectKind;
+    name?: string;
+    parent?: string;
+    status?: "running" | "ok" | "error";
+    startsRun?: boolean;
+    endsRun?: boolean;
+    startsStep?: boolean;
+    endsStep?: boolean;
+}
+type RedactionStrategy = "full" | "prefix" | "hash";
+type RedactionRule = string | {
+    key: string;
+    strategy: RedactionStrategy;
+    keep?: number;
+};
+interface LogIngestConfig {
+    runIdKeys: string[];
+    eventKey: string;
+    timestampKey?: string;
+    messageKey?: string;
+    levelKey?: string;
+    parentIdKey?: string;
+    durationKey?: string;
+    statusKey?: string;
+    mappings?: Record<string, LogEventMapping>;
+    redact?: RedactionRule[];
+    heuristicWindowMs?: number;
+}
+
 /**
  * Discriminator for what kind of work a {@link Step} represents.
  * `"decision"` captures agent branching/choices; other values cover runs, LLM calls, tools, and user-defined steps.
@@ -160,6 +230,19 @@ interface InspectRunOptions {
      * Omitted or `true` preserves default tracing behavior.
      */
     enabled?: boolean;
+    /**
+     * Redact sensitive metadata keys before writing JSONL. Default `true` (conservative keys).
+     * Pass `false` to persist metadata as-is (explicit opt-out).
+     */
+    redact?: boolean | {
+        rules?: RedactionRule[];
+    };
+    /** 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. */
+    maxMetadataValueLength?: number;
+    /** Max length for preview-like metadata keys (contains `preview`). Default 500. */
+    maxPreviewLength?: number;
 }
 /** Options passed when opening a logical step (implemented in a later step). */
 interface StepOptions {
@@ -195,75 +278,144 @@ declare function isStepStatus(value: unknown): value is StepStatus;
  */
 declare function isTraceEvent(value: unknown): value is TraceEvent;
 
-type AttributionConfidence = "explicit" | "correlated" | "heuristic" | "unknown";
-type InspectKind = "RUN" | "AGENT" | "LLM" | "TOOL" | "CHAIN" | "RETRIEVER" | "DECISION" | "RESULT" | "ERROR" | "LOGIC" | "LOG";
-interface EventSource {
-    type: "manual" | "json-log" | "log4js" | "pino" | "winston" | "adapter";
-    file?: string;
-    line?: number;
+type PersistedSchemaVersion = "0.2";
+type PersistedEventSourceType = "manual" | "json-log" | "log4js" | "adapter" | "ai-sdk" | "otel";
+interface PersistedEventSource {
+    type: PersistedEventSourceType;
+    name?: string;
+    version?: string;
 }
-interface InspectEvent {
+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;
-    name: string;
     kind: InspectKind;
-    timestamp: number;
-    status?: "running" | "ok" | "error";
+    name: string;
+    status?: PersistedEventStatus;
+    timestamp: string;
+    startedAt?: string;
+    endedAt?: string;
     durationMs?: number;
-    attributes?: Record<string, unknown>;
     confidence: AttributionConfidence;
-    source: EventSource;
+    source: PersistedEventSource;
+    attributes?: Record<string, unknown>;
+    inputSummary?: unknown;
+    outputSummary?: unknown;
+    error?: PersistedInspectError;
+    tokenUsage?: PersistedTokenUsage;
+    trace?: PersistedTraceContext;
 }
-interface InspectNode {
-    event: InspectEvent;
-    children: InspectNode[];
-    depth: number;
+/**
+ * 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;
 }
-interface InspectRunTree {
-    runId: string;
-    name?: string;
-    status?: "running" | "ok" | "error";
-    startedAt?: number;
-    endedAt?: number;
-    durationMs?: number;
-    children: InspectNode[];
-    metadata: {
-        totalEvents: number;
-        confidenceBreakdown: Record<AttributionConfidence, number>;
-        kinds: Record<InspectKind, number>;
-    };
+/**
+ * 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 LogEventMapping {
-    kind?: InspectKind;
-    name?: string;
-    parent?: string;
-    status?: "running" | "ok" | "error";
-    startsRun?: boolean;
-    endsRun?: boolean;
-    startsStep?: boolean;
-    endsStep?: boolean;
+interface PersistedToInspectEventOptions {
+    /**
+     * If true, invalid persisted events are skipped by batch conversion.
+     * If false or omitted, invalid events throw.
+     */
+    skipInvalid?: boolean;
 }
-type RedactionStrategy = "full" | "prefix" | "hash";
-type RedactionRule = string | {
-    key: string;
-    strategy: RedactionStrategy;
-    keep?: number;
-};
-interface LogIngestConfig {
-    runIdKeys: string[];
-    eventKey: string;
-    timestampKey?: string;
-    messageKey?: string;
-    levelKey?: string;
-    parentIdKey?: string;
-    durationKey?: string;
-    statusKey?: string;
-    mappings?: Record<string, LogEventMapping>;
-    redact?: RedactionRule[];
-    heuristicWindowMs?: number;
+/**
+ * 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 {
@@ -447,6 +599,30 @@ declare function truncateName(name: string, maxLength?: number): string;
  */
 declare function warn(message: string, error?: unknown): void;
 
+/** 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[];
+    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;
+/** 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`. */
@@ -468,11 +644,13 @@ 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): Promise<T>;
+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.
@@ -490,9 +668,6 @@ declare function serializeEvent(event: TraceEvent): string;
  * On failure, retries once under {@link FALLBACK_TRACE_DIR}.
  */
 declare function initializeTraceFile(runId: string, traceDir: string): Promise<string | undefined>;
-/**
- * Appends one validated JSONL line for `event.runId`. Falls back to {@link FALLBACK_TRACE_DIR} on append failure.
- */
 declare function writeTraceEvent(event: TraceEvent, traceDir: string): Promise<void>;
 /**
  * Reads raw JSONL file contents for a run, or `undefined` if missing or unreadable.
@@ -794,4 +969,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_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 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, hasActiveContext, initializeTraceFile, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, loadLogIngestConfig, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, maybeInspectRun, mergeExportDefaults, mergeLogIngestConfig, observe, parseDuration, parseLogLine, parseLogsToTrees, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunDiff, renderRunSummary, renderRunTree, renderRunTrees, renderStepLine, resolveTraceDir, 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 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 };