@opensearch-project/agent-health 0.4.0 → 0.6.0

package/lib/dist/lib/matchers/expect.js

@@ -0,0 +1,225 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Chai-based `expect` with two extensions:
+ *
+ *  1. A recording plugin that captures every assertion outcome on the
+ *     active matcher session (so the runner can persist per-matcher
+ *     results and the UI can show a breakdown).
+ *
+ *  2. Custom matchers tailored to agent trajectories:
+ *     - `.haveCalledTool(name)`            — tool was invoked
+ *     - `.haveStepsOfType(type)`           — at least one step of given type
+ *     - `.haveOutputMatching(regex)`       — final response matches regex
+ *     - `.haveCompletedWithin(ms)`         — durationMs is below threshold
+ *
+ * Chai's BDD style: `expect(value).to.<matcher>(...)`.
+ */
+import * as chai from 'chai';
+import { recordVerdict } from './session.js';
+let pluginsInstalled = false;
+/**
+ * Install the recording plugin once per process. Subsequent calls are
+ * no-ops so the plugin doesn't double-record when the SDK is loaded
+ * multiple times in the same Node session.
+ */
+function ensurePluginsInstalled() {
+    if (pluginsInstalled)
+        return;
+    pluginsInstalled = true;
+    const Assertion = chai.Assertion;
+    const utils = chai.util;
+    // ─── Recording plugin ────────────────────────────────────────────────
+    // Wraps Assertion.prototype.assert so every chai expr produces a
+    // MatcherResult on the active session.
+    const originalAssert = Assertion.prototype.assert;
+    Assertion.prototype.assert = function (expr, msg, negateMsg, expected, actual, showDiff) {
+        const negate = utils.flag(this, 'negate');
+        const ok = negate ? !expr : !!expr;
+        // chai resolves #{this}, #{exp}, #{act} placeholders only when it builds
+        // its own error message. We resolve them here so the recorded
+        // description is human-readable in the UI for both passing and failing
+        // assertions.
+        const description = describeAssertion(this, expr, msg, negateMsg, expected, actual, utils);
+        try {
+            const result = originalAssert.call(this, expr, msg, negateMsg, expected, actual, showDiff);
+            if (description) {
+                recordVerdict({
+                    description,
+                    pass: true,
+                    method: 'code-assertion',
+                    actual: safeClone(actual ?? utils.flag(this, 'object')),
+                    expected: safeClone(expected),
+                });
+            }
+            return result;
+        }
+        catch (err) {
+            if (description) {
+                recordVerdict({
+                    description,
+                    pass: false,
+                    method: 'code-assertion',
+                    actual: safeClone(actual ?? utils.flag(this, 'object')),
+                    expected: safeClone(expected),
+                    errorMessage: err?.message || String(err),
+                });
+            }
+            throw err;
+        }
+    };
+    // ─── Custom matchers ──────────────────────────────────────────────────
+    /**
+     * `.haveCalledTool(toolName, argsPartial?)`
+     * Asserts that `actual` is an array of TrajectoryStep with at least one
+     * `action` step whose toolName matches and whose toolArgs is a superset
+     * of `argsPartial` (when provided).
+     */
+    Assertion.addMethod('haveCalledTool', function (toolName, argsPartial) {
+        const trajectory = utils.flag(this, 'object');
+        if (!Array.isArray(trajectory)) {
+            this.assert(false, 'expected an array of TrajectoryStep', '', toolName, trajectory);
+            return;
+        }
+        const matches = trajectory.filter((step) => step?.type === 'action' && step?.toolName === toolName);
+        let hit = matches[0];
+        if (argsPartial && matches.length > 0) {
+            hit = matches.find((s) => isSupersetOf(s.toolArgs ?? s.input, argsPartial));
+        }
+        const argsLabel = argsPartial ? ` with args ${JSON.stringify(argsPartial)}` : '';
+        this.assert(!!hit, `expected trajectory to have called tool '${toolName}'${argsLabel}`, `expected trajectory to NOT have called tool '${toolName}'${argsLabel}`, toolName, matches.map((m) => ({ toolName: m.toolName, toolArgs: m.toolArgs ?? m.input })));
+    });
+    /**
+     * `.haveStepsOfType(type)` — at least one step has the given `type`
+     * (e.g. 'thinking', 'action', 'response', 'tool_result').
+     */
+    Assertion.addMethod('haveStepsOfType', function (type) {
+        const trajectory = utils.flag(this, 'object');
+        const arr = Array.isArray(trajectory) ? trajectory : [];
+        const found = arr.filter((s) => s?.type === type);
+        this.assert(found.length > 0, `expected trajectory to have at least one step of type '${type}'`, `expected trajectory to have NO steps of type '${type}' but found ${found.length}`, type, arr.map((s) => s?.type));
+    });
+    /**
+     * `.haveOutputMatching(pattern)` — `actual` is a string and matches the
+     * given regex (or contains the given substring).
+     */
+    Assertion.addMethod('haveOutputMatching', function (pattern) {
+        const text = utils.flag(this, 'object');
+        const str = typeof text === 'string' ? text : '';
+        const re = pattern instanceof RegExp ? pattern : new RegExp(escapeRegex(String(pattern)));
+        this.assert(re.test(str), `expected output to match ${re}`, `expected output to NOT match ${re}`, pattern, str);
+    });
+    /**
+     * `.haveCompletedWithin(thresholdMs)` — `actual` is an EvalResult-shaped
+     * object whose `durationMs` is below `thresholdMs`.
+     */
+    Assertion.addMethod('haveCompletedWithin', function (thresholdMs) {
+        const obj = utils.flag(this, 'object');
+        const duration = obj?.durationMs ?? 0;
+        this.assert(duration <= thresholdMs, `expected to have completed within ${thresholdMs}ms (took ${duration}ms)`, `expected to have NOT completed within ${thresholdMs}ms`, thresholdMs, duration);
+    });
+    /**
+     * `.toPass()` — assert a judge {@link Verdict} passed. Gives `judge()`'s
+     * non-throwing verdict an ergonomic gate:
+     *   expect(await judge(result, claim)).toPass();
+     * Reads `verdict.pass`; surfaces `verdict.reasoning` / `errorMessage` on
+     * failure so the recorded matcher is actionable.
+     */
+    Assertion.addMethod('toPass', function () {
+        const verdict = utils.flag(this, 'object');
+        const passed = !!verdict?.pass;
+        const detail = verdict?.errorMessage || verdict?.reasoning || '';
+        this.assert(passed, `expected judge verdict to pass${detail ? ` — ${detail}` : ''}`, `expected judge verdict to NOT pass`, true, passed);
+    });
+}
+ensurePluginsInstalled();
+/** The user-facing `expect` — chai's expect with our plugin pre-installed. */
+export const expect = chai.expect;
+/**
+ * Build a UI-friendly description for an assertion. Chai's raw msg/negateMsg
+ * contain `#{this}`, `#{exp}`, `#{act}` placeholders that only get resolved
+ * by chai when it builds an error message. We resolve them here so the
+ * description is readable on pass too.
+ */
+function describeAssertion(ctx, _expr, msg, negateMsg, expected, actual, utils) {
+    const rawMsg = typeof msg === 'function' ? msg() : msg;
+    const rawNeg = typeof negateMsg === 'function' ? negateMsg() : negateMsg;
+    const template = rawMsg || rawNeg || '';
+    if (!template)
+        return '';
+    const obj = utils.flag(ctx, 'object');
+    const resolved = template
+        .replace(/#\{this\}/g, () => safeInspect(obj, utils))
+        .replace(/#\{act\}/g, () => safeInspect(actual, utils))
+        .replace(/#\{exp\}/g, () => safeInspect(expected, utils));
+    return shortDescription(resolved);
+}
+function safeInspect(v, utils) {
+    try {
+        const str = utils.objDisplay && typeof utils.objDisplay === 'function'
+            ? utils.objDisplay(v)
+            : utils.inspect
+                ? utils.inspect(v)
+                : String(v);
+        if (typeof str !== 'string')
+            return String(v);
+        return str.length > 60 ? `${str.slice(0, 57)}\u2026` : str;
+    }
+    catch {
+        return String(v);
+    }
+}
+/** Trim chai's verbose default messages to a UI-friendly description. */
+function shortDescription(msg) {
+    // chai messages look like "expected X to contain Y". Drop the "expected X "
+    // prefix when we have a useful object label so the UI shows the matcher,
+    // not the actual data dump.
+    const trimmed = msg.replace(/^expected\s+/i, '');
+    // Cap at 120 chars to keep tables readable.
+    return trimmed.length > 120 ? `${trimmed.slice(0, 117)}\u2026` : trimmed;
+}
+/** Best-effort clone for serialization \u2014 stringify primitives and small objects. */
+function safeClone(v) {
+    if (v === undefined || v === null)
+        return v;
+    if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean')
+        return v;
+    try {
+        const s = JSON.stringify(v);
+        if (s && s.length < 2000)
+            return JSON.parse(s);
+        return s ? `${s.slice(0, 1997)}...` : '[unserializable]';
+    }
+    catch {
+        return '[circular]';
+    }
+}
+function isSupersetOf(actual, expected) {
+    if (typeof actual !== 'object' || actual === null)
+        return false;
+    for (const [k, v] of Object.entries(expected)) {
+        if (!(k in actual))
+            return false;
+        if (typeof v === 'object' && v !== null) {
+            if (!isSupersetOf(actual[k], v))
+                return false;
+        }
+        else if (actual[k] !== v) {
+            return false;
+        }
+    }
+    return true;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ─── TypeScript module augmentation ─────────────────────────────────
+// chai@4 uses ambient namespace declarations rather than modules, so we
+// can't `declare module 'chai'` here. The custom matchers above
+// (haveCalledTool, haveStepsOfType, haveOutputMatching, haveCompletedWithin)
+// are registered via `Assertion.addMethod` and work at runtime; user code
+// that wants type-safe access can either cast `as any` or drop a tiny
+// .d.ts in their own project that augments `Chai.Assertion`.
+//# sourceMappingURL=expect.js.map

package/lib/dist/lib/matchers/expect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expect.js","sourceRoot":"","sources":["../../../matchers/expect.ts"],"names":[],"mappings":"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"}

package/lib/dist/lib/matchers/index.d.ts

@@ -0,0 +1,8 @@
+export { expect } from './expect.js';
+export type { TracesAccessor } from './traces.js';
+export { buildTracesAccessor, emptyTracesAccessor, unavailableTracesAccessor } from './traces.js';
+export type { MatcherResult, MatcherMethod } from './types.js';
+export { getJudgeMatcherResults, getJudgeReasoningText, recordJudgeMatcherResult, buildJudgeMatcherEntry, formatExpectedOutcomesAsClaim, } from './judgeAccessor.js';
+export type { JudgeAccessReport, JudgeResultLike } from './judgeAccessor.js';
+export { startSession, endSession, isSessionActive, recordVerdict, recordWithTiming, runInSession, } from './session.js';
+//# sourceMappingURL=index.d.ts.map

package/lib/dist/lib/matchers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../matchers/index.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAClG,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC/D,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EACL,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,YAAY,GACb,MAAM,cAAc,CAAC"}

package/lib/dist/lib/matchers/index.js

@@ -0,0 +1,9 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+export { expect } from './expect.js';
+export { buildTracesAccessor, emptyTracesAccessor, unavailableTracesAccessor } from './traces.js';
+export { getJudgeMatcherResults, getJudgeReasoningText, recordJudgeMatcherResult, buildJudgeMatcherEntry, formatExpectedOutcomesAsClaim, } from './judgeAccessor.js';
+export { startSession, endSession, isSessionActive, recordVerdict, recordWithTiming, runInSession, } from './session.js';
+//# sourceMappingURL=index.js.map

package/lib/dist/lib/matchers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../matchers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAElG,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,6BAA6B,GAC9B,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,YAAY,EACZ,UAAU,EACV,eAAe,EACf,aAAa,EACb,gBAAgB,EAChB,YAAY,GACb,MAAM,cAAc,CAAC"}

package/lib/dist/lib/matchers/judgeAccessor.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Unified judge accessor — single source of truth for "what the LLM judge
+ * said" on an EvaluationReport.
+ *
+ * Background: historically the judge verdict + reasoning lived in two
+ * parallel surfaces:
+ *
+ *   1. report.llmJudgeReasoning (string) — written by the legacy
+ *      auto-judge path (services/evaluation/index.ts and the various
+ *      runners that call callBedrockJudge against expectedOutcomes).
+ *      One per report, last writer wins.
+ *
+ *   2. report.matcherResults[*] with method: 'llm-judge' — written by
+ *      the SDK `judge(result, claim)` matcher. Many per report.
+ *
+ * Both ultimately come from the same Bedrock Judge endpoint. Storing
+ * them in two places caused real bugs (notably issue #230, where the
+ * trace-mode placeholder leaked into the legacy field and bled through
+ * to the UI for deterministic SDK runs).
+ *
+ * The fix: `matcherResults[]` is the canonical surface. The legacy
+ * `llmJudgeReasoning` field is kept populated as a derived
+ * convenience for backward-compat readers, but new code MUST use
+ * {@link getJudgeMatcherResults} on the read side and
+ * {@link recordJudgeMatcherResult} on the write side.
+ */
+import type { MatcherResult } from './types.js';
+/** A minimal duck-typed report shape — accepts any object with the two fields. */
+export interface JudgeAccessReport {
+    matcherResults?: MatcherResult[];
+    llmJudgeReasoning?: string;
+}
+/**
+ * Returns every llm-judge MatcherResult on the report, including a
+ * synthetic entry derived from the legacy `llmJudgeReasoning` field
+ * when the report pre-dates the unified surface.
+ *
+ * Read-only: nothing is written back to the report.
+ *
+ * Behaviour matrix:
+ *
+ * | matcherResults has [llm-judge] | llmJudgeReasoning      | Returns                    |
+ * |--------------------------------|------------------------|----------------------------|
+ * | yes                            | anything               | the existing entries       |
+ * | no                             | empty / placeholder    | []                         |
+ * | no                             | real reasoning         | [<synthetic entry>]        |
+ *
+ * The placeholder string `Waiting for traces to become available...`
+ * is treated as "no judge ran yet" \u2014 see issue #230.
+ */
+export declare function getJudgeMatcherResults(report: JudgeAccessReport): MatcherResult[];
+/**
+ * Convenience: the single most recent llm-judge reasoning string, or
+ * empty when no judge ran. Used by surfaces that historically read
+ * `llmJudgeReasoning` directly (HTML report, skills grader, compare
+ * view) and only need a flat string.
+ */
+export declare function getJudgeReasoningText(report: JudgeAccessReport): string;
+/**
+ * Convert a `JudgeResult` from `callBedrockJudge` into a `MatcherResult`.
+ * Pure: doesn't touch any report. Used by inline-return code paths in
+ * services/evaluation/index.ts where building a fresh report object is
+ * cleaner than the mutate-then-return pattern.
+ */
+export declare function buildJudgeMatcherEntry(judgeResult: JudgeResultLike, options?: {
+    claim?: string;
+    model?: string;
+}): MatcherResult;
+/**
+ * Format an arbitrary `expectedOutcomes` value into a single description
+ * fragment suitable for the matcher entry's `description` field. Accepts
+ * the SDK's flat `string[]` *and* the legacy `{ rootCauses, requiredFacts,
+ * conclusions }` object — both shapes appear on persisted test cases.
+ */
+export declare function formatExpectedOutcomesAsClaim(outcomes?: unknown): string;
+/**
+ * Convert a `JudgeResult` from `callBedrockJudge` into a `MatcherResult`
+ * and append it to `report.matcherResults`. Also keeps the legacy
+ * `report.llmJudgeReasoning` field populated as a derived
+ * backward-compat shim (it equals the reasoning of the just-pushed
+ * entry, so direct readers continue to work).
+ *
+ * Mutates the passed report and returns the matcher entry.
+ *
+ * The `claim` argument is what the auto-judge was evaluating against
+ * (the test case's expected outcomes). The matcher description ends
+ * up as `judge: <claim>` matching the SDK convention.
+ */
+export declare function recordJudgeMatcherResult(report: JudgeAccessReport & {
+    matcherResults?: MatcherResult[];
+    llmJudgeReasoning?: string;
+}, judgeResult: JudgeResultLike, options?: {
+    claim?: string;
+    model?: string;
+}): MatcherResult;
+/** Subset of `JudgeResult` we depend on \u2014 keeps this module type-import-light. */
+export interface JudgeResultLike {
+    passFailStatus: 'passed' | 'failed';
+    metrics: {
+        accuracy?: number;
+        [k: string]: number | undefined;
+    };
+    llmJudgeReasoning: string;
+    judgeDurationMs?: number;
+    improvementStrategies?: Array<{
+        category: string;
+        issue: string;
+        recommendation: string;
+        priority: 'high' | 'medium' | 'low';
+    }>;
+}
+export type { JudgeResult } from '../../types/index.js';
+//# sourceMappingURL=judgeAccessor.d.ts.map

package/lib/dist/lib/matchers/judgeAccessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgeAccessor.d.ts","sourceRoot":"","sources":["../../../matchers/judgeAccessor.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,iBAAiB,GAAG,aAAa,EAAE,CAuBjF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,iBAAiB,GAAG,MAAM,CAevE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,eAAe,EAC5B,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,aAAa,CA0Bf;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,CAAC,EAAE,OAAO,GAAG,MAAM,CAoBxE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,iBAAiB,GAAG;IAAE,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5F,WAAW,EAAE,eAAe,EAC5B,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3C,aAAa,CAcf;AAED,uFAAuF;AACvF,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,QAAQ,GAAG,QAAQ,CAAC;IACpC,OAAO,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IAChE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,qBAAqB,CAAC,EAAE,KAAK,CAAC;QAC5B,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,cAAc,EAAE,MAAM,CAAC;QACvB,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;KACrC,CAAC,CAAC;CACJ;AA+BD,YAAY,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/dist/lib/matchers/judgeAccessor.js

@@ -0,0 +1,183 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Returns every llm-judge MatcherResult on the report, including a
+ * synthetic entry derived from the legacy `llmJudgeReasoning` field
+ * when the report pre-dates the unified surface.
+ *
+ * Read-only: nothing is written back to the report.
+ *
+ * Behaviour matrix:
+ *
+ * | matcherResults has [llm-judge] | llmJudgeReasoning      | Returns                    |
+ * |--------------------------------|------------------------|----------------------------|
+ * | yes                            | anything               | the existing entries       |
+ * | no                             | empty / placeholder    | []                         |
+ * | no                             | real reasoning         | [<synthetic entry>]        |
+ *
+ * The placeholder string `Waiting for traces to become available...`
+ * is treated as "no judge ran yet" \u2014 see issue #230.
+ */
+export function getJudgeMatcherResults(report) {
+    const fromMatcher = (report.matcherResults ?? []).filter(m => m.method === 'llm-judge');
+    if (fromMatcher.length > 0) {
+        return fromMatcher;
+    }
+    const legacy = report.llmJudgeReasoning?.trim();
+    if (!legacy || isPlaceholderReasoning(legacy)) {
+        return [];
+    }
+    // Old report: synthesize a single virtual matcher entry so UIs that
+    // render only matcherResults still have something to show.
+    return [
+        {
+            description: 'judge: expected outcomes',
+            pass: inferPassFromReport(report),
+            method: 'llm-judge',
+            reasoning: legacy,
+        },
+    ];
+}
+/**
+ * Convenience: the single most recent llm-judge reasoning string, or
+ * empty when no judge ran. Used by surfaces that historically read
+ * `llmJudgeReasoning` directly (HTML report, skills grader, compare
+ * view) and only need a flat string.
+ */
+export function getJudgeReasoningText(report) {
+    const entries = getJudgeMatcherResults(report);
+    if (entries.length === 0)
+        return '';
+    // Most-recent-first: prefer the last entry the runner pushed. If
+    // multiple entries exist (SDK with several judge() calls) we join
+    // them with horizontal-rule markers so a flat-string consumer still
+    // sees every claim.
+    if (entries.length === 1)
+        return entries[0].reasoning ?? '';
+    return entries
+        .map((m, i) => {
+        const claim = m.description?.replace(/^judge:\s*/, '') ?? `claim ${i + 1}`;
+        const verdict = m.pass ? 'PASS' : 'FAIL';
+        return `### ${verdict} \u2014 ${claim}\n\n${m.reasoning ?? ''}`;
+    })
+        .join('\n\n---\n\n');
+}
+/**
+ * Convert a `JudgeResult` from `callBedrockJudge` into a `MatcherResult`.
+ * Pure: doesn't touch any report. Used by inline-return code paths in
+ * services/evaluation/index.ts where building a fresh report object is
+ * cleaner than the mutate-then-return pattern.
+ */
+export function buildJudgeMatcherEntry(judgeResult, options) {
+    const claim = options?.claim?.trim() || 'expected outcomes';
+    const accuracy = judgeResult.metrics?.accuracy;
+    const score = typeof accuracy === 'number' ? accuracy / 100 : undefined;
+    const pass = judgeResult.passFailStatus === 'passed';
+    const reasoning = judgeResult.llmJudgeReasoning ?? '';
+    return {
+        description: `judge: ${claim}`,
+        pass,
+        method: 'llm-judge',
+        durationMs: judgeResult.judgeDurationMs,
+        score,
+        reasoning,
+        ...(options?.model ? { model: options.model } : {}),
+        ...(pass ? {} : { errorMessage: reasoning }),
+        // Carry the rest of the judge payload through so SDK
+        // `getJudgeMatcherResults()` consumers see the same data the
+        // legacy report-level fields used to expose. See MatcherResult.
+        ...(Array.isArray(judgeResult.improvementStrategies) && judgeResult.improvementStrategies.length > 0
+            ? { improvementStrategies: judgeResult.improvementStrategies }
+            : {}),
+        ...(judgeResult.metrics && typeof judgeResult.metrics === 'object'
+            ? { judgeMetrics: { ...judgeResult.metrics } }
+            : {}),
+    };
+}
+/**
+ * Format an arbitrary `expectedOutcomes` value into a single description
+ * fragment suitable for the matcher entry's `description` field. Accepts
+ * the SDK's flat `string[]` *and* the legacy `{ rootCauses, requiredFacts,
+ * conclusions }` object — both shapes appear on persisted test cases.
+ */
+export function formatExpectedOutcomesAsClaim(outcomes) {
+    const items = [];
+    if (Array.isArray(outcomes)) {
+        for (const o of outcomes) {
+            if (typeof o === 'string' && o.trim())
+                items.push(o.trim());
+        }
+    }
+    else if (outcomes && typeof outcomes === 'object') {
+        // Legacy shape: { rootCauses?: string[]; requiredFacts?: string[]; conclusions?: string[] }
+        for (const key of Object.keys(outcomes)) {
+            const v = outcomes[key];
+            if (Array.isArray(v)) {
+                for (const s of v) {
+                    if (typeof s === 'string' && s.trim())
+                        items.push(s.trim());
+                }
+            }
+        }
+    }
+    if (items.length === 0)
+        return 'expected outcomes';
+    if (items.length === 1)
+        return items[0];
+    return `${items.length} expected outcomes`;
+}
+/**
+ * Convert a `JudgeResult` from `callBedrockJudge` into a `MatcherResult`
+ * and append it to `report.matcherResults`. Also keeps the legacy
+ * `report.llmJudgeReasoning` field populated as a derived
+ * backward-compat shim (it equals the reasoning of the just-pushed
+ * entry, so direct readers continue to work).
+ *
+ * Mutates the passed report and returns the matcher entry.
+ *
+ * The `claim` argument is what the auto-judge was evaluating against
+ * (the test case's expected outcomes). The matcher description ends
+ * up as `judge: <claim>` matching the SDK convention.
+ */
+export function recordJudgeMatcherResult(report, judgeResult, options) {
+    const entry = buildJudgeMatcherEntry(judgeResult, options);
+    const existing = report.matcherResults ?? [];
+    report.matcherResults = [...existing, entry];
+    // Backward-compat shim: keep the legacy field populated with the most
+    // recent reasoning so external readers that haven't migrated still
+    // work. Empty string is a deliberate signal for SDK-multi-judge runs
+    // (the field can't represent multiple verdicts; consumers must look
+    // at matcherResults).
+    report.llmJudgeReasoning = entry.reasoning ?? '';
+    return entry;
+}
+// ─── internal helpers ───────────────────────────────────────────────────────
+/**
+ * The trace-mode init path sets `llmJudgeReasoning` to a placeholder
+ * before any real verdict exists. We must not synthesize a virtual
+ * matcher entry from that string \u2014 it's a "judge has not run yet"
+ * signal, not real reasoning.
+ */
+function isPlaceholderReasoning(s) {
+    return /^Waiting for traces/i.test(s);
+}
+/**
+ * Best-effort guess at the verdict for a synthesized entry on an old
+ * report. Prefers an explicit `passFailStatus` if present; otherwise
+ * falls back to the report's metrics.accuracy (>=70 ~ pass), and
+ * finally defaults to `false` so a missing verdict never silently
+ * looks green.
+ */
+function inferPassFromReport(report) {
+    if (report.passFailStatus === 'passed')
+        return true;
+    if (report.passFailStatus === 'failed')
+        return false;
+    const acc = report.metrics?.accuracy;
+    if (typeof acc === 'number')
+        return acc >= 70;
+    return false;
+}
+//# sourceMappingURL=judgeAccessor.js.map

package/lib/dist/lib/matchers/judgeAccessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"judgeAccessor.js","sourceRoot":"","sources":["../../../matchers/judgeAccessor.ts"],"names":[],"mappings":"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"}

package/lib/dist/lib/matchers/session.d.ts

@@ -0,0 +1,39 @@
+import type { MatcherResult, MatcherMethod } from './types.js';
+export interface MatcherSession {
+    results: MatcherResult[];
+    startedAt: number;
+}
+/**
+ * Run `fn` with a fresh, isolated matcher session and return the verdicts
+ * recorded during it. Concurrency-safe: each call gets its own session via
+ * AsyncLocalStorage, so interleaved bodies never share verdicts.
+ *
+ * Results are returned even when `fn` throws — the caller can inspect both
+ * the partial results and the error (cleanup hooks that record after a body
+ * failure therefore still surface in the breakdown).
+ */
+export declare function runInSession<T>(fn: () => Promise<T> | T): Promise<{
+    results: MatcherResult[];
+    value?: T;
+    error?: unknown;
+}>;
+/**
+ * Begin a fresh global session and make it active (legacy API).
+ *
+ * Prefer {@link runInSession} for anything that may run concurrently. This
+ * remains for synchronous, single-threaded callers.
+ */
+export declare function startSession(): MatcherSession;
+/** Stop the current global session and return its results (legacy API). */
+export declare function endSession(): MatcherResult[];
+/** True when a session is active (ALS scope or legacy global). */
+export declare function isSessionActive(): boolean;
+/** Record a single matcher verdict on the active session. No-op when none. */
+export declare function recordVerdict(result: MatcherResult): void;
+/**
+ * Record a verdict computed from a try/catch around the matcher body.
+ * Convenience wrapper used by judge() and traces helpers; chai matchers go
+ * through the chai plugin in `./expect.ts`.
+ */
+export declare function recordWithTiming<T>(description: string, method: MatcherMethod, fn: () => Promise<T> | T): Promise<T>;
+//# sourceMappingURL=session.d.ts.map

package/lib/dist/lib/matchers/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../matchers/session.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;CACnB;AAiBD;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,CAQnE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,cAAc,CAG7C;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,IAAI,aAAa,EAAE,CAK5C;AAED,kEAAkE;AAClE,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAIzD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,aAAa,EACrB,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACvB,OAAO,CAAC,CAAC,CAAC,CAqBZ"}