agent-inspect 1.8.0 → 2.0.0

package/packages/core/dist/context-CSKnzpXR.d.cts

@@ -0,0 +1,177 @@
+import { R as RedactionProfile, d as StepMetadata, h as TraceEvent, I as InspectRunOptions, i as ExecutionContext, g as TraceCorrelationMetadata, f as StepType } from './types-DgMN3qow.cjs';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-DHcHPUKv.cjs';
+import { TraceWriterStats, TraceWriter } from './writers.cjs';
+import { R as RedactionRule } from './log-config-8aE5Kxtr.cjs';
+
+/** 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;
+
+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;
+
+/**
+ * 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>;
+
+/** 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>;
+
+export { prepareTraceEventForDisk as A, resolveTraceSafetyOptions as B, type CreateInspectorOptions as C, DEFAULT_MAX_EVENT_BYTES as D, runWithContext as E, runWithStepContext as F, type Inspector as I, type TraceSafetyOptions as T, type InspectorCaptureOptions as a, type InspectorObserveOptions as b, type InspectorRunOptions as c, type InspectorStepOptions as d, createInspector as e, DEFAULT_MAX_METADATA_VALUE_LENGTH as f, getCurrentCorrelationMetadata as g, DEFAULT_MAX_PREVIEW_LENGTH as h, type InspectorRuntime as i, type InspectorRuntimeContext as j, type InspectorRuntimeDiagnostics as k, type InspectorRuntimeOptions as l, maybeInspectRun as m, createInspectorRuntime as n, getCurrentContext as o, getCurrentDepth as p, getCurrentRunId as q, getCurrentRunName as r, getCurrentStepId as s, getParentStepId as t, getTraceDirFromContext as u, getTraceSafetyFromContext as v, hasActiveContext as w, isAgentInspectEnabled as x, isSilentContext as y, prepareMetadataForDisk as z };

package/packages/core/dist/context-yv2VSDQF.d.ts

@@ -0,0 +1,177 @@
+import { R as RedactionProfile, d as StepMetadata, h as TraceEvent, I as InspectRunOptions, i as ExecutionContext, g as TraceCorrelationMetadata, f as StepType } from './types-D-Y1kOU-.js';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-D-WpXeZX.js';
+import { TraceWriterStats, TraceWriter } from './writers.js';
+import { R as RedactionRule } from './log-config-DVimQJho.js';
+
+/** 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;
+
+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;
+
+/**
+ * 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>;
+
+/** 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>;
+
+export { prepareTraceEventForDisk as A, resolveTraceSafetyOptions as B, type CreateInspectorOptions as C, DEFAULT_MAX_EVENT_BYTES as D, runWithContext as E, runWithStepContext as F, type Inspector as I, type TraceSafetyOptions as T, type InspectorCaptureOptions as a, type InspectorObserveOptions as b, type InspectorRunOptions as c, type InspectorStepOptions as d, createInspector as e, DEFAULT_MAX_METADATA_VALUE_LENGTH as f, getCurrentCorrelationMetadata as g, DEFAULT_MAX_PREVIEW_LENGTH as h, type InspectorRuntime as i, type InspectorRuntimeContext as j, type InspectorRuntimeDiagnostics as k, type InspectorRuntimeOptions as l, maybeInspectRun as m, createInspectorRuntime as n, getCurrentContext as o, getCurrentDepth as p, getCurrentRunId as q, getCurrentRunName as r, getCurrentStepId as s, getParentStepId as t, getTraceDirFromContext as u, getTraceSafetyFromContext as v, hasActiveContext as w, isAgentInspectEnabled as x, isSilentContext as y, prepareMetadataForDisk as z };

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

@@ -1,5 +1,5 @@
-import { T as TraceEvent } from './types-B2-BU5CS.cjs';
-import './log-config-DanPV3P9.cjs';
+import { h as TraceEvent } from './types-DgMN3qow.cjs';
+import './log-config-8aE5Kxtr.cjs';
 import './inspect-event-CevRYp58.cjs';
 
 type DiffSeverity = "info" | "warning" | "error";

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

@@ -1,5 +1,5 @@
-import { T as TraceEvent } from './types-Ap9uMdx_.js';
-import './log-config-BPHS4Sds.js';
+import { h as TraceEvent } from './types-D-Y1kOU-.js';
+import './log-config-DVimQJho.js';
 import './inspect-event-CevRYp58.js';
 
 type DiffSeverity = "info" | "warning" | "error";