@cephalization/phoenix-insight 1.0.3 → 1.1.0

package/README.md

@@ -6,6 +6,25 @@ Phoenix Insight brings AI-powered analysis to your [Phoenix](https://github.com/
 
 This filesystem-native approach provides transparency that traditional APIs can't match. Every query the agent runs is visible and reproducible. You can inspect the exact files it reads, copy its commands, and run them yourself. The data is just files, and the analysis is just bash, making AI-driven observability debuggable, auditable, and extensible with any tool in your Unix toolkit.
 
+## Requirements
+
+- **Node.js v22 or newer** - Required for the CLI to run
+- **Anthropic API key** - Required for the AI agent
+
+Set your Anthropic API key before running:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-api03-...
+```
+
+Or add it to your shell profile for persistence:
+
+```bash
+echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc  # or ~/.bashrc
+```
+
+You can get an API key from [console.anthropic.com](https://console.anthropic.com/).
+
 ## Installation
 
 ```bash

package/dist/cli.js

@@ -2709,6 +2709,7 @@ Make sure to build the UI package first: pnpm --filter @cephalization/phoenix-in
     );
   }
   return new Promise((resolve2, reject) => {
+    const activeConnections = /* @__PURE__ */ new Set();
     const httpServer = createServer((req, res) => {
       const urlPath = req.url ?? "/";
       let filePath = sanitizePath(urlPath, distPath);
@@ -2760,6 +2761,12 @@ Make sure to build the UI package first: pnpm --filter @cephalization/phoenix-in
         res.end("Internal Server Error");
       });
     });
+    httpServer.on("connection", (socket) => {
+      activeConnections.add(socket);
+      socket.on("close", () => {
+        activeConnections.delete(socket);
+      });
+    });
     httpServer.on("error", (err) => {
       reject(err);
     });
@@ -2781,6 +2788,12 @@ Make sure to build the UI package first: pnpm --filter @cephalization/phoenix-in
               }
             });
           });
+        },
+        forceClose() {
+          for (const socket of activeConnections) {
+            socket.destroy();
+          }
+          activeConnections.clear();
         }
       });
     });
@@ -2955,6 +2968,19 @@ var PhoenixWebSocketServer = class {
       });
     });
   }
+  /**
+   * Force terminate all WebSocket connections immediately.
+   * Use this when graceful close doesn't complete in time.
+   */
+  forceClose() {
+    if (!this.wss) {
+      return;
+    }
+    for (const client of this.clients) {
+      client.terminate();
+    }
+    this.clients.clear();
+  }
 };
 function createWebSocketServer(httpServer, options) {
   const server = new PhoenixWebSocketServer(options);
@@ -3317,6 +3343,26 @@ function formatBashCommand(command) {
     return firstLine.substring(0, 80) + (firstLine.length > 80 ? "..." : "");
   }
 }
+function ensureAnthropicApiKey() {
+  if (!process.env.ANTHROPIC_API_KEY) {
+    console.error(
+      "\n\u274C Error: Missing ANTHROPIC_API_KEY environment variable\n"
+    );
+    console.error("The Anthropic API key is required to run the AI agent.\n");
+    console.error("To fix this, set the environment variable:\n");
+    console.error("  export ANTHROPIC_API_KEY=sk-ant-api03-...\n");
+    console.error(
+      "Or add it to your shell profile (~/.zshrc, ~/.bashrc, etc.):\n"
+    );
+    console.error(
+      "  echo 'export ANTHROPIC_API_KEY=sk-ant-api03-...' >> ~/.zshrc\n"
+    );
+    console.error(
+      "You can get an API key from: https://console.anthropic.com/\n"
+    );
+    process.exit(1);
+  }
+}
 function handleError(error, context) {
   console.error(`
 \u274C Error ${context}:`);
@@ -3401,16 +3447,17 @@ Configuration:
   Set PHOENIX_INSIGHT_CONFIG env var to override the default config location.
 
 Examples:
-  $ phoenix-insight                                               # Start interactive mode
-  $ phoenix-insight "What are the slowest traces?"                # Single query (sandbox mode)
-  $ phoenix-insight --interactive                                  # Explicitly start interactive mode
-  $ phoenix-insight --local "Show me error patterns"              # Local mode with persistence
-  $ phoenix-insight --local --stream "Analyze recent experiments"  # Local mode with streaming
-  $ phoenix-insight --config ./my-config.json "Analyze traces"    # Use custom config file
-  $ phoenix-insight ui                                            # Start web UI on localhost:6007
-  $ phoenix-insight ui --port 8080                                # Start web UI on custom port
-  $ phoenix-insight ui --no-open                                  # Start web UI without opening browser
-  $ phoenix-insight help                                          # Show this help message
+  $ phoenix-insight                                                            # Start interactive mode
+  $ phoenix-insight "What are the slowest traces?"                             # Single query (sandbox mode)
+  $ phoenix-insight --interactive                                              # Explicitly start interactive mode
+  $ phoenix-insight --local "Show me error patterns"                           # Local mode with persistence
+  $ phoenix-insight --local --stream "Analyze recent experiments"              # Local mode with streaming
+  $ phoenix-insight --config ./my-config.json "Analyze traces"                 # Use custom config file
+  $ phoenix-insight ui                                                         # Start web UI on localhost:6007
+  $ phoenix-insight ui --port 8080                                             # Start web UI on custom port
+  $ phoenix-insight ui --no-open                                               # Start web UI without opening browser
+  $ opencode run "Analyze my spans" -f $(pxi snapshot latest)/_context.md      # Analyze phoenix data with OpenCode agent
+  $ phoenix-insight help                                                       # Show this help message
 `
 ).hook("preAction", async (thisCommand) => {
   const opts = thisCommand.opts();
@@ -3560,6 +3607,7 @@ program.argument("[query]", "Query to run against Phoenix data").option(
     await runInteractiveMode();
     return;
   }
+  ensureAnthropicApiKey();
   if (config.trace) {
     initializeObservability({
       enabled: true,
@@ -3682,6 +3730,7 @@ function openBrowser(url) {
   });
 }
 async function runUIServer(options) {
+  ensureAnthropicApiKey();
   const config = getConfig();
   const port = options.port ?? 6007;
   const shouldOpen = options.open !== false;
@@ -3766,21 +3815,30 @@ async function runUIServer(options) {
       openBrowser(url);
     }
     let isShuttingDown = false;
+    const SHUTDOWN_TIMEOUT_MS = 3e3;
     const shutdown = async (signal) => {
       if (isShuttingDown) return;
       isShuttingDown = true;
       console.log(`
 
 \u{1F4E5} Received ${signal}, shutting down gracefully...`);
+      const forceExitTimeout = setTimeout(() => {
+        console.log("\u23F1\uFE0F  Shutdown timeout reached, forcing exit...");
+        wsServer.forceClose();
+        uiServer.forceClose();
+        process.exit(0);
+      }, SHUTDOWN_TIMEOUT_MS);
       try {
         await wsServer.close();
         await uiServer.close();
         await sessionManager.cleanup();
         await mode.cleanup();
         await shutdownObservability();
+        clearTimeout(forceExitTimeout);
         console.log("\u{1F44B} Server stopped. Goodbye!");
         process.exit(0);
       } catch (error) {
+        clearTimeout(forceExitTimeout);
         console.error("Error during shutdown:", error);
         process.exit(1);
       }
@@ -3794,6 +3852,7 @@ async function runUIServer(options) {
   }
 }
 async function runInteractiveMode() {
+  ensureAnthropicApiKey();
   const config = getConfig();
   console.log("\u{1F680} Phoenix Insight Interactive Mode");
   console.log(