agent-inspect 1.4.0 → 1.6.0

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

@@ -0,0 +1,254 @@
+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-DB8jB6Jg.cjs';
+import { R as RedactionRule } from './log-config-BnH8Ykcb.cjs';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-0kaRADsp.cjs';
+import { TraceWriterStats, TraceWriter } from './writers.cjs';
+import './inspect-event-Des4JDHo.cjs';
+
+/** Default folder under the user home for AgentInspect data. */
+declare const DEFAULT_TRACE_DIR_NAME = ".agent-inspect";
+/** Subfolder where JSONL run traces are stored. */
+declare const RUNS_DIR_NAME = "runs";
+/** Writable trace root when the default home path cannot be used. */
+declare const FALLBACK_TRACE_DIR: string;
+/** Maximum display length for run/step names before truncation. */
+declare const MAX_NAME_LENGTH = 100;
+/** Returns `run_` + a 10-character nanoid segment. */
+declare function createRunId(): string;
+/** Returns `step_` + a 10-character nanoid segment. */
+declare function createStepId(): string;
+/** Formats a duration for CLI display (v0.2 rules). */
+declare function formatDuration(ms: number): string;
+/**
+ * Formats a Unix timestamp (ms) as local `YYYY-MM-DD HH:mm:ss`.
+ * Invalid values yield `"Invalid date"` (no throw).
+ */
+declare function formatTimestamp(timestamp: number): string;
+/**
+ * Default directory for trace files: `~/DEFAULT_TRACE_DIR_NAME/RUNS_DIR_NAME`.
+ * Falls back to {@link FALLBACK_TRACE_DIR} when home cannot be resolved.
+ */
+declare function getDefaultTraceDir(): string;
+/**
+ * Full path to the JSONL trace file for a run.
+ * `runId` is passed through `path.basename` to avoid traversal; empty ids become `run_unknown`.
+ */
+declare function getTraceFilePath(runId: string, traceDir?: string): string;
+/**
+ * Ensures a trace directory exists (recursive). Tries {@link FALLBACK_TRACE_DIR} on failure.
+ * Returns the directory path that callers should prefer: primary, fallback, or original if both mkdir attempts fail.
+ * Emits concise `[AgentInspect]` warnings on failure; never throws.
+ */
+declare function ensureTraceDir(traceDir: string): Promise<string>;
+/**
+ * Normalizes any thrown/caught value into {@link ErrorInfo}.
+ * Never throws (circular structures and non-JSON values fall back to a generic message).
+ */
+declare function formatError(error: unknown): ErrorInfo;
+/**
+ * Truncates a display name to `maxLength`, appending `"..."` when shortened.
+ * Empty or non-string input becomes `"unnamed"`.
+ */
+declare function truncateName(name: string, maxLength?: number): string;
+/**
+ * Instrumentation-only warning to stderr. Not a general-purpose logger.
+ * Optional `error` is summarized via {@link formatError} (message only).
+ */
+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). */
+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[];
+    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>;
+    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;
+
+/** 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;
+
+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 };

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

@@ -0,0 +1,254 @@
+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-tSix7tfv.js';
+import { R as RedactionRule } from './log-config-C1GcJPIM.js';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-DiFto0K2.js';
+import { TraceWriterStats, TraceWriter } from './writers.js';
+import './inspect-event-Des4JDHo.js';
+
+/** Default folder under the user home for AgentInspect data. */
+declare const DEFAULT_TRACE_DIR_NAME = ".agent-inspect";
+/** Subfolder where JSONL run traces are stored. */
+declare const RUNS_DIR_NAME = "runs";
+/** Writable trace root when the default home path cannot be used. */
+declare const FALLBACK_TRACE_DIR: string;
+/** Maximum display length for run/step names before truncation. */
+declare const MAX_NAME_LENGTH = 100;
+/** Returns `run_` + a 10-character nanoid segment. */
+declare function createRunId(): string;
+/** Returns `step_` + a 10-character nanoid segment. */
+declare function createStepId(): string;
+/** Formats a duration for CLI display (v0.2 rules). */
+declare function formatDuration(ms: number): string;
+/**
+ * Formats a Unix timestamp (ms) as local `YYYY-MM-DD HH:mm:ss`.
+ * Invalid values yield `"Invalid date"` (no throw).
+ */
+declare function formatTimestamp(timestamp: number): string;
+/**
+ * Default directory for trace files: `~/DEFAULT_TRACE_DIR_NAME/RUNS_DIR_NAME`.
+ * Falls back to {@link FALLBACK_TRACE_DIR} when home cannot be resolved.
+ */
+declare function getDefaultTraceDir(): string;
+/**
+ * Full path to the JSONL trace file for a run.
+ * `runId` is passed through `path.basename` to avoid traversal; empty ids become `run_unknown`.
+ */
+declare function getTraceFilePath(runId: string, traceDir?: string): string;
+/**
+ * Ensures a trace directory exists (recursive). Tries {@link FALLBACK_TRACE_DIR} on failure.
+ * Returns the directory path that callers should prefer: primary, fallback, or original if both mkdir attempts fail.
+ * Emits concise `[AgentInspect]` warnings on failure; never throws.
+ */
+declare function ensureTraceDir(traceDir: string): Promise<string>;
+/**
+ * Normalizes any thrown/caught value into {@link ErrorInfo}.
+ * Never throws (circular structures and non-JSON values fall back to a generic message).
+ */
+declare function formatError(error: unknown): ErrorInfo;
+/**
+ * Truncates a display name to `maxLength`, appending `"..."` when shortened.
+ * Empty or non-string input becomes `"unnamed"`.
+ */
+declare function truncateName(name: string, maxLength?: number): string;
+/**
+ * Instrumentation-only warning to stderr. Not a general-purpose logger.
+ * Optional `error` is summarized via {@link formatError} (message only).
+ */
+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). */
+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[];
+    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>;
+    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;
+
+/** 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;
+
+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 };

package/packages/core/dist/advanced.mjs

@@ -0,0 +1,11 @@
+export { MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, TERMINAL_INDENT, createInspector, createInspectorRuntime, formatTerminalName, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getIndent, getParentStepId, getTraceDirFromContext, getTraceSafetyFromContext, hasActiveContext, isSilentContext, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, renderErrorLine, renderRunSummary, renderStepLine, runWithContext, runWithStepContext } from './chunk-6QSLZCBJ.mjs';
+import './chunk-BT7CATSD.mjs';
+export { DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, prepareMetadataForDisk, prepareTraceEventForDisk, resolveTraceSafetyOptions } from './chunk-57S5D6HR.mjs';
+export { resolveRedactionProfile } from './chunk-EDTQHZPM.mjs';
+import './chunk-VU6O5QAH.mjs';
+import './chunk-S4YWKV4G.mjs';
+export { DEFAULT_TRACE_DIR_NAME, FALLBACK_TRACE_DIR, MAX_NAME_LENGTH, RUNS_DIR_NAME, createRunId, createStepId, ensureTraceDir, formatDuration, formatError, formatTimestamp, getDefaultTraceDir, getTraceFilePath, truncateName, warn } from './chunk-VTIB5MDK.mjs';
+import './chunk-74XZ6N7Q.mjs';
+import './chunk-7TGZLWEE.mjs';
+//# sourceMappingURL=advanced.mjs.map
+//# sourceMappingURL=advanced.mjs.map

package/packages/core/dist/advanced.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"advanced.mjs"}