@opensearch-project/agent-health 0.3.0 → 0.5.2

package/lib/dist/lib/benchmarkVersionUtils.js.map

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

package/lib/dist/lib/config/defineConfig.d.ts

@@ -0,0 +1,27 @@
+/**
+ * defineConfig Helper
+ * Provides type safety for agent-health.config.ts files
+ */
+import type { UserConfig } from './types.js';
+/**
+ * Define configuration with full type safety
+ *
+ * @example
+ * ```typescript
+ * // agent-health.config.ts
+ * import { defineConfig } from '@opensearch-project/agent-health';
+ *
+ * export default defineConfig({
+ *   agents: [
+ *     {
+ *       key: 'my-agent',
+ *       name: 'My Agent',
+ *       endpoint: 'https://api.example.com/chat',
+ *       connectorType: 'rest',
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export declare function defineConfig(config: UserConfig): UserConfig;
+//# sourceMappingURL=defineConfig.d.ts.map

package/lib/dist/lib/config/defineConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineConfig.d.ts","sourceRoot":"","sources":["../../../config/defineConfig.ts"],"names":[],"mappings":"AAKA;;;GAGG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAE3D"}

package/lib/dist/lib/config/defineConfig.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Define configuration with full type safety
+ *
+ * @example
+ * ```typescript
+ * // agent-health.config.ts
+ * import { defineConfig } from '@opensearch-project/agent-health';
+ *
+ * export default defineConfig({
+ *   agents: [
+ *     {
+ *       key: 'my-agent',
+ *       name: 'My Agent',
+ *       endpoint: 'https://api.example.com/chat',
+ *       connectorType: 'rest',
+ *     },
+ *   ],
+ * });
+ * ```
+ */
+export function defineConfig(config) {
+    return config;
+}
+//# sourceMappingURL=defineConfig.js.map

package/lib/dist/lib/config/defineConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defineConfig.js","sourceRoot":"","sources":["../../../config/defineConfig.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAAC,MAAkB;IAC7C,OAAO,MAAM,CAAC;AAChB,CAAC"}

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

@@ -0,0 +1,9 @@
+/**
+ * Config Module
+ * Public exports for configuration system
+ */
+export type { UserConfig, UserAgentConfig, UserModelConfig, ResolvedConfig, ConfigFileInfo, ReporterConfig, JudgeConfig, ServerConfig, ResolvedServerConfig, } from './types.js';
+export type { AgentHooks, BeforeRequestContext } from '../../types/index.js';
+export { defineConfig } from './defineConfig.js';
+export { loadConfig, loadConfigSync, findConfigFile, getConfigFileInfo, clearConfigCache, DEFAULT_SERVER_CONFIG, } from './loader.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../config/index.ts"],"names":[],"mappings":"AAKA;;;GAGG;AAGH,YAAY,EACV,UAAU,EACV,eAAe,EACf,eAAe,EACf,cAAc,EACd,cAAc,EACd,cAAc,EACd,WAAW,EACX,YAAY,EACZ,oBAAoB,GACrB,MAAM,SAAS,CAAC;AAGjB,YAAY,EAAE,UAAU,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAGhE,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,UAAU,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,UAAU,CAAC"}

package/lib/dist/lib/config/index.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+// Function exports
+export { defineConfig } from './defineConfig.js';
+export { loadConfig, loadConfigSync, findConfigFile, getConfigFileInfo, clearConfigCache, DEFAULT_SERVER_CONFIG, } from './loader.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../config/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH,mBAAmB;AACnB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,UAAU,EACV,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,qBAAqB,GACtB,MAAM,UAAU,CAAC"}

package/lib/dist/lib/config/loader.d.ts

@@ -0,0 +1,39 @@
+import type { ResolvedConfig, ResolvedServerConfig, ConfigFileInfo } from './types.js';
+/**
+ * Default server configuration
+ * Follows Playwright's webServer pattern
+ */
+export declare const DEFAULT_SERVER_CONFIG: ResolvedServerConfig;
+/**
+ * Runtime state file (config v2: `.agent-health/state.json`, user or project
+ * scope). Loaded by the *server services* (configService, customAgentStore,
+ * dataSourceConfig), not by this loader. We only probe for it so the startup
+ * log can tell the user whether on-disk runtime state is in effect (ui-first
+ * mode) instead of saying "No config file found".
+ */
+export declare function hasServerJsonConfig(cwd?: string): boolean;
+/**
+ * Find config file in the given directory
+ */
+export declare function findConfigFile(cwd?: string): ConfigFileInfo | null;
+/**
+ * Load and resolve configuration
+ *
+ * @param cwd - Working directory to search for config file
+ * @param force - Force reload even if cached
+ */
+export declare function loadConfig(cwd?: string, force?: boolean): Promise<ResolvedConfig>;
+/**
+ * Load config synchronously (for use in module initialization)
+ * Returns defaults if no config file or if loading fails
+ */
+export declare function loadConfigSync(cwd?: string): ResolvedConfig;
+/**
+ * Clear config cache (useful for testing)
+ */
+export declare function clearConfigCache(): void;
+/**
+ * Get config file info without loading
+ */
+export declare function getConfigFileInfo(cwd?: string): ConfigFileInfo | null;
+//# sourceMappingURL=loader.d.ts.map

package/lib/dist/lib/config/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../config/loader.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAIV,cAAc,EACd,oBAAoB,EACpB,cAAc,EAIf,MAAM,SAAS,CAAC;AAEjB;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,oBAInC,CAAC;AAWF;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAExE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,cAAc,GAAG,IAAI,CASjF;AAmJD;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,GAAG,GAAE,MAAsB,EAC3B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,cAAc,CAAC,CAqCzB;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,cAAc,CAmB1E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,cAAc,GAAG,IAAI,CAEpF"}

package/lib/dist/lib/config/loader.js

@@ -0,0 +1,258 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Config Loader
+ * Loads and resolves agent-health.config.ts files
+ */
+import { existsSync } from 'fs';
+import { resolve } from 'path';
+import { projectStatePath, userStatePath } from './statePaths.js';
+import { logStartupDiagnostic } from '../../lib/diagnostics.js';
+import { pathToFileURL } from 'url';
+import { DEFAULT_CONFIG } from '../../lib/constants.js';
+import { resolveBackendPort } from '../../lib/portConfig.js';
+/**
+ * Default server configuration
+ * Follows Playwright's webServer pattern
+ */
+export const DEFAULT_SERVER_CONFIG = {
+    port: resolveBackendPort(),
+    reuseExistingServer: !process.env.CI,
+    startTimeout: 30000,
+};
+/**
+ * Config file names to search for (in priority order)
+ */
+const CONFIG_FILE_NAMES = [
+    'agent-health.config.ts',
+    'agent-health.config.js',
+    'agent-health.config.mjs',
+];
+/**
+ * Runtime state file (config v2: `.agent-health/state.json`, user or project
+ * scope). Loaded by the *server services* (configService, customAgentStore,
+ * dataSourceConfig), not by this loader. We only probe for it so the startup
+ * log can tell the user whether on-disk runtime state is in effect (ui-first
+ * mode) instead of saying "No config file found".
+ */
+export function hasServerJsonConfig(cwd = process.cwd()) {
+    return existsSync(projectStatePath(cwd)) || existsSync(userStatePath());
+}
+/**
+ * Find config file in the given directory
+ */
+export function findConfigFile(cwd = process.cwd()) {
+    for (const fileName of CONFIG_FILE_NAMES) {
+        const filePath = resolve(cwd, fileName);
+        if (existsSync(filePath)) {
+            const format = fileName.endsWith('.ts') ? 'typescript' : 'javascript';
+            return { path: filePath, format, exists: true };
+        }
+    }
+    return null;
+}
+/**
+ * Convert UserAgentConfig to AgentConfig
+ */
+function toAgentConfig(userAgent) {
+    return {
+        key: userAgent.key,
+        name: userAgent.name,
+        endpoint: userAgent.endpoint,
+        description: userAgent.description,
+        enabled: userAgent.enabled ?? true,
+        headers: userAgent.headers ?? {},
+        useTraces: userAgent.useTraces ?? false,
+        connectorType: userAgent.connectorType,
+        connectorConfig: userAgent.connectorConfig,
+        hooks: userAgent.hooks,
+    };
+}
+/**
+ * Convert UserModelConfig to ModelConfig entry
+ */
+function toModelConfig(userModel) {
+    return [
+        userModel.key,
+        {
+            model_id: userModel.model_id,
+            display_name: userModel.display_name,
+            provider: userModel.provider ?? 'bedrock',
+            context_window: userModel.context_window ?? 200000,
+            max_output_tokens: userModel.max_output_tokens ?? 4096,
+        },
+    ];
+}
+/**
+ * Merge user config with defaults
+ */
+function mergeConfigs(userConfig, defaultConfig) {
+    const shouldExtend = userConfig.extends !== false;
+    // Merge agents
+    let agents;
+    if (shouldExtend) {
+        // Start with defaults, override/add user agents
+        const agentMap = new Map();
+        for (const agent of defaultConfig.agents) {
+            agentMap.set(agent.key, agent);
+        }
+        for (const userAgent of userConfig.agents ?? []) {
+            agentMap.set(userAgent.key, toAgentConfig(userAgent));
+        }
+        agents = Array.from(agentMap.values());
+    }
+    else {
+        // Only use user agents
+        agents = (userConfig.agents ?? []).map(toAgentConfig);
+    }
+    // Merge models
+    let models;
+    if (shouldExtend) {
+        models = { ...defaultConfig.models };
+        for (const userModel of userConfig.models ?? []) {
+            const [key, config] = toModelConfig(userModel);
+            models[key] = config;
+        }
+    }
+    else {
+        models = {};
+        for (const userModel of userConfig.models ?? []) {
+            const [key, config] = toModelConfig(userModel);
+            models[key] = config;
+        }
+    }
+    // Connectors (always additive)
+    const connectors = userConfig.connectors ?? [];
+    // Test cases
+    const testCases = userConfig.testCases
+        ? Array.isArray(userConfig.testCases)
+            ? userConfig.testCases
+            : [userConfig.testCases]
+        : [];
+    // Reporters
+    const reporters = userConfig.reporters ?? [['console']];
+    // Judge config
+    const judge = userConfig.judge ?? {
+        provider: 'bedrock',
+        model: 'claude-sonnet-4',
+    };
+    // Server config (merge user overrides with defaults)
+    const server = {
+        ...DEFAULT_SERVER_CONFIG,
+        ...userConfig.server,
+    };
+    // Telemetry config (user config overrides env vars, resolved at init time)
+    const telemetry = userConfig.telemetry ?? {};
+    return {
+        server,
+        agents,
+        models,
+        connectors,
+        testCases,
+        reporters,
+        judge,
+        telemetry,
+        // Cluster config authored in TS. Passed through verbatim; the server
+        // resolves it against JSON/env at startup (see resolveStorageConfig).
+        storage: userConfig.storage,
+        observability: userConfig.observability,
+    };
+}
+/**
+ * Load user config file
+ */
+async function loadUserConfig(configPath) {
+    try {
+        // Use dynamic import with file URL for cross-platform compatibility
+        const fileUrl = pathToFileURL(configPath).href;
+        // For TypeScript files, we need tsx or ts-node to be available
+        // The CLI build process compiles TS, so this works in production
+        const module = await import(fileUrl);
+        return module.default ?? module;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to load config file ${configPath}: ${message}`);
+    }
+}
+/**
+ * Cached resolved config
+ */
+let cachedConfig = null;
+let cachedConfigPath = null;
+/**
+ * Load and resolve configuration
+ *
+ * @param cwd - Working directory to search for config file
+ * @param force - Force reload even if cached
+ */
+export async function loadConfig(cwd = process.cwd(), force = false) {
+    const configFile = findConfigFile(cwd);
+    // Return cached config if available and unchanged
+    if (!force && cachedConfig && cachedConfigPath === configFile?.path) {
+        return cachedConfig;
+    }
+    let userConfig = {};
+    if (configFile) {
+        logStartupDiagnostic(`[Config] Loading ${configFile.path}`);
+        userConfig = await loadUserConfig(configFile.path);
+    }
+    else if (hasServerJsonConfig(cwd)) {
+        // Code config absent, but server-side JSON config present — it's loaded
+        // by separate server services (storage / observability / custom agents).
+        // Be explicit so the user doesn't think *no* config is in effect.
+        logStartupDiagnostic(`[Config] No code config (agent-health.config.{ts,js,mjs}); ` +
+            `runtime state (.agent-health/state.json) detected and loaded by server ` +
+            `services (ui-first mode). Using built-in defaults for agents/models.`);
+    }
+    else {
+        // Truly no config file — env vars and built-in defaults only.
+        logStartupDiagnostic('[Config] No config file found, using defaults + environment variables');
+    }
+    // Merge with defaults
+    const resolved = mergeConfigs(userConfig, DEFAULT_CONFIG);
+    // Cache the result
+    cachedConfig = resolved;
+    cachedConfigPath = configFile?.path ?? null;
+    logStartupDiagnostic(`[Config] Loaded ${resolved.agents.length} agents, ${Object.keys(resolved.models).length} models`);
+    return resolved;
+}
+/**
+ * Load config synchronously (for use in module initialization)
+ * Returns defaults if no config file or if loading fails
+ */
+export function loadConfigSync(cwd = process.cwd()) {
+    // Return cached if available
+    if (cachedConfig) {
+        return cachedConfig;
+    }
+    // Return defaults - async loading will update later
+    return {
+        server: DEFAULT_SERVER_CONFIG,
+        agents: DEFAULT_CONFIG.agents,
+        models: DEFAULT_CONFIG.models,
+        connectors: [],
+        testCases: [],
+        reporters: [['console']],
+        judge: { provider: 'bedrock', model: 'claude-sonnet-4' },
+        telemetry: {},
+        storage: undefined,
+        observability: undefined,
+    };
+}
+/**
+ * Clear config cache (useful for testing)
+ */
+export function clearConfigCache() {
+    cachedConfig = null;
+    cachedConfigPath = null;
+}
+/**
+ * Get config file info without loading
+ */
+export function getConfigFileInfo(cwd = process.cwd()) {
+    return findConfigFile(cwd);
+}
+//# sourceMappingURL=loader.js.map

package/lib/dist/lib/config/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../config/loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAChC,OAAO,EAAE,OAAO,EAAQ,MAAM,MAAM,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,KAAK,CAAC;AAGpC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAwB,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAa5E;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAyB;IACzD,IAAI,EAAE,kBAAkB,EAAE;IAC1B,mBAAmB,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE;IACpC,YAAY,EAAE,KAAK;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,iBAAiB,GAAG;IACxB,wBAAwB;IACxB,wBAAwB;IACxB,yBAAyB;CAC1B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IAC7D,OAAO,UAAU,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC,IAAI,UAAU,CAAC,aAAa,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IACxD,KAAK,MAAM,QAAQ,IAAI,iBAAiB,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACxC,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,YAAY,CAAC;YACtE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAClD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,SAA0B;IAC/C,OAAO;QACL,GAAG,EAAE,SAAS,CAAC,GAAG;QAClB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,IAAI;QAClC,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,EAAE;QAChC,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,KAAK;QACvC,aAAa,EAAE,SAAS,CAAC,aAAa;QACtC,eAAe,EAAE,SAAS,CAAC,eAAe;QAC1C,KAAK,EAAE,SAAS,CAAC,KAAK;KACvB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,SAA0B;IAC/C,OAAO;QACL,SAAS,CAAC,GAAG;QACb;YACE,QAAQ,EAAE,SAAS,CAAC,QAAQ;YAC5B,YAAY,EAAE,SAAS,CAAC,YAAY;YACpC,QAAQ,EAAE,SAAS,CAAC,QAAQ,IAAI,SAAS;YACzC,cAAc,EAAE,SAAS,CAAC,cAAc,IAAI,MAAM;YAClD,iBAAiB,EAAE,SAAS,CAAC,iBAAiB,IAAI,IAAI;SACvD;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAS,YAAY,CACnB,UAAsB,EACtB,aAAoC;IAEpC,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,KAAK,KAAK,CAAC;IAElD,eAAe;IACf,IAAI,MAAqB,CAAC;IAC1B,IAAI,YAAY,EAAE,CAAC;QACjB,gDAAgD;QAChD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;QAChD,KAAK,MAAM,KAAK,IAAI,aAAa,CAAC,MAAM,EAAE,CAAC;YACzC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;QACD,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YAChD,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;QACxD,CAAC;QACD,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,CAAC;SAAM,CAAC;QACN,uBAAuB;QACvB,MAAM,GAAG,CAAC,UAAU,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACxD,CAAC;IAED,eAAe;IACf,IAAI,MAAmC,CAAC;IACxC,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,GAAG,EAAE,GAAG,aAAa,CAAC,MAAM,EAAE,CAAC;QACrC,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;YAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QACvB,CAAC;IACH,CAAC;SAAM,CAAC;QACN,MAAM,GAAG,EAAE,CAAC;QACZ,KAAK,MAAM,SAAS,IAAI,UAAU,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC;YAChD,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;YAC/C,MAAM,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC;QACvB,CAAC;IACH,CAAC;IAED,+BAA+B;IAC/B,MAAM,UAAU,GAAqB,UAAU,CAAC,UAAU,IAAI,EAAE,CAAC;IAEjE,aAAa;IACb,MAAM,SAAS,GAAa,UAAU,CAAC,SAAS;QAC9C,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,SAAS,CAAC;YACnC,CAAC,CAAC,UAAU,CAAC,SAAS;YACtB,CAAC,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC;QAC1B,CAAC,CAAC,EAAE,CAAC;IAEP,YAAY;IACZ,MAAM,SAAS,GAAqB,UAAU,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IAE1E,eAAe;IACf,MAAM,KAAK,GAAgB,UAAU,CAAC,KAAK,IAAI;QAC7C,QAAQ,EAAE,SAAS;QACnB,KAAK,EAAE,iBAAiB;KACzB,CAAC;IAEF,qDAAqD;IACrD,MAAM,MAAM,GAAyB;QACnC,GAAG,qBAAqB;QACxB,GAAG,UAAU,CAAC,MAAM;KACrB,CAAC;IAEF,2EAA2E;IAC3E,MAAM,SAAS,GAAoB,UAAU,CAAC,SAAS,IAAI,EAAE,CAAC;IAE9D,OAAO;QACL,MAAM;QACN,MAAM;QACN,MAAM;QACN,UAAU;QACV,SAAS;QACT,SAAS;QACT,KAAK;QACL,SAAS;QACT,qEAAqE;QACrE,sEAAsE;QACtE,OAAO,EAAE,UAAU,CAAC,OAAO;QAC3B,aAAa,EAAE,UAAU,CAAC,aAAa;KACxC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,KAAK,UAAU,cAAc,CAAC,UAAkB;IAC9C,IAAI,CAAC;QACH,oEAAoE;QACpE,MAAM,OAAO,GAAG,aAAa,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC;QAE/C,+DAA+D;QAC/D,iEAAiE;QACjE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;QAErC,OAAO,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACvE,MAAM,IAAI,KAAK,CAAC,8BAA8B,UAAU,KAAK,OAAO,EAAE,CAAC,CAAC;IAC1E,CAAC;AACH,CAAC;AAED;;GAEG;AACH,IAAI,YAAY,GAA0B,IAAI,CAAC;AAC/C,IAAI,gBAAgB,GAAkB,IAAI,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,MAAc,OAAO,CAAC,GAAG,EAAE,EAC3B,QAAiB,KAAK;IAEtB,MAAM,UAAU,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC;IAEvC,kDAAkD;IAClD,IAAI,CAAC,KAAK,IAAI,YAAY,IAAI,gBAAgB,KAAK,UAAU,EAAE,IAAI,EAAE,CAAC;QACpE,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,IAAI,UAAU,GAAe,EAAE,CAAC;IAEhC,IAAI,UAAU,EAAE,CAAC;QACf,oBAAoB,CAAC,oBAAoB,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QAC5D,UAAU,GAAG,MAAM,cAAc,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;SAAM,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,wEAAwE;QACxE,yEAAyE;QACzE,kEAAkE;QAClE,oBAAoB,CAClB,6DAA6D;YAC7D,yEAAyE;YACzE,sEAAsE,CACvE,CAAC;IACJ,CAAC;SAAM,CAAC;QACN,8DAA8D;QAC9D,oBAAoB,CAAC,uEAAuE,CAAC,CAAC;IAChG,CAAC;IAED,sBAAsB;IACtB,MAAM,QAAQ,GAAG,YAAY,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC;IAE1D,mBAAmB;IACnB,YAAY,GAAG,QAAQ,CAAC;IACxB,gBAAgB,GAAG,UAAU,EAAE,IAAI,IAAI,IAAI,CAAC;IAE5C,oBAAoB,CAAC,mBAAmB,QAAQ,CAAC,MAAM,CAAC,MAAM,YAAY,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAM,SAAS,CAAC,CAAC;IAExH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IACxD,6BAA6B;IAC7B,IAAI,YAAY,EAAE,CAAC;QACjB,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,oDAAoD;IACpD,OAAO;QACL,MAAM,EAAE,qBAAqB;QAC7B,MAAM,EAAE,cAAc,CAAC,MAAuB;QAC9C,MAAM,EAAE,cAAc,CAAC,MAAM;QAC7B,UAAU,EAAE,EAAE;QACd,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC;QACxB,KAAK,EAAE,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,iBAAiB,EAAE;QACxD,SAAS,EAAE,EAAE;QACb,OAAO,EAAE,SAAS;QAClB,aAAa,EAAE,SAAS;KACzB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB;IAC9B,YAAY,GAAG,IAAI,CAAC;IACpB,gBAAgB,GAAG,IAAI,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc,OAAO,CAAC,GAAG,EAAE;IAC3D,OAAO,cAAc,CAAC,GAAG,CAAC,CAAC;AAC7B,CAAC"}

package/lib/dist/lib/config/statePaths.d.ts

@@ -0,0 +1,61 @@
+export declare const STATE_DIRNAME = ".agent-health";
+export declare const STATE_FILENAME = "state.json";
+/**
+ * Generated data lives UNDER the app-managed state dir: `.agent-health/data/`
+ * (runs, benchmarks, test-cases, analytics, profiles, skill-evals,
+ * uploaded-skills). Combined with state.json so there is ONE app-managed,
+ * gitignored directory — not a second top-level `agent-health-data/`.
+ */
+export declare const DATA_DIRNAME = "data";
+/** Authored config filenames, in priority order (shared with lib/config/loader). */
+export declare const AUTHORED_CONFIG_NAMES: string[];
+/** Legacy single-file runtime config (pre config-v2); migrated to STATE_FILENAME. */
+export declare const LEGACY_JSON_FILENAME = "agent-health.config.json";
+export type StateScope = 'project' | 'user';
+export declare function projectStateDir(cwd?: string): string;
+export declare function userStateDir(): string;
+export declare function projectStatePath(cwd?: string): string;
+export declare function userStatePath(): string;
+/** Generated-data dir, nested under the project state dir: `<cwd>/.agent-health/data`. */
+export declare function projectDataDir(cwd?: string): string;
+export declare function statePathForScope(scope: StateScope, cwd?: string): string;
+/**
+ * Locate an authored config file (project scope first, then user scope).
+ * Returns its absolute path, or null if none exists.
+ */
+export declare function findAuthoredConfig(cwd?: string): string | null;
+export declare function hasAuthoredConfig(cwd?: string): boolean;
+/**
+ * Code-first mode = an authored config file is present. In this mode the
+ * runtime state file is ignored entirely (strict rule, #271).
+ */
+export declare function isCodeFirstMode(cwd?: string): boolean;
+/**
+ * Read a single state file. Returns `{}` when missing/corrupt (safe to create);
+ * never throws.
+ */
+export declare function readStateFile(path: string): Record<string, unknown>;
+/**
+ * Layered runtime state: project overrides user, shallow per top-level key.
+ * Returns `{}` in code-first mode (state ignored).
+ */
+export declare function readLayeredState(cwd?: string): Record<string, unknown>;
+/**
+ * Which scope supplies a given top-level key, or null if absent / code-first.
+ * Used for UI source attribution.
+ */
+export declare function stateKeyScope(key: string, cwd?: string): StateScope | null;
+/**
+ * Read the raw state object for a single scope (no layering). Used by owners
+ * that need to merge against the exact file they will write back.
+ */
+export declare function readStateScope(scope: StateScope, cwd?: string): Record<string, unknown>;
+/**
+ * Merge `patch` into a scope's state file, preserving sibling keys. A key whose
+ * value is `undefined` is deleted. Creates the `.agent-health/` dir as needed.
+ *
+ * Throws in code-first mode — runtime state must not be written when an
+ * authored config file is present.
+ */
+export declare function writeStateScope(patch: Record<string, unknown>, scope?: StateScope, cwd?: string): void;
+//# sourceMappingURL=statePaths.d.ts.map

package/lib/dist/lib/config/statePaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statePaths.d.ts","sourceRoot":"","sources":["../../../config/statePaths.ts"],"names":[],"mappings":"AA6BA,eAAO,MAAM,aAAa,kBAAkB,CAAC;AAC7C,eAAO,MAAM,cAAc,eAAe,CAAC;AAE3C;;;;;GAKG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC,oFAAoF;AACpF,eAAO,MAAM,qBAAqB,UAIjC,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,oBAAoB,6BAA6B,CAAC;AAE/D,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAI5C,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAEnE;AACD,wBAAgB,YAAY,IAAI,MAAM,CAErC;AACD,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAEpE;AACD,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AACD,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAElE;AACD,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAExF;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,GAAG,IAAI,CAU7E;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAEpE;AAID;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAanE;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKrF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,MAAsB,GAAG,UAAU,GAAG,IAAI,CAKzF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,GAAE,MAAsB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEtG;AAkBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,GAAE,UAAsB,EAC7B,GAAG,GAAE,MAAsB,GAC1B,IAAI,CAmBN"}

package/lib/dist/lib/config/statePaths.js

@@ -0,0 +1,188 @@
+/*
+ * Copyright OpenSearch Contributors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Config state paths + mode resolution (config v2, #271).
+ *
+ * Two modes, decided by the presence of an authored config file:
+ *
+ *  - **code-first**: an `agent-health.config.{ts,js,mjs}` exists (project OR
+ *    user scope). The authored file (+ `.env`) is the single source of truth;
+ *    the runtime state file is **ignored entirely**, and the Settings UI write
+ *    paths are disabled.
+ *  - **ui-first**: no authored config file anywhere. Runtime state lives in
+ *    `.agent-health/state.json`, written by the Settings UI / CLI.
+ *
+ * `.agent-health/` is scoped at both **user** (`~/.agent-health/`) and
+ * **project** (`<cwd>/.agent-health/`) level, project overriding user.
+ *
+ * This module is the single owner of those paths + the mode rule. All runtime
+ * state owners (configService, customAgentStore, debug, remoteServers) read and
+ * write through it so there is no split-brain across files.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { resolve, join } from 'path';
+export const STATE_DIRNAME = '.agent-health';
+export const STATE_FILENAME = 'state.json';
+/**
+ * Generated data lives UNDER the app-managed state dir: `.agent-health/data/`
+ * (runs, benchmarks, test-cases, analytics, profiles, skill-evals,
+ * uploaded-skills). Combined with state.json so there is ONE app-managed,
+ * gitignored directory — not a second top-level `agent-health-data/`.
+ */
+export const DATA_DIRNAME = 'data';
+/** Authored config filenames, in priority order (shared with lib/config/loader). */
+export const AUTHORED_CONFIG_NAMES = [
+    'agent-health.config.ts',
+    'agent-health.config.js',
+    'agent-health.config.mjs',
+];
+/** Legacy single-file runtime config (pre config-v2); migrated to STATE_FILENAME. */
+export const LEGACY_JSON_FILENAME = 'agent-health.config.json';
+// ── Path helpers ────────────────────────────────────────────────────────────
+export function projectStateDir(cwd = process.cwd()) {
+    return join(cwd, STATE_DIRNAME);
+}
+export function userStateDir() {
+    return join(homedir(), STATE_DIRNAME);
+}
+export function projectStatePath(cwd = process.cwd()) {
+    return join(projectStateDir(cwd), STATE_FILENAME);
+}
+export function userStatePath() {
+    return join(userStateDir(), STATE_FILENAME);
+}
+/** Generated-data dir, nested under the project state dir: `<cwd>/.agent-health/data`. */
+export function projectDataDir(cwd = process.cwd()) {
+    return join(projectStateDir(cwd), DATA_DIRNAME);
+}
+export function statePathForScope(scope, cwd = process.cwd()) {
+    return scope === 'user' ? userStatePath() : projectStatePath(cwd);
+}
+// ── Mode detection ───────────────────────────────────────────────────────────
+/**
+ * Locate an authored config file (project scope first, then user scope).
+ * Returns its absolute path, or null if none exists.
+ */
+export function findAuthoredConfig(cwd = process.cwd()) {
+    for (const name of AUTHORED_CONFIG_NAMES) {
+        const p = resolve(cwd, name);
+        if (existsSync(p))
+            return p;
+    }
+    for (const name of AUTHORED_CONFIG_NAMES) {
+        const p = join(userStateDir(), name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+export function hasAuthoredConfig(cwd = process.cwd()) {
+    return findAuthoredConfig(cwd) !== null;
+}
+/**
+ * Code-first mode = an authored config file is present. In this mode the
+ * runtime state file is ignored entirely (strict rule, #271).
+ */
+export function isCodeFirstMode(cwd = process.cwd()) {
+    return hasAuthoredConfig(cwd);
+}
+// ── State read/write ─────────────────────────────────────────────────────────
+/**
+ * Read a single state file. Returns `{}` when missing/corrupt (safe to create);
+ * never throws.
+ */
+export function readStateFile(path) {
+    try {
+        if (!existsSync(path))
+            return {};
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            console.warn(`[statePaths] ${path} is not a JSON object — ignoring`);
+            return {};
+        }
+        return parsed;
+    }
+    catch (err) {
+        console.warn(`[statePaths] Failed to read ${path}:`, err.message);
+        return {};
+    }
+}
+/**
+ * Layered runtime state: project overrides user, shallow per top-level key.
+ * Returns `{}` in code-first mode (state ignored).
+ */
+export function readLayeredState(cwd = process.cwd()) {
+    if (isCodeFirstMode(cwd))
+        return {};
+    const user = readStateFile(userStatePath());
+    const project = readStateFile(projectStatePath(cwd));
+    return { ...user, ...project };
+}
+/**
+ * Which scope supplies a given top-level key, or null if absent / code-first.
+ * Used for UI source attribution.
+ */
+export function stateKeyScope(key, cwd = process.cwd()) {
+    if (isCodeFirstMode(cwd))
+        return null;
+    if (key in readStateFile(projectStatePath(cwd)))
+        return 'project';
+    if (key in readStateFile(userStatePath()))
+        return 'user';
+    return null;
+}
+/**
+ * Read the raw state object for a single scope (no layering). Used by owners
+ * that need to merge against the exact file they will write back.
+ */
+export function readStateScope(scope, cwd = process.cwd()) {
+    return readStateFile(statePathForScope(scope, cwd));
+}
+/**
+ * Strict read for the write path: returns `{}` when the file is missing (safe
+ * to create), `null` when it exists but is unreadable/corrupt (unsafe to
+ * overwrite — would clobber).
+ */
+function readStateFileOrNull(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Merge `patch` into a scope's state file, preserving sibling keys. A key whose
+ * value is `undefined` is deleted. Creates the `.agent-health/` dir as needed.
+ *
+ * Throws in code-first mode — runtime state must not be written when an
+ * authored config file is present.
+ */
+export function writeStateScope(patch, scope = 'project', cwd = process.cwd()) {
+    if (isCodeFirstMode(cwd)) {
+        throw new Error('Cannot write runtime state: data sources are managed by agent-health.config.ts (code-first mode). ' +
+            'Edit the config file and restart.');
+    }
+    const path = statePathForScope(scope, cwd);
+    const dir = scope === 'user' ? userStateDir() : projectStateDir(cwd);
+    const existing = readStateFileOrNull(path);
+    if (existing === null) {
+        throw new Error(`Cannot write runtime state: ${path} is unreadable or corrupt`);
+    }
+    const merged = { ...existing, ...patch };
+    for (const [k, v] of Object.entries(patch)) {
+        if (v === undefined)
+            delete merged[k];
+    }
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+}
+//# sourceMappingURL=statePaths.js.map