agent-inspect 1.0.2 → 1.1.0

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

@@ -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.
@@ -150,11 +220,29 @@ interface StepCompletedEvent extends TraceEventBase {
 }
 /** Discriminated union of all MVP trace events written as JSONL lines. */
 type TraceEvent = RunStartedEvent | RunCompletedEvent | StepStartedEvent | StepCompletedEvent;
-/** Options for `inspectRun()` (implemented in a later step). */
+/** Options for `inspectRun()` and `maybeInspectRun()`. */
 interface InspectRunOptions {
     traceDir?: string;
     silent?: boolean;
     metadata?: Record<string, unknown>;
+    /**
+     * When `false`, runs `fn` with no trace file, no execution context, and no terminal output.
+     * 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 {
@@ -190,76 +278,6 @@ 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;
-}
-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;
-}
-
 type ParserWarningCode = "MALFORMED_JSON" | "MISSING_RUN_ID" | "MISSING_EVENT" | "MISSING_TIMESTAMP" | "UNSUPPORTED_LOG4JS_PAYLOAD" | "CONFIG_ERROR" | "UNKNOWN";
 interface ParserWarning {
     code: ParserWarningCode;
@@ -442,6 +460,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`. */
@@ -463,11 +505,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.
@@ -485,9 +529,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.
@@ -653,6 +694,19 @@ declare function printFailedAt(stepName: string): void;
  */
 declare function inspectRun<T>(name: string, fn: () => Promise<T> | T, options?: InspectRunOptions): Promise<T>;
 
+/**
+ * Returns true when `value` is one of the recognized AGENT_INSPECT enable tokens
+ * (`1`, `true`, `yes`, `on`, `enabled`, case-insensitive). Undefined or any other value is false.
+ */
+declare function isAgentInspectEnabled(value?: string): boolean;
+/**
+ * Runs `fn` with tracing when enabled; otherwise passthrough (no trace file, no context).
+ *
+ * Enablement order: explicit `options.enabled` wins; when omitted, reads `process.env.AGENT_INSPECT`.
+ * Unset or unrecognized env values disable tracing.
+ */
+declare function maybeInspectRun<T>(name: string, fn: () => Promise<T> | T, options?: InspectRunOptions): Promise<T>;
+
 /**
  * Stable v1.0 API for instrumenting a named step inside an AgentInspect run.
  *
@@ -776,4 +830,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, isAgentInspectTrace, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, loadLogIngestConfig, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, 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 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 };

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.
@@ -150,11 +220,29 @@ interface StepCompletedEvent extends TraceEventBase {
 }
 /** Discriminated union of all MVP trace events written as JSONL lines. */
 type TraceEvent = RunStartedEvent | RunCompletedEvent | StepStartedEvent | StepCompletedEvent;
-/** Options for `inspectRun()` (implemented in a later step). */
+/** Options for `inspectRun()` and `maybeInspectRun()`. */
 interface InspectRunOptions {
     traceDir?: string;
     silent?: boolean;
     metadata?: Record<string, unknown>;
+    /**
+     * When `false`, runs `fn` with no trace file, no execution context, and no terminal output.
+     * 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 {
@@ -190,76 +278,6 @@ 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;
-}
-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;
-}
-
 type ParserWarningCode = "MALFORMED_JSON" | "MISSING_RUN_ID" | "MISSING_EVENT" | "MISSING_TIMESTAMP" | "UNSUPPORTED_LOG4JS_PAYLOAD" | "CONFIG_ERROR" | "UNKNOWN";
 interface ParserWarning {
     code: ParserWarningCode;
@@ -442,6 +460,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`. */
@@ -463,11 +505,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.
@@ -485,9 +529,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.
@@ -653,6 +694,19 @@ declare function printFailedAt(stepName: string): void;
  */
 declare function inspectRun<T>(name: string, fn: () => Promise<T> | T, options?: InspectRunOptions): Promise<T>;
 
+/**
+ * Returns true when `value` is one of the recognized AGENT_INSPECT enable tokens
+ * (`1`, `true`, `yes`, `on`, `enabled`, case-insensitive). Undefined or any other value is false.
+ */
+declare function isAgentInspectEnabled(value?: string): boolean;
+/**
+ * Runs `fn` with tracing when enabled; otherwise passthrough (no trace file, no context).
+ *
+ * Enablement order: explicit `options.enabled` wins; when omitted, reads `process.env.AGENT_INSPECT`.
+ * Unset or unrecognized env values disable tracing.
+ */
+declare function maybeInspectRun<T>(name: string, fn: () => Promise<T> | T, options?: InspectRunOptions): Promise<T>;
+
 /**
  * Stable v1.0 API for instrumenting a named step inside an AgentInspect run.
  *
@@ -776,4 +830,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, isAgentInspectTrace, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, loadLogIngestConfig, manualTraceEventsToComparableRun, manualTraceEventsToRunTree, matchMapping, 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 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 };