eve/dist/src/evals/match.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import type { EveEvalSubagentCall, EveEvalToolCall } from "#evals/types.js";
/**
 * One matcher accepted by the assertion options (`t.calledTool`,
 * `t.calledSubagent`):
 *
 * - a **literal** is compared structurally; objects partial-deep-match (every
 *   key in the matcher must match the observed value, recursively, and nested
 *   values are matchers themselves), arrays match element-wise, primitives
 *   compare with `Object.is`
 * - a **RegExp** tests string values directly and the JSON serialization of
 *   anything else
 * - a **function** receives the observed value and either returns a boolean
 *   verdict, or returns a resolved expected value that is then compared like a
 *   literal — e.g. `(o) => o === process.env.EVE_WEATHER_AGENT_HOST`. To assert
 *   a literal boolean field, use the literal directly; boolean returns are
 *   always treated as verdicts.
 */
export type EveEvalValueMatcher<T = unknown> = T | RegExp | ((value: T) => unknown);
/**
 * Constraints applied to tool calls by `t.calledTool`. All provided
 * constraints must hold for a call to match.
 */
export interface EveEvalToolCallMatchOptions {
    /** Partial-deep matcher over the call input (see {@link EveEvalValueMatcher}). */
    readonly input?: EveEvalValueMatcher;
    /** Matcher over the call output. */
    readonly output?: EveEvalValueMatcher;
    /** Required error state of matching calls. */
    readonly isError?: boolean;
    /** Exact number of matching calls required. Defaults to "at least one". */
    readonly times?: number;
}
/**
 * Constraints applied to a `load_skill` call by `t.loadedSkill`. Identical to
 * {@link EveEvalToolCallMatchOptions} without `input`, which the helper fixes to
 * the loaded skill id.
 */
export type EveEvalSkillLoadMatchOptions = Omit<EveEvalToolCallMatchOptions, "input">;
/**
 * Constraints applied to subagent calls by `t.calledSubagent`.
 */
export interface EveEvalSubagentCallMatchOptions {
    /** Matcher over the `subagent.called` remote URL. */
    readonly remoteUrl?: EveEvalValueMatcher;
    /** Matcher over the `subagent.completed` output. */
    readonly output?: EveEvalValueMatcher;
}
/**
 * Returns true when the observed value satisfies a matcher (literal, RegExp,
 * or function — see {@link EveEvalValueMatcher}).
 */
export declare function matchesValue(matcher: unknown, value: unknown): boolean;
/**
 * Returns true when one derived tool call satisfies the `input`/`output`/
 * `isError` constraints (the `times` count is the caller's concern).
 */
export declare function toolCallMatches(call: EveEvalToolCall, options: EveEvalToolCallMatchOptions): boolean;
/**
 * Returns true when one derived subagent call satisfies the `remoteUrl`/
 * `output` constraints.
 */
export declare function subagentCallMatches(call: EveEvalSubagentCall, options: EveEvalSubagentCallMatchOptions): boolean;
/**
 * Strict structural equality used by `t.outputEquals`: unlike matcher
 * comparison, objects must carry exactly the same keys on both sides.
 */
export declare function deepEquals(a: unknown, b: unknown): boolean;
/**
 * Tests a RegExp without carrying `lastIndex` state between calls. Matcher
 * patterns are reused across tool calls and across every case in an eval, so
 * a `g`/`y`-flagged pattern would otherwise return order-dependent results.
 */
export declare function testRegExp(pattern: RegExp, text: string): boolean;