@opensearch-project/agent-health 0.4.0 → 0.6.0

package/lib/dist/lib/debug.js

@@ -0,0 +1,132 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Simple Debug Utility
+ *
+ * Single source of truth: agent-health.config.json on server
+ *
+ * Server: Reads/writes agent-health.config.json
+ * Browser: Uses localStorage cache (synced via Settings page API calls)
+ */
+import fs from 'fs';
+import path from 'path';
+const isBrowser = typeof window !== 'undefined';
+// Config v2: debug lives in the project runtime state file
+// (<cwd>/.agent-health/state.json). In code-first mode (an
+// agent-health.config.ts is present) it is in-memory only (DEBUG env still honored).
+// Kept fs/path-only here because this module is isomorphic (browser + server);
+// statePaths.ts is server-only.
+const STATE_DIR = '.agent-health';
+const STATE_FILE = 'state.json';
+const AUTHORED_CONFIG_NAMES = ['agent-health.config.ts', 'agent-health.config.js', 'agent-health.config.mjs'];
+function debugIsCodeFirst() {
+    // Mirror statePaths.isCodeFirstMode: an authored config at project OR user
+    // scope (~/.agent-health/) means code-first. os.homedir() is avoided so this
+    // isomorphic module stays browser-safe; this path only runs server-side.
+    const home = process.env.HOME || process.env.USERPROFILE || '';
+    return AUTHORED_CONFIG_NAMES.some((n) => fs.existsSync(path.join(process.cwd(), n)) ||
+        (!!home && fs.existsSync(path.join(home, STATE_DIR, n))));
+}
+function debugStatePath() {
+    return path.join(process.cwd(), STATE_DIR, STATE_FILE);
+}
+// Server-side: persist debug state in the runtime state file
+let serverDebugEnabled = false;
+// Initialize server debug state from the state file (ui-first) or env var
+if (!isBrowser) {
+    try {
+        const statePath = debugStatePath();
+        if (!debugIsCodeFirst() && fs.existsSync(statePath)) {
+            const config = JSON.parse(fs.readFileSync(statePath, 'utf-8')) || {};
+            serverDebugEnabled = config.debug === true;
+        }
+        else if (process.env?.DEBUG === 'true') {
+            serverDebugEnabled = true;
+        }
+    }
+    catch (err) {
+        // Ignore read errors, fall back to env var
+        if (process.env?.DEBUG === 'true') {
+            serverDebugEnabled = true;
+        }
+    }
+}
+/**
+ * Check if debug mode is enabled
+ * Server: reads from memory (loaded from agent-health.config.json)
+ * Browser: reads from localStorage cache (synced by Settings page)
+ */
+export function isDebugEnabled() {
+    if (isBrowser) {
+        try {
+            return localStorage.getItem('agenteval_debug') === 'true';
+        }
+        catch {
+            return false;
+        }
+    }
+    return serverDebugEnabled;
+}
+/**
+ * Set debug state
+ * Server: updates memory + persists to agent-health.config.json
+ * Browser: updates localStorage cache (Settings page also calls /api/debug)
+ */
+export function setDebugEnabled(enabled) {
+    if (isBrowser) {
+        try {
+            localStorage.setItem('agenteval_debug', String(enabled));
+        }
+        catch {
+            // Ignore errors (e.g. private browsing)
+        }
+        return;
+    }
+    // Server-side: update memory + persist to the runtime state file
+    serverDebugEnabled = enabled;
+    // Code-first mode: the state file is ignored; keep debug in-memory only.
+    if (debugIsCodeFirst()) {
+        console.info(`[Debug] code-first mode (agent-health.config.ts present): debug ${enabled ? 'enabled' : 'disabled'} in-memory only (not persisted)`);
+        return;
+    }
+    try {
+        const dir = path.join(process.cwd(), STATE_DIR);
+        const statePath = debugStatePath();
+        let config = {};
+        if (fs.existsSync(statePath)) {
+            const parsed = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                console.warn(`[Debug] State file contains non-object content, skipping write to avoid clobber`);
+                return;
+            }
+            config = parsed;
+        }
+        config.debug = enabled;
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(statePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+        console.info(`[Debug] Debug mode ${enabled ? 'enabled' : 'disabled'}, persisted to ${STATE_DIR}/${STATE_FILE}`);
+    }
+    catch (err) {
+        console.warn(`[Debug] Failed to persist debug state:`, err);
+    }
+}
+/**
+ * Debug log - only shown when debug mode is enabled
+ * Use for verbose/detailed logs that are noisy in normal operation
+ */
+export function debug(module, ...args) {
+    if (isDebugEnabled()) {
+        console.debug(`[${module}]`, ...args);
+    }
+}
+/**
+ * Standard log levels - always available, use appropriately:
+ * - console.error() - errors
+ * - console.warn() - warnings
+ * - console.info() - important milestones (connection established, eval complete)
+ * - console.log() - normal operational logs
+ * - debug() - verbose details (raw data, classifications, etc.)
+ */
+//# sourceMappingURL=debug.js.map

package/lib/dist/lib/debug.js.map

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

package/lib/dist/lib/diagnostics.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Startup-diagnostic gating.
+ *
+ * Informational startup lines (`[Connectors] … registered`, `[Config] …`) are
+ * useful in interactive use and in the long-running server's own log stream,
+ * but they MUST NOT corrupt machine-readable CLI output. `console.log` writes
+ * to stdout, which is exactly the channel `agent-health list … --output json`
+ * needs to keep clean for `| jq` / `python -m json.tool`.
+ *
+ * `canLogStartupDiagnosticsToStdout()` decides whether those lines may go to
+ * stdout. It returns false (suppress) when the current invocation is a CLI
+ * command whose stdout is being consumed by a machine:
+ *   - `--output json` / `-o json` / `--output=json` was requested, or
+ *   - `--quiet` / `-q`, or
+ *   - stdout is not an interactive TTY (piped to `| jq`, redirected to a file).
+ *
+ * The long-running server is exempt: its stdout IS its log stream (often a
+ * non-TTY pipe under a process manager / tunnel), so its startup diagnostics
+ * always pass through.
+ */
+export declare function canLogStartupDiagnosticsToStdout(): boolean;
+/**
+ * Convenience: emit an informational startup diagnostic to stdout, but only
+ * when it won't corrupt machine-readable output (see
+ * `canLogStartupDiagnosticsToStdout`). A no-op otherwise.
+ */
+export declare function logStartupDiagnostic(...args: unknown[]): void;
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/dist/lib/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../diagnostics.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gCAAgC,IAAI,OAAO,CAoB1D;AAUD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAK7D"}

package/lib/dist/lib/diagnostics.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Startup-diagnostic gating.
+ *
+ * Informational startup lines (`[Connectors] … registered`, `[Config] …`) are
+ * useful in interactive use and in the long-running server's own log stream,
+ * but they MUST NOT corrupt machine-readable CLI output. `console.log` writes
+ * to stdout, which is exactly the channel `agent-health list … --output json`
+ * needs to keep clean for `| jq` / `python -m json.tool`.
+ *
+ * `canLogStartupDiagnosticsToStdout()` decides whether those lines may go to
+ * stdout. It returns false (suppress) when the current invocation is a CLI
+ * command whose stdout is being consumed by a machine:
+ *   - `--output json` / `-o json` / `--output=json` was requested, or
+ *   - `--quiet` / `-q`, or
+ *   - stdout is not an interactive TTY (piped to `| jq`, redirected to a file).
+ *
+ * The long-running server is exempt: its stdout IS its log stream (often a
+ * non-TTY pipe under a process manager / tunnel), so its startup diagnostics
+ * always pass through.
+ */
+export function canLogStartupDiagnosticsToStdout() {
+    // Server process: stdout is its own log stream, not the CLI's data channel.
+    if (isServerProcess())
+        return true;
+    const args = process.argv.slice(2);
+    // Explicit quiet.
+    if (args.includes('--quiet') || args.includes('-q'))
+        return false;
+    // Structured output requested (the documented breakage: list … --output json).
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if ((a === '--output' || a === '-o') && /^json$/i.test(args[i + 1] ?? ''))
+            return false;
+        if (/^--output=json$/i.test(a))
+            return false;
+    }
+    // Piped or redirected stdout (| jq, > file): keep it machine-clean.
+    if (process.stdout.isTTY !== true)
+        return false;
+    return true;
+}
+function isServerProcess() {
+    if (process.env.AGENT_HEALTH_SERVER === '1')
+        return true;
+    const entry = process.argv[1] ?? '';
+    // server/dist/index.js (built) or server.ts / server/index.ts (tsx dev).
+    return /(?:^|[/\\])server[/\\](?:dist[/\\])?index\.(?:js|ts)$/.test(entry)
+        || /(?:^|[/\\])server\.ts$/.test(entry);
+}
+/**
+ * Convenience: emit an informational startup diagnostic to stdout, but only
+ * when it won't corrupt machine-readable output (see
+ * `canLogStartupDiagnosticsToStdout`). A no-op otherwise.
+ */
+export function logStartupDiagnostic(...args) {
+    if (canLogStartupDiagnosticsToStdout()) {
+        // eslint-disable-next-line no-console
+        console.log(...args);
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/lib/dist/lib/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../diagnostics.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,gCAAgC;IAC9C,4EAA4E;IAC5E,IAAI,eAAe,EAAE;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEnC,kBAAkB;IAClB,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAElE,+EAA+E;IAC/E,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,CAAC,KAAK,UAAU,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO,KAAK,CAAC;QACxF,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;IAC/C,CAAC;IAED,oEAAoE;IACpE,IAAI,OAAO,CAAC,MAAM,CAAC,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAEhD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,eAAe;IACtB,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IACpC,yEAAyE;IACzE,OAAO,uDAAuD,CAAC,IAAI,CAAC,KAAK,CAAC;WACrE,wBAAwB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAG,IAAe;IACrD,IAAI,gCAAgC,EAAE,EAAE,CAAC;QACvC,sCAAsC;QACtC,OAAO,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/lib/dist/lib/envCompat.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Read an env var, preferring `newName`, falling back to `oldName`.
+ * Returns `undefined` when neither is set.
+ *
+ * On first use of the old name in the current process, prints a one-time
+ * deprecation warning to stderr.
+ */
+export declare function readEnv(newName: string, oldName: string): string | undefined;
+/**
+ * Whether the old name is currently set (regardless of the new name).
+ * Useful for tests that exercise deprecation paths without triggering reads.
+ */
+export declare function isLegacyEnvSet(oldName: string): boolean;
+/**
+ * Emit a one-time deprecation warning for an old env var name.
+ * Subsequent calls for the same `oldName` are no-ops.
+ *
+ * Suppressed when AH_QUIET_DEPRECATIONS=1 (also accepts the old prefix
+ * AGENT_HEALTH_QUIET_DEPRECATIONS=1) so tests and CI can stay quiet.
+ */
+export declare function warnDeprecated(oldName: string, newName: string): void;
+/**
+ * TEST-ONLY: reset the warned set so a single test process can exercise
+ * multiple deprecation paths without one suppressing the next.
+ */
+export declare function _resetDeprecationCacheForTests(): void;
+//# sourceMappingURL=envCompat.d.ts.map

package/lib/dist/lib/envCompat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envCompat.d.ts","sourceRoot":"","sources":["../../envCompat.ts"],"names":[],"mappings":"AAuBA;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAkB5E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAGvD;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAkBrE;AAED;;;GAGG;AACH,wBAAgB,8BAA8B,IAAI,IAAI,CAErD"}

package/lib/dist/lib/envCompat.js

@@ -0,0 +1,82 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Environment Variable Compatibility Layer
+ *
+ * Soft-deprecation helper for the `AGENT_HEALTH_*` → `AH_*` env var rename.
+ *
+ * Read sites should prefer the new `AH_*` name but fall back to the old
+ * `AGENT_HEALTH_*` name for one release. Old names emit a one-time
+ * deprecation warning per process.
+ *
+ * Example:
+ *
+ *   const port = readEnv('AH_PORT', 'AGENT_HEALTH_PORT');
+ *
+ * The old name is scheduled for removal in a future major release.
+ */
+const warned = new Set();
+/**
+ * Read an env var, preferring `newName`, falling back to `oldName`.
+ * Returns `undefined` when neither is set.
+ *
+ * On first use of the old name in the current process, prints a one-time
+ * deprecation warning to stderr.
+ */
+export function readEnv(newName, oldName) {
+    // Browser-like environments (and tests simulating them) may have no
+    // process.env at all; env reads must degrade to "unset", never throw,
+    // because this helper sits on module-load paths (lib/config,
+    // lib/portConfig) that browser bundles also import.
+    const env = typeof process !== 'undefined' ? process.env : undefined;
+    if (!env)
+        return undefined;
+    const newVal = env[newName];
+    if (newVal !== undefined)
+        return newVal;
+    const oldVal = env[oldName];
+    if (oldVal !== undefined) {
+        warnDeprecated(oldName, newName);
+        return oldVal;
+    }
+    return undefined;
+}
+/**
+ * Whether the old name is currently set (regardless of the new name).
+ * Useful for tests that exercise deprecation paths without triggering reads.
+ */
+export function isLegacyEnvSet(oldName) {
+    const env = typeof process !== 'undefined' ? process.env : undefined;
+    return env ? env[oldName] !== undefined : false;
+}
+/**
+ * Emit a one-time deprecation warning for an old env var name.
+ * Subsequent calls for the same `oldName` are no-ops.
+ *
+ * Suppressed when AH_QUIET_DEPRECATIONS=1 (also accepts the old prefix
+ * AGENT_HEALTH_QUIET_DEPRECATIONS=1) so tests and CI can stay quiet.
+ */
+export function warnDeprecated(oldName, newName) {
+    if (warned.has(oldName))
+        return;
+    warned.add(oldName);
+    const env = typeof process !== 'undefined' ? process.env : undefined;
+    if (env?.AH_QUIET_DEPRECATIONS === '1' ||
+        env?.AGENT_HEALTH_QUIET_DEPRECATIONS === '1') {
+        return;
+    }
+    // Use console.warn so this surfaces in normal stderr but doesn't crash
+    // structured-logging consumers. Prefix matches the rest of the codebase.
+    console.warn(`[agent-health] Deprecated env var ${oldName} is set; please rename it to ${newName}. ` +
+        `The old name will be removed in a future release.`);
+}
+/**
+ * TEST-ONLY: reset the warned set so a single test process can exercise
+ * multiple deprecation paths without one suppressing the next.
+ */
+export function _resetDeprecationCacheForTests() {
+    warned.clear();
+}
+//# sourceMappingURL=envCompat.js.map

package/lib/dist/lib/envCompat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envCompat.js","sourceRoot":"","sources":["../../envCompat.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;AAEjC;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,OAAe,EAAE,OAAe;IACtD,oEAAoE;IACpE,sEAAsE;IACtE,6DAA6D;IAC7D,oDAAoD;IACpD,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAE3B,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IAExC,MAAM,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,CAAC;IAC5B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe;IAC5C,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;AAClD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,OAAe;IAC7D,IAAI,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO;IAChC,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IAEpB,MAAM,GAAG,GAAG,OAAO,OAAO,KAAK,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,IACE,GAAG,EAAE,qBAAqB,KAAK,GAAG;QAClC,GAAG,EAAE,+BAA+B,KAAK,GAAG,EAC5C,CAAC;QACD,OAAO;IACT,CAAC;IAED,uEAAuE;IACvE,yEAAyE;IACzE,OAAO,CAAC,IAAI,CACV,qCAAqC,OAAO,gCAAgC,OAAO,IAAI;QACvF,mDAAmD,CACpD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,8BAA8B;IAC5C,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC"}

package/lib/dist/lib/evaluationRerun.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Pure, isomorphic helpers for "re-run an evaluation run" (duplicate the
+ * source run's config into a brand-new run, linked back via `rerunOf`).
+ *
+ * Split out from the route/service layer so both the server (which owns the
+ * real duplication + creation) and the UI (which renders a name preview in
+ * the confirm dialog before the user commits) can share the exact same
+ * naming logic without an extra network round-trip. No storage/IO here.
+ */
+import type { EvaluationRun, TestCaseSource } from '../types/index.js';
+/**
+ * Compute the name for a new run being created as a re-run of `sourceName`.
+ *
+ * - "My Run"            -> "My Run (re-run)"
+ * - "My Run (re-run)"   -> "My Run (re-run 2)"
+ * - "My Run (re-run 2)" -> "My Run (re-run 3)"
+ * - undefined/empty     -> "Evaluation Run (re-run)"
+ */
+export declare function computeRerunName(sourceName: string | undefined | null): string;
+/**
+ * Fields duplicated onto the new run when re-running a source run. Mirrors
+ * the subset of {@link EvaluationRun} that `POST /api/storage/evaluation-runs`
+ * accepts as input (see server/routes/storage/evaluationRuns.ts) — i.e. the
+ * "config" as opposed to results/stats/timestamps, which are always fresh.
+ */
+export interface RerunConfig {
+    sources: TestCaseSource[];
+    agentKey: string;
+    /** Fallback modelId if the agent's own config can't resolve one (legacy). */
+    modelId: string;
+    judgeModelId?: string;
+    evaluatorId?: string;
+    headers?: Record<string, string>;
+    concurrency?: number;
+    agentEndpoint?: string;
+    description?: string;
+    benchmarkId?: string;
+    benchmarkVersion?: number;
+}
+export interface BuildRerunConfigResult {
+    config: RerunConfig;
+    /**
+     * Human-readable notes on which fields were missing on the source run and
+     * what explicit default was substituted (empty when the source run's
+     * config was fully populated). Surfaced back to the caller (API response
+     * -> UI) so a legacy run's best-effort re-run isn't a silent guess.
+     */
+    defaultsApplied: string[];
+}
+export interface BuildRerunConfigError {
+    error: string;
+}
+/**
+ * Duplicate a source run's execution config for a re-run, applying explicit,
+ * reported defaults for fields missing on legacy run documents. Pure
+ * function — no storage access (benchmark-existence checks live in
+ * services/evaluationRerun.ts, which needs the storage module).
+ *
+ * Returns `{ error }` only when the source run is missing a field with no
+ * safe default (nothing to run, or no agent to run it against).
+ */
+export declare function buildRerunConfig(sourceRun: EvaluationRun): BuildRerunConfigResult | BuildRerunConfigError;
+//# sourceMappingURL=evaluationRerun.d.ts.map

package/lib/dist/lib/evaluationRerun.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluationRerun.d.ts","sourceRoot":"","sources":["../../evaluationRerun.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAU7D;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,CAgB9E;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,WAAW,CAAC;IACpB;;;;;OAKG;IACH,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,aAAa,GACvB,sBAAsB,GAAG,qBAAqB,CAiDhD"}

package/lib/dist/lib/evaluationRerun.js

@@ -0,0 +1,85 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+const DEFAULT_RUN_NAME = 'Evaluation Run';
+/**
+ * Matches a trailing "(re-run)" or "(re-run N)" suffix, case-insensitively,
+ * capturing the base name and the optional numeric suffix.
+ */
+const RERUN_SUFFIX_RE = /^(.*?)\s*\(re-run(?:\s+(\d+))?\)$/i;
+/**
+ * Compute the name for a new run being created as a re-run of `sourceName`.
+ *
+ * - "My Run"            -> "My Run (re-run)"
+ * - "My Run (re-run)"   -> "My Run (re-run 2)"
+ * - "My Run (re-run 2)" -> "My Run (re-run 3)"
+ * - undefined/empty     -> "Evaluation Run (re-run)"
+ */
+export function computeRerunName(sourceName) {
+    const trimmed = (sourceName || '').trim();
+    const base = trimmed || DEFAULT_RUN_NAME;
+    const match = base.match(RERUN_SUFFIX_RE);
+    if (!match) {
+        return `${base} (re-run)`;
+    }
+    const [, rawBaseName, suffixNumber] = match;
+    // A source named literally "(re-run)" / "(re-run 2)" (no prefix) captures
+    // an empty baseName — fall back to the default rather than emitting a
+    // leading-space name like " (re-run 2)".
+    const baseName = rawBaseName.trim() || DEFAULT_RUN_NAME;
+    const nextNumber = suffixNumber ? parseInt(suffixNumber, 10) + 1 : 2;
+    return `${baseName} (re-run ${nextNumber})`;
+}
+/**
+ * Duplicate a source run's execution config for a re-run, applying explicit,
+ * reported defaults for fields missing on legacy run documents. Pure
+ * function — no storage access (benchmark-existence checks live in
+ * services/evaluationRerun.ts, which needs the storage module).
+ *
+ * Returns `{ error }` only when the source run is missing a field with no
+ * safe default (nothing to run, or no agent to run it against).
+ */
+export function buildRerunConfig(sourceRun) {
+    const defaultsApplied = [];
+    if (!sourceRun.agentKey) {
+        return { error: 'Source run is missing agentKey; cannot determine which agent to re-run.' };
+    }
+    let sources = sourceRun.sources;
+    if (!sources || sources.length === 0) {
+        const snapshotIds = (sourceRun.testCaseSnapshots || []).map(s => s.id);
+        if (snapshotIds.length === 0) {
+            return {
+                error: 'Source run has no test cases to re-run (missing both sources and testCaseSnapshots).',
+            };
+        }
+        sources = [{ type: 'test-case-ids', ids: snapshotIds }];
+        defaultsApplied.push(`sources -> derived from testCaseSnapshots (${snapshotIds.length} test case id(s); legacy run had no sources recorded)`);
+    }
+    let concurrency = sourceRun.concurrency;
+    if (concurrency == null) {
+        concurrency = 1;
+        defaultsApplied.push('concurrency -> 1 (default; not set on source run)');
+    }
+    const config = {
+        sources,
+        agentKey: sourceRun.agentKey,
+        modelId: sourceRun.modelId || '',
+        judgeModelId: sourceRun.judgeModelId,
+        evaluatorId: sourceRun.evaluatorId,
+        headers: sourceRun.headers,
+        concurrency,
+        agentEndpoint: sourceRun.agentEndpoint,
+        description: sourceRun.description,
+        benchmarkId: sourceRun.benchmarkId,
+        benchmarkVersion: sourceRun.benchmarkVersion,
+    };
+    // NOTE: evaluatorId/judgeModelId/agentEndpoint/headers/description are
+    // legitimately optional on ANY run (not just legacy ones), so leaving them
+    // `undefined` is normal behavior, not a legacy-config gap — they are NOT
+    // reported in `defaultsApplied` (that list is reserved for cases where we
+    // had to fabricate a value because the source run's config was
+    // incomplete).
+    return { config, defaultsApplied };
+}
+//# sourceMappingURL=evaluationRerun.js.map

package/lib/dist/lib/evaluationRerun.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluationRerun.js","sourceRoot":"","sources":["../../evaluationRerun.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAcH,MAAM,gBAAgB,GAAG,gBAAgB,CAAC;AAE1C;;;GAGG;AACH,MAAM,eAAe,GAAG,oCAAoC,CAAC;AAE7D;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,UAAqC;IACpE,MAAM,OAAO,GAAG,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1C,MAAM,IAAI,GAAG,OAAO,IAAI,gBAAgB,CAAC;IAEzC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,GAAG,IAAI,WAAW,CAAC;IAC5B,CAAC;IAED,MAAM,CAAC,EAAE,WAAW,EAAE,YAAY,CAAC,GAAG,KAAK,CAAC;IAC5C,0EAA0E;IAC1E,sEAAsE;IACtE,yCAAyC;IACzC,MAAM,QAAQ,GAAG,WAAW,CAAC,IAAI,EAAE,IAAI,gBAAgB,CAAC;IACxD,MAAM,UAAU,GAAG,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,OAAO,GAAG,QAAQ,YAAY,UAAU,GAAG,CAAC;AAC9C,CAAC;AAsCD;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAwB;IAExB,MAAM,eAAe,GAAa,EAAE,CAAC;IAErC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,yEAAyE,EAAE,CAAC;IAC9F,CAAC;IAED,IAAI,OAAO,GAAG,SAAS,CAAC,OAAO,CAAC;IAChC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrC,MAAM,WAAW,GAAG,CAAC,SAAS,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACvE,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO;gBACL,KAAK,EAAE,sFAAsF;aAC9F,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,WAAW,EAAE,CAAC,CAAC;QACxD,eAAe,CAAC,IAAI,CAClB,8CAA8C,WAAW,CAAC,MAAM,uDAAuD,CACxH,CAAC;IACJ,CAAC;IAED,IAAI,WAAW,GAAG,SAAS,CAAC,WAAW,CAAC;IACxC,IAAI,WAAW,IAAI,IAAI,EAAE,CAAC;QACxB,WAAW,GAAG,CAAC,CAAC;QAChB,eAAe,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;IAC5E,CAAC;IAED,MAAM,MAAM,GAAgB;QAC1B,OAAO;QACP,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,EAAE;QAChC,YAAY,EAAE,SAAS,CAAC,YAAY;QACpC,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,WAAW;QACX,aAAa,EAAE,SAAS,CAAC,aAAa;QACtC,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,gBAAgB,EAAE,SAAS,CAAC,gBAAgB;KAC7C,CAAC;IAEF,uEAAuE;IACvE,2EAA2E;IAC3E,yEAAyE;IACzE,0EAA0E;IAC1E,+DAA+D;IAC/D,eAAe;IAEf,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;AACrC,CAAC"}

package/lib/dist/lib/findPackageRoot.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Walk up from `startDir` looking for the agent-health package root.
+ *
+ * @throws if no package.json is found within `maxLevels` parents.
+ */
+export declare function findPackageRootFrom(startDir: string, maxLevels?: number): string;
+//# sourceMappingURL=findPackageRoot.d.ts.map

package/lib/dist/lib/findPackageRoot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"findPackageRoot.d.ts","sourceRoot":"","sources":["../../findPackageRoot.ts"],"names":[],"mappings":"AAyBA;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,GAAE,MAA2B,GACrC,MAAM,CA6BR"}

package/lib/dist/lib/findPackageRoot.js

@@ -0,0 +1,57 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Pure helper to locate the agent-health package root from any starting
+ * directory.
+ *
+ * Kept in its own file (no `import.meta.url`) so it can be unit-tested with
+ * ts-jest's CommonJS loader without needing module mocks.
+ *
+ * The walk preferentially anchors on the agent-health package.json (matched
+ * by `name`) so we don't stop at a parent monorepo root or a wrapper
+ * package.json. If no matching package.json is found within `maxLevels`
+ * (e.g., the user has forked and renamed the package), we fall back to the
+ * nearest package.json on the path — best-effort.
+ */
+import { existsSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+const PACKAGE_NAME = '@opensearch-project/agent-health';
+const DEFAULT_MAX_LEVELS = 6;
+/**
+ * Walk up from `startDir` looking for the agent-health package root.
+ *
+ * @throws if no package.json is found within `maxLevels` parents.
+ */
+export function findPackageRootFrom(startDir, maxLevels = DEFAULT_MAX_LEVELS) {
+    // First pass: prefer a package.json with the canonical agent-health name.
+    let dir = resolve(startDir);
+    let firstPkgRoot = null;
+    for (let i = 0; i <= maxLevels; i++) {
+        const pkgPath = join(dir, 'package.json');
+        if (existsSync(pkgPath)) {
+            if (firstPkgRoot === null)
+                firstPkgRoot = dir;
+            try {
+                const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+                if (pkg && pkg.name === PACKAGE_NAME)
+                    return dir;
+            }
+            catch {
+                /* unreadable / unparseable package.json — keep walking */
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: nearest package.json regardless of name. Covers forks that
+    // rename the package and unusual local layouts.
+    if (firstPkgRoot !== null)
+        return firstPkgRoot;
+    throw new Error(`Could not locate package root for ${PACKAGE_NAME} from ${startDir} ` +
+        `within ${maxLevels} parent directories`);
+}
+//# sourceMappingURL=findPackageRoot.js.map

package/lib/dist/lib/findPackageRoot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"findPackageRoot.js","sourceRoot":"","sources":["../../findPackageRoot.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,IAAI,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAE9C,MAAM,YAAY,GAAG,kCAAkC,CAAC;AACxD,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAE7B;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,YAAoB,kBAAkB;IAEtC,0EAA0E;IAC1E,IAAI,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,IAAI,YAAY,GAAkB,IAAI,CAAC;IAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,SAAS,EAAE,CAAC,EAAE,EAAE,CAAC;QACpC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,CAAC;QAC1C,IAAI,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;YACxB,IAAI,YAAY,KAAK,IAAI;gBAAE,YAAY,GAAG,GAAG,CAAC;YAC9C,IAAI,CAAC;gBACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;gBACtD,IAAI,GAAG,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY;oBAAE,OAAO,GAAG,CAAC;YACnD,CAAC;YAAC,MAAM,CAAC;gBACP,0DAA0D;YAC5D,CAAC;QACH,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,MAAM;QAC1B,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;IAED,uEAAuE;IACvE,gDAAgD;IAChD,IAAI,YAAY,KAAK,IAAI;QAAE,OAAO,YAAY,CAAC;IAE/C,MAAM,IAAI,KAAK,CACb,qCAAqC,YAAY,SAAS,QAAQ,GAAG;QACrE,UAAU,SAAS,qBAAqB,CACzC,CAAC;AACJ,CAAC"}

package/lib/dist/lib/hooks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent Lifecycle Hook Utilities
+ * Executes user-defined hooks from agent-health.config.ts
+ */
+import type { AgentHooks, BeforeRequestContext, AfterResponseContext, BuildTrajectoryContext, TrajectoryStep } from '../types/index.js';
+/**
+ * Execute the beforeRequest hook if defined on the agent.
+ *
+ * - Returns the original context unchanged if no hook is defined
+ * - Validates the hook return value has required fields
+ * - Wraps errors with a descriptive message including the agent key
+ */
+export declare function executeBeforeRequestHook(hooks: AgentHooks | undefined, context: BeforeRequestContext, agentKey: string): Promise<BeforeRequestContext>;
+/**
+ * Execute the afterResponse hook if defined on the agent.
+ *
+ * Use this hook to extract custom runId formats from agent responses
+ * (e.g., PER agent's memory_id).
+ *
+ * - Returns the original context unchanged if no hook is defined
+ * - Validates the hook return value has required fields
+ * - Wraps errors with a descriptive message including the agent key
+ */
+export declare function executeAfterResponseHook(hooks: AgentHooks | undefined, context: AfterResponseContext, agentKey: string): Promise<AfterResponseContext>;
+/**
+ * Execute the buildTrajectory hook if defined on the agent.
+ *
+ * Use this hook to customize trajectory extraction from OTEL traces
+ * for agents with custom span formats.
+ *
+ * - Returns null if no hook is defined
+ * - Validates the hook return value is an array
+ * - Wraps errors with a descriptive message including the agent key
+ */
+export declare function executeBuildTrajectoryHook(hooks: AgentHooks | undefined, context: BuildTrajectoryContext, agentKey: string): Promise<TrajectoryStep[] | null>;
+//# sourceMappingURL=hooks.d.ts.map

package/lib/dist/lib/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../hooks.ts"],"names":[],"mappings":"AAKA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAG9H;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,CAAC,CA6B/B;AAED;;;;;;;;;GASG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,OAAO,EAAE,oBAAoB,EAC7B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,CAAC,CAoC/B;AAED;;;;;;;;;GASG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,UAAU,GAAG,SAAS,EAC7B,OAAO,EAAE,sBAAsB,EAC/B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,EAAE,GAAG,IAAI,CAAC,CAkBlC"}