agent-inspect 0.1.2 → 1.0.1

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

@@ -1,3 +1,5 @@
+import { Stats } from 'node:fs';
+
 /**
  * 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.
@@ -61,6 +63,44 @@ interface Step {
 }
 /** Version of the JSONL trace line schema consumed by AgentInspect tooling. */
 type TraceSchemaVersion = "0.1";
+/**
+ * Status for lightweight trace metadata extraction.
+ * `"unknown"` means the file contained valid events but a run status could not be determined safely.
+ */
+type TraceMetadataStatus = "success" | "error" | "running" | "unknown";
+interface TraceMetadata {
+    runId: string;
+    name?: string;
+    status: TraceMetadataStatus;
+    startedAt?: number;
+    endedAt?: number;
+    durationMs?: number;
+    eventCount: number;
+    filePath: string;
+    fileSize: number;
+    createdAt: Date;
+}
+interface RunSummary {
+    runId: string;
+    name?: string;
+    status: TraceMetadataStatus;
+    durationMs?: number;
+    totalSteps: number;
+    llmSteps: number;
+    toolSteps: number;
+    logicSteps: number;
+    errorSteps: number;
+    maxDepth: number;
+    longestStep?: {
+        name: string;
+        durationMs: number;
+        type: string;
+    };
+    totalTokens?: {
+        input: number;
+        output: number;
+    };
+}
 /** Fields shared by every persisted trace event line. */
 interface TraceEventBase {
     schemaVersion: TraceSchemaVersion;
@@ -150,6 +190,207 @@ 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;
+    message: string;
+    file?: string;
+    line?: number;
+    raw?: string;
+}
+interface ParseResult<T> {
+    records: T[];
+    warnings: ParserWarning[];
+}
+
+declare const DEFAULT_LOG_INGEST_CONFIG: LogIngestConfig;
+declare function mergeLogIngestConfig(base: LogIngestConfig, override: Partial<LogIngestConfig>): LogIngestConfig;
+declare function loadLogIngestConfig(configPath?: string): Promise<LogIngestConfig>;
+
+interface RawLogRecord {
+    raw: Record<string, unknown>;
+    file?: string;
+    line: number;
+    sourceType: "json-log" | "log4js";
+}
+
+declare class JsonLogParser {
+    parseLines(lines: string[], filePath?: string): ParseResult<RawLogRecord>;
+    parseFile(filePath: string): Promise<ParseResult<RawLogRecord>>;
+}
+
+declare class Log4jsParser {
+    parseLines(lines: string[], filePath?: string): ParseResult<RawLogRecord>;
+    parseFile(filePath: string): Promise<ParseResult<RawLogRecord>>;
+}
+
+declare function wildcardMatch(pattern: string, value: string): boolean;
+declare function matchMapping(eventName: string, mappings?: Record<string, LogEventMapping>): LogEventMapping | undefined;
+
+declare const DEFAULT_REDACT_KEYS: readonly ["authorization", "cookie", "token", "apiKey", "password", "secret", "email"];
+interface RedactorOptions {
+    rules?: RedactionRule[];
+}
+declare class Redactor {
+    #private;
+    constructor(options?: RedactorOptions);
+    redactValue(key: string, value: unknown): unknown;
+    redactRecord(record: Record<string, unknown>): Record<string, unknown>;
+}
+
+interface NormalizeOptions {
+    config: LogIngestConfig;
+    sourceFile?: string;
+}
+declare class EventNormalizer {
+    #private;
+    constructor(options: NormalizeOptions);
+    normalize(record: RawLogRecord): InspectEvent | ParserWarning;
+    normalizeAll(records: RawLogRecord[]): ParseResult<InspectEvent>;
+}
+
+interface TreeBuilderOptions {
+    config?: LogIngestConfig;
+}
+declare class TreeBuilder {
+    constructor(options?: TreeBuilderOptions);
+    build(events: InspectEvent[]): InspectRunTree[];
+}
+
+interface RenderTreeOptions {
+    verbose?: boolean;
+    showConfidence?: "always" | "non-explicit" | "never";
+    showMetadata?: boolean;
+    color?: boolean;
+    maxAttributeLength?: number;
+    summary?: boolean;
+}
+declare function renderRunTree(tree: InspectRunTree, options?: RenderTreeOptions): string;
+declare function renderRunTrees(trees: InspectRunTree[], options?: RenderTreeOptions): string;
+
+type LogSourceFormat = "json" | "log4js" | "auto";
+interface ParseLogLineOptions {
+    format?: LogSourceFormat;
+    file?: string;
+    line?: number;
+}
+declare function parseLogLine(line: string, options?: ParseLogLineOptions): ParseResult<RawLogRecord>;
+
+interface LiveLogUpdate {
+    events: InspectEvent[];
+    trees: InspectRunTree[];
+    warnings: ParserWarning[];
+}
+interface LiveLogAccumulatorOptions {
+    config: LogIngestConfig;
+    format?: LogSourceFormat;
+    file?: string;
+}
+declare class LiveLogAccumulator {
+    #private;
+    constructor(options: LiveLogAccumulatorOptions);
+    pushLine(line: string, lineNumber?: number): LiveLogUpdate;
+    getEvents(): InspectEvent[];
+    getTrees(): InspectRunTree[];
+    getWarnings(): ParserWarning[];
+    reset(): void;
+}
+
+interface ParseLogsOptions {
+    format?: "json" | "log4js" | "auto";
+    config?: LogIngestConfig;
+    configPath?: string;
+    runIdKeys?: string[];
+    eventKey?: string;
+    timestampKey?: string;
+    messageKey?: string;
+    levelKey?: string;
+    parentIdKey?: string;
+    durationKey?: string;
+    statusKey?: string;
+    warnings?: "none" | "summary" | "all";
+}
+interface LogToTreeResult {
+    events: InspectEvent[];
+    trees: InspectRunTree[];
+    warnings: ParserWarning[];
+}
+/**
+ * @experimental Compatibility-oriented API for parsing structured logs into normalized run trees.
+ * Subject to refinement before a future stability declaration.
+ */
+declare function parseLogsToTrees(filePath: string, options?: ParseLogsOptions): Promise<LogToTreeResult>;
+
 /** Default folder under the user home for AgentInspect data. */
 declare const DEFAULT_TRACE_DIR_NAME = ".agent-inspect";
 /** Subfolder where JSONL run traces are stored. */
@@ -162,10 +403,7 @@ declare const MAX_NAME_LENGTH = 100;
 declare function createRunId(): string;
 /** Returns `step_` + a 10-character nanoid segment. */
 declare function createStepId(): string;
-/**
- * Formats a duration for CLI display.
- * Under 1000 ms uses whole milliseconds; from 1000 ms uses seconds with one decimal.
- */
+/** 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`.
@@ -264,6 +502,120 @@ declare function listTraceFiles(traceDir: string): Promise<string[]>;
 /** Maps a `.jsonl` file name to its run id (basename only; no traversal). */
 declare function getRunIdFromTraceFileName(fileName: string): string | undefined;
 
+interface TraceDirectoryOptions {
+    dir?: string;
+}
+declare function resolveTraceDir(options?: TraceDirectoryOptions): string;
+declare class TraceDirectory {
+    #private;
+    constructor(options?: TraceDirectoryOptions);
+    getPath(filename?: string): string;
+    list(): Promise<string[]>;
+    getFileStats(filename: string): Promise<Stats>;
+}
+
+declare function extractMetadata(filePath: string, _quickScan?: boolean): Promise<TraceMetadata>;
+declare function buildRunSummary(events: TraceEvent[]): RunSummary;
+
+interface TraceFilterOptions {
+    status?: TraceMetadataStatus;
+    name?: string;
+    since?: string;
+    limit?: number;
+}
+declare function filterTraces(traces: TraceMetadata[], options: TraceFilterOptions): TraceMetadata[];
+
+/**
+ * Safety check for cleanup workflows: returns true only when the file appears to be an AgentInspect trace.
+ * This should be conservative: false positives are more dangerous than false negatives.
+ */
+declare function isAgentInspectTrace(filePath: string): Promise<boolean>;
+
+/**
+ * v0.2 shared duration utilities.
+ *
+ * `parseDuration` is used for filters such as "since" / "older-than".
+ * `formatDuration` is used for compact display in CLI and summaries.
+ */
+declare function parseDuration(duration: string): number;
+
+type DiffSeverity = "info" | "warning" | "error";
+type DiffKind = "run-status" | "structure" | "step-added" | "step-removed" | "step-status" | "step-type" | "duration" | "error" | "metadata" | "output" | "first-divergence";
+interface DiffPathSegment {
+    index: number;
+    name: string;
+    stepId?: string;
+}
+interface DiffPath {
+    path: DiffPathSegment[];
+}
+interface RunDiffItem {
+    kind: DiffKind;
+    severity: DiffSeverity;
+    message: string;
+    path?: DiffPath;
+    left?: unknown;
+    right?: unknown;
+}
+interface StepComparable {
+    id: string;
+    name: string;
+    type?: string;
+    status?: string;
+    durationMs?: number;
+    error?: string;
+    metadata?: Record<string, unknown>;
+    outputPreview?: unknown;
+    children: StepComparable[];
+}
+interface RunComparable {
+    runId: string;
+    name?: string;
+    status?: string;
+    durationMs?: number;
+    steps: StepComparable[];
+}
+interface RunDiffSummary {
+    leftRunId: string;
+    rightRunId: string;
+    totalDifferences: number;
+    errors: number;
+    warnings: number;
+    info: number;
+    firstDivergence?: RunDiffItem;
+}
+interface RunDiffResult {
+    summary: RunDiffSummary;
+    differences: RunDiffItem[];
+}
+interface DiffOptions {
+    ignoreDuration?: boolean;
+    durationThresholdMs?: number;
+    focus?: "all" | "errors" | "structure" | "outputs";
+    check?: "all" | "structure" | "outputs" | "errors" | "timing";
+}
+interface RenderDiffOptions {
+    json?: boolean;
+    verbose?: boolean;
+    color?: boolean;
+}
+
+/**
+ * Normalize v0.1 manual JSONL events into a comparable run tree.
+ * Does not mutate input events.
+ */
+declare function manualTraceEventsToComparableRun(events: TraceEvent[]): RunComparable;
+
+declare function diffRuns(left: RunComparable, right: RunComparable, options?: DiffOptions): RunDiffResult;
+
+declare function renderRunDiff(result: RunDiffResult, options?: RenderDiffOptions): string;
+
+/**
+ * @experimental Compare two v0.1 manual traces as normalized trees (read-only).
+ * Subject to refinement before a future stability declaration.
+ */
+declare function diffTraceEvents(leftEvents: TraceEvent[], rightEvents: TraceEvent[], options?: DiffOptions): RunDiffResult;
+
 /** Two spaces per nesting level in terminal output. */
 declare const TERMINAL_INDENT = "  ";
 /** Max display length for names in terminal output. */
@@ -294,12 +646,18 @@ declare function printRunComplete(_name: string, _runId: string, durationMs: num
 declare function printFailedAt(stepName: string): void;
 
 /**
+ * Stable v1.0 API for local manual run tracing.
+ *
  * Runs `fn` inside an AgentInspect trace: JSONL `run_started` / `run_completed`, optional terminal output,
  * and {@link ExecutionContext} for nested APIs. Instrumentation failures are swallowed; user errors are re-thrown.
  */
 declare function inspectRun<T>(name: string, fn: () => Promise<T> | T, options?: InspectRunOptions): Promise<T>;
 
-/** Callable step tracer plus {@link step.llm} and {@link step.tool} shortcuts. */
+/**
+ * Stable v1.0 API for instrumenting a named step inside an AgentInspect run.
+ *
+ * Callable step tracer plus {@link step.llm} and {@link step.tool} shortcuts.
+ */
 type StepFunction = {
     <T>(name: string, fn: () => Promise<T> | T, options?: StepOptions): Promise<T>;
     llm: <T>(model: string, fn: () => Promise<T> | T) => Promise<T>;
@@ -315,10 +673,107 @@ type StepFunction = {
 declare const step: StepFunction;
 
 /**
+ * Stable v1.0 API for observing agent-like objects locally.
+ *
  * Returns a Proxy that traces top-level `run`, `execute`, and `invoke` via {@link inspectRun}.
  * Other properties pass through; function members are bound to the real target so class private fields work.
  * Invalid agents are returned unchanged (with a warn); this function never throws.
  */
 declare function observe<T>(agent: T, options?: ObserveOptions): T;
 
-export { type ActiveStepContext, DEFAULT_TRACE_DIR_NAME, type ErrorInfo, type ExecutionContext, FALLBACK_TRACE_DIR, type InspectRunOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, type ObserveOptions, RUNS_DIR_NAME, type Run, type RunCompletedEvent, type RunStartedEvent, type RunStatus, type Step, type StepCompletedEvent, type StepMetadata, type StepOptions, type StepStartedEvent, type StepStatus, type StepType, TERMINAL_INDENT, type TokenMetadata, type TraceEvent, type TraceEventBase, type TraceSchemaVersion, createRunId, createStepId, ensureTraceDir, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getRunIdFromTraceFileName, getTraceDirFromContext, getTraceFilePath, hasActiveContext, initializeTraceFile, inspectRun, isSilentContext, isStepStatus, isStepType, isTraceEvent, listTraceFiles, observe, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readTraceEvents, readTraceFile, renderErrorLine, renderRunSummary, renderStepLine, runWithContext, runWithStepContext, serializeEvent, step, truncateName, validateEvent, warn, writeTraceEvent };
+/**
+ * v0.7 local export formats. No sinks — string output only.
+ */
+
+type ExportFormat = "markdown" | "html" | "openinference" | "otlp-json";
+interface ExportOptions {
+    format: ExportFormat;
+    includeMetadata?: boolean;
+    includeAttributes?: boolean;
+    includeErrors?: boolean;
+    pretty?: boolean;
+    redacted?: boolean;
+    maxAttributeLength?: number;
+}
+interface ExportResult {
+    format: ExportFormat;
+    content: string;
+    contentType: string;
+    fileExtension: string;
+    warnings: string[];
+}
+interface ExportValidationResult {
+    ok: boolean;
+    format: ExportFormat;
+    errors: string[];
+    warnings: string[];
+}
+interface TraceExporter {
+    name: string;
+    format: ExportFormat;
+    export(tree: InspectRunTree, options?: Partial<ExportOptions>): ExportResult;
+    validate?(content: string): ExportValidationResult;
+}
+/** Library version string embedded in JSON exports (human-readable, not semver guarantee for formats). */
+declare const EXPORT_PAYLOAD_VERSION = "0.1.2";
+
+declare function safeString(value: unknown, maxLength?: number): string;
+/** Escape markdown table pipes and normalize line breaks for safe inline text. */
+declare function escapeMarkdown(value: string): string;
+declare function escapeHtml(value: string): string;
+declare function stableJson(value: unknown, pretty?: boolean): string;
+declare function compactAttributes(attrs: Record<string, unknown> | undefined, options?: {
+    maxLength?: number;
+    redacted?: boolean;
+}): Record<string, unknown>;
+declare function summarizeTree(tree: InspectRunTree): Record<string, unknown>;
+/** Depth-first pre-order flatten (matches typical tree display). */
+declare function flattenTree(tree: InspectRunTree): InspectNode[];
+
+/**
+ * Build an {@link InspectRunTree} from v0.1 JSONL {@link TraceEvent} rows (manual tracing).
+ * Does not mutate the input array or event objects.
+ */
+declare function manualTraceEventsToRunTree(events: TraceEvent[]): InspectRunTree;
+
+declare function exportMarkdown(tree: InspectRunTree, options?: Partial<ExportOptions>): ExportResult;
+
+declare function exportHtml(tree: InspectRunTree, options?: Partial<ExportOptions>): ExportResult;
+
+interface OpenInferenceSpan {
+    trace_id: string;
+    span_id: string;
+    parent_span_id?: string;
+    name: string;
+    start_time_unix_nano: number;
+    end_time_unix_nano?: number;
+    attributes: Record<string, unknown>;
+    status?: {
+        code: "OK" | "ERROR" | "UNSET";
+        message?: string;
+    };
+}
+interface OpenInferenceExport {
+    exporter: "agent-inspect";
+    format: "openinference";
+    compatibility: "openinference-compatible";
+    version: string;
+    trace_id: string;
+    spans: OpenInferenceSpan[];
+    warnings: string[];
+}
+declare function exportOpenInference(tree: InspectRunTree, options?: Partial<ExportOptions>): ExportResult;
+
+declare function exportOtlpJson(tree: InspectRunTree, options?: Partial<ExportOptions>): ExportResult;
+
+declare function validateExportContent(format: ExportFormat, content: string): ExportValidationResult;
+
+declare function mergeExportDefaults(options: ExportOptions): ExportOptions;
+/**
+ * @experimental Compatibility-oriented export API. Exports are local-only and do not upload anywhere.
+ * Subject to refinement before a future stability declaration.
+ */
+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 };