agent-inspect 0.1.0

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

@@ -0,0 +1,324 @@
+/**
+ * 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";
+/** 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;
+/** Options for `inspectRun()` (implemented in a later step). */
+interface InspectRunOptions {
+    traceDir?: string;
+    silent?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** 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;
+
+/** 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.
+ * Under 1000 ms uses whole milliseconds; from 1000 ms uses seconds with one decimal.
+ */
+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;
+
+/** 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;
+/** 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;
+/**
+ * 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>;
+/**
+ * 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>;
+
+/**
+ * Strict MVP validation before writing JSONL. Rejects empty ids, non-finite times, and malformed payloads.
+ */
+declare function validateEvent(event: unknown): event is TraceEvent;
+/** Serializes a trace line as compact JSON without a trailing newline. */
+declare function serializeEvent(event: TraceEvent): string;
+/**
+ * Creates (or truncates) an empty JSONL file for a run. Uses {@link ensureTraceDir} then {@link getTraceFilePath}.
+ * 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.
+ */
+declare function readTraceFile(runId: string, traceDir: string): Promise<string | undefined>;
+/** Parses JSONL into validated {@link TraceEvent} rows; invalid lines are skipped with a warning. */
+declare function readTraceEvents(runId: string, traceDir: string): Promise<TraceEvent[]>;
+/**
+ * Lists `.jsonl` file names in `traceDir`, newest by mtime first (name sort as tie-breaker).
+ */
+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;
+
+/** 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;
+
+/**
+ * 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. */
+type StepFunction = {
+    <T>(name: string, fn: () => Promise<T> | T, options?: StepOptions): Promise<T>;
+    llm: <T>(model: string, fn: () => Promise<T> | T) => Promise<T>;
+    tool: <T>(toolName: string, fn: () => Promise<T> | T) => Promise<T>;
+};
+/**
+ * Traces a named unit of work inside `inspectRun` (`step_started` / `step_completed`, optional terminal).
+ * Outside a run, executes `fn` with a warn only. Preserves return values and rethrows user errors unchanged.
+ *
+ * - `step.llm(model, fn)` — `type: "llm"`, `metadata.model` (no SDK calls or token counting).
+ * - `step.tool(toolName, fn)` — `type: "tool"`, `metadata.toolName` (no framework interception).
+ */
+declare const step: StepFunction;
+
+/**
+ * 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 };