@opensearch-project/agent-health 0.2.0 → 0.4.0

package/cli/dist/index.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // cli/index.ts
-import { Command as Command10 } from "commander";
-import chalk10 from "chalk";
-import { fileURLToPath as fileURLToPath3 } from "url";
-import { dirname as dirname3, join as join4, resolve as resolve4 } from "path";
-import { readFileSync as readFileSync3, existsSync as existsSync5 } from "fs";
+import { Command as Command14 } from "commander";
+import chalk14 from "chalk";
+import { fileURLToPath as fileURLToPath5 } from "url";
+import { dirname as dirname5, join as join7, resolve as resolve4 } from "path";
+import { readFileSync as readFileSync5, existsSync as existsSync7 } from "fs";
 import { config as loadDotenv } from "dotenv";
 import open from "open";
 import ora5 from "ora";
@@ -26,17 +26,37 @@ function findPackageRoot() {
   }
   return join(__dirname, "..");
 }
+var MAX_PORT_ATTEMPTS = 10;
 async function startServer(options) {
   process.env.VITE_BACKEND_PORT = String(options.port);
+  if (options.headless) process.env.AGENT_HEALTH_HEADLESS = "1";
+  if (options.apiKey) process.env.AGENT_HEALTH_API_KEY = options.apiKey;
   const packageRoot = findPackageRoot();
   const serverPath = join(packageRoot, "server", "dist", "app.js");
   const { createApp } = await import(serverPath);
   const app = await createApp();
-  return new Promise((resolve5) => {
-    app.listen(options.port, "0.0.0.0", () => {
-      resolve5();
+  const tryListen = (port) => {
+    return new Promise((resolve5, reject) => {
+      const server = app.listen(port, "0.0.0.0");
+      server.on("listening", () => {
+        resolve5(port);
+      });
+      server.on("error", (err) => {
+        server.close();
+        if (err.code === "EADDRINUSE" && port <= options.port + MAX_PORT_ATTEMPTS) {
+          console.log(`  Port ${port} is in use, trying ${port + 1}...`);
+          resolve5(tryListen(port + 1));
+        } else {
+          reject(err);
+        }
+      });
     });
-  });
+  };
+  const actualPort = await tryListen(options.port);
+  if (actualPort !== options.port) {
+    process.env.VITE_BACKEND_PORT = String(actualPort);
+  }
+  return actualPort;
 }
 
 // cli/commands/list.ts
@@ -99,6 +119,8 @@ var ENV_CONFIG = {
   // OpenAI-compatible (optional - for OpenAI-compatible judge/agent endpoints)
   openaiCompatibleApiKey: getEnvVar("OPENAI_COMPATIBLE_API_KEY", ""),
   openaiCompatibleEndpoint: getEnvVar("OPENAI_COMPATIBLE_ENDPOINT", "http://localhost:4000/v1/chat/completions"),
+  // Observio Sample Agent endpoint
+  observioEndpoint: getEnvVar("OBSERVIO_ENDPOINT", "http://localhost:3001/run-agent"),
   // Claude Code Telemetry (optional - for OTEL traces from Claude Code)
   claudeCodeTelemetryEnabled: getEnvVar("CLAUDE_CODE_TELEMETRY_ENABLED", "false") === "true",
   otelExporterEndpoint: getEnvVar("OTEL_EXPORTER_OTLP_ENDPOINT", ""),
@@ -134,6 +156,16 @@ var CONNECTOR_TYPE_INFO = {
     description: "Invokes the Claude Code CLI. Server-only \u2014 use the CLI or benchmark runner.",
     serverOnly: true
   },
+  "strands": {
+    label: "Amazon Strands",
+    description: "Amazon Strands agent framework via Bedrock Agent Runtime API. Server-only \u2014 requires AWS SDK.",
+    serverOnly: true
+  },
+  "langgraph": {
+    label: "LangGraph (REST)",
+    description: "LangGraph agent via direct REST API. Use for non-AG-UI LangGraph instances.",
+    serverOnly: false
+  },
   "mock": {
     label: "Mock",
     description: "Built-in demo agent for testing. No real endpoint needed.",
@@ -176,6 +208,15 @@ var DEFAULT_CONFIG = {
       headers: {},
       useTraces: false
     },
+    {
+      key: "observio",
+      name: "Observio Sample Agent",
+      endpoint: ENV_CONFIG.observioEndpoint || "http://localhost:3001/run-agent",
+      description: "Observio sample agent \u2014 ReAct pattern with LangGraph and Bedrock. Start with: cd observio-sample-agent && npm run start:ag-ui",
+      connectorType: "agui-streaming",
+      headers: {},
+      useTraces: true
+    },
     {
       key: "claude-code",
       name: "Claude Code",
@@ -185,6 +226,30 @@ var DEFAULT_CONFIG = {
       headers: {},
       useTraces: ENV_CONFIG.claudeCodeTelemetryEnabled && !!ENV_CONFIG.otelExporterEndpoint,
       connectorConfig: { env: getClaudeCodeConnectorEnv() }
+    },
+    {
+      key: "strands",
+      name: "Amazon Strands",
+      endpoint: "${STRANDS_AGENT_ID}",
+      description: "Amazon Strands agent framework (Bedrock Agent Runtime)",
+      connectorType: "strands",
+      headers: {},
+      useTraces: false,
+      connectorConfig: {
+        agentAliasId: "${STRANDS_ALIAS_ID:-TSTALIASID}",
+        region: "${AWS_REGION:-us-east-1}"
+      },
+      enabled: false
+    },
+    {
+      key: "langgraph-rest",
+      name: "LangGraph (REST)",
+      endpoint: "${LANGGRAPH_API_ENDPOINT:-http://localhost:8000}",
+      description: "LangGraph agent via direct REST API",
+      connectorType: "langgraph",
+      headers: {},
+      useTraces: false,
+      enabled: false
     }
   ],
   models: {
@@ -373,6 +438,7 @@ function mergeConfigs(userConfig, defaultConfig) {
     ...DEFAULT_SERVER_CONFIG,
     ...userConfig.server
   };
+  const telemetry = userConfig.telemetry ?? {};
   return {
     server,
     agents,
@@ -380,7 +446,8 @@ function mergeConfigs(userConfig, defaultConfig) {
     connectors,
     testCases,
     reporters,
-    judge
+    judge,
+    telemetry
   };
 }
 async function loadUserConfig(configPath) {
@@ -1713,11 +1780,150 @@ var OpenAICompatibleConnector = class extends BaseConnector {
 };
 var openaiCompatibleConnector = new OpenAICompatibleConnector();
 
+// services/connectors/langgraph/LangGraphConnector.ts
+var LangGraphConnector = class extends BaseConnector {
+  constructor() {
+    super(...arguments);
+    this.type = "langgraph";
+    this.name = "LangGraph (REST)";
+    this.supportsStreaming = false;
+  }
+  buildPayload(request) {
+    const config = request.connectorConfig || {};
+    return {
+      input: {
+        messages: [
+          {
+            role: "user",
+            content: request.testCase.initialPrompt
+          }
+        ]
+      },
+      config: {
+        configurable: {
+          ...request.modelId && { model: request.modelId },
+          ...config.configurable
+        }
+      }
+    };
+  }
+  async execute(endpoint, request, auth, onProgress, onRawEvent) {
+    const payload = request.payload || this.buildPayload(request);
+    const headers = this.buildAuthHeaders(auth);
+    const config = request.connectorConfig || {};
+    const graphId = config.graphId || "agent";
+    const baseUrl = endpoint.replace(/\/+$/, "");
+    const threadId = config.threadId || request.threadId;
+    const invokeUrl = threadId ? `${baseUrl}/threads/${threadId}/runs/wait` : `${baseUrl}/assistants/${graphId}/invoke`;
+    this.debug("Executing LangGraph request");
+    this.debug("URL:", invokeUrl);
+    const response = await fetch(invokeUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...headers
+      },
+      body: JSON.stringify(payload)
+    });
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`LangGraph request failed: ${response.status} - ${errorText}`);
+    }
+    const data = await response.json();
+    onRawEvent?.(data);
+    const trajectory = this.parseResponse(data);
+    trajectory.forEach((step) => onProgress?.(step));
+    return {
+      trajectory,
+      runId: data.run_id || data.thread_id || threadId || null,
+      rawEvents: [data],
+      metadata: {
+        graphId,
+        threadId: data.thread_id || threadId
+      }
+    };
+  }
+  parseResponse(data) {
+    const steps = [];
+    const messages = data.output?.messages || data.values?.messages || data.messages || [];
+    for (const msg of messages) {
+      const role = msg.type || msg.role;
+      const content = typeof msg.content === "string" ? msg.content : Array.isArray(msg.content) ? msg.content.map((c) => c.text || JSON.stringify(c)).join("\n") : JSON.stringify(msg.content);
+      if (role === "ai" || role === "assistant") {
+        if (msg.tool_calls && Array.isArray(msg.tool_calls) && msg.tool_calls.length > 0) {
+          for (const toolCall of msg.tool_calls) {
+            steps.push(this.createStep("action", `Calling ${toolCall.name}...`, {
+              toolName: toolCall.name,
+              toolArgs: toolCall.args
+            }));
+          }
+        }
+        if (content && !msg.tool_calls?.length) {
+          steps.push(this.createStep("assistant", content));
+        }
+      } else if (role === "tool") {
+        steps.push(this.createStep("tool_result", content, {
+          toolName: msg.name,
+          status: "SUCCESS"
+        }));
+      }
+    }
+    const lastAssistant = [...steps].reverse().find((s) => s.type === "assistant");
+    if (lastAssistant) {
+      lastAssistant.type = "response";
+    }
+    if (data.intermediate_steps && Array.isArray(data.intermediate_steps)) {
+      for (const [action, observation] of data.intermediate_steps) {
+        if (action?.tool) {
+          steps.push(this.createStep("action", `Calling ${action.tool}...`, {
+            toolName: action.tool,
+            toolArgs: action.tool_input
+          }));
+        }
+        if (observation !== void 0) {
+          const obsContent = typeof observation === "string" ? observation : JSON.stringify(observation);
+          steps.push(this.createStep("tool_result", obsContent, {
+            status: "SUCCESS"
+          }));
+        }
+      }
+    }
+    if (data.output && typeof data.output === "string" && steps.length === 0) {
+      steps.push(this.createStep("response", data.output));
+    }
+    if (steps.length === 0 && data) {
+      steps.push(this.createStep("response", JSON.stringify(data, null, 2)));
+    }
+    return steps;
+  }
+  async healthCheck(endpoint, auth) {
+    try {
+      const headers = this.buildAuthHeaders(auth);
+      const baseUrl = endpoint.replace(/\/+$/, "");
+      const response = await fetch(`${baseUrl}/ok`, {
+        method: "GET",
+        headers
+      });
+      return response.ok;
+    } catch {
+      try {
+        const headers = this.buildAuthHeaders(auth);
+        const response = await fetch(endpoint, { method: "GET", headers });
+        return response.ok;
+      } catch {
+        return false;
+      }
+    }
+  }
+};
+var langgraphConnector = new LangGraphConnector();
+
 // services/connectors/index.ts
 connectorRegistry.register(aguiStreamingConnector);
 connectorRegistry.register(mockConnector);
 connectorRegistry.register(restConnector);
 connectorRegistry.register(openaiCompatibleConnector);
+connectorRegistry.register(langgraphConnector);
 console.log("[Connectors] Browser-safe connectors registered:", connectorRegistry.getRegisteredTypes().join(", "));
 
 // services/connectors/subprocess/SubprocessConnector.ts
@@ -1761,6 +1967,7 @@ Question: ${prompt}`;
     const command = endpoint || this.config.command;
     const args = this.config.args || [];
     const input = request.payload || this.buildPayload(request);
+    const runId = `subprocess-${Date.now()}`;
     this.debug("Command:", command);
     this.debug("Args:", args);
     this.debug("Input mode:", this.config.inputMode);
@@ -1768,10 +1975,12 @@ Question: ${prompt}`;
     this.debug("Timeout:", this.config.timeout);
     this.debug("Input (first 500 chars):", input.substring(0, 500));
     this.debug("Working dir:", this.config.workingDir || process.cwd());
+    this.debug("Run ID:", runId);
     const env = {
       ...process.env,
       ...this.buildAuthEnv(auth),
-      ...this.config.env
+      ...this.config.env,
+      AGENT_EVAL_RUN_ID: runId
     };
     return new Promise((resolve5, reject) => {
       const trajectory = [];
@@ -1830,6 +2039,17 @@ Question: ${prompt}`;
           this.error(`Process exited with code ${code}`);
           this.error("stderr:", stderr);
         }
+        if (this.config.outputParser === "streaming") {
+          this.onBeforeStreamEnd(trajectory, onProgress);
+          if (code !== 0 && trajectory.length === 0) {
+            const errorContent = stderr.trim() ? `Error: Process exited with code ${code}. ${stderr.trim()}` : `Error: Process exited with code ${code}`;
+            const errorStep = this.createStep("tool_result", errorContent, {
+              status: "FAILURE" /* FAILURE */
+            });
+            trajectory.push(errorStep);
+            onProgress?.(errorStep);
+          }
+        }
         const finalTrajectory = this.config.outputParser === "streaming" ? trajectory : this.parseResponse({ stdout, stderr, exitCode: code });
         if (this.config.outputParser !== "streaming") {
           finalTrajectory.forEach((step) => onProgress?.(step));
@@ -1837,7 +2057,7 @@ Question: ${prompt}`;
         this.debug("Resolving with trajectory of", finalTrajectory.length, "steps");
         resolve5({
           trajectory: finalTrajectory,
-          runId: `subprocess-${Date.now()}`,
+          runId,
           rawEvents: rawOutput,
           metadata: {
             command,
@@ -1868,6 +2088,12 @@ Question: ${prompt}`;
     });
     this.debug("========== execute() COMPLETED ==========");
   }
+  /**
+   * Hook called before returning the streaming trajectory on process close.
+   * Subclasses can override to flush internal buffers.
+   */
+  onBeforeStreamEnd(_trajectory, _onProgress) {
+  }
   /**
    * Parse streaming output and emit steps in real-time
    */
@@ -1962,6 +2188,7 @@ var ClaudeCodeConnector = class extends SubprocessConnector {
     this.name = "Claude Code CLI";
     this.outputBuffer = "";
     this.thinkingBuffer = "";
+    this.textBuffer = "";
     this.isInThinking = false;
   }
   /**
@@ -2031,11 +2258,17 @@ var ClaudeCodeConnector = class extends SubprocessConnector {
       if (event.delta?.type === "thinking_delta" && event.delta.thinking) {
         this.thinkingBuffer += event.delta.thinking;
       } else if (event.delta?.type === "text_delta" && event.delta.text) {
-        steps.push(this.createStep("assistant", event.delta.text));
+        this.textBuffer += event.delta.text;
+      }
+    } else if (event.type === "content_block_stop") {
+      if (this.thinkingBuffer) {
+        steps.push(this.createStep("thinking", this.thinkingBuffer));
+        this.thinkingBuffer = "";
+      }
+      if (this.textBuffer) {
+        steps.push(this.createStep("assistant", this.textBuffer));
+        this.textBuffer = "";
       }
-    } else if (event.type === "content_block_stop" && this.thinkingBuffer) {
-      steps.push(this.createStep("thinking", this.thinkingBuffer));
-      this.thinkingBuffer = "";
     } else if (event.type === "result" && event.result) {
       steps.push(this.createStep(
         "response",
@@ -2081,8 +2314,41 @@ var ClaudeCodeConnector = class extends SubprocessConnector {
   resetState() {
     this.outputBuffer = "";
     this.thinkingBuffer = "";
+    this.textBuffer = "";
     this.isInThinking = false;
   }
+  /**
+   * Flush remaining buffers when the subprocess stream ends.
+   */
+  onBeforeStreamEnd(trajectory, onProgress) {
+    if (this.outputBuffer.trim()) {
+      try {
+        const event = JSON.parse(this.outputBuffer.trim());
+        const steps = this.parseJsonEvent(event);
+        for (const step of steps) {
+          trajectory.push(step);
+          onProgress?.(step);
+        }
+      } catch {
+        const step = this.createStep("assistant", this.outputBuffer.trim());
+        trajectory.push(step);
+        onProgress?.(step);
+      }
+      this.outputBuffer = "";
+    }
+    if (this.thinkingBuffer) {
+      const step = this.createStep("thinking", this.thinkingBuffer);
+      trajectory.push(step);
+      onProgress?.(step);
+      this.thinkingBuffer = "";
+    }
+    if (this.textBuffer) {
+      const step = this.createStep("response", this.textBuffer);
+      trajectory.push(step);
+      onProgress?.(step);
+      this.textBuffer = "";
+    }
+  }
   /**
    * Build CLI args from ClaudeCodeConnectorConfig
    */
@@ -2183,9 +2449,214 @@ var ClaudeCodeConnector = class extends SubprocessConnector {
 };
 var claudeCodeConnector = new ClaudeCodeConnector();
 
+// services/connectors/strands/StrandsConnector.ts
+var StrandsConnector = class extends BaseConnector {
+  constructor() {
+    super(...arguments);
+    this.type = "strands";
+    this.name = "Amazon Strands";
+    this.supportsStreaming = true;
+  }
+  buildPayload(request) {
+    const config = request.connectorConfig || {};
+    return {
+      agentId: "",
+      // Set from endpoint in execute()
+      agentAliasId: config.agentAliasId || "TSTALIASID",
+      sessionId: config.sessionId || `eval-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+      inputText: request.testCase.initialPrompt,
+      enableTrace: config.enableTrace !== false
+    };
+  }
+  async execute(endpoint, request, auth, onProgress, onRawEvent) {
+    const payload = request.payload || this.buildPayload(request);
+    payload.agentId = endpoint;
+    const config = request.connectorConfig || {};
+    const region = config.region || auth.awsRegion || process.env.AWS_REGION || "us-east-1";
+    this.debug("Executing Strands agent");
+    this.debug("Agent ID:", endpoint);
+    this.debug("Alias:", payload.agentAliasId);
+    this.debug("Region:", region);
+    const { BedrockAgentRuntimeClient, InvokeAgentCommand } = await import("@aws-sdk/client-bedrock-agent-runtime");
+    const clientConfig = { region };
+    if (auth.type === "aws-sigv4" && auth.awsAccessKeyId && auth.awsSecretAccessKey) {
+      clientConfig.credentials = {
+        accessKeyId: auth.awsAccessKeyId,
+        secretAccessKey: auth.awsSecretAccessKey,
+        ...auth.awsSessionToken && { sessionToken: auth.awsSessionToken }
+      };
+    }
+    const client = new BedrockAgentRuntimeClient(clientConfig);
+    const command = new InvokeAgentCommand({
+      agentId: payload.agentId,
+      agentAliasId: payload.agentAliasId,
+      sessionId: payload.sessionId,
+      inputText: payload.inputText,
+      enableTrace: payload.enableTrace
+    });
+    const response = await client.send(command);
+    const trajectory = [];
+    let finalOutput = "";
+    if (response.completion) {
+      for await (const event of response.completion) {
+        onRawEvent?.(event);
+        if (event.chunk?.bytes) {
+          const text = new TextDecoder().decode(event.chunk.bytes);
+          finalOutput += text;
+        }
+        if (event.trace?.trace) {
+          const traceSteps = this.parseTraceEvent(event.trace.trace);
+          for (const step of traceSteps) {
+            trajectory.push(step);
+            onProgress?.(step);
+          }
+        }
+      }
+    }
+    const hasResponseFromTrace = trajectory.some((s) => s.type === "response");
+    if (finalOutput && !hasResponseFromTrace) {
+      const responseStep = this.createStep("response", finalOutput);
+      trajectory.push(responseStep);
+      onProgress?.(responseStep);
+    }
+    return {
+      trajectory,
+      runId: payload.sessionId,
+      metadata: {
+        agentId: endpoint,
+        agentAliasId: payload.agentAliasId,
+        sessionId: payload.sessionId,
+        region
+      }
+    };
+  }
+  parseResponse(rawResponse) {
+    if (rawResponse?.trace?.trace) {
+      return this.parseTraceEvent(rawResponse.trace.trace);
+    }
+    if (typeof rawResponse === "string") {
+      return [this.createStep("response", rawResponse)];
+    }
+    return [];
+  }
+  /**
+   * Parse a Bedrock Agent trace event into TrajectorySteps
+   */
+  parseTraceEvent(trace) {
+    const steps = [];
+    if (trace.preProcessingTrace) {
+      const pre = trace.preProcessingTrace;
+      if (pre.modelInvocationOutput?.parsedResponse?.isValid !== void 0) {
+        steps.push(this.createStep(
+          "thinking",
+          `Pre-processing: Input ${pre.modelInvocationOutput.parsedResponse.isValid ? "valid" : "invalid"}` + (pre.modelInvocationOutput.parsedResponse.rationale ? ` \u2014 ${pre.modelInvocationOutput.parsedResponse.rationale}` : "")
+        ));
+      }
+    }
+    if (trace.orchestrationTrace) {
+      const orch = trace.orchestrationTrace;
+      if (orch.rationale?.text) {
+        steps.push(this.createStep("thinking", orch.rationale.text));
+      }
+      if (orch.modelInvocationInput?.text) {
+        steps.push(this.createStep("thinking", `Model input: ${this.truncate(orch.modelInvocationInput.text, 500)}`));
+      }
+      if (orch.invocationInput) {
+        const inv = orch.invocationInput;
+        if (inv.actionGroupInvocationInput) {
+          const action = inv.actionGroupInvocationInput;
+          steps.push(this.createStep("action", `Calling ${action.actionGroupName || "action"}::${action.apiPath || action.function || "invoke"}`, {
+            toolName: `${action.actionGroupName || "action"}::${action.apiPath || action.function || "invoke"}`,
+            toolArgs: action.parameters ? Object.fromEntries(
+              action.parameters.map((p) => [p.name, p.value])
+            ) : void 0
+          }));
+        }
+        if (inv.knowledgeBaseLookupInput) {
+          steps.push(this.createStep("action", `Knowledge base lookup: ${inv.knowledgeBaseLookupInput.text}`, {
+            toolName: "knowledge_base_lookup",
+            toolArgs: { query: inv.knowledgeBaseLookupInput.text }
+          }));
+        }
+      }
+      if (orch.observation) {
+        const obs = orch.observation;
+        if (obs.actionGroupInvocationOutput?.text) {
+          steps.push(this.createStep("tool_result", obs.actionGroupInvocationOutput.text, {
+            status: "SUCCESS"
+          }));
+        }
+        if (obs.knowledgeBaseLookupOutput?.retrievedReferences) {
+          const refs = obs.knowledgeBaseLookupOutput.retrievedReferences;
+          steps.push(this.createStep(
+            "tool_result",
+            `Retrieved ${refs.length} reference(s) from knowledge base`,
+            {
+              status: "SUCCESS",
+              toolOutput: refs.map((r) => ({
+                content: this.truncate(r.content?.text, 200),
+                location: r.location
+              }))
+            }
+          ));
+        }
+        if (obs.finalResponse?.text) {
+          steps.push(this.createStep("response", obs.finalResponse.text));
+        }
+      }
+    }
+    if (trace.postProcessingTrace) {
+      const post = trace.postProcessingTrace;
+      if (post.modelInvocationOutput?.parsedResponse?.text) {
+        steps.push(this.createStep(
+          "thinking",
+          `Post-processing: ${this.truncate(post.modelInvocationOutput.parsedResponse.text, 300)}`
+        ));
+      }
+    }
+    if (trace.failureTrace) {
+      steps.push(this.createStep(
+        "response",
+        `Agent error: ${trace.failureTrace.failureReason || "Unknown failure"}`
+      ));
+    }
+    return steps;
+  }
+  /**
+   * Health check: verify the agent exists via GetAgent
+   */
+  async healthCheck(endpoint, auth) {
+    try {
+      const config = auth;
+      const region = config.awsRegion || process.env.AWS_REGION || "us-east-1";
+      const { BedrockAgentClient, GetAgentCommand } = await import("@aws-sdk/client-bedrock-agent");
+      const clientConfig = { region };
+      if (auth.type === "aws-sigv4" && auth.awsAccessKeyId && auth.awsSecretAccessKey) {
+        clientConfig.credentials = {
+          accessKeyId: auth.awsAccessKeyId,
+          secretAccessKey: auth.awsSecretAccessKey,
+          ...auth.awsSessionToken && { sessionToken: auth.awsSessionToken }
+        };
+      }
+      const client = new BedrockAgentClient(clientConfig);
+      const result = await client.send(new GetAgentCommand({ agentId: endpoint }));
+      return result.agent?.agentStatus === "PREPARED";
+    } catch (error) {
+      this.error("Health check failed:", error);
+      return false;
+    }
+  }
+  truncate(text, maxLen) {
+    if (!text) return "";
+    return text.length > maxLen ? text.slice(0, maxLen) + "..." : text;
+  }
+};
+var strandsConnector = new StrandsConnector();
+
 // services/connectors/server.ts
 connectorRegistry.register(subprocessConnector);
 connectorRegistry.register(claudeCodeConnector);
+connectorRegistry.register(strandsConnector);
 console.log("[Connectors] Server connectors registered:", connectorRegistry.getRegisteredTypes().join(", "));
 
 // cli/utils/serverLifecycle.ts
@@ -2327,20 +2798,35 @@ async function startServer2(port, timeout) {
   });
   let stderrOutput = "";
   let stdoutOutput = "";
+  let resolvePortDetection;
+  const portDetected = new Promise((resolve5) => {
+    resolvePortDetection = resolve5;
+  });
   child.stderr?.on("data", (data) => {
     stderrOutput += data.toString();
   });
   child.stdout?.on("data", (data) => {
-    stdoutOutput += data.toString();
+    const chunk = data.toString();
+    stdoutOutput += chunk;
+    const match = chunk.match(/Backend Server running on http:\/\/0\.0\.0\.0:(\d+)/);
+    if (match) {
+      resolvePortDetection(parseInt(match[1], 10));
+    }
   });
   let earlyExit = false;
   let exitCode = null;
   child.on("exit", (code) => {
     earlyExit = true;
     exitCode = code;
+    resolvePortDetection(port);
   });
   child.unref();
-  const ready = await waitForServer(port, timeout);
+  const portDetectionTimeout = Math.min(timeout, 1e4);
+  const actualPort = await Promise.race([
+    portDetected,
+    new Promise((resolve5) => setTimeout(() => resolve5(port), portDetectionTimeout))
+  ]);
+  const ready = await waitForServer(actualPort, timeout);
   if (!ready) {
     try {
       child.kill();
@@ -2366,7 +2852,7 @@ ${stdoutOutput}`);
     }
     throw new Error(`Server failed to start within ${timeout}ms on port ${port}`);
   }
-  return child;
+  return { child, actualPort };
 }
 function stopServer(process2) {
   try {
@@ -2410,11 +2896,14 @@ async function ensureServer(config) {
       );
     }
   }
-  const serverProcess = await startServer2(port, startTimeout);
+  const { child, actualPort } = await startServer2(port, startTimeout);
+  if (actualPort !== port) {
+    console.log(`[ServerLifecycle] Port ${port} was in use, server started on port ${actualPort}`);
+  }
   return {
     wasStarted: true,
-    baseUrl,
-    process: serverProcess
+    baseUrl: `http://localhost:${actualPort}`,
+    process: child
   };
 }
 function createServerCleanup(result, isCI) {
@@ -3243,10 +3732,10 @@ function getDefaultModel(config) {
   return Object.keys(config.models)[0] || "claude-sonnet";
 }
 async function commandExists(command) {
-  const { execSync: execSync2 } = await import("child_process");
+  const { execSync: execSync3 } = await import("child_process");
   const checkCommand = process.platform === "win32" ? `where ${command}` : `which ${command}`;
   try {
-    execSync2(checkCommand, { stdio: "ignore" });
+    execSync3(checkCommand, { stdio: "ignore" });
     return true;
   } catch {
     return false;
@@ -4183,7 +4672,7 @@ function checkEnvFile() {
     details: ["Env vars can be set in shell, CI/CD, or via --env-file"]
   };
 }
-function checkAWSCredentials() {
+async function checkAWSCredentials() {
   const profile = process.env.AWS_PROFILE;
   const accessKey = process.env.AWS_ACCESS_KEY_ID;
   const region = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
@@ -4197,28 +4686,58 @@ function checkAWSCredentials() {
   if (region) {
     details.push(`AWS_REGION: ${region}`);
   }
-  if (profile || accessKey) {
+  if (!profile && !accessKey) {
+    return {
+      name: "AWS Credentials",
+      status: "warning",
+      message: "No AWS credentials detected",
+      details: [
+        "Set AWS_PROFILE or AWS_ACCESS_KEY_ID for Bedrock judge",
+        "Claude Code connector also requires AWS credentials"
+      ]
+    };
+  }
+  try {
+    const { fromNodeProviderChain } = await import("@aws-sdk/credential-providers");
+    const provider = fromNodeProviderChain({
+      ...profile && { profile }
+    });
+    const creds = await provider();
+    if (creds.expiration && creds.expiration.getTime() < Date.now()) {
+      return {
+        name: "AWS Credentials",
+        status: "error",
+        message: "AWS credentials are expired",
+        details: [
+          ...details,
+          `Expired: ${creds.expiration.toISOString()}`,
+          profile ? `Run: aws sso login --profile ${profile}` : "Refresh your AWS credentials"
+        ]
+      };
+    }
     return {
       name: "AWS Credentials",
       status: "ok",
-      message: profile ? `Profile: ${profile}` : "Using access key",
+      message: profile ? `Profile: ${profile} (validated)` : "Using access key (validated)",
       details: details.length > 0 ? details : void 0
     };
+  } catch (err) {
+    return {
+      name: "AWS Credentials",
+      status: "error",
+      message: `AWS credentials invalid: ${err.message}`,
+      details: [
+        ...details,
+        "Run: aws sts get-caller-identity to debug",
+        profile ? `Run: aws sso login --profile ${profile}` : "Check AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY"
+      ]
+    };
   }
-  return {
-    name: "AWS Credentials",
-    status: "warning",
-    message: "No AWS credentials detected",
-    details: [
-      "Set AWS_PROFILE or AWS_ACCESS_KEY_ID for Bedrock judge",
-      "Claude Code connector also requires AWS credentials"
-    ]
-  };
 }
 async function checkClaudeCodeCLI() {
-  const { execSync: execSync2 } = await import("child_process");
+  const { execSync: execSync3 } = await import("child_process");
   try {
-    execSync2("which claude", { stdio: "pipe" });
+    execSync3("which claude", { stdio: "pipe" });
     return {
       name: "Claude Code CLI",
       status: "ok",
@@ -4303,6 +4822,45 @@ function checkOpenSearchObservability() {
     ]
   };
 }
+async function checkTracesConnectivity() {
+  const port = process.env.PORT || "4001";
+  try {
+    const response = await fetch(`http://localhost:${port}/api/traces/health`, {
+      signal: AbortSignal.timeout(5e3)
+    });
+    const data = await response.json();
+    if (data.status === "ok") {
+      return {
+        name: "Traces Connectivity",
+        status: "ok",
+        message: "OpenSearch traces index is accessible"
+      };
+    }
+    if (data.status === "sample_only") {
+      return {
+        name: "Traces Connectivity",
+        status: "ok",
+        message: "Sample data only (no observability backend)"
+      };
+    }
+    const details = [];
+    if (data.error) details.push(data.error);
+    if (data.suggestion) details.push(data.suggestion);
+    return {
+      name: "Traces Connectivity",
+      status: "error",
+      message: data.errorCategory === "auth" ? "Authentication failed \u2014 credentials may be expired" : `Connection error: ${data.error || "unknown"}`,
+      details: details.length > 0 ? details : void 0
+    };
+  } catch {
+    return {
+      name: "Traces Connectivity",
+      status: "ok",
+      message: "Server not running (skipped)",
+      details: ["Start the server first: npm run dev:server"]
+    };
+  }
+}
 function displayResults2(results) {
   console.log(chalk6.bold("\n  Configuration Check\n"));
   for (const result of results) {
@@ -4345,12 +4903,13 @@ function createDoctorCommand() {
     }
     results.push(checkConfigFile());
     results.push(checkEnvFile());
-    results.push(checkAWSCredentials());
+    results.push(await checkAWSCredentials());
     results.push(await checkClaudeCodeCLI());
     results.push(checkAgents(config));
     results.push(checkConnectors());
     results.push(checkOpenSearchStorage());
     results.push(checkOpenSearchObservability());
+    results.push(await checkTracesConnectivity());
     if (options.output === "json") {
       console.log(JSON.stringify(results, null, 2));
     } else {
@@ -4898,38 +5457,768 @@ function createCompareServicesCommand() {
   return cmd;
 }
 
-// cli/index.ts
+// cli/commands/remote.ts
+import { Command as Command10 } from "commander";
+import chalk10 from "chalk";
+import fs2 from "fs";
+import path2 from "path";
+var CONFIG_FILENAME2 = "agent-health.config.json";
+function getConfigPath() {
+  return path2.join(process.cwd(), CONFIG_FILENAME2);
+}
+function readConfig() {
+  const filePath = getConfigPath();
+  if (!fs2.existsSync(filePath)) return {};
+  try {
+    return JSON.parse(fs2.readFileSync(filePath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function writeConfig(config) {
+  fs2.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function getRemoteServers(config) {
+  return Array.isArray(config.remoteServers) ? config.remoteServers : [];
+}
+function createRemoteCommand() {
+  const remote = new Command10("remote").description("Manage remote agent-health server connections");
+  remote.command("add").description("Add a remote server").requiredOption("--name <name>", "Display name for the server").requiredOption("--url <url>", "Server URL (e.g. http://10.0.1.50:4001)").option("--api-key <key>", "API key for authentication").action((options) => {
+    const config = readConfig();
+    const servers = getRemoteServers(config);
+    if (servers.some((s) => s.name === options.name)) {
+      console.error(chalk10.red(`
+  Error: Server "${options.name}" already exists. Use 'remote remove' first.
+`));
+      process.exit(1);
+    }
+    const server = { name: options.name, url: options.url.replace(/\/$/, "") };
+    if (options.apiKey) server.apiKey = options.apiKey;
+    servers.push(server);
+    config.remoteServers = servers;
+    writeConfig(config);
+    console.log(chalk10.green(`
+  Added remote server: ${options.name} (${options.url})
+`));
+  });
+  remote.command("remove").description("Remove a remote server").argument("<name>", "Server name to remove").action((name) => {
+    const config = readConfig();
+    const servers = getRemoteServers(config);
+    const idx = servers.findIndex((s) => s.name === name);
+    if (idx === -1) {
+      console.error(chalk10.red(`
+  Error: Server "${name}" not found.
+`));
+      process.exit(1);
+    }
+    servers.splice(idx, 1);
+    config.remoteServers = servers;
+    writeConfig(config);
+    console.log(chalk10.green(`
+  Removed remote server: ${name}
+`));
+  });
+  remote.command("list").description("List configured remote servers").action(() => {
+    const config = readConfig();
+    const servers = getRemoteServers(config);
+    if (servers.length === 0) {
+      console.log(chalk10.gray("\n  No remote servers configured.\n"));
+      console.log(chalk10.gray("  Add one with: agent-health remote add --name <name> --url <url>\n"));
+      return;
+    }
+    console.log(chalk10.cyan(`
+  Remote Servers (${servers.length}):
+`));
+    for (const s of servers) {
+      const auth = s.apiKey ? chalk10.green(" [auth]") : chalk10.gray(" [no auth]");
+      console.log(`  ${chalk10.bold(s.name)}  ${s.url}${auth}`);
+    }
+    console.log("");
+  });
+  remote.command("test").description("Test connectivity to all remote servers").action(async () => {
+    const config = readConfig();
+    const servers = getRemoteServers(config);
+    if (servers.length === 0) {
+      console.log(chalk10.gray("\n  No remote servers configured.\n"));
+      return;
+    }
+    console.log(chalk10.cyan(`
+  Testing ${servers.length} remote server(s)...
+`));
+    for (const s of servers) {
+      try {
+        const headers = {};
+        if (s.apiKey) headers["Authorization"] = `Bearer ${s.apiKey}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 5e3);
+        const response = await fetch(`${s.url}/api/coding-agents/available`, {
+          headers,
+          signal: controller.signal
+        });
+        clearTimeout(timer);
+        if (response.ok) {
+          const data = await response.json();
+          const agentCount = data.agents?.length ?? 0;
+          console.log(chalk10.green(`  \u2713 ${s.name} \u2014 OK (${agentCount} agents detected)`));
+        } else {
+          console.log(chalk10.red(`  \u2717 ${s.name} \u2014 HTTP ${response.status} ${response.statusText}`));
+        }
+      } catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        console.log(chalk10.red(`  \u2717 ${s.name} \u2014 ${msg}`));
+      }
+    }
+    console.log("");
+  });
+  return remote;
+}
+
+// cli/commands/configure.ts
+import { Command as Command11 } from "commander";
+import chalk11 from "chalk";
+import { existsSync as existsSync5, readFileSync as readFileSync3, writeFileSync as writeFileSync5 } from "fs";
+import { join as join4 } from "path";
+import { execSync as execSync2, spawnSync } from "child_process";
+var CONFIG_FILENAME3 = "agent-health.config.json";
+function readConfig2() {
+  const filePath = join4(process.cwd(), CONFIG_FILENAME3);
+  if (!existsSync5(filePath)) return {};
+  const raw = readFileSync3(filePath, "utf-8");
+  try {
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error(`Config file must contain a JSON object: ${filePath}`);
+    }
+    return parsed;
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      throw new Error(`Failed to parse ${filePath}: ${err.message}. Fix the JSON syntax or delete the file to start fresh.`);
+    }
+    throw err;
+  }
+}
+function writeConfig2(config) {
+  const filePath = join4(process.cwd(), CONFIG_FILENAME3);
+  writeFileSync5(filePath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function validateInput(value, label) {
+  if (/[;&|`$(){}[\]<>!#'"\\\n\r]/.test(value)) {
+    throw new Error(`Invalid ${label}: contains disallowed characters`);
+  }
+}
+function getStackOutputs(stackName, region, profile) {
+  validateInput(stackName, "stack name");
+  if (region) validateInput(region, "region");
+  if (profile) validateInput(profile, "profile");
+  const args = ["cloudformation", "describe-stacks", "--stack-name", stackName, "--output", "json"];
+  if (region) args.push("--region", region);
+  if (profile) args.push("--profile", profile);
+  try {
+    const result = spawnSync("aws", args, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+    if (result.status !== 0) {
+      const stderr = (result.stderr || "").trim();
+      if (stderr.includes("Unable to locate credentials")) {
+        throw new Error("AWS credentials not configured. Run `aws configure` or set AWS_PROFILE.");
+      }
+      throw new Error(stderr || `AWS CLI exited with code ${result.status}`);
+    }
+    const parsed = JSON.parse(result.stdout);
+    const stacks = parsed.Stacks || [];
+    if (stacks.length === 0) {
+      throw new Error(`Stack '${stackName}' not found`);
+    }
+    const stack = stacks[0];
+    if (!stack.Outputs || stack.Outputs.length === 0) {
+      throw new Error(`Stack '${stackName}' has no outputs (status: ${stack.StackStatus})`);
+    }
+    return stack.Outputs;
+  } catch (err) {
+    if (err instanceof Error && (err.message.includes("not found") || err.message.includes("credentials") || err.message.includes("Invalid"))) {
+      throw err;
+    }
+    throw new Error(`Failed to describe stack '${stackName}': ${err instanceof Error ? err.message : err}`);
+  }
+}
+function createConfigureCommand() {
+  const cmd = new Command11("configure").description("Configure Agent Health from infrastructure outputs").option("--from-stack <stackName>", "Import observability config from a CloudFormation stack").option("--region <region>", "AWS region for the CloudFormation stack").option("--profile <profile>", "AWS CLI profile to use").option("--dry-run", "Show what would be written without making changes").action(async (options) => {
+    if (options.fromStack) {
+      await configureFromStack(options.fromStack, options.region, options.profile, options.dryRun);
+    } else {
+      console.log(chalk11.yellow("\n  No configuration source specified.\n"));
+      console.log(chalk11.gray("  Usage:"));
+      console.log(chalk11.gray("    agent-health configure --from-stack <stack-name>"));
+      console.log(chalk11.gray("    agent-health configure --from-stack AgentHealthObservability --region us-west-2"));
+      console.log(chalk11.gray("    agent-health configure --from-stack AgentHealthObservability --dry-run\n"));
+    }
+  });
+  return cmd;
+}
+async function configureFromStack(stackName, region, profile, dryRun) {
+  console.log(chalk11.cyan(`
+  Importing configuration from CloudFormation stack: ${chalk11.bold(stackName)}
+`));
+  try {
+    execSync2("aws --version", { stdio: ["pipe", "pipe", "pipe"] });
+  } catch {
+    console.error(chalk11.red("  AWS CLI is not installed. Install it from https://aws.amazon.com/cli/\n"));
+    process.exit(1);
+  }
+  let outputs;
+  try {
+    outputs = getStackOutputs(stackName, region, profile);
+  } catch (err) {
+    console.error(chalk11.red(`  ${err instanceof Error ? err.message : err}
+`));
+    process.exit(1);
+  }
+  const outputMap = new Map(outputs.map((o) => [o.OutputKey, o.OutputValue]));
+  const endpoint = outputMap.get("OpenSearchEndpoint");
+  const osisEndpoint = outputMap.get("OSISTraceIngestEndpoint") || outputMap.get("OSISIngestEndpoint");
+  const stackRegion = outputMap.get("Region") || region;
+  const ingestionRoleArn = outputMap.get("IngestionRoleArn");
+  if (!endpoint) {
+    console.error(chalk11.red("  Stack does not have an OpenSearchEndpoint output."));
+    console.error(chalk11.gray("  Available outputs: " + outputs.map((o) => o.OutputKey).join(", ") + "\n"));
+    process.exit(1);
+  }
+  const observabilityConfig = {
+    endpoint,
+    authType: "sigv4",
+    awsRegion: stackRegion,
+    awsService: "es",
+    tlsSkipVerify: false
+  };
+  console.log(chalk11.green("  Stack outputs found:"));
+  console.log(chalk11.gray(`    OpenSearch Endpoint:  ${endpoint}`));
+  if (osisEndpoint) {
+    console.log(chalk11.gray(`    OSIS Ingest Endpoint: ${osisEndpoint}`));
+  }
+  if (stackRegion) {
+    console.log(chalk11.gray(`    Region:               ${stackRegion}`));
+  }
+  if (ingestionRoleArn) {
+    console.log(chalk11.gray(`    Ingestion Role:       ${ingestionRoleArn}`));
+  }
+  console.log();
+  if (dryRun) {
+    console.log(chalk11.yellow("  Dry run \u2014 would write this to agent-health.config.json:\n"));
+    console.log(chalk11.gray(JSON.stringify({ observability: observabilityConfig }, null, 2)));
+    console.log();
+    return;
+  }
+  const config = readConfig2();
+  if (config.observability) {
+    console.log(chalk11.yellow("  Existing observability config found \u2014 overwriting.\n"));
+  }
+  config.observability = observabilityConfig;
+  writeConfig2(config);
+  console.log(chalk11.green(`  \u2713 Observability config written to ${CONFIG_FILENAME3}
+`));
+  if (osisEndpoint) {
+    console.log(chalk11.cyan("  Next step: Configure your agent to send traces to:"));
+    console.log(chalk11.bold(`    OTEL_EXPORTER_OTLP_ENDPOINT=${osisEndpoint}
+`));
+  }
+  if (ingestionRoleArn) {
+    console.log(chalk11.gray(`  Your agents should assume this role for SigV4 auth:`));
+    console.log(chalk11.gray(`    ${ingestionRoleArn}
+`));
+  }
+  console.log(chalk11.green("  Done! Start Agent Health with: npx @opensearch-project/agent-health\n"));
+}
+
+// cli/commands/kill.ts
+import { Command as Command12 } from "commander";
+import chalk12 from "chalk";
+
+// server/services/observioAgent.ts
+import { join as join5, dirname as dirname3 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import net2 from "net";
 var __filename3 = fileURLToPath3(import.meta.url);
 var __dirname3 = dirname3(__filename3);
-var packageJsonPath2 = join4(__dirname3, "..", "..", "package.json");
+var OBSERVIO_PORT = 3001;
+var observioChild = null;
+function isPortFree(port) {
+  return new Promise((resolve5) => {
+    let resolved = false;
+    const done = (value) => {
+      if (!resolved) {
+        resolved = true;
+        socket.destroy();
+        resolve5(value);
+      }
+    };
+    const socket = new net2.Socket();
+    socket.setTimeout(1e3);
+    socket.once("connect", () => done(false));
+    socket.once("timeout", () => done(true));
+    socket.once("error", () => done(true));
+    socket.connect(port, "localhost");
+  });
+}
+async function killObservioAgent(port = OBSERVIO_PORT) {
+  if (observioChild && !observioChild.killed) {
+    try {
+      observioChild.kill("SIGTERM");
+      for (let i = 0; i < 10; i++) {
+        await new Promise((r) => setTimeout(r, 500));
+        if (observioChild === null || observioChild.killed) break;
+      }
+      if (observioChild && !observioChild.killed) {
+        observioChild.kill("SIGKILL");
+      }
+      observioChild = null;
+    } catch {
+    }
+    for (let i = 0; i < 10; i++) {
+      await new Promise((r) => setTimeout(r, 500));
+      if (await isPortFree(port)) return true;
+    }
+  }
+  const free = await isPortFree(port);
+  if (free) return false;
+  console.warn(`  [observio] Port ${port} is in use but not by a tracked process. Use 'lsof -i :${port}' to investigate.`);
+  return false;
+}
+
+// cli/commands/kill.ts
+function createKillCommand() {
+  const command = new Command12("kill").description("Kill a running agent process").argument("<target>", "What to kill: sample-agent").action(async (target) => {
+    switch (target) {
+      case "sample-agent": {
+        const free = await isPortFree(OBSERVIO_PORT);
+        if (free) {
+          console.log(chalk12.yellow(`  No process found on port ${OBSERVIO_PORT}`));
+          return;
+        }
+        const killed = await killObservioAgent();
+        if (killed) {
+          console.log(chalk12.green("  \u2713 Sample agent stopped"));
+        } else {
+          console.log(chalk12.red("  \u2717 Failed to stop sample agent"));
+          process.exitCode = 1;
+        }
+        break;
+      }
+      default:
+        console.error(chalk12.red(`  Unknown target: ${target}`));
+        console.log(`  Available targets: ${chalk12.cyan("sample-agent")}`);
+        process.exitCode = 1;
+    }
+  });
+  return command;
+}
+
+// cli/commands/setup-telemetry.ts
+import { Command as Command13 } from "commander";
+import chalk13 from "chalk";
+import { existsSync as existsSync6, readFileSync as readFileSync4, appendFileSync, writeFileSync as writeFileSync6 } from "fs";
+import { join as join6, dirname as dirname4 } from "path";
+import { spawnSync as spawnSync2 } from "child_process";
+import { homedir } from "os";
+import { fileURLToPath as fileURLToPath4 } from "url";
+var __dirname4 = dirname4(fileURLToPath4(import.meta.url));
+function getCfnTemplatePath() {
+  const candidates = [
+    join6(__dirname4, "..", "..", "deployment", "cloudformation", "agent-health-observability.yaml"),
+    join6(__dirname4, "..", "deployment", "cloudformation", "agent-health-observability.yaml")
+  ];
+  for (const p of candidates) {
+    if (existsSync6(p)) return p;
+  }
+  return candidates[0];
+}
+var RC_BLOCK_START = "# --- Agent Health: Claude Code Telemetry ---";
+var RC_BLOCK_END = "# --- End Agent Health Telemetry ---";
+function validateInput2(value, label) {
+  if (/[;&|`$(){}[\]<>!#'"\\\n\r]/.test(value)) {
+    throw new Error(`Invalid ${label}: contains disallowed characters`);
+  }
+}
+function detectRcFile() {
+  const shellEnv = process.env.SHELL || "";
+  const home = homedir();
+  if (shellEnv.includes("zsh")) {
+    return { shell: "zsh", rcPath: join6(home, ".zshrc") };
+  }
+  if (shellEnv.includes("fish")) {
+    return { shell: "fish", rcPath: join6(home, ".config", "fish", "config.fish") };
+  }
+  const bashrc = join6(home, ".bashrc");
+  const profile = join6(home, ".bash_profile");
+  return { shell: "bash", rcPath: existsSync6(bashrc) ? bashrc : profile };
+}
+function rcFileHasTelemetryBlock(rcPath) {
+  if (!existsSync6(rcPath)) return false;
+  const content = readFileSync4(rcPath, "utf-8");
+  return content.includes(RC_BLOCK_START);
+}
+function getStackOutputs2(stackName, region, profile) {
+  validateInput2(stackName, "stack name");
+  if (region) validateInput2(region, "region");
+  if (profile) validateInput2(profile, "profile");
+  const args = ["cloudformation", "describe-stacks", "--stack-name", stackName, "--output", "json"];
+  if (region) args.push("--region", region);
+  if (profile) args.push("--profile", profile);
+  const result = spawnSync2("aws", args, { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+  if (result.status !== 0) {
+    const stderr = (result.stderr || "").trim();
+    if (stderr.includes("Unable to locate credentials")) {
+      throw new Error("AWS credentials not configured. Run `aws configure` or set AWS_PROFILE.");
+    }
+    if (stderr.includes("does not exist")) {
+      const templatePath = getCfnTemplatePath();
+      throw new Error(`Stack '${stackName}' not found. Deploy it first:
+    npx @goyamegh/agent-health setup-telemetry --deploy
+  Or manually:
+    aws cloudformation deploy --template-file ${templatePath} --stack-name ${stackName} --capabilities CAPABILITY_NAMED_IAM`);
+    }
+    throw new Error(stderr || `AWS CLI exited with code ${result.status}`);
+  }
+  const parsed = JSON.parse(result.stdout);
+  const stacks = parsed.Stacks || [];
+  if (stacks.length === 0) {
+    throw new Error(`Stack '${stackName}' not found`);
+  }
+  const outputs = stacks[0].Outputs || [];
+  const outputMap = new Map(outputs.map((o) => [o.OutputKey, o.OutputValue]));
+  const otlpEndpoint = outputMap.get("OTLPProxyApiEndpoint") || outputMap.get("OTLPIngestEndpoint");
+  if (!otlpEndpoint) {
+    const available = outputs.map((o) => o.OutputKey).join(", ");
+    throw new Error(`Stack '${stackName}' has no OTLP endpoint output.
+    Available outputs: ${available}
+    Make sure the stack includes the API Gateway OTLP proxy.`);
+  }
+  const opensearchEndpoint = outputMap.get("OpenSearchEndpoint") || outputMap.get("DomainEndpoint");
+  const stackRegion = outputMap.get("Region") || region;
+  return { otlpEndpoint, opensearchEndpoint, region: stackRegion };
+}
+var CONFIG_FILENAME4 = "agent-health.config.json";
+function writeServerConfig(opensearchEndpoint, region) {
+  const fullEndpoint = opensearchEndpoint.startsWith("https://") ? opensearchEndpoint : `https://${opensearchEndpoint}`;
+  const observability = {
+    endpoint: fullEndpoint,
+    authType: "sigv4",
+    awsRegion: region,
+    awsService: "es"
+  };
+  const paths = [
+    join6(process.cwd(), CONFIG_FILENAME4),
+    join6(homedir(), CONFIG_FILENAME4)
+  ];
+  const uniquePaths = [...new Set(paths)];
+  const written = [];
+  for (const configPath of uniquePaths) {
+    let config = {};
+    if (existsSync6(configPath)) {
+      try {
+        config = JSON.parse(readFileSync4(configPath, "utf-8"));
+      } catch {
+      }
+    }
+    config.observability = observability;
+    writeFileSync6(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    written.push(configPath);
+  }
+  return written;
+}
+function isClaudeInstalled() {
+  const result = spawnSync2("which", ["claude"], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+  return result.status === 0;
+}
+function isAwsCliInstalled() {
+  const result = spawnSync2("aws", ["--version"], { encoding: "utf-8", stdio: ["pipe", "pipe", "pipe"] });
+  return result.status === 0;
+}
+async function testEndpoint(endpoint) {
+  try {
+    const url = endpoint.replace(/\/+$/, "") + "/v1/traces";
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1e4);
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-protobuf" },
+      body: new Uint8Array(0),
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    if (res.ok || res.status === 400) {
+      return { ok: true, message: `Endpoint reachable (HTTP ${res.status})` };
+    }
+    if (res.status === 403) {
+      return { ok: true, message: "Endpoint reachable (HTTP 403 \u2014 IAM auth required, which is expected)" };
+    }
+    return { ok: false, message: `Endpoint returned HTTP ${res.status}` };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("abort")) {
+      return { ok: false, message: "Endpoint timed out after 10s" };
+    }
+    return { ok: false, message: `Connection failed: ${msg}` };
+  }
+}
+function buildRcBlock(endpoint) {
+  const lines = [
+    RC_BLOCK_START,
+    `export CLAUDE_CODE_ENABLE_TELEMETRY=1`,
+    `export OTEL_METRICS_EXPORTER=otlp`,
+    `export OTEL_LOGS_EXPORTER=otlp`,
+    `export OTEL_TRACES_EXPORTER=otlp`,
+    `export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf`,
+    `export OTEL_EXPORTER_OTLP_ENDPOINT=${endpoint}`,
+    "",
+    `# cc-otel: Launch Claude Code with telemetry enabled`,
+    `alias cc-otel="export AWS_PROFILE=Bedrock && export CLAUDE_CODE_USE_BEDROCK=1 && export DISABLE_PROMPT_CACHING=1 && export DISABLE_ERROR_REPORTING=1 && export DISABLE_TELEMETRY=0 && export AWS_REGION=us-east-1 && export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 && export CLAUDE_CODE_ENABLE_TELEMETRY=1 && export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 && export OTEL_METRICS_EXPORTER=otlp && export OTEL_LOGS_EXPORTER=otlp && export OTEL_TRACES_EXPORTER=otlp && export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf && export OTEL_EXPORTER_OTLP_ENDPOINT=${endpoint} && claude"`,
+    RC_BLOCK_END
+  ];
+  return "\n" + lines.join("\n") + "\n";
+}
+function createSetupTelemetryCommand() {
+  const command = new Command13("setup-telemetry").description("Configure Claude Code to send telemetry to Agent Health").option("--stack <name>", "CloudFormation stack name", "AgentHealthObservability").option("--region <region>", "AWS region for the CloudFormation stack").option("--profile <profile>", "AWS CLI profile to use").option("--endpoint <url>", "OTLP endpoint URL (skip stack lookup)").option("--dry-run", "Show what would be written without making changes").option("--skip-rc", "Print env vars without writing to shell rc file").option("--status", "Check current telemetry configuration status").option("--deploy", "Deploy the CloudFormation stack before configuring telemetry").option("--force", "Replace existing telemetry block in shell rc file").action(async (options) => {
+    console.log(chalk13.cyan.bold("\n  Agent Health \u2014 Claude Code Telemetry Setup\n"));
+    if (options.status) {
+      await showStatus();
+      return;
+    }
+    console.log(chalk13.bold("  Checking prerequisites...\n"));
+    if (!isClaudeInstalled()) {
+      console.log(chalk13.yellow("  \u26A0 Claude Code CLI not found"));
+      console.log(chalk13.gray("    Install: npm install -g @anthropic-ai/claude-code\n"));
+    } else {
+      console.log(chalk13.green("  \u2713 Claude Code CLI installed"));
+    }
+    if (options.deploy && !options.endpoint) {
+      if (!isAwsCliInstalled()) {
+        console.error(chalk13.red("  \u2717 AWS CLI not found. Install it first or use --endpoint <url>.\n"));
+        process.exit(1);
+      }
+      console.log(chalk13.green("  \u2713 AWS CLI installed"));
+      const templatePath = getCfnTemplatePath();
+      if (!existsSync6(templatePath)) {
+        console.error(chalk13.red(`
+  \u2717 CFN template not found at ${templatePath}`));
+        console.error(chalk13.gray("    This can happen if running from source. Try: npx @goyamegh/agent-health setup-telemetry --deploy\n"));
+        process.exit(1);
+      }
+      console.log(chalk13.gray(`
+  Deploying stack ${chalk13.bold(options.stack)}...`));
+      console.log(chalk13.gray(`  Template: ${templatePath}`));
+      console.log(chalk13.gray("  This may take 10-15 minutes on first deploy.\n"));
+      const deployArgs = [
+        "cloudformation",
+        "deploy",
+        "--template-file",
+        templatePath,
+        "--stack-name",
+        options.stack,
+        "--capabilities",
+        "CAPABILITY_NAMED_IAM",
+        "--no-fail-on-empty-changeset"
+      ];
+      if (options.region) deployArgs.push("--region", options.region);
+      if (options.profile) deployArgs.push("--profile", options.profile);
+      const deployResult = spawnSync2("aws", deployArgs, {
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 20 * 60 * 1e3
+        // 20 min timeout for CFN deploy
+      });
+      if (deployResult.status !== 0) {
+        const stderr = (deployResult.stderr || "").trim();
+        console.error(chalk13.red(`
+  \u2717 Stack deployment failed:
+    ${stderr}
+`));
+        process.exit(1);
+      }
+      console.log(chalk13.green(`  \u2713 Stack ${options.stack} deployed successfully`));
+    }
+    let endpoint;
+    let stackOutputs = null;
+    if (options.endpoint) {
+      endpoint = options.endpoint;
+      console.log(chalk13.green(`  \u2713 Using provided endpoint: ${endpoint}`));
+    } else {
+      if (!isAwsCliInstalled()) {
+        console.error(chalk13.red("  \u2717 AWS CLI not found. Install it or use --endpoint <url> to skip stack lookup.\n"));
+        process.exit(1);
+      }
+      if (!options.deploy) console.log(chalk13.green("  \u2713 AWS CLI installed"));
+      console.log(chalk13.gray(`
+  Reading stack outputs from ${chalk13.bold(options.stack)}...`));
+      try {
+        stackOutputs = getStackOutputs2(options.stack, options.region, options.profile);
+        endpoint = stackOutputs.otlpEndpoint;
+        console.log(chalk13.green(`  \u2713 OTLP endpoint: ${endpoint}`));
+        if (stackOutputs.opensearchEndpoint) {
+          console.log(chalk13.green(`  \u2713 OpenSearch endpoint: ${stackOutputs.opensearchEndpoint}`));
+        }
+      } catch (err) {
+        console.error(chalk13.red(`
+  \u2717 ${err instanceof Error ? err.message : err}
+`));
+        process.exit(1);
+      }
+    }
+    console.log(chalk13.gray("\n  Testing OTLP endpoint connectivity..."));
+    const connectivity = await testEndpoint(endpoint);
+    if (connectivity.ok) {
+      console.log(chalk13.green(`  \u2713 ${connectivity.message}`));
+    } else {
+      console.log(chalk13.yellow(`  \u26A0 ${connectivity.message}`));
+      console.log(chalk13.gray("    Telemetry may not work until the endpoint is reachable."));
+    }
+    if (stackOutputs?.opensearchEndpoint) {
+      const effectiveRegion = stackOutputs.region || options.region;
+      if (effectiveRegion) {
+        if (options.dryRun) {
+          console.log(chalk13.yellow("\n  Dry run \u2014 would write server config:"));
+          console.log(chalk13.gray(`    OpenSearch endpoint: ${stackOutputs.opensearchEndpoint}`));
+          console.log(chalk13.gray(`    Auth: SigV4, Region: ${effectiveRegion}
+`));
+        } else {
+          const configPaths = writeServerConfig(stackOutputs.opensearchEndpoint, effectiveRegion);
+          for (const p of configPaths) {
+            console.log(chalk13.green(`  \u2713 Server config written to ${p}`));
+          }
+          console.log(chalk13.gray(`    Agent Health server will read traces from this OpenSearch domain.`));
+        }
+      } else {
+        console.log(chalk13.yellow("\n  \u26A0 Could not determine region for server config. Set --region explicitly."));
+      }
+    }
+    const { shell, rcPath } = detectRcFile();
+    console.log(chalk13.gray(`
+  Detected shell: ${shell} \u2192 ${rcPath}`));
+    if (options.dryRun) {
+      console.log(chalk13.yellow("\n  Dry run \u2014 would append to " + rcPath + ":\n"));
+      console.log(chalk13.gray(buildRcBlock(endpoint)));
+      console.log(chalk13.yellow("  No changes made.\n"));
+      return;
+    }
+    if (options.skipRc) {
+      console.log(chalk13.yellow("\n  Add these to your shell profile:\n"));
+      console.log(chalk13.gray(buildRcBlock(endpoint)));
+      return;
+    }
+    if (rcFileHasTelemetryBlock(rcPath)) {
+      if (options.force) {
+        const content = readFileSync4(rcPath, "utf-8");
+        const regex = new RegExp(`${RC_BLOCK_START}[\\s\\S]*?${RC_BLOCK_END}\\n?`, "g");
+        const cleaned = content.replace(regex, "");
+        writeFileSync6(rcPath, cleaned + buildRcBlock(endpoint), "utf-8");
+        console.log(chalk13.green(`
+  \u2713 Telemetry env vars updated in ${rcPath}`));
+      } else {
+        console.log(chalk13.yellow(`
+  \u26A0 Telemetry block already exists in ${rcPath}`));
+        console.log(chalk13.gray(`    Use --force to replace it, or manually remove the block between "${RC_BLOCK_START}" and "${RC_BLOCK_END}".
+`));
+      }
+    } else {
+      appendFileSync(rcPath, buildRcBlock(endpoint));
+      console.log(chalk13.green(`
+  \u2713 Telemetry env vars written to ${rcPath}`));
+    }
+    console.log(chalk13.cyan.bold("\n  Next steps:\n"));
+    console.log(chalk13.gray(`    1. Reload your shell:  ${chalk13.white(`source ${rcPath}`)}`));
+    console.log(chalk13.gray(`    2. Start Claude Code:  ${chalk13.white("cc-otel")} (launches Claude with telemetry)`));
+    console.log(chalk13.gray(`    3. View traces:        ${chalk13.white("http://localhost:4001/coding-agents")}`));
+    console.log(chalk13.gray(`
+    The ${chalk13.white("cc-otel")} alias combines Bedrock auth + OTel telemetry + Claude launch.
+`));
+  });
+  return command;
+}
+async function showStatus() {
+  console.log(chalk13.bold("  Current Telemetry Status\n"));
+  const checks = [
+    { name: "Telemetry enabled", envVar: "CLAUDE_CODE_ENABLE_TELEMETRY", expected: "1" },
+    { name: "Traces exporter", envVar: "OTEL_TRACES_EXPORTER", expected: "otlp" },
+    { name: "Logs exporter", envVar: "OTEL_LOGS_EXPORTER", expected: "otlp" },
+    { name: "Metrics exporter", envVar: "OTEL_METRICS_EXPORTER", expected: "otlp" },
+    { name: "OTLP protocol", envVar: "OTEL_EXPORTER_OTLP_PROTOCOL" },
+    { name: "OTLP endpoint", envVar: "OTEL_EXPORTER_OTLP_ENDPOINT" }
+  ];
+  let allOk = true;
+  for (const check of checks) {
+    const value = process.env[check.envVar];
+    if (!value) {
+      console.log(chalk13.yellow(`  \u26A0 ${check.name}: ${chalk13.gray("not set")} (${check.envVar})`));
+      allOk = false;
+    } else if (check.expected && value !== check.expected) {
+      console.log(chalk13.yellow(`  \u26A0 ${check.name}: ${value} (expected ${check.expected})`));
+      allOk = false;
+    } else {
+      console.log(chalk13.green(`  \u2713 ${check.name}: ${value}`));
+    }
+  }
+  console.log("");
+  if (isClaudeInstalled()) {
+    console.log(chalk13.green("  \u2713 Claude Code CLI installed"));
+  } else {
+    console.log(chalk13.yellow("  \u26A0 Claude Code CLI not found"));
+    allOk = false;
+  }
+  const { rcPath } = detectRcFile();
+  if (rcFileHasTelemetryBlock(rcPath)) {
+    console.log(chalk13.green(`  \u2713 Telemetry block in ${rcPath}`));
+  } else {
+    console.log(chalk13.yellow(`  \u26A0 No telemetry block in ${rcPath}`));
+    allOk = false;
+  }
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (endpoint) {
+    console.log(chalk13.gray("\n  Testing endpoint..."));
+    const result = await testEndpoint(endpoint);
+    if (result.ok) {
+      console.log(chalk13.green(`  \u2713 ${result.message}`));
+    } else {
+      console.log(chalk13.yellow(`  \u26A0 ${result.message}`));
+      allOk = false;
+    }
+  }
+  console.log("");
+  if (allOk) {
+    console.log(chalk13.green("  All checks passed! Telemetry is configured.\n"));
+  } else {
+    console.log(chalk13.yellow("  Some checks failed. Run `agent-health setup-telemetry` to fix.\n"));
+  }
+}
+
+// cli/index.ts
+var __filename4 = fileURLToPath5(import.meta.url);
+var __dirname5 = dirname5(__filename4);
+var packageJsonPath2 = join7(__dirname5, "..", "..", "package.json");
 var version = "0.1.0";
 try {
-  const packageJson = JSON.parse(readFileSync3(packageJsonPath2, "utf-8"));
+  const packageJson = JSON.parse(readFileSync5(packageJsonPath2, "utf-8"));
   version = packageJson.version;
 } catch {
 }
 function loadEnvFile(envPath) {
   const absolutePath = resolve4(process.cwd(), envPath);
-  if (!existsSync5(absolutePath)) {
-    console.error(chalk10.red(`
+  if (!existsSync7(absolutePath)) {
+    console.error(chalk14.red(`
   Error: Environment file not found: ${absolutePath}
 `));
     process.exit(1);
   }
   const result = loadDotenv({ path: absolutePath });
   if (result.error) {
-    console.error(chalk10.red(`
+    console.error(chalk14.red(`
   Error loading environment file: ${result.error.message}
 `));
     process.exit(1);
   }
-  console.log(chalk10.gray(`  Loaded environment from: ${envPath}`));
+  console.log(chalk14.gray(`  Loaded environment from: ${envPath}`));
 }
 var defaultEnvPath = resolve4(process.cwd(), ".env");
-if (existsSync5(defaultEnvPath)) {
+if (existsSync7(defaultEnvPath)) {
   loadDotenv({ path: defaultEnvPath });
 }
-var program = new Command10();
+var program = new Command14();
 program.name("agent-health").description("Agent Health Evaluation Framework - Evaluate and monitor AI agent performance").version(version).enablePositionalOptions().passThroughOptions().configureHelp({
   sortSubcommands: false,
   // Hide default command list — replaced by grouped custom help below
@@ -4942,81 +6231,105 @@ program.name("agent-health").description("Agent Health Evaluation Framework - Ev
     if (desc) {
       output.push(desc, "");
     }
-    output.push(`${chalk10.cyan.bold("Usage:")} ${helper.commandUsage(cmd)}`, "");
+    output.push(`${chalk14.cyan.bold("Usage:")} ${helper.commandUsage(cmd)}`, "");
     const optionList = helper.visibleOptions(cmd).map((opt) => {
       const term = helper.optionTerm(opt);
       const desc2 = helper.optionDescription(opt);
       return `  ${term.padEnd(termWidth)}  ${desc2}`;
     }).join("\n");
     if (optionList) {
-      output.push(`${chalk10.cyan.bold("Options:")}`, optionList, "");
+      output.push(`${chalk14.cyan.bold("Options:")}`, optionList, "");
     }
     return output.join("\n");
   }
 });
 program.addHelpText("after", `
-${chalk10.cyan.bold("Getting Started:")}
-  ${chalk10.yellow("agent-health")}                        Launch the web UI and evaluation server
-  ${chalk10.yellow("agent-health init")}                   Generate an agent-health.config.ts file
-  ${chalk10.yellow("agent-health doctor")}                 Verify your setup (AWS creds, OpenSearch, agents)
+${chalk14.cyan.bold("Getting Started:")}
+  ${chalk14.yellow("agent-health")}                        Launch the web UI and evaluation server
+  ${chalk14.yellow("agent-health init")}                   Generate an agent-health.config.ts file
+  ${chalk14.yellow("agent-health doctor")}                 Verify your setup (AWS creds, OpenSearch, agents)
+
+${chalk14.cyan.bold("Running Evaluations:")}
+  ${chalk14.yellow("agent-health run")} ${chalk14.gray("-t <case> -a <agent>")}   Run a single test case against an agent
+  ${chalk14.yellow("agent-health benchmark")} ${chalk14.gray("-f <file>")}        Run a full benchmark from a test cases JSON file
+  ${chalk14.yellow("agent-health benchmark")} ${chalk14.gray("-b <id>")}          Re-run an existing benchmark
 
-${chalk10.cyan.bold("Running Evaluations:")}
-  ${chalk10.yellow("agent-health run")} ${chalk10.gray("-t <case> -a <agent>")}   Run a single test case against an agent
-  ${chalk10.yellow("agent-health benchmark")} ${chalk10.gray("-f <file>")}        Run a full benchmark from a test cases JSON file
-  ${chalk10.yellow("agent-health benchmark")} ${chalk10.gray("-b <id>")}          Re-run an existing benchmark
+${chalk14.cyan.bold("Viewing Results:")}
+  ${chalk14.yellow("agent-health list")} ${chalk14.gray("agents|benchmarks|...")}  List agents, connectors, test cases, or benchmarks
+  ${chalk14.yellow("agent-health report")} ${chalk14.gray("-b <benchmark>")}       Generate an HTML/PDF/JSON report
+  ${chalk14.yellow("agent-health export")} ${chalk14.gray("-b <benchmark>")}       Export test cases as re-importable JSON
+  ${chalk14.yellow("agent-health compare-services")} ${chalk14.gray("-s A B")}    Compare error patterns between services
 
-${chalk10.cyan.bold("Viewing Results:")}
-  ${chalk10.yellow("agent-health list")} ${chalk10.gray("agents|benchmarks|...")}  List agents, connectors, test cases, or benchmarks
-  ${chalk10.yellow("agent-health report")} ${chalk10.gray("-b <benchmark>")}       Generate an HTML/PDF/JSON report
-  ${chalk10.yellow("agent-health export")} ${chalk10.gray("-b <benchmark>")}       Export test cases as re-importable JSON
-  ${chalk10.yellow("agent-health compare-services")} ${chalk10.gray("-s A B")}    Compare error patterns between services
+${chalk14.cyan.bold("Remote Servers:")}
+  ${chalk14.yellow("agent-health remote add")} ${chalk14.gray("--name <n> --url <u>")}  Add a remote server
+  ${chalk14.yellow("agent-health remote list")}             List configured remote servers
+  ${chalk14.yellow("agent-health remote test")}             Test connectivity to all remotes
 
-${chalk10.cyan.bold("Maintenance:")}
-  ${chalk10.yellow("agent-health migrate")}                Migrate legacy benchmark data to current format
-  ${chalk10.yellow("agent-health serve")}                  Start the server (same as default, explicit command)
+${chalk14.cyan.bold("Infrastructure:")}
+  ${chalk14.yellow("agent-health configure")} ${chalk14.gray("--from-stack <name>")}  Import config from a CloudFormation stack
+  ${chalk14.yellow("agent-health setup-telemetry")}            Configure Claude Code \u2192 Agent Health telemetry
+  ${chalk14.yellow("agent-health setup-telemetry")} ${chalk14.gray("--status")}  Check current telemetry status
 
-${chalk10.cyan.bold("Examples:")}
-  ${chalk10.gray("$")} npx @opensearch-project/agent-health
-  ${chalk10.gray("$")} npx @opensearch-project/agent-health --port 8080 --no-browser
-  ${chalk10.gray("$")} npx @opensearch-project/agent-health run -t "RCA for 500 errors" -a langgraph
-  ${chalk10.gray("$")} npx @opensearch-project/agent-health benchmark -f ./test-cases.json -a my-agent
-  ${chalk10.gray("$")} npx @opensearch-project/agent-health list agents
-  ${chalk10.gray("$")} npx @opensearch-project/agent-health report -b bench-123 -f pdf -o report.pdf
+${chalk14.cyan.bold("Maintenance:")}
+  ${chalk14.yellow("agent-health migrate")}                Migrate legacy benchmark data to current format
+  ${chalk14.yellow("agent-health kill")} ${chalk14.gray("sample-agent")}       Stop a running sample agent by name
+  ${chalk14.yellow("agent-health serve")}                  Start the server (same as default, explicit command)
+
+${chalk14.cyan.bold("Examples:")}
+  ${chalk14.gray("$")} npx @opensearch-project/agent-health
+  ${chalk14.gray("$")} npx @opensearch-project/agent-health --port 8080 --no-browser
+  ${chalk14.gray("$")} npx @opensearch-project/agent-health run -t "RCA for 500 errors" -a langgraph
+  ${chalk14.gray("$")} npx @opensearch-project/agent-health benchmark -f ./test-cases.json -a my-agent
+  ${chalk14.gray("$")} npx @opensearch-project/agent-health list agents
+  ${chalk14.gray("$")} npx @opensearch-project/agent-health report -b bench-123 -f pdf -o report.pdf
+  ${chalk14.gray("$")} npx @opensearch-project/agent-health serve --headless --api-key sk-secret
 `);
-program.option("-p, --port <number>", "Server port", "4001").option("-e, --env-file <path>", "Load environment variables from file (e.g., .env)").option("--no-browser", "Do not open browser automatically");
+program.option("-p, --port <number>", "Server port", "4001").option("-e, --env-file <path>", "Load environment variables from file (e.g., .env)").option("--no-browser", "Do not open browser automatically").option("--headless", "Run API server only (no frontend, no browser)").option("--api-key <key>", "Require API key for coding-agents endpoints");
 program.action(async (options) => {
-  console.log(chalk10.cyan.bold(`
+  console.log(chalk14.cyan.bold(`
   Agent Health v${version} - AI Agent Evaluation Framework
 `));
-  console.log(chalk10.gray(`  Working directory: ${process.cwd()}`));
-  console.log(chalk10.gray(`  Package directory: ${__dirname3}`));
+  console.log(chalk14.gray(`  Working directory: ${process.cwd()}`));
+  console.log(chalk14.gray(`  Package directory: ${__dirname5}`));
   if (options.envFile) {
     loadEnvFile(options.envFile);
-  } else if (existsSync5(defaultEnvPath)) {
-    console.log(chalk10.gray("  Auto-loaded .env from current directory"));
+  } else if (existsSync7(defaultEnvPath)) {
+    console.log(chalk14.gray("  Auto-loaded .env from current directory"));
   }
   const port = parseInt(options.port, 10);
-  const spinner = ora5("Starting server...").start();
+  const headless = options.headless || false;
+  const spinner = ora5(headless ? "Starting headless API server..." : "Starting server...").start();
   try {
-    await startServer({ port });
-    spinner.succeed("Server started");
-    console.log(chalk10.gray("\n  Configuration:"));
-    console.log(chalk10.gray(`    Storage: Sample data (configure OpenSearch for persistence)`));
-    console.log(chalk10.gray(`    Agent: Select in UI (Demo Agent for mock, real agents require endpoints)`));
-    console.log(chalk10.gray(`    Judge: Select in UI (Demo Judge for mock, Bedrock requires AWS creds)
+    const actualPort = await startServer({ port, headless, apiKey: options.apiKey });
+    spinner.succeed(headless ? "Headless API server started" : "Server started");
+    if (actualPort !== port) {
+      console.log(chalk14.yellow(`
+  Port ${port} was in use, started on port ${actualPort} instead`));
+    }
+    if (headless) {
+      console.log(chalk14.green(`
+  API server running on http://0.0.0.0:${actualPort}`));
+      if (options.apiKey) console.log(chalk14.gray("  API key authentication enabled"));
+      console.log(chalk14.gray("  Mode: headless (API only, no frontend)\n"));
+    } else {
+      console.log(chalk14.gray("\n  Configuration:"));
+      console.log(chalk14.gray(`    Storage: Sample data (configure OpenSearch for persistence)`));
+      console.log(chalk14.gray(`    Agent: Select in UI (Demo Agent for mock, real agents require endpoints)`));
+      console.log(chalk14.gray(`    Judge: Select in UI (Demo Judge for mock, Bedrock requires AWS creds)
 `));
-    const url = `http://localhost:${port}`;
-    console.log(chalk10.green(`  Server running at ${chalk10.bold(url)}
+      const url = `http://localhost:${actualPort}`;
+      console.log(chalk14.green(`  Server running at ${chalk14.bold(url)}
 `));
-    console.log(chalk10.green(`  Demo data loaded`));
-    if (options.browser !== false) {
-      console.log(chalk10.gray("  Opening browser..."));
-      await open(url);
+      console.log(chalk14.green(`  Demo data loaded`));
+      if (options.browser !== false) {
+        console.log(chalk14.gray("  Opening browser..."));
+        await open(url);
+      }
     }
-    console.log(chalk10.gray("  Press Ctrl+C to stop\n"));
+    console.log(chalk14.gray("  Press Ctrl+C to stop\n"));
   } catch (error) {
     spinner.fail("Failed to start server");
-    console.error(chalk10.red(`
+    console.error(chalk14.red(`
   Error: ${error instanceof Error ? error.message : error}
 `));
     process.exit(1);
@@ -5031,26 +6344,41 @@ program.addCommand(createDoctorCommand());
 program.addCommand(createInitCommand());
 program.addCommand(createMigrateCommand());
 program.addCommand(createCompareServicesCommand());
-program.command("serve").description("Start the Agent Health server (same as default action)").option("-p, --port <number>", "Server port", "4001").option("--no-browser", "Do not open browser automatically").action(async (options) => {
-  console.log(chalk10.cyan.bold(`
+program.addCommand(createRemoteCommand());
+program.addCommand(createConfigureCommand());
+program.addCommand(createKillCommand());
+program.addCommand(createSetupTelemetryCommand());
+program.command("serve").description("Start the Agent Health server (same as default action)").option("-p, --port <number>", "Server port", "4001").option("--no-browser", "Do not open browser automatically").option("--headless", "Run API server only (no frontend, no browser)").option("--api-key <key>", "Require API key for coding-agents endpoints").action(async (options) => {
+  console.log(chalk14.cyan.bold(`
   Agent Health v${version} - AI Agent Evaluation Framework
 `));
   const port = parseInt(options.port, 10);
-  const spinner = ora5("Starting server...").start();
+  const headless = options.headless || false;
+  const spinner = ora5(headless ? "Starting headless API server..." : "Starting server...").start();
   try {
-    await startServer({ port });
-    spinner.succeed("Server started");
-    const url = `http://localhost:${port}`;
-    console.log(chalk10.green(`  Server running at ${chalk10.bold(url)}
+    const actualPort = await startServer({ port, headless, apiKey: options.apiKey });
+    spinner.succeed(headless ? "Headless API server started" : "Server started");
+    if (actualPort !== port) {
+      console.log(chalk14.yellow(`
+  Port ${port} was in use, started on port ${actualPort} instead`));
+    }
+    const url = `http://localhost:${actualPort}`;
+    if (headless) {
+      console.log(chalk14.green(`  API server running on http://0.0.0.0:${actualPort}`));
+      if (options.apiKey) console.log(chalk14.gray("  API key authentication enabled"));
+      console.log(chalk14.gray("  Mode: headless (API only, no frontend)\n"));
+    } else {
+      console.log(chalk14.green(`  Server running at ${chalk14.bold(url)}
 `));
-    if (options.browser !== false) {
-      console.log(chalk10.gray("  Opening browser..."));
-      await open(url);
+      if (options.browser !== false) {
+        console.log(chalk14.gray("  Opening browser..."));
+        await open(url);
+      }
     }
-    console.log(chalk10.gray("  Press Ctrl+C to stop\n"));
+    console.log(chalk14.gray("  Press Ctrl+C to stop\n"));
   } catch (error) {
     spinner.fail("Failed to start server");
-    console.error(chalk10.red(`
+    console.error(chalk14.red(`
   Error: ${error instanceof Error ? error.message : error}
 `));
     process.exit(1);
@@ -5059,15 +6387,15 @@ program.command("serve").description("Start the Agent Health server (same as def
 program.on("command:*", (operands) => {
   const unknownCommand = operands[0];
   const availableCommands = program.commands.map((cmd) => cmd.name());
-  console.error(chalk10.red(`
+  console.error(chalk14.red(`
   Error: Unknown command '${unknownCommand}'`));
   console.log("");
-  console.log(chalk10.cyan("  Available commands:"));
+  console.log(chalk14.cyan("  Available commands:"));
   for (const cmd of availableCommands) {
-    console.log(chalk10.gray(`    - ${cmd}`));
+    console.log(chalk14.gray(`    - ${cmd}`));
   }
   console.log("");
-  console.log(chalk10.gray(`  Run ${chalk10.cyan("agent-health --help")} for usage information.
+  console.log(chalk14.gray(`  Run ${chalk14.cyan("agent-health --help")} for usage information.
 `));
   process.exitCode = 1;
 });