/**
 * Helpers for representing *evaluator failures* on a run.
 *
 * Issue #242: a non-retryable judge / evaluator validation error used to be
 * recorded as a normal `completed` run with `metrics: { … all 0 }` and the
 * surface field `llmJudgeReasoning` left at its `'Waiting for traces to
 * become available...'` placeholder. From a user's perspective that was
 * indistinguishable from "the agent answered terribly" — the actual cause
 * (e.g. `Missing required field: expectedOutcomes`) was hidden in a
 * separate `traceError` field that nothing surfaced in the UI or in
 * benchmark summaries.
 *
 * Two things every error site must do consistently:
 *   1. Set `metricsStatus: 'error'` so stats aggregation can bucket the run
 *      into `errored` instead of `failed` (see {@link RunStats}).
 *   2. Replace `llmJudgeReasoning` with a clearly-labelled error message
 *      reflecting the *actual* terminal cause, so the run-report Judge tab
 *      stops showing the misleading "waiting for traces" placeholder.
 *
 * `buildEvaluatorErrorPatch()` returns the canonical patch payload covering
 * both. Use it everywhere you would otherwise hand-roll
 * `{ metricsStatus: 'error', traceError: ... }`.
 */
export type EvaluatorErrorKind = 'judge_failed' | 'agent_failed' | 'trace_timeout' | 'trace_incomplete' | 'trace_callback_failed' | 'trace_fetch_failed' | 'unknown';
export interface EvaluatorErrorPatch {
    metricsStatus: 'error';
    /** Machine-readable cause, persisted alongside the run. */
    traceError: string;
    /** Human-readable surface message shown in the Judge tab. */
    llmJudgeReasoning: string;
    /**
     * Pass/fail is meaningless when the evaluator never ran — set to `null`
     * so the storage layer (`asyncRunStorage.updateReport`) actually CLEARS
     * the field on the persisted document. Using `undefined` here would be
     * filtered out by the typical `!== undefined` allow-list, leaving a
     * stale `'passed'` / `'failed'` on disk inconsistent with
     * `metricsStatus: 'error'`.
     */
    passFailStatus: null;
    /** Reset metrics so charts don't graph the placeholder zeroes as a real run. */
    metrics: {
        accuracy: 0;
        faithfulness: 0;
        latency_score: 0;
        trajectory_alignment_score: 0;
    };
}
/**
 * Build the canonical "evaluator could not run" patch for `runs.update()`.
 *
 * @param kind   short tag used in logs and as the `traceError` prefix
 * @param error  the underlying error or message; we extract `.message`
 *               when given an Error so logs aren't `[object Object]`
 */
export declare function buildEvaluatorErrorPatch(kind: EvaluatorErrorKind, error: unknown): EvaluatorErrorPatch;
//# sourceMappingURL=evaluatorError.d.ts.map