agent-inspect 1.4.0 → 1.5.0

package/packages/core/dist/types-Bkt7LS01.d.ts

@@ -0,0 +1,226 @@
+import { R as RedactionRule } from './log-config-BzGmDYum.js';
+
+/**
+ * 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.
+ */
+type StepType = "run" | "llm" | "tool" | "decision" | "logic" | "state" | "custom";
+/** Lifecycle state of a single {@link Step}. */
+type StepStatus = "running" | "success" | "error";
+/** Lifecycle state of an entire {@link Run}. */
+type RunStatus = "running" | "success" | "error";
+/** Structured error attached to a run or step when status is `"error"`. */
+interface ErrorInfo {
+    message: string;
+    stack?: string;
+}
+/**
+ * Optional token counts for a step (e.g. LLM usage).
+ * Reserved for future roadmap; MVP does not compute or persist token usage.
+ */
+interface TokenMetadata {
+    input?: number;
+    output?: number;
+}
+/** Arbitrary structured fields for a step; safe extensions use string keys. */
+interface StepMetadata {
+    model?: string;
+    toolName?: string;
+    tokens?: TokenMetadata;
+    retryCount?: number;
+    [key: string]: unknown;
+}
+/**
+ * One traced agent run (root of an execution tree).
+ * MVP intentionally omits `input` / `output` on the run to limit PII, secrets, and serialization risk.
+ */
+interface Run {
+    id: string;
+    name: string;
+    status: RunStatus;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    error?: ErrorInfo;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * One node in the execution tree under a {@link Run}.
+ * MVP intentionally omits `input` / `output`; capture/redaction may come in a later version.
+ */
+interface Step {
+    id: string;
+    runId: string;
+    parentId?: string;
+    name: string;
+    type: StepType;
+    status: StepStatus;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    error?: ErrorInfo;
+    metadata?: StepMetadata;
+}
+/** 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;
+    event: string;
+    timestamp: number;
+}
+/** Emitted when a run begins. */
+interface RunStartedEvent extends TraceEventBase {
+    event: "run_started";
+    runId: string;
+    name: string;
+    startTime: number;
+    metadata?: Record<string, unknown>;
+}
+/** Emitted when a run finishes successfully or with an error. */
+interface RunCompletedEvent extends TraceEventBase {
+    event: "run_completed";
+    runId: string;
+    status: "success" | "error";
+    endTime: number;
+    durationMs: number;
+    error?: ErrorInfo;
+}
+/** Emitted when a step begins (including nested steps under `parentId`). */
+interface StepStartedEvent extends TraceEventBase {
+    event: "step_started";
+    runId: string;
+    stepId: string;
+    parentId?: string;
+    name: string;
+    type: StepType;
+    startTime: number;
+    metadata?: StepMetadata;
+}
+/**
+ * Emitted when a step finishes (success or failure).
+ * Failures use `status: "error"` and optional {@link ErrorInfo}; there is no separate `step_failed` event in MVP.
+ */
+interface StepCompletedEvent extends TraceEventBase {
+    event: "step_completed";
+    runId: string;
+    stepId: string;
+    status: "success" | "error";
+    endTime: number;
+    durationMs: number;
+    error?: ErrorInfo;
+}
+/** Discriminated union of all MVP trace events written as JSONL lines. */
+type TraceEvent = RunStartedEvent | RunCompletedEvent | StepStartedEvent | StepCompletedEvent;
+/** Named redaction presets for trace writing and share-safe exports (v1.3.0+). */
+type RedactionProfile = "local" | "share" | "strict";
+/** Optional correlation fields for grouping and cross-run tracing (v1.3.0+). */
+interface TraceCorrelationMetadata {
+    correlationId?: string;
+    requestId?: string;
+    decisionId?: string;
+    groupId?: string;
+}
+/** Options for `inspectRun()` and `maybeInspectRun()`. */
+interface InspectRunOptions extends TraceCorrelationMetadata {
+    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[];
+    };
+    /**
+     * Redaction preset for trace metadata. Default `local` (same keys as default redaction).
+     * `share` and `strict` add extra key-based redaction and tighter string bounds.
+     * Ignored when `redact: false`.
+     */
+    redactionProfile?: RedactionProfile;
+    /** 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 {
+    type?: StepType;
+    metadata?: StepMetadata;
+}
+/** Options for `observe()` — same surface as {@link InspectRunOptions} in MVP. */
+type ObserveOptions = InspectRunOptions;
+/**
+ * Resolved settings for the active run while tracing is enabled.
+ * Populated by runtime code in a later step; defined here for `context.ts`.
+ */
+interface ExecutionContext {
+    runId: string;
+    runName: string;
+    traceDir: string;
+    silent: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Stack position of the step currently executing (used by future context tracking). */
+interface ActiveStepContext {
+    stepId: string;
+    parentId?: string;
+    depth: number;
+}
+/** Returns true if `value` is one of the MVP {@link StepType} literals. */
+declare function isStepType(value: unknown): value is StepType;
+/** Returns true if `value` is one of the MVP {@link StepStatus} literals. */
+declare function isStepStatus(value: unknown): value is StepStatus;
+/**
+ * Narrowing guard for a {@link TraceEvent} object with required MVP fields.
+ * Does not deeply validate optional `metadata` shapes.
+ */
+declare function isTraceEvent(value: unknown): value is TraceEvent;
+
+export { type ActiveStepContext as A, type ErrorInfo as E, type InspectRunOptions as I, type ObserveOptions as O, type RunSummary as R, type StepType as S, type TraceEvent as T, type TraceMetadata as a, type TraceMetadataStatus as b, type StepStatus as c, type TraceCorrelationMetadata as d, type RedactionProfile as e, type StepOptions as f, type ExecutionContext as g, type Run as h, type RunCompletedEvent as i, type RunStartedEvent as j, type RunStatus as k, type Step as l, type StepCompletedEvent as m, type StepMetadata as n, type StepStartedEvent as o, type TokenMetadata as p, type TraceEventBase as q, type TraceSchemaVersion as r, isStepStatus as s, isStepType as t, isTraceEvent as u };

package/packages/core/dist/types-CNbheSdk.d.cts

@@ -0,0 +1,226 @@
+import { R as RedactionRule } from './log-config-BzGmDYum.cjs';
+
+/**
+ * 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.
+ */
+type StepType = "run" | "llm" | "tool" | "decision" | "logic" | "state" | "custom";
+/** Lifecycle state of a single {@link Step}. */
+type StepStatus = "running" | "success" | "error";
+/** Lifecycle state of an entire {@link Run}. */
+type RunStatus = "running" | "success" | "error";
+/** Structured error attached to a run or step when status is `"error"`. */
+interface ErrorInfo {
+    message: string;
+    stack?: string;
+}
+/**
+ * Optional token counts for a step (e.g. LLM usage).
+ * Reserved for future roadmap; MVP does not compute or persist token usage.
+ */
+interface TokenMetadata {
+    input?: number;
+    output?: number;
+}
+/** Arbitrary structured fields for a step; safe extensions use string keys. */
+interface StepMetadata {
+    model?: string;
+    toolName?: string;
+    tokens?: TokenMetadata;
+    retryCount?: number;
+    [key: string]: unknown;
+}
+/**
+ * One traced agent run (root of an execution tree).
+ * MVP intentionally omits `input` / `output` on the run to limit PII, secrets, and serialization risk.
+ */
+interface Run {
+    id: string;
+    name: string;
+    status: RunStatus;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    error?: ErrorInfo;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * One node in the execution tree under a {@link Run}.
+ * MVP intentionally omits `input` / `output`; capture/redaction may come in a later version.
+ */
+interface Step {
+    id: string;
+    runId: string;
+    parentId?: string;
+    name: string;
+    type: StepType;
+    status: StepStatus;
+    startTime: number;
+    endTime?: number;
+    durationMs?: number;
+    error?: ErrorInfo;
+    metadata?: StepMetadata;
+}
+/** 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;
+    event: string;
+    timestamp: number;
+}
+/** Emitted when a run begins. */
+interface RunStartedEvent extends TraceEventBase {
+    event: "run_started";
+    runId: string;
+    name: string;
+    startTime: number;
+    metadata?: Record<string, unknown>;
+}
+/** Emitted when a run finishes successfully or with an error. */
+interface RunCompletedEvent extends TraceEventBase {
+    event: "run_completed";
+    runId: string;
+    status: "success" | "error";
+    endTime: number;
+    durationMs: number;
+    error?: ErrorInfo;
+}
+/** Emitted when a step begins (including nested steps under `parentId`). */
+interface StepStartedEvent extends TraceEventBase {
+    event: "step_started";
+    runId: string;
+    stepId: string;
+    parentId?: string;
+    name: string;
+    type: StepType;
+    startTime: number;
+    metadata?: StepMetadata;
+}
+/**
+ * Emitted when a step finishes (success or failure).
+ * Failures use `status: "error"` and optional {@link ErrorInfo}; there is no separate `step_failed` event in MVP.
+ */
+interface StepCompletedEvent extends TraceEventBase {
+    event: "step_completed";
+    runId: string;
+    stepId: string;
+    status: "success" | "error";
+    endTime: number;
+    durationMs: number;
+    error?: ErrorInfo;
+}
+/** Discriminated union of all MVP trace events written as JSONL lines. */
+type TraceEvent = RunStartedEvent | RunCompletedEvent | StepStartedEvent | StepCompletedEvent;
+/** Named redaction presets for trace writing and share-safe exports (v1.3.0+). */
+type RedactionProfile = "local" | "share" | "strict";
+/** Optional correlation fields for grouping and cross-run tracing (v1.3.0+). */
+interface TraceCorrelationMetadata {
+    correlationId?: string;
+    requestId?: string;
+    decisionId?: string;
+    groupId?: string;
+}
+/** Options for `inspectRun()` and `maybeInspectRun()`. */
+interface InspectRunOptions extends TraceCorrelationMetadata {
+    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[];
+    };
+    /**
+     * Redaction preset for trace metadata. Default `local` (same keys as default redaction).
+     * `share` and `strict` add extra key-based redaction and tighter string bounds.
+     * Ignored when `redact: false`.
+     */
+    redactionProfile?: RedactionProfile;
+    /** 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 {
+    type?: StepType;
+    metadata?: StepMetadata;
+}
+/** Options for `observe()` — same surface as {@link InspectRunOptions} in MVP. */
+type ObserveOptions = InspectRunOptions;
+/**
+ * Resolved settings for the active run while tracing is enabled.
+ * Populated by runtime code in a later step; defined here for `context.ts`.
+ */
+interface ExecutionContext {
+    runId: string;
+    runName: string;
+    traceDir: string;
+    silent: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Stack position of the step currently executing (used by future context tracking). */
+interface ActiveStepContext {
+    stepId: string;
+    parentId?: string;
+    depth: number;
+}
+/** Returns true if `value` is one of the MVP {@link StepType} literals. */
+declare function isStepType(value: unknown): value is StepType;
+/** Returns true if `value` is one of the MVP {@link StepStatus} literals. */
+declare function isStepStatus(value: unknown): value is StepStatus;
+/**
+ * Narrowing guard for a {@link TraceEvent} object with required MVP fields.
+ * Does not deeply validate optional `metadata` shapes.
+ */
+declare function isTraceEvent(value: unknown): value is TraceEvent;
+
+export { type ActiveStepContext as A, type ErrorInfo as E, type InspectRunOptions as I, type ObserveOptions as O, type RunSummary as R, type StepType as S, type TraceEvent as T, type TraceMetadata as a, type TraceMetadataStatus as b, type StepStatus as c, type TraceCorrelationMetadata as d, type RedactionProfile as e, type StepOptions as f, type ExecutionContext as g, type Run as h, type RunCompletedEvent as i, type RunStartedEvent as j, type RunStatus as k, type Step as l, type StepCompletedEvent as m, type StepMetadata as n, type StepStartedEvent as o, type TokenMetadata as p, type TraceEventBase as q, type TraceSchemaVersion as r, isStepStatus as s, isStepType as t, isTraceEvent as u };