@jmoak/vibrissa 0.1.0 → 2.0.0-alpha.0

package/dist/index.d.ts

@@ -1,73 +1,852 @@
-interface ServerConfig {
-    cmd: string;
-    args?: string[];
-    cwd?: string;
-    env?: Record<string, string>;
-}
-interface RunCasesOptions {
-    server: ServerConfig;
-    globs: string[];
-    timeoutMs: number;
-    failFast: boolean;
-    display?: 'plain' | 'pretty';
-    rootDir?: string;
-    allowEmpty?: boolean;
+import { J as JsonValue, M as Mismatch, R as Reporter, a as ReporterContext, b as RunEvent, C as CaseStatus, c as CheckOutcome, d as ResourceSummary, e as ResourceTemplateSummary, P as PromptSummary, T as ToolSummary, f as ManifestLike, S as ServerConfig, N as NormalizeConfig$1, g as ShardSpec, h as SuiteHooks, i as RunOptions, j as ProtocolMode } from './runner-J_V7pgax.js';
+export { A as AwaitOptions, k as CASE_KEYS, l as CallOptions, m as CaptureManifestOptions, n as CapturedManifest, o as CaseExecution, p as CaseFilters, q as CaseOutcome, r as CaseRef, D as DEFAULT_BASELINE_LATENCY_MIN_MS, s as DEFAULT_BASELINE_LATENCY_PCT, t as DEFAULT_FLAKY_FLOOR, u as DEFAULT_MANIFEST_IGNORE, v as DiffManifestOptions, w as DiscoverInfo, E as ExecuteContext, x as ExpectError, y as ExpectationUpdate, F as FieldChange, H as HttpServerConfig, I as InputResponder, z as InterpolationError, B as InterpolationScope, G as ItemChange, K as JsonObject, L as ListResult, O as LoadCasesOptions, Q as LoadCasesResult, U as LoadedCase, V as MANIFEST_SECTIONS, W as MANIFEST_VERSION, X as MODERN_PROTOCOL_VERSION, Y as Manifest, Z as ManifestDiff, _ as ManifestFileError, $ as ManifestResult, a0 as ManifestSection, a1 as McpSession, a2 as OP_KINDS, a3 as OpKind, a4 as Operation, a5 as Outcome, a6 as PlannedStep, a7 as PromptSummary, a8 as ResourceSummary, a9 as ResourceTemplateSummary, aa as RunCasesInput, ab as RunResult, ac as RunSummary, ad as Runner, ae as RunnerOptions, af as STEP_KEYS, ag as SectionDiff, ah as SessionOptions, ai as SessionRequestError, aj as SessionStartError, ak as SessionStartErrorCode, al as StdioServerConfig, am as Step, an as StepRef, ao as TASKS_EXTENSION, ap as TestCase, aq as ToolError, ar as ToolSummary, as as TranscriptEntry, at as applyUpdates, au as buildManifest, av as canonicalCodeName, aw as captureManifest, ax as caseIdFor, ay as detectIndent, az as diffManifest, aA as errorCodeName, aB as errorMatchesCode, aC as executeCase, aD as expandUriTemplate, aE as filterCases, aF as formatDiff, aG as getPath, aH as inputRequestView, aI as interpolate, aJ as interpolateStep, aK as isHttpServerConfig, aL as isStdioServerConfig, aM as jsonEqual, aN as knownCodeNames, aO as loadCaseFile, aP as loadCases, aQ as loadCasesSync, aR as looksLikeManifest, aS as manifestFrom, aT as manifestPathFor, aU as matcherPathSegments, aV as parseCaseText, aW as parsePath, aX as placeholdersIn, aY as planSteps, aZ as readManifest, a_ as resolveCaseFiles, a$ as resolveRunnerOptions, b0 as runCases, b1 as shardCases, b2 as summarizeDiff, b3 as toPointer, b4 as traceName, b5 as validateCaseShape, b6 as wordDiff, b7 as writeManifest } from './runner-J_V7pgax.js';
+import '@modelcontextprotocol/client';
+
+type EnvLike = Record<string, string | undefined>;
+
+/**
+ * Paste-ready `respond` suggestions for unanswered input requests (MRTR rounds or 2025-era
+ * server→client requests). Used by `vib call`/`vib record` hints and by the runner's
+ * failure messages, so every surface suggests the same answer.
+ */
+
+/**
+ * A `respond` map (keyed by request method) that answers every request in an
+ * InputRequests map (`{ key: { method, params } }`):
+ * - `elicitation/create` → `{ action: "accept", content: { <each requested field>: <sample> } }`
+ * - `sampling/createMessage` → a scripted assistant text message
+ * - `roots/list` → `{ roots: [] }`
+ * - anything else → `{}`
+ * The first request of each method wins (a respond map holds one answer per method).
+ */
+declare function suggestRespond(requests: JsonValue): Record<string, JsonValue>;
+
+interface MatchOptions {
+    /** Start in partial mode, as if the root expectation carried `"$partial": true`. */
+    partial?: boolean;
 }
-type JsonValue = null | boolean | number | string | JsonValue[] | {
-    [key: string]: JsonValue;
-};
-interface TestCase {
-    name?: string;
-    tool?: string;
-    args?: Record<string, JsonValue>;
-    expect?: JsonValue;
-    expectError?: {
-        code?: string;
-        message?: string | {
-            $regex?: string;
-            flags?: string;
-        };
-    };
+declare const MAX_MISMATCHES = 25;
+declare function matchValue(expected: JsonValue, actual: unknown, options?: MatchOptions): Mismatch[];
+declare function matches(expected: JsonValue, actual: unknown, options?: MatchOptions): boolean;
+/**
+ * True when `value` would be interpreted as a matcher (`{"$regex": ...}`, `{"$type": ...}`,
+ * `{"$ref": ...}`, `{"$literal": ...}`), not compared as plain data. Plain objects carrying
+ * only `$partial` next to data keys are not matchers.
+ */
+declare function isMatcherObject(value: unknown): boolean;
+/**
+ * Statically check an expectation for malformed matchers (bad shapes, invalid regexes,
+ * uncompilable `$schema`s), including inside `$oneOf` alternatives that matching may never
+ * reach. Paths point into the expectation tree (e.g. `content[0].text.$oneOf[1]`).
+ * Returns an empty array when the expectation is well formed.
+ */
+declare function lintExpectation(expected: JsonValue): Mismatch[];
+/**
+ * Make recorded data safe to use as an expectation: any object that would be read as a
+ * matcher (it has a key such as `$ref`, `$type`, `$regex`, `$partial`) is wrapped in
+ * `{"$literal": ...}` so it is compared as plain data. Use when writing goldens from
+ * live results.
+ */
+declare function escapeDirectives(value: JsonValue): JsonValue;
+/**
+ * Loads a referenced fragment. `relPath` is a normalized POSIX path relative to the
+ * directory of the case file (nested refs are already re-based onto that directory), or
+ * an absolute path / URL when the ref was written that way.
+ */
+type RefLoader = (relPath: string) => JsonValue;
+declare class RefResolutionError extends Error {
+    /** The `$ref` string as written. */
+    readonly ref: string;
+    /** Where in the expectation tree the failing `$ref` sits (matcher path format). */
+    readonly path: string;
+    /** Fragments being expanded when the error occurred, outermost first. */
+    readonly chain: string[];
+    constructor(message: string, ref: string, path: string, chain: string[]);
 }
+/**
+ * Expand every `{"$ref": "./shared/x.json"}` (optionally with a `#/json/pointer`) in an
+ * expectation tree. Refs may appear anywhere and fragments may contain further refs,
+ * which resolve relative to the fragment that contains them. `$schema` bodies and
+ * `$literal` values are left untouched (their `$ref`s are JSON Schema refs / data).
+ * Throws `RefResolutionError` on load failures, bad pointers and cycles.
+ */
+declare function resolveRefs(expected: JsonValue, loader: RefLoader): JsonValue;
 
-declare const defaultRunCasesOptions: RunCasesOptions;
+/**
+ * Result-envelope normalization, applied by the runner before matching and before
+ * recording so goldens stay free of per-protocol-version noise. Pure and idempotent:
+ * the input is never mutated and `normalizeResult(normalizeResult(x)) === normalizeResult(x)`
+ * structurally.
+ */
+
+interface NormalizeConfig {
+    /** Glob patterns (`*` = any run of characters) for keys removed from every `_meta` object. */
+    stripMeta?: string[];
+    /** Top-level result keys to remove. */
+    dropKeys?: string[];
+    /** `'ignore'` removes top-level `ttlMs` and `cacheScope` (list-result cache hints). */
+    ttlMs?: 'keep' | 'ignore';
+}
+declare const defaultNormalizeConfig: Required<NormalizeConfig>;
+/** True when `key` matches the simple glob `pattern` (`*` matches any run of characters). */
+declare function matchesGlob(pattern: string, key: string): boolean;
+/**
+ * Normalize an MCP result for matching/recording. Missing config fields fall back to
+ * `defaultNormalizeConfig`; pass empty arrays / `ttlMs: 'keep'` to disable a rule.
+ */
+declare function normalizeResult(result: JsonValue, cfg?: NormalizeConfig): JsonValue;
 
-interface Mismatch {
+interface SchemaIssue {
+    /** Location in the validated value (matcher path format; '' = the value itself). */
     path: string;
     message: string;
-    expected?: unknown;
-    actual?: unknown;
+    /** The JSON Schema keyword that failed (e.g. `type`, `required`). */
+    keyword?: string;
+    /** Pointer into the schema, e.g. `#/properties/id/type`. */
+    schemaPath?: string;
 }
-declare function matchValue(expected: JsonValue, actual: unknown): Mismatch[];
-declare function matches(expected: JsonValue, actual: unknown): boolean;
+interface ValidationResult {
+    ok: boolean;
+    errors: SchemaIssue[];
+    /** Set when the schema itself could not be compiled; `errors` then holds one entry. */
+    schemaError?: string;
+}
+/**
+ * Hook for `$ref`s that point outside the schema document. Receives the ref URI resolved
+ * against the schema's `$id` (as written when there is no `$id`), without its `#fragment`.
+ * Return the referenced schema document, or `undefined` if it cannot be found.
+ */
+type SchemaRefResolver = (ref: string) => JsonValue | undefined;
+interface CompileOptions {
+    resolve?: SchemaRefResolver;
+}
+type Validator = (value: unknown) => ValidationResult;
+declare class SchemaCompileError extends Error {
+    constructor(message: string);
+}
+/**
+ * Compile a JSON Schema into a reusable validator. Results are cached by schema object
+ * identity (and resolver identity, when one is given), so compiling the same schema
+ * object repeatedly is cheap. Throws `SchemaCompileError` if the schema is unusable.
+ */
+declare function compileSchema(schema: JsonValue, opts?: CompileOptions): Validator;
+/** Validate `value` against `schema`. Never throws; compile failures set `schemaError`. */
+declare function validate(schema: JsonValue, value: unknown, opts?: CompileOptions): ValidationResult;
+/**
+ * Meta-validate a schema (is it a well-formed schema for its dialect?) and check that it
+ * compiles, i.e. every `$ref` resolves. Error paths point into the schema document.
+ */
+declare function isValidSchema(schema: JsonValue, opts?: CompileOptions): {
+    ok: boolean;
+    errors: SchemaIssue[];
+};
+
+/**
+ * Console reporter (default). Replaces v1's display.ts.
+ *
+ * - Quiet on success: one line per case, a header, and the summary banner.
+ * - Loud on failure: a Failures section with the reason, flow steps, the mismatch list
+ *   (capped), budget breaches, a Jest-style expected/actual diff, and the trace path.
+ * - Pretty mode: ANSI colors and unicode glyphs, v1-style summary box.
+ * - Plain mode (non-TTY, NO_COLOR, TERM=dumb, or ctx.pretty=false): same information,
+ *   ASCII only, line-oriented, stable for CI logs.
+ *
+ * Output order is stable under concurrency: a case (and its steps) prints only at
+ * case:end, so interleaved events from parallel workers never interleave lines.
+ */
 
-interface ToolError {
-    kind: 'protocol' | 'tool';
-    code?: number;
-    codeName?: string;
+interface ConsoleReporterOptions {
+    /** Force a style. Default: derived from ctx.pretty, NO_COLOR, FORCE_COLOR and TTY. */
+    style?: 'pretty' | 'plain';
+    /** Environment used for style detection. Default: process.env. */
+    env?: EnvLike;
+    /** Whether stdout is a terminal. Default: process.stdout.isTTY. */
+    isTTY?: boolean;
+    /** Max mismatches listed per failed case. Default 10. */
+    maxMismatches?: number;
+    /** Max diff lines per failed case. Default 80. */
+    maxDiffLines?: number;
+    /** Width of the pretty summary box. Default 64 (v1). */
+    width?: number;
+}
+declare class ConsoleReporter implements Reporter {
+    private readonly ctx;
+    readonly name = "console";
+    readonly style: 'pretty' | 'plain';
+    private readonly c;
+    private readonly g;
+    private readonly run;
+    private readonly maxMismatches;
+    private readonly maxDiffLines;
+    private readonly width;
+    private finished;
+    /** Passing checks, folded into one "Checks: N passed" line per server. */
+    private readonly passedChecks;
+    /** The runner's "no cases matched" warning, printed as an error line at the end. */
+    private noCasesMessage?;
+    constructor(ctx: ReporterContext, options?: ConsoleReporterOptions);
+    onEvent(event: RunEvent): void;
+    close(): void;
+    private out;
+    private path;
+    private badge;
+    /** `[server] ` prefix for manifest/check lines, only when the run spans several servers. */
+    private serverTag;
+    private printHeader;
+    private caseTitle;
+    private caseMeta;
+    private printCase;
+    private stepLines;
+    /**
+     * Like `vib check`: passing checks fold into one line; failed/warned checks print their
+     * id, title and detail, plus the allow-list entry that would accept them after review.
+     */
+    private printCheck;
+    private flushPassedChecks;
+    private printWarning;
+    /** "No cases matched" is an error unless the runner accepted it (allowEmpty). */
+    private printNoCases;
+    private finish;
+    private rule;
+    private printFailures;
+    private printFailure;
+    private printManifestDrift;
+    private summaryParts;
+    /** `6 cases` or, when repeated, `2 cases, 6 runs`. */
+    private sizeLabel;
+    private printPlainSummary;
+    /** v1-style ASCII banner box. */
+    private printBox;
+}
+
+declare const RESULTS_FILE = "results.json";
+/**
+ * Shape of `results.json` (version 1). Additive changes keep `version: 1`; any removal or
+ * change of meaning bumps it.
+ *
+ * ```jsonc
+ * {
+ *   "version": 1,
+ *   "generator": "vibrissa",
+ *   "ok": false,                      // run:end.ok, else: no failed cases/checks, no drift
+ *   "complete": true,                 // false when the run stopped before run:end
+ *   "startedAt": "2026-10-28T12:00:00.000Z",
+ *   "finishedAt": "2026-10-28T12:00:01.234Z",   // startedAt + summary.durationMs
+ *   "repeat": 3,                                // run:start.repeat, when > 1
+ *   "shard": { "index": 1, "total": 4 },        // run:start.shard, when sharded
+ *   "servers": [{ "name": "local", "era": "modern", "protocolVersion": "2026-07-28",
+ *                 "serverInfo": { "name": "echo-server", "version": "1.2.0" } }],
+ *   "summary": {
+ *     "total": 3,                                // distinct cases (not runs)
+ *     "runs": 9,                                 // executions; only when repeated
+ *     "passed": 1, "failed": 1, "skipped": 1, "updated": 0,   // per run when repeated
+ *     "durationMs": 1234,
+ *     "passRates": { "cases/echo.json": 0.6 },   // only with --repeat > 1
+ *     "flaky": ["cases/echo.json"],              // 0 < pass rate < 1; omitted when none
+ *     "checks": { "passed": 2, "failed": 0, "warned": 1 },
+ *     "manifestDrift": 0,
+ *     "warnings": 1
+ *   },
+ *   "cases": [{
+ *     "id": "cases/echo.json#2",       // CaseRef.id as emitted (unique per run)
+ *     "caseId": "cases/echo.json",     // id without the repeat suffix (stable across runs)
+ *     "run": 2,                         // repeat index, only when repeated
+ *     "name": "echo returns input", "file": "cases/echo.json", "server": "local",
+ *     "tags": ["smoke"], "line": 1, "flaky": true,   // line/flaky only when known/declared
+ *     "status": "failed", "durationMs": 12,
+ *     "errorKind": "assertion",        // assertion | error | timeout | budget | load
+ *     "reason": "Expectation failed at content[0].text: ...",
+ *     "mismatches": [{ "path": "content[0].text", "message": "...", "expected": "A", "actual": "a",
+ *                      "field": "expect", "pointer": "/steps/1/expect/content/0/text", "stepIndex": 1 }],
+ *     "updateSkipped": { "reason": "expect contains matchers" },   // --update left it alone
+ *     "expected": { ... }, "actual": { ... },
+ *     "steps": [{ "index": 0, "name": "create", "kind": "tool", "target": "session.create",
+ *                 "status": "passed", "durationMs": 5 }],
+ *     "budget": { "budgetMs": 800, "actualMs": 812 },
+ *     "tracePath": "reports/traces/echo.ndjson",
+ *     "stderrPath": "reports/traces/echo.stderr.log"
+ *   }],
+ *   "checks": [{ "id": "spec/tools-list-stable", "server": "local", "title": "...", "status": "warned",
+ *                "detail": "..." }],
+ *   "manifests": [{ "path": "tests/integration/__manifest__.json", "server": "local", "status": "diff",
+ *                   "summary": "1 tool changed", "diff": { ... } }],
+ *   "warnings": ["..."]
+ * }
+ * ```
+ *
+ * Empty arrays are omitted (`tags`, `summary.flaky`, `checks`, `manifests`, `warnings`);
+ * `servers` and `cases` are always present.
+ */
+interface JsonReport {
+    version: 1;
+    generator: 'vibrissa';
+    /**
+     * The run's verdict: run:end.ok when the runner sent it; otherwise true when no case
+     * failed, no check failed and no manifest drifted.
+     */
+    ok: boolean;
+    /** False when the reporter was closed without seeing run:end (crash / abort). */
+    complete: boolean;
+    /** ISO 8601, from run:start.startedAt; null if run:start never arrived. */
+    startedAt: string | null;
+    /** ISO 8601, startedAt + summary.durationMs; null if unknown. */
+    finishedAt: string | null;
+    /** run:start.repeat, when cases were repeated (> 1). */
+    repeat?: number;
+    /** run:start.shard, when the run was one shard of several. */
+    shard?: {
+        index: number;
+        total: number;
+    };
+    servers: JsonServer[];
+    summary: JsonSummary;
+    /** Sorted by caseId, then run. */
+    cases: JsonCase[];
+    /** In emission order; omitted when no checks ran. */
+    checks?: CheckOutcome[];
+    /** One entry per manifest:ok / manifest:diff event; omitted when no manifest was checked. */
+    manifests?: JsonManifest[];
+    /** Omitted when there were none. */
+    warnings?: string[];
+}
+interface JsonServer {
+    name: string;
+    era?: 'legacy' | 'modern';
+    protocolVersion?: string;
+    /** What the server reported about itself (session:start.serverInfo). */
+    serverInfo?: {
+        name?: string;
+        version?: string;
+    };
+}
+interface JsonSummary {
+    /** Distinct cases. With --repeat this is not the number of executions (see `runs`). */
+    total: number;
+    /** Executions (cases x repeat); present only when cases were repeated. */
+    runs?: number;
+    /** Status counts; counted per run when repeated, so they sum to `runs`. */
+    passed: number;
+    failed: number;
+    skipped: number;
+    updated: number;
+    durationMs: number;
+    /** Pass rate per case id; present only when cases were repeated. */
+    passRates?: Record<string, number>;
+    /** Case ids (without repeat suffix) whose pass rate is strictly between 0 and 1; omitted when none. */
+    flaky?: string[];
+    checks: {
+        passed: number;
+        failed: number;
+        warned: number;
+    };
+    /** Number of manifests that differ from the lock file. */
+    manifestDrift: number;
+    warnings: number;
+}
+interface JsonCase {
+    /** CaseRef.id as emitted: relative case file path, plus `#<n>` for repeated runs. */
+    id: string;
+    /** id without the `#<n>` repeat suffix; the key to aggregate or compare on. */
+    caseId: string;
+    /** Repeat index, present only for repeated runs. */
+    run?: number;
+    name: string;
+    /** Case file, forward slashes. */
+    file: string;
+    server: string;
+    /** Omitted when the case has no tags. */
+    tags?: string[];
+    /** 1-based line of the case in its file, when known. */
+    line?: number;
+    /** The case declared `flaky: true`. */
+    flaky?: true;
+    status: CaseStatus;
+    durationMs: number;
+    /** Kind of failure: assertion | error | timeout | budget | load. */
+    errorKind?: 'assertion' | 'error' | 'timeout' | 'budget' | 'load';
+    reason?: string;
+    mismatches?: JsonMismatch[];
+    /** Present when --update left this failing golden alone, and why. */
+    updateSkipped?: {
+        reason: string;
+    };
+    expected?: JsonValue;
+    actual?: JsonValue;
+    steps?: JsonStep[];
+    budget?: {
+        budgetMs: number;
+        actualMs: number;
+    };
+    /** Transcript path, relative to the project root when inside it. */
+    tracePath?: string;
+    /** Captured server stderr for this case, relative to the project root when inside it. */
+    stderrPath?: string;
+}
+interface JsonMismatch {
+    path: string;
     message: string;
+    expected?: JsonValue;
+    actual?: JsonValue;
+    /** Case field the mismatch belongs to (`expect`, `expectError`, ...). */
+    field?: string;
+    /** RFC 6901 pointer into the case file, e.g. `/steps/1/expect/content/0/text`. */
+    pointer?: string;
+    /** 0-based step index for flows. */
+    stepIndex?: number;
 }
-type ToolCallOutcome = {
-    kind: 'result';
-    result: JsonValue;
-} | {
-    kind: 'error';
-    error: ToolError;
-};
-interface ToolSummary {
+interface JsonStep {
+    /** 0-based step index. */
+    index: number;
     name: string;
-    description?: string;
-    inputSchema: JsonValue;
-}
-declare class McpSession {
-    private readonly client;
-    private constructor();
-    static start(server: ServerConfig, timeoutMs: number): Promise<McpSession>;
-    callTool(name: string, args: Record<string, JsonValue>, timeoutMs: number): Promise<ToolCallOutcome>;
-    listTools(): Promise<ToolSummary[]>;
+    kind: string;
+    target: string;
+    status: CaseStatus;
+    durationMs: number;
+    reason?: string;
+}
+interface JsonManifest {
+    path: string;
+    /** Server whose manifest this is, when the runner attributed it. */
+    server?: string;
+    status: 'ok' | 'diff';
+    summary?: string;
+    diff?: JsonValue;
+}
+declare class JsonReporter implements Reporter {
+    private readonly ctx;
+    readonly name = "json";
+    private readonly run;
+    /** Absolute path of the file written (or to be written). */
+    readonly filePath: string;
+    constructor(ctx: ReporterContext);
+    onEvent(event: RunEvent): void;
+    /** The document as it would be written right now. */
+    report(): JsonReport;
+    close(): Promise<void>;
+}
+
+declare class JunitReporter implements Reporter {
+    private readonly ctx;
+    readonly name = "junit";
+    private readonly run;
+    readonly filePath: string;
+    constructor(ctx: ReporterContext);
+    onEvent(event: RunEvent): void;
+    xml(): string;
+    close(): Promise<void>;
+}
+
+interface GithubReporterOptions {
+    /** Environment (GITHUB_ACTIONS, GITHUB_STEP_SUMMARY, GITHUB_WORKSPACE). Default: process.env. */
+    env?: EnvLike;
+    /** 'auto' (default): workflow commands only when GITHUB_ACTIONS=true. */
+    annotations?: 'auto' | 'always' | 'never';
+    /** Mismatches included per annotation. Default 10. */
+    maxMismatches?: number;
+    /** Failure detail blocks included in the summary. Default 25. */
+    maxDetails?: number;
+    /** Rows in the collapsed "all cases" table. Default 500. */
+    maxRows?: number;
+}
+declare class GithubReporter implements Reporter {
+    private readonly ctx;
+    readonly name = "github";
+    private readonly run;
+    private readonly env;
+    private readonly annotate;
+    private readonly maxMismatches;
+    private readonly maxDetails;
+    private readonly maxRows;
+    constructor(ctx: ReporterContext, options?: GithubReporterOptions);
+    /** True when workflow commands are written to stdout. */
+    get annotating(): boolean;
+    onEvent(event: RunEvent): void;
+    private emit;
+    /** Annotation paths must be relative to the repository root (GITHUB_WORKSPACE). */
+    private annotationPath;
+    private caseTitle;
+    private annotateCase;
+    private annotateCheck;
+    /** Markdown job summary for the run so far. */
+    markdown(): string;
     close(): Promise<void>;
 }
 
-declare function runCases(options: RunCasesOptions): Promise<number>;
+/**
+ * TAP 14 reporter (https://testanything.org/tap-version-14-specification.html).
+ *
+ * Streams one test point per case as it completes (plus manifest and check results),
+ * with YAML diagnostics (`duration_ms`, failure message, mismatches, diff). Flows are
+ * emitted as TAP 14 subtests, one point per step. The plan is trailing (`1..N`) because
+ * points stream before the total is known; an aborted run ends with `Bail out!`.
+ */
+
+declare class TapReporter implements Reporter {
+    private readonly ctx;
+    readonly name = "tap";
+    private readonly run;
+    private started;
+    private finished;
+    private count;
+    constructor(ctx: ReporterContext);
+    private out;
+    private ensureHeader;
+    onEvent(event: RunEvent): void;
+    close(): void;
+    private point;
+    private checkPoint;
+    private casePoint;
+    private finish;
+}
+
+/**
+ * Reporter registry. Built-ins: console (default), json, junit, github, tap.
+ * Plugins add their own with `registerReporter(name, factory)`; the runner builds the
+ * active set with `createReporters(names, ctx)` and drives them through `fanout(...)`.
+ */
+
+type ReporterFactory = (ctx: ReporterContext) => Reporter;
+declare const BUILTIN_REPORTERS: readonly ["console", "json", "junit", "github", "tap"];
+/**
+ * Register a reporter factory under `name` (case-insensitive). Throws if the name is
+ * taken, unless `{ override: true }` — which also allows replacing a built-in.
+ */
+declare function registerReporter(name: string, factory: ReporterFactory, options?: {
+    override?: boolean;
+}): void;
+/** Remove a reporter. Built-ins removed this way can be restored with `resetReporters()`. */
+declare function unregisterReporter(name: string): boolean;
+/** Restore the registry to just the built-ins (mainly for tests). */
+declare function resetReporters(): void;
+declare function hasReporter(name: string): boolean;
+/** Registered reporter names, sorted. */
+declare function listReporters(): string[];
+declare class UnknownReporterError extends Error {
+    readonly reporter: string;
+    readonly known: string[];
+    readonly suggestion?: string;
+    constructor(reporter: string, known: string[]);
+}
+/**
+ * Instantiate reporters by name. Names are case-insensitive, may be comma-separated
+ * (`"console,junit"`), and duplicates collapse to one instance. All names are validated
+ * before any reporter is created, so a typo never leaves half the set constructed.
+ */
+declare function createReporters(names: string[], ctx: ReporterContext): Reporter[];
+/**
+ * Combine reporters into one. Every reporter sees every event even if another throws;
+ * failures are rethrown afterwards (one Error, or an AggregateError for several). The
+ * return value is synchronous when all reporters handled the event synchronously, and a
+ * promise otherwise. `close()` waits for queued events, then awaits every close().
+ */
+declare function fanout(reporters: Reporter[]): Reporter;
+
+/**
+ * Shared plumbing for lint rules and spec checks: allow-listing, severity
+ * overrides, grouping findings into CheckOutcomes, sorting and summarizing.
+ */
+
+type Severity = 'failed' | 'warned';
+interface LintOptions {
+    /**
+     * Check ids to skip. Each entry is one of:
+     * - an exact id: `desc/long-description`
+     * - a prefix wildcard: `desc/*`
+     * - an id scoped to one subject: `desc/sensitive-paths:ssh.list_keys`
+     *   (subject = tool / prompt name, resource URI, or `instructions`)
+     */
+    allow?: string[];
+    /** Per-check severity override for findings, e.g. `{ "desc/embedded-url": "failed" }`. */
+    severity?: Record<string, Severity>;
+}
+declare function summarizeChecks(outcomes: readonly CheckOutcome[]): {
+    failed: number;
+    warned: number;
+    passed: number;
+};
+
+/**
+ * Tool-description lint: a deterministic, offline smoke detector for tool
+ * poisoning, shadowing and exfiltration hints in model-visible text, plus a few
+ * quality checks. Pattern-based by design — it catches the well-known shapes of
+ * these attacks, not every paraphrase. See docs/CHECKS.md for every rule.
+ *
+ * Adding a rule = one entry in DESCRIPTION_RULES. Adding a phrase to an existing
+ * rule = one entry in its pattern table.
+ */
+
+interface DescriptionLintOptions extends LintOptions {
+    /** Also lint these descriptions (pattern rules only; quality rules are tool-only). */
+    resources?: ResourceSummary[];
+    resourceTemplates?: ResourceTemplateSummary[];
+    prompts?: PromptSummary[];
+    /** Server instructions from discover/initialize. */
+    instructions?: string;
+    /** Tool names from other servers the same client loads, for cross-server shadowing. */
+    knownToolNames?: string[];
+    /** Threshold for `desc/long-description`. Default 2000. */
+    maxDescriptionLength?: number;
+}
+/**
+ * Lint tool descriptions (and, via opts, resource/prompt descriptions and server
+ * instructions). Pure. Returns one `passed` outcome per clean rule and one
+ * outcome per offending subject otherwise, sorted failed -> warned -> passed.
+ */
+declare function lintDescriptions(tools?: ToolSummary[], opts?: DescriptionLintOptions): CheckOutcome[];
+
+/**
+ * Deterministic spec-sanity checks over a recorded manifest (the Layer 0 subset
+ * Vibrissa can run on stdio): protocol version, tools/list determinism, list
+ * cache metadata, JSON Schema validity and local `$ref` resolution, server
+ * identity and capabilities. Pure: takes data, never opens a session.
+ *
+ * Also exports `errorCodeExpectations`, the per-era error-code table the live
+ * runner uses to assert error behavior.
+ */
+
+type SchemaValidator = (schema: JsonValue) => {
+    ok: boolean;
+    /** `keyword` is the failing JSON Schema keyword when known (`$ref` for unresolved refs). */
+    errors: Array<{
+        path: string;
+        message: string;
+        keyword?: string;
+    }>;
+};
+interface SpecInput extends ManifestLike {
+    /** Two or more consecutive tools/list results, in call order. */
+    toolsListSamples?: ToolSummary[][];
+}
+interface SpecOptions extends LintOptions {
+    /** Defaults to `isValidSchema` from src/schema.ts (Ajv 2020-12). */
+    validateSchema?: SchemaValidator;
+}
+/** Run every spec-sanity check over `input`. Pure; sorted failed -> warned -> passed. */
+declare function checkSpec(input: SpecInput, opts?: SpecOptions): CheckOutcome[];
+
+/**
+ * `vib check` engine: spec-sanity checks + description lint over a manifest.
+ * Pure: give it data recorded from a session, get CheckOutcome[] back.
+ */
+
+interface RunChecksOptions {
+    /** Two or more consecutive tools/list results, for `spec/tools-list-stable`. */
+    toolsListSamples?: ToolSummary[][];
+    /** Check ids to skip (`id`, `prefix/*`, or `id:subject`). Config: `checks.allow`. */
+    allow?: string[];
+    /** Severity overrides by check id. Config: `checks.severity`. */
+    severity?: Record<string, Severity>;
+    /** Tool names from other configured servers, for cross-server shadowing detection. */
+    knownToolNames?: string[];
+    maxDescriptionLength?: DescriptionLintOptions['maxDescriptionLength'];
+    /** Override the JSON Schema validator (defaults to src/schema.ts `isValidSchema`). */
+    validateSchema?: SchemaValidator;
+}
+/** Every check id with its title and default severity, in table order. */
+declare function listChecks(): Array<{
+    id: string;
+    title: string;
+    severity: Severity;
+}>;
+/**
+ * Run spec-sanity checks and description lint over a manifest.
+ * Returns outcomes sorted failed -> warned -> passed (then by id).
+ */
+declare function runChecks(manifest: ManifestLike, opts?: RunChecksOptions): CheckOutcome[];
+
+type Strategy = 'valid' | 'boundary' | 'invalid' | 'inject';
+type Expectation = 'success' | 'invalid-params' | 'any';
+interface GeneratedCase {
+    /** `<strategy>-<hash>`; stable for a given schema + seed (content-addressed). */
+    id: string;
+    strategy: Strategy;
+    args: Record<string, JsonValue>;
+    /**
+     * success: schema-valid, the server must not answer with a protocol error.
+     * invalid-params: schema-invalid, the server must reject it (InvalidParams or a tool error).
+     * any: no contract either way; the server must merely survive it.
+     */
+    expectation: Expectation;
+    /** Human-readable why, e.g. "required property 'text' omitted". */
+    reason: string;
+    /** The argument this case targets, in matcher path format ('(root)' for the args object). */
+    target?: string;
+    /** Injection payload ids carried by this case (inject strategy only). */
+    payloadIds?: string[];
+}
+interface GenerateOptions {
+    seed: number | string;
+    /** Total number of cases across all strategies (an upper bound; small schemas yield fewer). */
+    count: number;
+    /** Default: valid, boundary, invalid. `inject` is opt-in (`vib fuzz --inject`). */
+    strategies?: Strategy[];
+    /** Maximum object/array nesting the generator builds (default 6). */
+    maxDepth?: number;
+    /**
+     * Validate each case with `validateAgainstSchema` (or the given predicate) and drop any
+     * whose expectation would be wrong. Also restores strict expectations that were relaxed
+     * to 'any' inside non-discriminated oneOf/anyOf. Recommended for the runner.
+     */
+    selfCheck?: boolean | ((schema: JsonValue, args: Record<string, JsonValue>) => boolean);
+}
+/**
+ * Generate up to `count` argument sets for a tool's `inputSchema`.
+ *
+ * Cases are taken round-robin from each requested strategy (systematic cases first, then
+ * seeded random variations) and returned grouped by strategy. A strategy that runs out
+ * (e.g. `inject` on a schema without free-form strings) leaves its share to the others.
+ * Raising `count` only appends: every case of a smaller run is in the larger one.
+ */
+declare function generateArgs(schema: JsonValue, opts: GenerateOptions): GeneratedCase[];
+
+/**
+ * Fuzz invariants as data: properties every tool call must satisfy without any golden.
+ * Each invariant says which generated cases it applies to and judges one call outcome.
+ * The runner (phase 2) supplies the outcome; this module never touches a session.
+ */
+
+interface FuzzOutcome {
+    /**
+     * result: the call returned a CallToolResult (possibly `isError: true`).
+     * error: a JSON-RPC / tool / transport error. input_required: an MRTR pause.
+     * crash: the server process died or the connection dropped. timeout: no answer in time.
+     */
+    kind: 'result' | 'error' | 'input_required' | 'crash' | 'timeout';
+    result?: JsonValue;
+    /** `kind` mirrors the session's ToolError: 'protocol' | 'tool' | 'transport' | 'timeout'. */
+    error?: {
+        kind: string;
+        code?: number;
+        codeName?: string;
+        message: string;
+    };
+    durationMs: number;
+    /** structuredContent validated against the tool's outputSchema; undefined = no outputSchema. */
+    structuredValid?: boolean;
+}
+interface Verdict {
+    ok: boolean;
+    detail?: string;
+    /** The invariant did not judge this outcome (e.g. no outputSchema declared). Always ok. */
+    skipped?: boolean;
+}
+type InvariantLevel = 'error' | 'warn';
+interface Invariant {
+    id: string;
+    title: string;
+    /** 'warn' verdicts are reported but never fail a run. */
+    level: InvariantLevel;
+    applies: (c: GeneratedCase) => boolean;
+    check: (c: GeneratedCase, outcome: FuzzOutcome) => Verdict;
+}
+interface EvaluatedVerdict extends Verdict {
+    invariant: string;
+    title: string;
+    level: InvariantLevel;
+}
+interface InvalidParamsOptions {
+    /**
+     * Accept a tool error (`isError: true`) as a correct rejection. MCP 2025-11-25 asks
+     * servers to report input validation failures as tool errors so the model can
+     * self-correct, so this defaults to true. Set false to require JSON-RPC InvalidParams.
+     */
+    acceptToolError?: boolean;
+}
+interface InvariantOptions extends InvalidParamsOptions {
+    /** Adds latency-under-budget when set. */
+    budgetMs?: number;
+}
+/** The standard invariant set; `latency-under-budget` only when `budgetMs` is given. */
+declare function createDefaultInvariants(opts?: InvariantOptions): Invariant[];
+declare const defaultInvariants: readonly Invariant[];
+/** Judge one outcome against every applicable invariant. */
+declare function evaluate(c: GeneratedCase, outcome: FuzzOutcome, invariants?: readonly Invariant[]): EvaluatedVerdict[];
+
+/** The on-disk config shape. Every key is optional; v1 files are valid. */
+interface ConfigFile {
+    $schema?: string;
+    /** v1 sugar for `servers.default`. */
+    server?: ServerConfig;
+    servers?: Record<string, ServerConfig>;
+    defaultServer?: string;
+    globs?: string[] | string;
+    manifest?: string;
+    normalize?: NormalizeConfig$1;
+    timeoutMs?: number;
+    budgetMs?: number;
+    failFast?: boolean;
+    allowEmpty?: boolean;
+    reporters?: string[] | string;
+    tags?: string[];
+    excludeTags?: string[];
+    grep?: string;
+    repeat?: number;
+    shard?: ShardSpec | string;
+    concurrency?: number;
+    update?: boolean;
+    trace?: boolean;
+    check?: boolean;
+    baseline?: string;
+    hooks?: SuiteHooks;
+    checks?: ChecksOptions;
+    manifestIgnore?: string[] | string;
+    outDir?: string;
+    profiles?: Record<string, ConfigFile>;
+}
+/** `checks` config: skipped check ids and per-check severity overrides. */
+type ChecksOptions = NonNullable<RunOptions['checks']>;
+/** Programmatic / CLI overrides: the top layer. */
+interface ConfigOverrides extends Partial<Omit<RunOptions, 'servers' | 'rootDir' | 'normalize' | 'defaultServer'>> {
+    servers?: Record<string, ServerConfig>;
+    defaultServer?: string;
+    normalize?: NormalizeConfig$1;
+    /**
+     * CLI `--server`: a name from `servers` (selects it), an http(s) URL, or a command line
+     * (`"node dist/index.js"`) replacing the selected server's command.
+     */
+    server?: string;
+    /** CLI `--server-cwd` (absolute) for the selected stdio server. */
+    serverCwd?: string;
+    /** CLI `--env KEY=VALUE`: merged into every stdio server's env. */
+    env?: Record<string, string>;
+    /** CLI `--protocol`: applied to every server. */
+    protocol?: ProtocolMode;
+}
+interface ResolveOptionsInput {
+    /** Explicit config file (absolute or relative to cwd). */
+    configPath?: string;
+    /** Name under `profiles` to merge over the base config. */
+    profile?: string;
+    overrides?: ConfigOverrides;
+    /** Environment for `${VAR}` interpolation. Default `process.env`. */
+    env?: Record<string, string | undefined>;
+}
+interface ResolvedConfig {
+    options: RunOptions;
+    /** Non-fatal problems (unknown keys, unset env vars). Print them; do not ignore them. */
+    warnings: string[];
+    configPath?: string;
+    profile?: string;
+}
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+/** Parse "auto" | "legacy" | "modern" | "<YYYY-MM-DD>" | { pin }. */
+declare function parseProtocolMode(value: unknown, onError?: (got: unknown) => never): ProtocolMode;
+/** Parse "1/4" or { index, total } (1-based). Undefined when invalid. */
+declare function parseShard(value: unknown): ShardSpec | undefined;
+/** Load + merge config. Prefer this in CLIs so `warnings` can be printed. */
+declare function loadConfig(cwd: string, input?: ResolveOptionsInput): ResolvedConfig;
+/**
+ * Resolve RunOptions: defaults → file → profile → overrides.
+ * The second argument may be a config path (v1 signature).
+ */
+declare function resolveOptions(cwd: string, input?: ResolveOptionsInput | string): RunOptions;
+
+declare const DEFAULT_NORMALIZE: Required<NormalizeConfig$1>;
+/** Built-in defaults: the bottom layer of defaults → file → profile → CLI. */
+declare const defaultRunOptions: RunOptions;
+/** @deprecated v1 name; use defaultRunOptions. */
+declare const defaultRunCasesOptions: RunOptions;
 
-export { type JsonValue, McpSession, type Mismatch, type RunCasesOptions, type ServerConfig, type TestCase, type ToolCallOutcome, type ToolError, type ToolSummary, defaultRunCasesOptions, matchValue, matches, runCases };
+export { BUILTIN_REPORTERS, CaseStatus, CheckOutcome, type CompileOptions, ConfigError, type ConfigFile, type ConfigOverrides, ConsoleReporter, DEFAULT_NORMALIZE, type FuzzOutcome, type GenerateOptions, type GeneratedCase, GithubReporter, type Invariant, type JsonCase, type JsonReport, JsonReporter, JsonValue, JunitReporter, MAX_MISMATCHES, ManifestLike, type MatchOptions, Mismatch, NormalizeConfig$1 as NormalizeConfig, ProtocolMode, RESULTS_FILE, type RefLoader, RefResolutionError, Reporter, ReporterContext, type ReporterFactory, type ResolvedConfig, RunOptions as RunCasesOptions, type RunChecksOptions, RunEvent, RunOptions, SchemaCompileError, type SchemaIssue, type SchemaRefResolver, ServerConfig, ShardSpec, SuiteHooks, TapReporter, UnknownReporterError, type ValidationResult, type Validator, checkSpec, compileSchema, createDefaultInvariants, createReporters, defaultInvariants, defaultNormalizeConfig, defaultRunCasesOptions, defaultRunOptions, escapeDirectives, evaluate, fanout, generateArgs, hasReporter, isMatcherObject, isValidSchema, lintDescriptions, lintExpectation, listChecks, listReporters, loadConfig, matchValue, matches, matchesGlob, normalizeResult, parseProtocolMode, parseShard, registerReporter, resetReporters, resolveOptions, resolveRefs, runChecks, suggestRespond, summarizeChecks, unregisterReporter, validate };