export { C as CreateInspectorOptions, D as DEFAULT_MAX_EVENT_BYTES, f as DEFAULT_MAX_METADATA_VALUE_LENGTH, h as DEFAULT_MAX_PREVIEW_LENGTH, I as Inspector, a as InspectorCaptureOptions, b as InspectorObserveOptions, c as InspectorRunOptions, i as InspectorRuntime, j as InspectorRuntimeContext, k as InspectorRuntimeDiagnostics, l as InspectorRuntimeOptions, d as InspectorStepOptions, T as TraceSafetyOptions, e as createInspector, n as createInspectorRuntime, o as getCurrentContext, g as getCurrentCorrelationMetadata, p as getCurrentDepth, q as getCurrentRunId, r as getCurrentRunName, s as getCurrentStepId, t as getParentStepId, u as getTraceDirFromContext, v as getTraceSafetyFromContext, w as hasActiveContext, x as isAgentInspectEnabled, y as isSilentContext, m as maybeInspectRun, z as prepareMetadataForDisk, A as prepareTraceEventForDisk, B as resolveTraceSafetyOptions, E as runWithContext, F as runWithStepContext } from './context-B7DqUmsJ.js';
import { R as RedactionRule } from './log-config-DAV_sR9A.js';
import { R as RedactionProfile, h as TraceEvent, E as ErrorInfo, b as RunStatus, e as StepStatus, k as RunSummary, l as TraceMetadata, j as TraceMetadataStatus, f as StepType, g as TraceCorrelationMetadata } from './types-BX1EPji1.js';
export { A as ActiveStepContext, i as ExecutionContext, I as InspectRunOptions, O as ObserveOptions, a as Run, m as RunCompletedEvent, n as RunStartedEvent, c as Step, o as StepCompletedEvent, d as StepMetadata, S as StepOptions, p as StepStartedEvent, T as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-BX1EPji1.js';
import { a as InspectRunTree } from './inspect-event-ClM5Z8om.js';
export { b as ATTRIBUTION_CONFIDENCES, c as ATTRIBUTION_CONFIDENCE_RANK, A as AttributionConfidence, E as EventSource, d as InspectEvent, I as InspectKind, e as InspectNode, i as isAttributionConfidence } from './inspect-event-ClM5Z8om.js';
import { P as PersistedInspectEvent } from './persisted-inspect-event-DG02LhEP.js';
import { Stats } from 'node:fs';
import { aZ as SessionWorkflowMetadata, a_ as SessionRunRecord, a$ as EnrichSessionSummaryOptions, b0 as SessionStatus, b1 as SessionSummary, b2 as SessionIndex, b3 as BuildActivitySummaryOptions, b4 as ActivitySummary, b5 as SessionWarning, b6 as BuildSessionIndexOptions, U as TraceCheckResult, _ as TraceCheckStatus, a5 as TraceContractInput, a0 as TraceContract } from './index-CgOAGuM5.js';
export { b7 as ActivityEntry, b8 as CriticalPathStep, b9 as HandoffEdge, ba as RetryLink, bb as SESSION_WORKFLOW_KEYS, bc as SessionCheckSummary, bd as SessionConfidence, be as SessionEdgeSource, bf as SessionGroup, bg as SessionLastError, bh as SessionWorkflowKey } from './index-CgOAGuM5.js';
import { b as ObservedOutcome } from './types-BA_IOdg4.js';
export { a as ObservedOutcomeStatus } from './types-BA_IOdg4.js';
import './writers.js';
import './index-xUbdpcrP.js';

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;

declare function extractOutcomesFromTraceEvents(events: readonly TraceEvent[]): ObservedOutcome[];
declare function extractOutcomesFromPersistedEvents(events: readonly PersistedInspectEvent[]): ObservedOutcome[];

/** Default bound for adapter preview fields (characters). */
declare const DEFAULT_ADAPTER_MAX_PREVIEW_CHARS = 200;
/**
 * Capture policy shared by the official adapters.
 *
 * `metadata-only` is the default everywhere and never persists framework
 * payload content. `preview` opts into bounded, redacted previews.
 */
type AdapterCaptureMode = "metadata-only" | "preview";
/** Stable diagnostic codes emitted by shared preview capture. */
declare const ADAPTER_CAPTURE_DIAGNOSTIC_CODES: readonly ["AI_CAPTURE_FIELD_UNAVAILABLE", "AI_CAPTURE_PREVIEW_TRUNCATED", "AI_CAPTURE_PREVIEW_REDACTED"];
type AdapterCaptureDiagnosticCode = (typeof ADAPTER_CAPTURE_DIAGNOSTIC_CODES)[number];
/** One bounded diagnostic. Never contains preview content or filesystem paths. */
interface AdapterCaptureDiagnostic {
    readonly code: AdapterCaptureDiagnosticCode;
    readonly message: string;
    /** Persisted attribute name the diagnostic refers to (e.g. `inputPreview`). */
    readonly field: string;
    readonly capture: AdapterCaptureMode;
}
/** Optional consumer hook for adapter capture diagnostics. */
type AdapterDiagnosticListener = (diagnostic: AdapterCaptureDiagnostic) => void;
/** Preview capture options accepted by every official adapter. */
interface AdapterPreviewCaptureOptions {
    /** Defaults to `metadata-only`. */
    capture?: AdapterCaptureMode;
    /** Redaction profile applied to preview values before they reach an event. */
    redactionProfile?: RedactionProfile;
    /** Upper bound for each serialized preview field. */
    maxPreviewChars?: number;
    /** Extra adapter-supplied redaction rules. */
    redact?: RedactionRule[];
    /** Receives bounded capture diagnostics. Listener failures are swallowed. */
    onDiagnostic?: AdapterDiagnosticListener;
}
/** Bounded capture counters for adapter `getDiagnostics()` surfaces. */
interface AdapterCaptureDiagnostics {
    readonly capture: AdapterCaptureMode;
    readonly redactionProfile: RedactionProfile;
    readonly maxPreviewChars: number;
    readonly previewFieldsCaptured: number;
    readonly previewFieldsUnavailable: number;
    readonly previewFieldsTruncated: number;
    readonly previewFieldsRedacted: number;
    readonly lastDiagnosticCode?: AdapterCaptureDiagnosticCode;
    readonly lastDiagnosticMessage?: string;
}
/** Shared preview capture handle owned by one adapter instance. */
interface AdapterPreviewCapture {
    /** Effective capture mode (adapters no longer downgrade `preview`). */
    readonly capture: AdapterCaptureMode;
    readonly previewEnabled: boolean;
    readonly maxPreviewChars: number;
    readonly redactionProfile: RedactionProfile;
    /** Normalizes a logical field to a persisted `*Preview` attribute name. */
    previewFieldName(field: string): string;
    /**
     * Returns a bounded, redacted preview string, or `undefined` when capture is
     * metadata-only or the field could not be sourced.
     */
    capturePreviewField(field: string, value: unknown): string | undefined;
    /** Writes every available preview onto `target` and returns it. */
    applyPreviewFields(target: Record<string, unknown>, fields: Record<string, unknown>): Record<string, unknown>;
    getDiagnostics(): AdapterCaptureDiagnostics;
}
/**
 * JSON-ish serialization that tolerates cycles, bigints, and throwing getters,
 * bounded to `maxChars`. Returns `undefined` for a non-positive bound or a
 * value JSON cannot represent.
 */
declare function serializeAdapterPreview(value: unknown, maxChars: number): string | undefined;
/**
 * Resolves the effective preview bound. Profile caps apply so a `share` or
 * `strict` profile cannot be widened by a larger adapter option.
 */
declare function resolveAdapterMaxPreviewChars(value: unknown, profile?: RedactionProfile): number;
/** Creates the shared preview capture handle for one adapter instance. */
declare function createAdapterPreviewCapture(options?: AdapterPreviewCaptureOptions): AdapterPreviewCapture;

/** 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;

/** 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;

/**
 * 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>;
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 (v0.1 native or v0.2 normalized).
 * 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;

type TraceJsonlFormat = "0.1" | "0.2" | "1.0" | "mixed" | "empty";
type ParsedTraceJsonlRow = {
    format: "0.1";
    event: TraceEvent;
    sourceLine: number;
} | {
    format: "0.2";
    event: PersistedInspectEvent;
    sourceLine: number;
} | {
    format: "1.0";
    event: PersistedInspectEvent;
    sourceLine: number;
};
interface ParseTraceJsonlResult {
    format: TraceJsonlFormat;
    /** Count of valid source JSONL rows before any one-to-many normalization. */
    sourceEventCount: number;
    events: TraceEvent[];
    persisted: PersistedInspectEvent[];
    /** Valid source rows in JSONL order, before cross-version normalization. */
    rows: ParsedTraceJsonlRow[];
}
interface ParseTraceJsonlOptions {
    validate?: (value: unknown) => value is TraceEvent;
    /** Emit parse warnings through the standard AgentInspect warning channel (default true). */
    warnings?: boolean;
}
/**
 * Parses JSONL content into normalized v0.1 {@link TraceEvent} rows.
 * Accepts homogenous v0.1, v0.2, or v1.0 files; mixed files are converted with a warning.
 */
declare function parseTraceJsonl(raw: string, options?: ParseTraceJsonlOptions): ParseTraceJsonlResult;
/**
 * Returns a user-facing message when a trace file uses an unsupported schema version.
 */
declare function unknownTraceFormatMessage(): string;

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[];

type TimelineFocus = "all" | "slow";
interface TimelineEntry {
    stepId: string;
    name: string;
    type: StepType;
    status: StepStatus;
    depth: number;
    startedAt: number;
    offsetMs: number;
    durationMs?: number;
    isError: boolean;
    slow?: boolean;
    streaming?: {
        chunkCount?: number;
        streamDurationMs?: number;
        streamedCharCount?: number;
    };
}
interface RunTimeline {
    runId: string;
    name?: string;
    status: TraceMetadataStatus;
    startedAt?: number;
    endedAt?: number;
    durationMs?: number;
    correlation?: {
        correlationId?: string;
        requestId?: string;
        decisionId?: string;
        groupId?: string;
    };
    entries: TimelineEntry[];
}
interface TimelineOptions {
    focus?: TimelineFocus;
    slowTopN?: number;
}
declare function buildRunTimeline(events: readonly TraceEvent[], options?: TimelineOptions): RunTimeline;
interface RenderTimelineOptions {
    focus?: TimelineFocus;
}
declare function renderTimeline(timeline: RunTimeline, options?: RenderTimelineOptions): string;

interface RunWhatSummary {
    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;
        total?: number;
        cached?: number;
        cacheWrite?: number;
        reasoning?: number;
    };
    correlation?: TraceCorrelationMetadata;
    failedStepNames: string[];
    runErrorMessage?: string;
}
/**
 * Build a concise inspection summary for `what` / report workflows.
 * Read-only over in-memory v0.1 {@link TraceEvent} rows.
 */
declare function buildRunWhatSummary(events: TraceEvent[]): RunWhatSummary;
interface RenderWhatOptions {
    /** Include correlation ids when present (default true). */
    correlation?: boolean;
}
/**
 * Render a human-readable `what` summary (plain text, no ANSI).
 */
declare function renderRunWhat(summary: RunWhatSummary, options?: RenderWhatOptions): string;

type CausalFailureKind = "explicit_error_event" | "failed_observed_outcome" | "contract_failure" | "failed_ancestor_or_child" | "none";
interface CausalContractFindingInput {
    ruleId: string;
    status: "fail" | "pass" | "warning" | string;
    /** Linked event/step ids from check evidence. */
    evidenceIds?: string[];
    message?: string;
}
interface FirstCausalFailure {
    kind: CausalFailureKind;
    /** Stable evidence ids (stepId / outcomeId / event-linked ids). No raw paths. */
    evidenceIds: string[];
    rationale: string;
    /** 1–4 when matched; 0 when none. */
    orderIndex: 0 | 1 | 2 | 3 | 4;
    runId?: string;
    primary?: {
        stepId?: string;
        outcomeId?: string;
        ruleId?: string;
        name?: string;
    };
    relationship?: {
        role: "self" | "ancestor" | "child";
        relatedIds: string[];
    };
    engine: "conservative-causal-v1";
}
interface FindFirstCausalFailureOptions {
    /** Optional contract/check failures (step 3). Omitted → skip contract stage. */
    contractFindings?: readonly CausalContractFindingInput[];
}
/**
 * Find the first causal failure using the locked conservative order.
 * Does not infer from timing correlation alone.
 */
declare function findFirstCausalFailure(events: readonly TraceEvent[], options?: FindFirstCausalFailureOptions): FirstCausalFailure;

type ExplainMode = "dry-run" | "local";
interface ExplainFact {
    id: string;
    label: string;
    value: unknown;
    source: "trace";
    confidence: "observed";
}
interface ExplainInference {
    id: string;
    label: string;
    text: string;
    evidence: string[];
    confidence: "deterministic";
}
interface ExplainResult {
    mode: ExplainMode;
    runId: string;
    name?: string;
    status?: string;
    redactionProfile: RedactionProfile;
    facts: ExplainFact[];
    inferences: ExplainInference[];
    notes: string[];
}
interface ExplainOptions {
    mode?: ExplainMode;
    redactionProfile?: RedactionProfile;
}
/**
 * Build a local, deterministic explanation payload from a reader-selected run.
 *
 * This helper performs no network I/O and does not call a model provider.
 */
declare function buildLocalExplanation(run: InspectRunTree, options?: ExplainOptions): ExplainResult;

interface DurationStats {
    minMs?: number;
    maxMs?: number;
    avgMs?: number;
    p50Ms?: number;
    p95Ms?: number;
}
interface TraceStatsRankedRun {
    runId: string;
    name?: string;
    durationMs?: number;
    status: string;
}
interface TraceStatsRankedStep {
    runId: string;
    stepName: string;
    stepType: string;
    durationMs: number;
}
interface TraceStats {
    traceDir: string;
    since?: string;
    correlationId?: string;
    groupId?: string;
    totalRuns: number;
    successCount: number;
    errorCount: number;
    runningCount: number;
    unknownCount: number;
    errorRate: number;
    duration: DurationStats;
    totalSteps: number;
    avgStepsPerRun: number;
    totalLlmSteps: number;
    totalToolSteps: number;
    totalErrorSteps: number;
    slowestRuns: TraceStatsRankedRun[];
    slowestSteps: TraceStatsRankedStep[];
}
interface TraceStatsOptions {
    traceDir: string;
    since?: string;
    correlationId?: string;
    groupId?: string;
    slowRunLimit?: number;
    slowStepLimit?: number;
}
declare function buildTraceStats(metas: TraceMetadata[], options: TraceStatsOptions): Promise<TraceStats>;
/**
 * Formats a step label for display. `step.tool`/`step.llm` already store the
 * name with its type prefix (e.g. "tool:lookup"), while plain `step()` stores a
 * bare name, so prefixing unconditionally would double the prefix. Add the type
 * prefix only when the name does not already carry it, matching what list/view
 * show for the same step.
 */
declare function formatStepLabel(stepType: string, stepName: string): string;
declare function renderTraceStats(stats: TraceStats): string;

interface TraceSearchOptions {
    traceDir: string;
    since?: string;
    status?: "success" | "error" | "running" | "unknown";
    kind?: string;
    type?: string;
    name?: string;
    tool?: string;
    duration?: string;
    limit?: number;
    session?: string;
    correlateGroup?: boolean;
    observation?: string;
}
interface TraceSearchResult {
    runId: string;
    runName?: string;
    runStatus: string;
    stepId?: string;
    stepName?: string;
    stepType?: string;
    timestamp?: number;
    durationMs?: number;
    matchReason: string;
    matchedFields: string[];
    filePath: string;
    sessionId?: string;
}
interface ParsedDurationFilter {
    op: ">" | ">=" | "<" | "<=";
    ms: number;
}
declare function parseDurationFilter(expr: string): ParsedDurationFilter;
declare function searchTraces(metas: TraceMetadata[], options: TraceSearchOptions): Promise<TraceSearchResult[]>;
declare function loadTraceMetadataList(_traceDir: string, fileNames: string[], getPath: (fileName: string) => string): Promise<TraceMetadata[]>;

/** Extracts session/workflow metadata from a run metadata or attributes bag. */
declare function extractSessionWorkflowMetadata(record: Record<string, unknown> | undefined): SessionWorkflowMetadata | undefined;
declare function sessionKeyForRun(meta: SessionWorkflowMetadata | undefined, options?: {
    correlateByGroupId?: boolean;
}): string | undefined;

/** Derives session status from run records per the v4.2 RFC (no timestamp-only causality). */
declare function deriveSessionStatus(runs: readonly SessionRunRecord[], options?: EnrichSessionSummaryOptions): SessionStatus;
/**
 * Enriches a session summary with v4.2 derived fields (status, timing, errors).
 * Pure function; does not read trace files.
 */
declare function enrichSessionSummary(summary: Omit<SessionSummary, "status" | "lastActivity" | "retryCount" | "startedAt" | "endedAt" | "durationMs" | "correlationId" | "jobId" | "workflowId" | "lastError" | "observationSummary" | "checkSummary">, runs: readonly SessionRunRecord[], options?: EnrichSessionSummaryOptions): SessionSummary;

/**
 * Builds a deterministic activity summary from a session index (v4.2).
 * Read-only; does not mutate traces or invent relationships.
 */
declare function buildActivitySummary(index: SessionIndex, options?: BuildActivitySummaryOptions): ActivitySummary;
/** Renders a human activity summary for terminal output. */
declare function renderActivitySummaryHuman(summary: ActivitySummary, options?: {
    nowMs?: number;
}): string;

/** Enriches trace metadata with run_started metadata for session indexing. */
declare function enrichSessionRunRecord(meta: TraceMetadata): Promise<SessionRunRecord>;
/** Builds session run records from extracted trace metadata rows. */
declare function loadSessionRunRecords(metas: readonly TraceMetadata[]): Promise<SessionRunRecord[]>;

interface SessionScopeOptions {
    sessionId?: string;
    groupId?: string;
    correlateByGroupId?: boolean;
}
interface SessionScopeResult {
    metas: TraceMetadata[];
    scopeLabel: string;
    scopeKind: "session" | "group";
    runIds: string[];
    warnings: SessionWarning[];
    notFound: boolean;
}
/** Filters trace metadata rows to runs in a session or group scope. */
declare function filterMetasBySessionScope(metas: readonly TraceMetadata[], records: readonly SessionRunRecord[], options: SessionScopeOptions): SessionScopeResult;
/** Lightweight metadata rows for scope resolution when run_started metadata is absent. */
declare function traceMetasToSessionRunRecords(metas: readonly TraceMetadata[]): SessionRunRecord[];

type SessionCohortKind = "session" | "group";
interface SessionCohort {
    key: string;
    kind: SessionCohortKind;
    runIds: string[];
}
interface GroupSessionCohortsOptions extends BuildSessionIndexOptions {
    groupBy?: "session" | "group";
}
/**
 * Groups runs into session or group cohort buckets for local search/check aggregation.
 * Deterministic; does not infer causality from timestamps.
 */
declare function groupSessionCohorts(runs: readonly SessionRunRecord[], options?: GroupSessionCohortsOptions): SessionCohort[];

interface TraceSessionCheckResult extends TraceCheckResult {
    scopeKind: "session" | "group";
    scopeLabel: string;
    runIds: string[];
    runResults: Array<{
        runId: string;
        status: TraceCheckStatus;
    }>;
    sessionWarnings?: SessionWarning[];
}
/** Aggregates per-run check results for a session or group scope. */
declare function aggregateSessionCheckResults(perRun: readonly TraceCheckResult[], scope: {
    scopeKind: "session" | "group";
    scopeLabel: string;
    runIds: string[];
    sessionWarnings?: SessionWarning[];
    notFound?: boolean;
    empty?: boolean;
}): TraceSessionCheckResult;

/**
 * Builds a deterministic session index from local run records and metadata.
 * Does not read files or infer causality from timestamps alone.
 */
declare function buildSessionIndex(inputRuns: readonly SessionRunRecord[], options?: BuildSessionIndexOptions): SessionIndex;

/**
 * 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;

/** Aggregate verify-safe status for a bundle. */
type BundleSafeStatus = "SAFE" | "SAFE WITH WARNINGS" | "UNSAFE" | "UNKNOWN";
/** Metadata-safe status (underscore form). */
type BundleSafeStatusMetadata = "SAFE" | "SAFE_WITH_WARNINGS" | "UNSAFE" | "UNKNOWN";
type BundleRedactionProfile = "local" | "share" | "strict";
interface BundleMetadata {
    createdAt: string;
    agentInspectVersion: string;
    redactionProfile: BundleRedactionProfile;
    sourceTraceCount: number;
    runIds: string[];
    safeStatus: BundleSafeStatusMetadata;
    files: string[];
    note: string;
    sessionId?: string;
    since?: string;
}
interface BundleRedactionReportRun {
    runId: string;
    findings: number;
    detectors: string[];
}
interface BundleRedactionReport {
    profile: BundleRedactionProfile;
    totalFindings: number;
    runs: BundleRedactionReportRun[];
}
interface BundleCheckRunResult {
    runId: string;
    /** Artifact (redacted) assessment — controls share-safe gating. */
    status: BundleSafeStatus;
    /** Source-trace assessment (informational; may be UNSAFE when artifact is SAFE). */
    sourceStatus?: BundleSafeStatus;
    errors: number;
    warnings: number;
    findings: number;
}
interface BundleCheckResults {
    aggregateStatus: BundleSafeStatus;
    runs: BundleCheckRunResult[];
}
interface BundleResolveOptions {
    runId?: string;
    sessionId?: string;
    since?: string;
}
interface BundleResolveResult {
    runIds: string[];
    sessionId?: string;
    since?: string;
}
interface BundlePlaceholderArtifact {
    status: "not_requested";
    note: string;
}

/**
 * Resolves which run ids belong in a bundle.
 *
 * @throws when target mode is missing, ambiguous, or yields zero runs.
 */
declare function resolveBundleRunIds(index: SessionIndex, runs: readonly SessionRunRecord[], options: BundleResolveOptions): BundleResolveResult;

declare function buildBundleMetadata(parts: {
    agentInspectVersion: string;
    profile: BundleRedactionProfile;
    resolve: BundleResolveResult;
    checks: BundleCheckResults;
    files: string[];
    createdAt?: string;
}): BundleMetadata;
declare function buildPlaceholderArtifact(): BundlePlaceholderArtifact;

/**
 * Builds a human-readable bundle summary for `summary.md`.
 */
declare function buildBundleSummaryMarkdown(parts: {
    metadata: BundleMetadata;
    checks: BundleCheckResults;
    redaction: BundleRedactionReport;
}): string;

declare function aggregateBundleSafeStatus(statuses: readonly BundleSafeStatus[]): BundleSafeStatus;
declare function toMetadataSafeStatus(status: BundleSafeStatus): BundleSafeStatusMetadata;
declare function bundleFailsOnSafety(status: BundleSafeStatus, allowUnsafe: boolean): boolean;

/**
 * Sanitizes a run id for bundle directory and asset filenames.
 * Strips path segments and replaces unsafe characters.
 */
declare function sanitizeBundleRunId(runId: string): string;
/**
 * Relative POSIX path for a run asset inside a bundle directory.
 */
declare function bundleRunAssetRelativePath(runId: string, extension: string): string;
/**
 * Ensures a relative bundle path resolves inside the output directory.
 */
declare function assertBundlePathContained(outputDir: string, relativePath: string): string;
/**
 * Normalizes bundle output path.
 * For directory/html modes, strips a trailing `.zip` suffix (folder-first).
 * Pass `preserveZipExtension: true` for `--format zip`.
 */
declare function normalizeBundleOutputPath(out: string, options?: {
    preserveZipExtension?: boolean;
}): string;
/**
 * Default bundle directory when --out is omitted.
 */
declare function defaultBundleOutputPath(runIds: readonly string[]): string;

/** Portable Evidence v2 (`evidenceFormatVersion`) — independent of trace schema. */
type EvidenceFormatVersion = "1.0";
type EvidenceSafeStatus = "SAFE" | "SAFE WITH WARNINGS" | "UNSAFE" | "UNKNOWN";
type EvidenceRedactionProfile = "local" | "share" | "strict";
type EvidenceVerificationPolicy = "development" | "local" | "share" | "strict";
type EvidenceFileRole = "report" | "redacted-trace" | "checks" | "contract" | "redaction-report" | "summary" | "other";
/** How a packaged contract/preset was supplied (6.28+). */
type EvidenceContractBindingSource = "file" | "inline" | "preset" | "cli-shorthand" | "programmatic";
/** Reproducibility honesty for contract binding (6.28+). */
type EvidenceContractBindingStatus = "complete" | "partial" | "unavailable";
/**
 * Optional Evidence v2 contract binding (6.28+).
 * Additive; older readers ignore unknown fields. Not a signature or trusted-time claim.
 */
interface EvidenceContractBinding {
    status: EvidenceContractBindingStatus;
    source: EvidenceContractBindingSource;
    contractId?: string;
    contractVersion?: string;
    canonicalizationVersion: "1";
    engineVersion: string;
    /** Relative packaged path (typically `contract.resolved.json`). */
    path?: string;
    /** SHA-256 of the packaged resolved-contract bytes. */
    sha256?: string;
    ruleIds: string[];
    unsupportedRuleIds?: string[];
    note?: string;
}
/**
 * Optional fields embedded in `check-results.json` to bind results to a contract digest.
 */
interface EvidenceCheckContractBinding {
    contractDigest?: string;
    canonicalizationVersion?: "1";
    engineVersion?: string;
    evaluatedRuleIds?: string[];
    bindingStatus?: EvidenceContractBindingStatus;
    unsupportedRuleIds?: string[];
    origin?: {
        source: EvidenceContractBindingSource;
        preset?: string;
        path?: string;
    };
    selectedScope?: Record<string, unknown>;
    selectedAlternativeBranch?: string;
}
interface EvidenceSourceHash {
    runId: string;
    algorithm: "sha256";
    hash: string;
}
interface EvidenceFileEntry {
    path: string;
    sha256: string;
    role?: EvidenceFileRole;
}
interface EvidenceManifest {
    evidenceFormatVersion: EvidenceFormatVersion;
    generator: {
        name: string;
        version: string;
    };
    createdAt?: string;
    source: {
        runIds: string[];
        traceSchemaVersions: string[];
        sourceHashes: EvidenceSourceHash[];
    };
    policy: {
        redactionProfile: EvidenceRedactionProfile;
        verificationPolicy: EvidenceVerificationPolicy;
    };
    assessment: {
        status: EvidenceSafeStatus;
        sourceStatus?: EvidenceSafeStatus;
        note?: string;
    };
    /**
     * Optional TraceFacts / logical-projection summary (6.14+).
     * Additive; older readers ignore unknown fields.
     */
    semantics?: EvidenceSemantics;
    /**
     * Optional resolved-contract binding (6.28+).
     * Additive; older readers ignore unknown fields.
     */
    contract?: EvidenceContractBinding;
    files: EvidenceFileEntry[];
}
/**
 * Bounded semantic summary embedded in Evidence v2 (mirrors check parity summary).
 * Does not embed raw events or prompts.
 */
interface EvidenceSemantics {
    projectionVersion?: string;
    rawEventCount?: number;
    logicalEventCount?: number;
    runningLogicalCount?: number;
    finishedToolCount?: number;
    finishedToolNames?: string[];
    pairedCount?: number;
    parentRemapCount?: number;
    contractStatus?: "pass" | "fail" | "error";
    /**
     * Bounded derived failure role counts (6.19+). IDs and error bodies omitted.
     *
     * @experimental
     */
    failureRoleCounts?: {
        transient: number;
        recovered: number;
        terminal: number;
        unknown: number;
    };
}
interface EvidencePackagedFile {
    /** Relative POSIX path inside the evidence/bundle directory. */
    path: string;
    /** Exact bytes that will be / were written. */
    content: string | Uint8Array;
    role?: EvidenceFileRole;
}
declare const EVIDENCE_FORMAT_VERSION: EvidenceFormatVersion;
declare const EVIDENCE_ASSESSMENT_NOTE = "Best-effort local safety verification only; not a compliance certification.";
declare const EVIDENCE_MANIFEST_FILENAME = "evidence.json";
/** Packaged resolved TraceContract / check-preset snapshot (6.28+). */
declare const EVIDENCE_RESOLVED_CONTRACT_FILENAME = "contract.resolved.json";

/**
 * SHA-256 hex digest of exact bytes (UTF-8 when `data` is a string).
 */
declare function sha256Hex(data: string | Uint8Array): string;
declare function isSha256Hex(value: string): boolean;
/**
 * Constant-time-ish equality for hex digests (length-checked; not for secrets).
 */
declare function sha256Equals(expected: string, actual: string): boolean;

/**
 * Validates a relative evidence/bundle path: no absolute paths, no `..`, POSIX separators.
 * Returns the normalized POSIX relative path.
 */
declare function assertEvidenceRelativePath(relativePath: string): string;

/**
 * Deterministic JSON serialization used for evidence manifests (trailing newline).
 */
declare function serializeEvidenceManifest(manifest: EvidenceManifest): string;
declare function inferEvidenceFileRole(relativePath: string): EvidenceFileRole;
/**
 * Hash packaged file bytes into Evidence `files[]` entries (sorted by path).
 * Rejects `evidence.json` itself (manifest is not self-hashed).
 */
declare function buildEvidenceFileEntries(files: readonly EvidencePackagedFile[]): EvidenceFileEntry[];
declare function buildEvidenceManifest(parts: {
    generatorVersion: string;
    generatorName?: string;
    runIds: readonly string[];
    traceSchemaVersions: readonly string[];
    sourceHashes: readonly EvidenceSourceHash[];
    redactionProfile: EvidenceRedactionProfile;
    verificationPolicy?: EvidenceVerificationPolicy;
    assessmentStatus: EvidenceSafeStatus;
    sourceStatus?: EvidenceSafeStatus;
    files: readonly EvidencePackagedFile[];
    createdAt?: string;
    note?: string;
    semantics?: EvidenceManifest["semantics"];
    contract?: EvidenceManifest["contract"];
}): EvidenceManifest;
/**
 * Minimal structural validation for a parsed evidence manifest object.
 * Unknown fields are preserved by returning the cast value after checks.
 */
declare function validateEvidenceManifest(value: unknown): EvidenceManifest;
declare function parseEvidenceManifestJson(text: string): EvidenceManifest;
/**
 * Collect unique `schemaVersion` values from agent-inspect JSONL text.
 */
declare function collectTraceSchemaVersions(jsonl: string): string[];

/**
 * Evidence v2 contract binding (6.28) — package a resolved serializable
 * TraceContract / check-preset snapshot and bind its digest to check results.
 *
 * Does not claim producer identity, trusted time, or semantic proof.
 */

declare const EVIDENCE_CONTRACT_CANONICALIZATION_VERSION: "1";
declare const EVIDENCE_CONTRACT_PARTIAL_NOTE = "Custom or programmatic rules are not serializable; Evidence records rule IDs only and does not claim complete reviewer replay.";
declare const EVIDENCE_CONTRACT_UNAVAILABLE_NOTE = "No resolved TraceContract or check preset was packaged with this Evidence artifact.";
declare const EVIDENCE_CONTRACT_ASSURANCE_NOTE = "Contract binding verifies packaged digest integrity only; it does not prove producer identity, trusted time, source completeness, semantic truth, or external acceptance.";
/** Deterministic JSON (sorted keys) with trailing newline. */
declare function serializeCanonicalJson(value: unknown): string;
/**
 * Normalize TraceContract aliases and make common evaluator defaults explicit
 * for canonicalization version `"1"`.
 */
declare function resolveSerializableTraceContract(input: TraceContractInput | TraceContract): TraceContract;
/**
 * Static rule-id inventory implied by a resolved TraceContract (no evaluation).
 */
declare function collectResolvedContractRuleIds(contract: TraceContract): string[];
interface ResolvedContractDocument {
    canonicalizationVersion: typeof EVIDENCE_CONTRACT_CANONICALIZATION_VERSION;
    kind: "trace-contract" | "check-preset";
    resolved: Record<string, unknown>;
    origin: {
        source: EvidenceContractBindingSource;
        preset?: string;
        path?: string;
    };
}
interface BuildEvidenceContractPackageInput {
    engineVersion: string;
    source: EvidenceContractBindingSource;
    /** Serializable TraceContract (preferred for `complete`). */
    contract?: TraceContractInput | TraceContract;
    /**
     * Pre-resolved check preset / CLI shorthand snapshot (caller expands).
     * Used when `contract` is omitted or as origin metadata beside a contract.
     */
    preset?: {
        name: string;
        resolved: Record<string, unknown>;
    };
    /** Original config path (omit or redact when sensitive). */
    path?: string;
    contractId?: string;
    contractVersion?: string;
    /**
     * Stable IDs for programmatic / custom rules that cannot be serialized.
     * Presence forces `status: "partial"`.
     */
    unsupportedRuleIds?: readonly string[];
    /** Override rule ID list (defaults to static inventory from the contract / preset select). */
    ruleIds?: readonly string[];
    note?: string;
}
interface EvidenceContractPackage {
    /** Packaged `contract.resolved.json` when a serializable snapshot exists. */
    file?: EvidencePackagedFile;
    binding: EvidenceContractBinding;
    /** Fields to merge into `check-results.json`. */
    checkBinding: EvidenceCheckContractBinding;
    /** Canonical document bytes when packaged (same as `file.content`). */
    resolvedJson?: string;
}
/**
 * Build a resolved contract artifact + Evidence binding for packaging.
 *
 * Pass no `contract` and no `preset` to record an honest `unavailable` binding
 * (missing-contract case). Pass `unsupportedRuleIds` to force `partial`.
 */
declare function buildEvidenceContractPackage(input: BuildEvidenceContractPackageInput): EvidenceContractPackage;
/**
 * Merge contract-binding fields into a check-results JSON object (additive).
 */
declare function bindCheckResultsToContract(checkResults: Record<string, unknown>, checkBinding: EvidenceCheckContractBinding): Record<string, unknown>;
declare function serializeCheckResultsJson(value: unknown): string;
/**
 * Parse the optional `contract` object from check-results.json when present.
 */
declare function readCheckResultsContractBinding(checkResultsJson: string): EvidenceCheckContractBinding | undefined;
interface EvidenceContractVerifyIssue {
    code: "contract_file_missing" | "contract_hash_mismatch" | "contract_digest_mismatch" | "contract_binding_invalid";
    severity: "error" | "warning";
    message: string;
    path?: string;
}
/**
 * Verify digest binding between manifest.contract, contract.resolved.json, and
 * check-results.json. Older Evidence without `manifest.contract` is a no-op.
 */
declare function verifyEvidenceContractBinding(parts: {
    binding?: EvidenceContractBinding;
    resolvedContractBytes?: string | Uint8Array;
    checkResultsJson?: string;
}): EvidenceContractVerifyIssue[];

declare const EVIDENCE_HTML_FILENAME = "evidence.html";
/** View ids reserved for later 6.10 chunks; shell renders stubs except summary. */
declare const EVIDENCE_VIEW_IDS: readonly ["summary", "tree", "timeline", "causal", "tools-llm", "outcomes", "contracts", "circuit", "diff", "safety", "provenance"];
type EvidenceViewId = (typeof EVIDENCE_VIEW_IDS)[number];
interface EvidenceHtmlShellInput {
    title?: string;
    runIds: readonly string[];
    assessmentStatus: EvidenceSafeStatus;
    sourceStatus?: EvidenceSafeStatus;
    redactionProfile: string;
    verificationPolicy: string;
    generatorName: string;
    generatorVersion: string;
    createdAt?: string;
    evidenceFormatVersion?: string;
    /** Optional short summary markdown already safe for display (will be escaped). */
    summaryText?: string;
    /** Bounded check counts (no finding payloads / prompts). */
    checkSummary?: {
        aggregateStatus: EvidenceSafeStatus;
        runs: readonly {
            runId: string;
            status: EvidenceSafeStatus;
            sourceStatus?: EvidenceSafeStatus;
            errors: number;
            warnings: number;
            findings: number;
        }[];
    };
    /** Max chars for embedded JSON payload (default 64 KiB). */
    maxEmbeddedJsonChars?: number;
    /**
     * Pre-escaped HTML bodies for views. Missing ids keep the stub panel.
     * Callers must pass only trusted, escaped fragments (use evidence view builders).
     */
    viewBodies?: Partial<Record<EvidenceViewId, string>>;
    /**
     * Safe contract-binding metadata only (status / digest / note). Never embed
     * expected-value payloads in HTML (6.29.3).
     */
    contractBinding?: {
        status: string;
        sha256?: string;
        note?: string;
        ruleCount?: number;
    };
}
/**
 * Encode JSON for embedding in HTML without breaking out of a script/pre context.
 * Escapes `<` so `</script>` cannot appear in payload text.
 */
declare function encodeEmbeddedEvidenceJson(value: unknown): string;
/**
 * Build a self-contained offline `evidence.html` shell (no external assets/network).
 * View panels beyond Summary are stubs filled in later 6.10 chunks.
 */
declare function buildEvidenceHtmlShell(input: EvidenceHtmlShellInput): string;
/**
 * Convenience: build shell fields from an EvidenceManifest (views still stubbed).
 */
declare function buildEvidenceHtmlShellFromManifest(manifest: EvidenceManifest, extras?: Partial<Pick<EvidenceHtmlShellInput, "summaryText" | "checkSummary" | "title" | "viewBodies">>): string;

/**
 * Execution-tree HTML fragment for the Evidence Tree view (already escaped).
 */
declare function buildEvidenceTreeViewHtml(trees: readonly InspectRunTree[]): string;
/**
 * Timeline / waterfall HTML fragment (escaped; no external assets).
 */
declare function buildEvidenceTimelineViewHtml(trees: readonly InspectRunTree[]): string;
/**
 * First causal failure view: earliest error by timestamp, with parent chain.
 * Does not invent relationships; if no parentId chain exists, shows the error alone.
 */
declare function buildEvidenceCausalFailureViewHtml(trees: readonly InspectRunTree[]): string;
/** Extra CSS for tree / timeline / causal panels (inlined into evidence shell). */
declare const EVIDENCE_VIEW_CSS: string;

interface EvidenceCheckFindingSummary {
    runId: string;
    ruleId: string;
    severity: string;
    message: string;
    category?: string;
    detector?: string;
    confidence?: string;
    action?: string;
}
interface EvidenceContractsViewInput {
    aggregateStatus: string;
    runs: readonly {
        runId: string;
        status: string;
        sourceStatus?: string;
        errors: number;
        warnings: number;
        findings: number;
    }[];
    findingSummaries?: readonly EvidenceCheckFindingSummary[];
}
/**
 * Contracts / checks HTML: aggregate status + bounded finding taxonomy (no evidence payloads).
 */
declare function buildEvidenceContractsViewHtml(input: EvidenceContractsViewInput): string;
/**
 * Observed outcomes view from persisted inspect events (redacted artifact).
 */
declare function buildEvidenceOutcomesViewHtml(runs: readonly {
    runId: string;
    events: readonly PersistedInspectEvent[];
}[]): string;
/**
 * Diff view: when two event sets are supplied, render a local run diff.
 * Otherwise show an empty-state explaining baseline/candidate is optional.
 */
declare function buildEvidenceDiffViewHtml(parts?: {
    leftRunId: string;
    rightRunId: string;
    leftEvents: readonly PersistedInspectEvent[];
    rightEvents: readonly PersistedInspectEvent[];
}): string;

interface EvidenceSafetyViewInput {
    artifactStatus: EvidenceSafeStatus | string;
    sourceStatus?: EvidenceSafeStatus | string;
    redactionProfile: string;
    verificationPolicy: string;
    redaction?: {
        totalFindings: number;
        runs: readonly {
            runId: string;
            findings: number;
            detectors: string[];
        }[];
    };
    findingSummaries?: readonly EvidenceCheckFindingSummary[];
}
interface EvidenceProvenanceViewInput {
    generatorName: string;
    generatorVersion: string;
    evidenceFormatVersion: string;
    createdAt?: string;
    runIds: readonly string[];
    traceSchemaVersions: readonly string[];
    sourceHashes: readonly EvidenceSourceHash[];
    packagedFiles: readonly {
        path: string;
        role?: string;
    }[];
    note?: string;
}
/**
 * Safety / redaction view: artifact vs source status + detector summary (no raw secrets).
 */
declare function buildEvidenceSafetyViewHtml(input: EvidenceSafetyViewInput): string;
/**
 * Provenance / mapping view: generator, schema versions, source hashes, packaged roles.
 */
declare function buildEvidenceProvenanceViewHtml(input: EvidenceProvenanceViewInput): string;
/**
 * Tools / LLM metadata view: names, kinds, statuses, durations — no prompts/outputs.
 */
declare function buildEvidenceToolsLlmViewHtml(trees: readonly InspectRunTree[]): string;
/**
 * Circuit / guardrails placeholder filled with conservative empty state unless findings supplied.
 */
declare function buildEvidenceCircuitViewHtml(parts?: {
    findings?: readonly {
        runId: string;
        name: string;
        status: string;
        detail?: string;
    }[];
}): string;

interface ZipEntry {
    path: string;
    content: string | Uint8Array;
}
/**
 * Build a minimal ZIP archive (STORE method) with traversal-safe relative paths.
 * No external dependencies — suitable for Evidence `--format zip`.
 */
declare function buildZipArchive(entries: readonly ZipEntry[]): Buffer;

type EvidenceVerifyStatus = "pass" | "fail";
interface EvidenceVerifyIssue {
    code: "manifest_missing" | "manifest_invalid" | "file_missing" | "file_unexpected" | "hash_mismatch" | "assessment_missing" | "provenance_missing" | "path_unsafe" | "io_error" | "contract_file_missing" | "contract_hash_mismatch" | "contract_digest_mismatch" | "contract_binding_invalid";
    severity: "error" | "warning";
    message: string;
    path?: string;
}
interface EvidenceVerifyResult {
    ok: boolean;
    status: EvidenceVerifyStatus;
    root: string;
    manifest?: EvidenceManifest;
    issues: EvidenceVerifyIssue[];
    checkedFiles: number;
}
interface EvidenceVerifyOptions {
    /** Unexpected files: default fail for share/strict-style verification. */
    unexpectedFiles?: "fail" | "warn" | "ignore";
}
/**
 * Verify an Evidence v2 directory (contains `evidence.json`).
 * Does not extract ZIP archives — callers should unpack first when needed.
 */
declare function verifyEvidenceDirectory(rootPath: string, options?: EvidenceVerifyOptions): Promise<EvidenceVerifyResult>;

interface EvidenceCiPackageInput {
    generatorVersion: string;
    runIds: readonly string[];
    /** Pre-redaction source bytes keyed by run id (for sourceHashes). */
    sourceContents: ReadonlyMap<string, string> | Record<string, string>;
    /** Redacted combined JSONL written as trace.jsonl. */
    redactedTraceJsonl: string;
    redactionProfile: "local" | "share" | "strict";
    assessmentStatus: EvidenceSafeStatus;
    sourceStatus?: EvidenceSafeStatus;
    checkResultsJson: string;
    createdAt?: string;
    summaryText?: string;
    /** Optional TraceFacts/parity summary embedded in evidence.json (6.14+). */
    semantics?: EvidenceManifest["semantics"];
    /**
     * Optional TraceContract / preset binding (6.28+).
     * When omitted, no contract section is written (older Evidence shape).
     * Pass `{ engineVersion, source }` with neither contract nor preset to record `unavailable`.
     */
    contractPackage?: BuildEvidenceContractPackageInput;
}
interface EvidenceCiPackageFiles {
    "evidence.html": string;
    "evidence.json": string;
    "check-results.json": string;
    "trace.jsonl": string;
    "contract.resolved.json"?: string;
    manifest: EvidenceManifest;
}
/**
 * Build the standard CI evidence files (in memory) using Evidence v2 helpers.
 * Order (6.29.3): resolve → safety → bind → HTML → manifest last.
 * Optionally packages `contract.resolved.json` and binds digests (6.28+).
 */
declare function buildEvidenceCiPackage(input: EvidenceCiPackageInput): EvidenceCiPackageFiles;

type SuiteCaseStatus = "pass" | "fail" | "error" | "skipped";
type SuiteDiagnosticCode = "AI_SUITE_CONFIG_INVALID" | "AI_SUITE_CONFIG_LOAD_FAILED" | "AI_SUITE_CASE_TRACE_MISSING" | "AI_SUITE_CASE_CHECK_FAILED" | "AI_SUITE_CASE_EVAL_FAILED" | "AI_SUITE_CASE_OBSERVATION_FAILED" | "AI_SUITE_TRACE_UNREADABLE";
interface SuiteDiagnostic {
    code: SuiteDiagnosticCode;
    severity: "error" | "warning" | "info";
    message: string;
    caseId?: string;
}
interface SuiteCaseConfig {
    id: string;
    trace?: string;
    runId?: string;
    input?: string;
    requireTools?: string[];
    forbidTools?: string[];
    maxDurationMs?: number;
    expectedObservations?: string[];
}
interface SuiteChecksConfig {
    select?: string[];
    run?: {
        maxDurationMs?: number;
        maxDepth?: number;
    };
    tool?: {
        required?: string[];
        forbidden?: string[];
    };
    llm?: {
        allowedModels?: string[];
        maxTotalTokens?: number;
    };
}
interface SuiteEvalConfig {
    requireSuccess?: boolean;
    requiredTools?: string[];
    forbiddenTools?: string[];
    maxDurationMs?: number;
    maxDepth?: number;
    maxRetries?: number;
    maxTotalTokens?: number;
}
interface SuiteArtifactsConfig {
    outputDir?: string;
}
interface SuiteConfig {
    name: string;
    traces: string;
    cases: SuiteCaseConfig[];
    checks?: SuiteChecksConfig;
    eval?: SuiteEvalConfig;
    redactionProfile?: RedactionProfile;
    artifacts?: SuiteArtifactsConfig;
    baseline?: string;
    candidate?: string;
}
interface SuiteCaseResult {
    id: string;
    status: SuiteCaseStatus;
    tracePath?: string;
    runId?: string;
    checkOk?: boolean;
    evalOk?: boolean;
    observationsOk?: boolean;
    message?: string;
    diagnostics: SuiteDiagnostic[];
}
interface SuiteRunSummary {
    passed: number;
    failed: number;
    errors: number;
    skipped: number;
}
interface SuiteRunResult {
    ok: boolean;
    status: "pass" | "fail" | "error";
    suiteName: string;
    configPath: string;
    tracesDir: string;
    startedAt: string;
    finishedAt: string;
    summary: SuiteRunSummary;
    cases: SuiteCaseResult[];
    diagnostics: SuiteDiagnostic[];
}
interface LoadSuiteConfigOptions {
    configPath?: string;
    cwd?: string;
}
interface ValidateSuiteConfigResult {
    ok: boolean;
    diagnostics: SuiteDiagnostic[];
}
interface RunSuiteOptions {
    configPath?: string;
    cwd?: string;
    nowMs?: number;
}
interface RenderSuiteReportOptions {
    format?: "markdown" | "json";
}
declare const DEFAULT_SUITE_CONFIG_NAMES: readonly ["agent-inspect.suite.json", "agent-inspect.suite.js", "agent-inspect.suite.mjs", "agent-inspect.suite.cjs"];
declare const DEFAULT_SUITE_ARTIFACTS_DIR = ".agent-inspect/suite-runs";

declare function resolveSuiteConfigPath(options?: LoadSuiteConfigOptions): Promise<string>;
declare function loadSuiteConfig(options?: LoadSuiteConfigOptions): Promise<{
    config: SuiteConfig;
    configPath: string;
    configDir: string;
}>;
declare function defaultSuiteConfigTemplate(): SuiteConfig;

declare function normalizeSuiteConfig(value: unknown): SuiteConfig;
declare function validateSuiteConfig(config: SuiteConfig, options: {
    configDir: string;
}): Promise<ValidateSuiteConfigResult>;

interface ResolvedSuiteCase {
    caseId: string;
    tracePath?: string;
    runId?: string;
    missing: boolean;
    reason?: string;
}
declare function resolveSuiteCaseTrace(suiteCase: SuiteCaseConfig, options: {
    configDir: string;
    tracesDir: string;
}): Promise<ResolvedSuiteCase>;

declare function runSuite(options?: RunSuiteOptions): Promise<SuiteRunResult>;

declare function renderSuiteReportMarkdown(result: SuiteRunResult): string;
declare function renderSuiteReport(result: SuiteRunResult, options?: RenderSuiteReportOptions): string;

declare const SUITE_TEMPLATE_IDS: readonly ["customer-support-agent", "refund-agent", "sales-assistant", "browser-task-agent", "mcp-tool-agent", "workflow-agent", "rag-answer-agent", "human-approval-agent"];
type SuiteTemplateId = (typeof SUITE_TEMPLATE_IDS)[number];
declare function listSuiteTemplates(): SuiteTemplateId[];
declare function getSuiteTemplate(id: string): SuiteConfig | undefined;
declare function resolveSuiteTemplate(id: string): SuiteConfig;

type CohortMetricId = "errorRate" | "duration" | "toolChoice" | "toolOrdering" | "llmCallCount" | "tokenUsage" | "retryCount" | "observationFailure" | "guardrailFailure" | "circuitViolation" | "redactionWarning";
declare const COHORT_METRIC_IDS: readonly CohortMetricId[];
interface CohortRunMetrics {
    runId: string;
    cohortLabel?: string;
    groupKey: string;
    status: TraceMetadataStatus;
    error: boolean;
    durationMs?: number;
    llmCallCount: number;
    tokenUsageTotal?: number;
    retryCount: number;
    observationFailures: number;
    guardrailFailures: number;
    circuitViolations: number;
    redactionWarnings: number;
    toolChoices: string[];
    toolOrdering: string[];
}
interface CohortAggregateMetrics {
    groupKey: string;
    cohortLabel?: string;
    runCount: number;
    errorRate: number;
    avgDurationMs?: number;
    p95DurationMs?: number;
    avgLlmCallCount: number;
    avgTokenUsage?: number;
    avgRetryCount: number;
    observationFailureRate: number;
    avgGuardrailFailures: number;
    avgCircuitViolations: number;
    avgRedactionWarnings: number;
    dominantToolChoice?: string;
    toolOrderingSignature?: string;
}
interface CohortMetricComparison {
    metric: CohortMetricId;
    baseline?: number | string;
    candidate?: number | string;
    delta?: number | string;
    regression: boolean;
    message: string;
}
interface CohortAnalysisResult {
    ok: boolean;
    traceDir: string;
    baseline?: string;
    candidate?: string;
    cohortKey: string;
    groupBy: string;
    metrics: CohortMetricId[];
    groups: CohortAggregateMetrics[];
    comparisons: CohortMetricComparison[];
    runs: CohortRunMetrics[];
    warnings: string[];
}
interface CohortToleranceOptions {
    /** Minimum runs per cohort label before comparisons are considered valid. */
    minSampleSize?: number;
    /** Allowed relative delta (0–1) before a metric comparison is a regression. */
    maxRelativeDelta?: number;
}
interface AnalyzeCohortOptions {
    traceDir: string;
    baseline?: string;
    candidate?: string;
    cohortKey?: string;
    groupBy?: string;
    metrics?: CohortMetricId[];
    tolerance?: CohortToleranceOptions;
}
interface RenderCohortReportOptions {
    format?: "markdown" | "json" | "html";
}

declare function analyzeCohort(runsInput: readonly SessionRunRecord[], options: AnalyzeCohortOptions): Promise<CohortAnalysisResult>;

declare function compareCohortAggregates(groups: readonly CohortAggregateMetrics[], options: {
    baseline: string;
    candidate: string;
    metrics: readonly CohortMetricId[];
    groupKey?: string;
    maxRelativeDelta?: number;
}): CohortMetricComparison[];

declare function parseCohortMetricList(value: string | undefined): string[];
declare function parseGroupBySpec(groupBy: string | undefined): {
    kind: "model" | "session" | "group" | "metadata";
    metadataKey?: string;
};

declare function renderCohortSummaryMarkdown(result: CohortAnalysisResult): string;
declare function renderCohortReport(result: CohortAnalysisResult, options?: RenderCohortReportOptions): string;

type GateExitCode = 0 | 1 | 2 | 3 | 4;
type GateCheckId = "suite" | "maxErrorRate" | "maxP95Duration" | "forbidTool" | "requireObservation";
interface GateCheckResult {
    id: GateCheckId;
    name: string;
    ok: boolean;
    message: string;
    expected?: string | number;
    actual?: string | number;
    runId?: string;
}
interface GateResult {
    ok: boolean;
    exitCode: GateExitCode;
    traceDir?: string;
    suitePath?: string;
    runCount: number;
    checks: GateCheckResult[];
    diagnostics: string[];
    suiteResult?: SuiteRunResult;
}
interface RunGateOptions {
    traceDir?: string;
    suitePath?: string;
    cwd?: string;
    maxErrorRate?: number;
    maxP95DurationMs?: number;
    forbidTools?: string[];
    requireObservations?: string[];
}
interface RenderGateReportOptions {
    format?: "markdown" | "json" | "json-compact" | "html" | "junit" | "github" | "github-annotations";
}

declare function parseGateList(value: string | undefined): string[];
declare function parseGateNumber(value: string | undefined, label: string, options?: {
    min?: number;
    max?: number;
}): number | undefined;

declare function gateHasThresholds(options: RunGateOptions): boolean;

declare function runGate(runs: readonly SessionRunRecord[], options: RunGateOptions): Promise<GateResult>;

declare function renderGateSummaryMarkdown(result: GateResult): string;
declare function renderGateGithubStepSummary(result: GateResult): string;
declare function renderGateJUnit(result: GateResult): string;
/**
 * Compact GitHub Actions workflow-command annotations for failed checks.
 * File/line are omitted when the gate has no source locations (typical for
 * trajectory thresholds).
 */
declare function renderGateGithubAnnotations(result: GateResult): string;
declare function renderGateReport(result: GateResult, options?: RenderGateReportOptions): string;

/**
 * Optional omitted-payload digest commitment helpers (6.22; preflight bound in 6.25.1).
 *
 * A digest proves bytes were observed/omitted; it is not redaction, authorization,
 * or a secret-management feature. AgentInspect does not hold HMAC keys.
 *
 * @experimental Available through `agent-inspect/advanced`.
 */
type OmittedPayloadAlgorithm = "sha256";
/**
 * Bounded commitment recorded when payload bytes are intentionally omitted.
 *
 * @experimental
 */
interface OmittedPayloadCommitment {
    algorithm: OmittedPayloadAlgorithm;
    digest: string;
    byteLength: number;
    contentType?: string;
    shape?: string;
    capturePolicy: "omitted" | "preview-only" | "digest-only";
}
/** Maximum input size accepted for digest commitment (1 MiB). */
declare const OMITTED_PAYLOAD_MAX_DIGEST_INPUT_BYTES: number;
/**
 * Preflight byte length without allocating a full Buffer copy for oversized input.
 */
declare function omittedPayloadByteLength(payload: string | Uint8Array): number;
/**
 * Build a SHA-256 digest commitment for omitted payload bytes.
 * Throws if input exceeds the 1 MiB bound (checked before copying oversized strings).
 */
declare function createOmittedPayloadCommitment(payload: string | Uint8Array, options?: {
    contentType?: string;
    shape?: string;
    capturePolicy?: OmittedPayloadCommitment["capturePolicy"];
}): OmittedPayloadCommitment;

export { ADAPTER_CAPTURE_DIAGNOSTIC_CODES, ActivitySummary, type AdapterCaptureDiagnostic, type AdapterCaptureDiagnosticCode, type AdapterCaptureDiagnostics, type AdapterCaptureMode, type AdapterDiagnosticListener, type AdapterPreviewCapture, type AdapterPreviewCaptureOptions, type AnalyzeCohortOptions, BuildActivitySummaryOptions, type BuildEvidenceContractPackageInput, BuildSessionIndexOptions, type BundleCheckResults, type BundleCheckRunResult, type BundleMetadata, type BundlePlaceholderArtifact, type BundleRedactionProfile, type BundleRedactionReport, type BundleRedactionReportRun, type BundleResolveOptions, type BundleResolveResult, type BundleSafeStatus, type BundleSafeStatusMetadata, COHORT_METRIC_IDS, type CausalContractFindingInput, type CausalFailureKind, type CohortAggregateMetrics, type CohortAnalysisResult, type CohortMetricComparison, type CohortMetricId, type CohortRunMetrics, DEFAULT_ADAPTER_MAX_PREVIEW_CHARS, DEFAULT_SUITE_ARTIFACTS_DIR, DEFAULT_SUITE_CONFIG_NAMES, DEFAULT_TRACE_DIR_NAME, type DurationStats, EVIDENCE_ASSESSMENT_NOTE, EVIDENCE_CONTRACT_ASSURANCE_NOTE, EVIDENCE_CONTRACT_CANONICALIZATION_VERSION, EVIDENCE_CONTRACT_PARTIAL_NOTE, EVIDENCE_CONTRACT_UNAVAILABLE_NOTE, EVIDENCE_FORMAT_VERSION, EVIDENCE_HTML_FILENAME, EVIDENCE_MANIFEST_FILENAME, EVIDENCE_RESOLVED_CONTRACT_FILENAME, EVIDENCE_VIEW_CSS, EVIDENCE_VIEW_IDS, EnrichSessionSummaryOptions, ErrorInfo, type EvidenceCheckContractBinding, type EvidenceCheckFindingSummary, type EvidenceCiPackageFiles, type EvidenceCiPackageInput, type EvidenceContractBinding, type EvidenceContractBindingSource, type EvidenceContractBindingStatus, type EvidenceContractPackage, type EvidenceContractVerifyIssue, type EvidenceContractsViewInput, type EvidenceFileEntry, type EvidenceFileRole, type EvidenceFormatVersion, type EvidenceHtmlShellInput, type EvidenceManifest, type EvidencePackagedFile, type EvidenceProvenanceViewInput, type EvidenceRedactionProfile, type EvidenceSafeStatus, type EvidenceSafetyViewInput, type EvidenceSourceHash, type EvidenceVerificationPolicy, type EvidenceVerifyIssue, type EvidenceVerifyOptions, type EvidenceVerifyResult, type EvidenceVerifyStatus, type EvidenceViewId, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, FALLBACK_TRACE_DIR, type FindFirstCausalFailureOptions, type FirstCausalFailure, type GateCheckId, type GateCheckResult, type GateExitCode, type GateResult, type GroupSessionCohortsOptions, InspectRunTree, type LoadSuiteConfigOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, OMITTED_PAYLOAD_MAX_DIGEST_INPUT_BYTES, ObservedOutcome, type OmittedPayloadAlgorithm, type OmittedPayloadCommitment, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, RUNS_DIR_NAME, RedactionProfile, type RenderCohortReportOptions, type RenderGateReportOptions, type RenderSuiteReportOptions, type RenderTimelineOptions, type RenderWhatOptions, type ResolvedContractDocument, type ResolvedRedactionProfile, type ResolvedSuiteCase, type RunGateOptions, RunStatus, type RunSuiteOptions, RunSummary, type RunTimeline, type RunWhatSummary, SUITE_TEMPLATE_IDS, type SessionCohort, type SessionCohortKind, SessionIndex, SessionRunRecord, type SessionScopeOptions, type SessionScopeResult, SessionStatus, SessionSummary, SessionWarning, SessionWorkflowMetadata, StepStatus, StepType, type SuiteArtifactsConfig, type SuiteCaseConfig, type SuiteCaseResult, type SuiteCaseStatus, type SuiteChecksConfig, type SuiteConfig, type SuiteDiagnostic, type SuiteDiagnosticCode, type SuiteEvalConfig, type SuiteRunResult, type SuiteRunSummary, type SuiteTemplateId, TERMINAL_INDENT, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceSessionCheckResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, type ValidateSuiteConfigResult, type ZipEntry, aggregateBundleSafeStatus, aggregateSessionCheckResults, analyzeCohort, assertBundlePathContained, assertEvidenceRelativePath, bindCheckResultsToContract, buildActivitySummary, buildBundleMetadata, buildBundleSummaryMarkdown, buildEvidenceCausalFailureViewHtml, buildEvidenceCiPackage, buildEvidenceCircuitViewHtml, buildEvidenceContractPackage, buildEvidenceContractsViewHtml, buildEvidenceDiffViewHtml, buildEvidenceFileEntries, buildEvidenceHtmlShell, buildEvidenceHtmlShellFromManifest, buildEvidenceManifest, buildEvidenceOutcomesViewHtml, buildEvidenceProvenanceViewHtml, buildEvidenceSafetyViewHtml, buildEvidenceTimelineViewHtml, buildEvidenceToolsLlmViewHtml, buildEvidenceTreeViewHtml, buildLocalExplanation, buildPlaceholderArtifact, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildSessionIndex, buildTraceStats, buildZipArchive, bundleFailsOnSafety, bundleRunAssetRelativePath, collectResolvedContractRuleIds, collectTraceSchemaVersions, compareCohortAggregates, createAdapterPreviewCapture, createOmittedPayloadCommitment, createRunId, createStepId, defaultBundleOutputPath, defaultSuiteConfigTemplate, deriveSessionStatus, encodeEmbeddedEvidenceJson, enrichSessionRunRecord, enrichSessionSummary, ensureTraceDir, extractMetadata, extractOutcomesFromPersistedEvents, extractOutcomesFromTraceEvents, extractSessionWorkflowMetadata, filterMetasBySessionScope, filterTraces, findFirstCausalFailure, formatDuration, formatError, formatStepLabel, formatTerminalName, formatTimestamp, gateHasThresholds, getDefaultTraceDir, getIndent, getRunIdFromTraceFileName, getSuiteTemplate, getTraceFilePath, groupSessionCohorts, inferEvidenceFileRole, initializeTraceFile, isAgentInspectTrace, isSha256Hex, listSuiteTemplates, listTraceFiles, loadSessionRunRecords, loadSuiteConfig, loadTraceMetadataList, normalizeBundleOutputPath, normalizeSuiteConfig, omittedPayloadByteLength, parseCohortMetricList, parseDuration, parseDurationFilter, parseEvidenceManifestJson, parseGateList, parseGateNumber, parseGroupBySpec, parseTraceJsonl, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, readCheckResultsContractBinding, readTraceEvents, readTraceFile, renderActivitySummaryHuman, renderCohortReport, renderCohortSummaryMarkdown, renderErrorLine, renderGateGithubAnnotations, renderGateGithubStepSummary, renderGateJUnit, renderGateReport, renderGateSummaryMarkdown, renderRunSummary, renderRunWhat, renderStepLine, renderSuiteReport, renderSuiteReportMarkdown, renderTimeline, renderTraceStats, resolveAdapterMaxPreviewChars, resolveBundleRunIds, resolveRedactionProfile, resolveSerializableTraceContract, resolveSuiteCaseTrace, resolveSuiteConfigPath, resolveSuiteTemplate, resolveTraceDir, runGate, runSuite, sanitizeBundleRunId, searchTraces, serializeAdapterPreview, serializeCanonicalJson, serializeCheckResultsJson, serializeEvent, serializeEvidenceManifest, sessionKeyForRun, sha256Equals, sha256Hex, toMetadataSafeStatus, traceMetasToSessionRunRecords, truncateName, unknownTraceFormatMessage, validateEvent, validateEvidenceManifest, validateSuiteConfig, verifyEvidenceContractBinding, verifyEvidenceDirectory, warn, writeTraceEvent };