@cephalization/phoenix-insight 0.3.0 → 1.0.0

package/README.md

@@ -148,10 +148,33 @@ phoenix-insight --refresh "show me the latest errors"
 phoenix-insight --no-stream "generate report" > report.txt
 ```
 
+### Web UI
+
+Start the web-based UI for a visual chat interface and structured report display:
+
+```bash
+# Start web UI (opens browser automatically)
+phoenix-insight ui
+
+# Start on a custom port
+phoenix-insight ui --port 8080
+
+# Start without opening browser
+phoenix-insight ui --no-open
+```
+
+The web UI provides:
+
+- **Split-pane interface**: Chat panel on the left, report display on the right
+- **Real-time streaming**: See agent responses and tool usage as they happen
+- **Structured reports**: AI-generated reports with tables, metrics, and formatted content
+- **Session history**: Persist and browse previous conversations and reports
+- **WebSocket connection**: Real-time bidirectional communication with the agent
+
 ### Observability
 
 ```bash
-# Enable tracing of agent operations to Phoenix
+# Enable tracing of agent operations to Phoenix (enabled by default)
 phoenix-insight --trace "analyze performance"
 ```
 
@@ -398,6 +421,134 @@ phoenix-insight prune [options]
 | ----------- | ---------------------------------------- | ------- | ------------------------------- |
 | `--dry-run` | Preview what would be deleted without actually deleting | `false` | `phoenix-insight prune --dry-run` |
 
+### UI Command
+
+Starts a web-based UI for visual interaction with the Phoenix Insight agent.
+
+```bash
+phoenix-insight ui [options]
+```
+
+| Option          | Description                                      | Default | Example                          |
+| --------------- | ------------------------------------------------ | ------- | -------------------------------- |
+| `--port <n>`    | Port to run the UI server on                     | `6007`  | `phoenix-insight ui --port 8080` |
+| `--no-open`     | Do not automatically open browser                | `false` | `phoenix-insight ui --no-open`   |
+
+The UI server provides:
+
+- **HTTP server**: Serves the web UI on `http://localhost:6007` (configurable port)
+- **WebSocket**: Real-time bidirectional communication at `/ws`
+- **Session management**: Multiple concurrent sessions with conversation history
+- **Report generation**: Agent can generate structured reports displayed in the UI
+
+**Usage notes:**
+
+- The server binds to localhost only (127.0.0.1) for security
+- Press Ctrl+C to stop the server gracefully
+- Configuration is loaded from the standard config file and environment variables
+
+#### Web UI Features
+
+The web UI provides a rich interface for interacting with Phoenix Insight:
+
+**Split-pane Layout:**
+- Left panel: Chat interface with message history
+- Right panel: Structured report display
+- Resizable panels with drag handle
+- Responsive design: stacked tabs on mobile devices
+
+**Chat Interface:**
+- Real-time streaming of agent responses
+- Markdown rendering optimized for streaming content
+- Session history with dropdown to switch between conversations
+- Create, switch, and delete sessions
+- Visual indicators for agent tool usage (tool_call/tool_result events)
+
+**Report Panel:**
+- Structured reports generated by the agent using `generate_report` tool
+- Components: Cards, Tables, Metrics, Alerts, Badges, Lists, Code blocks, and more
+- Download reports as Markdown
+- Browse and restore previous reports from history
+
+**Connection Management:**
+- Automatic reconnection with exponential backoff (via partysocket)
+- Visual connection status indicator (green/yellow/red)
+- Toast notifications for connection state changes
+- Message buffering during temporary disconnections
+
+**Data Persistence:**
+- Sessions and reports stored in browser's IndexedDB
+- Survives page refreshes and browser restarts
+- Export reports as Markdown files
+
+#### WebSocket Protocol
+
+The UI communicates with the CLI server over WebSocket at the `/ws` endpoint. All messages are JSON-encoded.
+
+**Client Messages (UI to Server):**
+
+```typescript
+// Send a query to the agent
+{ type: "query", payload: { content: string, sessionId?: string } }
+
+// Cancel the current query
+{ type: "cancel", payload: { sessionId?: string } }
+```
+
+**Server Messages (Server to UI):**
+
+```typescript
+// Streaming text content from the agent
+{ type: "text", payload: { content: string, sessionId: string } }
+
+// Agent is calling a tool
+{ type: "tool_call", payload: { toolName: string, args: unknown, sessionId: string } }
+
+// Tool execution result
+{ type: "tool_result", payload: { toolName: string, result: unknown, sessionId: string } }
+
+// Agent generated a structured report
+{ type: "report", payload: { content: UITree, sessionId: string } }
+
+// Error occurred during processing
+{ type: "error", payload: { message: string, sessionId?: string } }
+
+// Agent finished processing the query
+{ type: "done", payload: { sessionId: string } }
+```
+
+**Report Content Structure (UITree):**
+
+The `report` message contains a `UITree` structure compatible with [json-render](https://github.com/vercel-labs/json-render):
+
+```typescript
+interface UITree {
+  root: string;  // Key of the root element
+  elements: Record<string, UIElement>;  // Flat map of all elements
+}
+
+interface UIElement {
+  key: string;
+  type: "Card" | "Text" | "Heading" | "List" | "Table" | "Metric" | "Badge" | "Alert" | "Separator" | "Code";
+  props: Record<string, unknown>;  // Component-specific props
+  children?: string[];  // Keys of child elements
+  parentKey?: string;
+}
+```
+
+**Example WebSocket Session:**
+
+```
+Client: {"type":"query","payload":{"content":"Show error patterns","sessionId":"session-1"}}
+Server: {"type":"text","payload":{"content":"I'll analyze","sessionId":"session-1"}}
+Server: {"type":"text","payload":{"content":" the error patterns...","sessionId":"session-1"}}
+Server: {"type":"tool_call","payload":{"toolName":"bash","args":{"command":"grep -c 'error' spans.jsonl"},"sessionId":"session-1"}}
+Server: {"type":"tool_result","payload":{"toolName":"bash","result":"42","sessionId":"session-1"}}
+Server: {"type":"text","payload":{"content":"Found 42 errors.","sessionId":"session-1"}}
+Server: {"type":"report","payload":{"content":{"root":"card-1","elements":{...}},"sessionId":"session-1"}}
+Server: {"type":"done","payload":{"sessionId":"session-1"}}
+```
+
 ### Help Command
 
 Displays help information and available options.
@@ -691,6 +842,49 @@ pnpm test test/modes/sandbox.test.ts
 pnpm typecheck
 ```
 
+#### UI Integration Testing
+
+The web UI has manual integration tests using [agent-browser](https://github.com/vercel-labs/agent-browser) for browser automation. These tests are NOT run in CI because they require a live Phoenix server with data.
+
+**Prerequisites:**
+
+1. Phoenix server running on `localhost:6006` with data
+2. Run from the monorepo root
+
+**Running UI tests:**
+
+```bash
+# From monorepo root - builds packages and runs UI integration tests
+pnpm test:ui
+```
+
+The test:ui script will:
+1. Build the UI package
+2. Build the CLI package (which bundles the UI)
+3. Expect a running Phoenix server at localhost:6006
+4. Expect the UI server to be running at localhost:6007 (start with `phoenix-insight ui`)
+5. Run browser automation tests that verify:
+   - Layout renders correctly (chat panel, report panel)
+   - Chat input is functional
+   - WebSocket connection works
+   - Session management works
+   - Report panel displays correctly
+
+**Manual testing workflow:**
+
+```bash
+# Terminal 1: Start Phoenix
+phoenix serve
+
+# Terminal 2: Start the UI server
+cd packages/cli && pnpm dev ui
+
+# Terminal 3: Run UI tests
+pnpm test:ui
+```
+
+**Note:** If tests skip with "Phoenix server not running" or "UI server not running", ensure both servers are accessible before running tests.
+
 ### Contributing & Releases
 
 Contributions are welcome! This project uses [changesets](https://github.com/changesets/changesets) for version management and automated releases.

package/dist/agent/index.js

@@ -4,9 +4,8 @@
 import { generateText, streamText, tool, stepCountIs, } from "ai";
 import { anthropic } from "@ai-sdk/anthropic";
 import { z } from "zod";
-import { INSIGHT_SYSTEM_PROMPT } from "../prompts/system.js";
+import { getInsightSystemPrompt } from "../prompts/system.js";
 import { fetchMoreSpans, fetchMoreTrace, } from "../commands/index.js";
-import { PhoenixClientError } from "../snapshot/client.js";
 /**
  * Phoenix Insight Agent
  */
@@ -15,11 +14,16 @@ export class PhoenixInsightAgent {
     client;
     maxSteps;
     tools = null;
+    additionalTools;
     model = anthropic("claude-sonnet-4-5");
+    systemPrompt;
     constructor(config) {
         this.mode = config.mode;
         this.client = config.client;
         this.maxSteps = config.maxSteps || 25;
+        this.additionalTools = config.additionalTools || {};
+        // Generate the system prompt with the snapshot root path from the mode
+        this.systemPrompt = getInsightSystemPrompt(this.mode.getSnapshotRoot());
     }
     /**
      * Initialize the agent tools
@@ -103,6 +107,7 @@ export class PhoenixInsightAgent {
             bash: bashTool,
             px_fetch_more_spans: pxFetchMoreSpans,
             px_fetch_more_trace: pxFetchMoreTrace,
+            ...this.additionalTools,
         };
         return this.tools;
     }
@@ -120,7 +125,7 @@ export class PhoenixInsightAgent {
         try {
             const result = await generateText({
                 model: this.model,
-                system: INSIGHT_SYSTEM_PROMPT,
+                system: this.systemPrompt,
                 prompt: userQuery,
                 tools,
                 stopWhen: stepCountIs(this.maxSteps),
@@ -162,7 +167,7 @@ export class PhoenixInsightAgent {
         try {
             const result = streamText({
                 model: this.model,
-                system: INSIGHT_SYSTEM_PROMPT,
+                system: this.systemPrompt,
                 prompt: userQuery,
                 tools,
                 stopWhen: stepCountIs(this.maxSteps),

package/dist/cli.js

@@ -4,6 +4,7 @@ import * as readline from "node:readline";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import * as os from "node:os";
+import { exec } from "node:child_process";
 import { createSandboxMode, createLocalMode } from "./modes/index.js";
 import { createInsightAgent, runOneShotQuery } from "./agent/index.js";
 import { createSnapshot, createIncrementalSnapshot, createPhoenixClient, PhoenixClientError, } from "./snapshot/index.js";
@@ -11,6 +12,9 @@ import { getLatestSnapshot, listSnapshots } from "./snapshot/utils.js";
 import { AgentProgress } from "./progress.js";
 import { initializeObservability, shutdownObservability, } from "./observability/index.js";
 import { initializeConfig, getConfig } from "./config/index.js";
+import { createUIServer } from "./server/ui.js";
+import { createWebSocketServer } from "./server/websocket.js";
+import { createSessionManager } from "./server/session.js";
 // Version will be read from package.json during build
 const VERSION = "0.0.1";
 const program = new Command();
@@ -164,6 +168,9 @@ Examples:
   $ 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
 `)
     .hook("preAction", async (thisCommand) => {
@@ -324,6 +331,15 @@ program
         process.exit(1);
     }
 });
+// UI Command - starts web-based UI server
+program
+    .command("ui")
+    .description("Start the web-based UI for interactive Phoenix analysis")
+    .option("--port <number>", "Port to run the UI server on", parseInt)
+    .option("--no-open", "Do not automatically open the browser")
+    .action(async (options) => {
+    await runUIServer(options);
+});
 program
     .argument("[query]", "Query to run against Phoenix data")
     .option("--sandbox", "Run in sandbox mode with in-memory filesystem (default)")
@@ -474,6 +490,162 @@ program
         await shutdownObservability();
     }
 });
+/**
+ * Open a URL in the default browser
+ */
+function openBrowser(url) {
+    const platform = process.platform;
+    let command;
+    if (platform === "darwin") {
+        command = `open "${url}"`;
+    }
+    else if (platform === "win32") {
+        command = `start "" "${url}"`;
+    }
+    else {
+        // Linux and others - try xdg-open, fallback to sensible-browser
+        command = `xdg-open "${url}" || sensible-browser "${url}"`;
+    }
+    exec(command, (error) => {
+        if (error && process.env.DEBUG) {
+            console.warn(`Could not open browser: ${error.message}`);
+        }
+    });
+}
+/**
+ * Run the UI server with WebSocket support for agent interaction
+ */
+async function runUIServer(options) {
+    const config = getConfig();
+    const port = options.port ?? 6007;
+    const shouldOpen = options.open !== false; // Default to opening browser
+    console.log("🚀 Starting Phoenix Insight UI...\n");
+    // Initialize observability if trace is enabled in config
+    if (config.trace) {
+        initializeObservability({
+            enabled: true,
+            baseUrl: config.baseUrl,
+            apiKey: config.apiKey,
+            projectName: "phoenix-insight-ui",
+            debug: !!process.env.DEBUG,
+        });
+    }
+    try {
+        // Determine the execution mode - UI always uses local mode for persistence
+        const mode = await createLocalMode();
+        // Create Phoenix client
+        const client = createPhoenixClient({
+            baseURL: config.baseUrl,
+            apiKey: config.apiKey,
+        });
+        // Create snapshot with config values
+        const snapshotOptions = {
+            baseURL: config.baseUrl,
+            apiKey: config.apiKey,
+            spansPerProject: config.limit,
+            showProgress: true,
+        };
+        // Always use incremental snapshot for UI to reuse existing data
+        await createIncrementalSnapshot(mode, snapshotOptions);
+        console.log("\n✅ Snapshot ready.\n");
+        // Create the UI HTTP server
+        const uiServer = await createUIServer({ port, host: "127.0.0.1" });
+        // Create the WebSocket server and attach to HTTP server
+        const sessionManager = createSessionManager({
+            mode,
+            client,
+            maxSteps: 25,
+        });
+        const wsServer = createWebSocketServer(uiServer.httpServer, {
+            path: "/ws",
+            onConnection: (ws) => {
+                if (process.env.DEBUG) {
+                    console.log("WebSocket client connected");
+                }
+            },
+            onDisconnection: async (ws, code, reason) => {
+                if (process.env.DEBUG) {
+                    console.log(`WebSocket client disconnected: ${code} ${reason}`);
+                }
+                // Clean up the session when client disconnects
+                await sessionManager.removeSession(ws);
+            },
+            onMessage: async (message, ws) => {
+                if (message.type === "query") {
+                    const { content, sessionId: clientSessionId } = message.payload;
+                    const sessionId = clientSessionId ?? `session-${Date.now()}`;
+                    // Get or create session for this client
+                    const session = sessionManager.getOrCreateSession(ws, sessionId, (msg) => wsServer.sendToClient(ws, msg));
+                    // Execute the query (this is async but we don't await - let it stream)
+                    session.executeQuery(content).catch((error) => {
+                        console.error("Error executing query:", error);
+                        wsServer.sendToClient(ws, {
+                            type: "error",
+                            payload: {
+                                message: error instanceof Error
+                                    ? error.message
+                                    : "An error occurred while executing the query",
+                                sessionId,
+                            },
+                        });
+                    });
+                }
+                else if (message.type === "cancel") {
+                    const session = sessionManager.getSessionForClient(ws);
+                    if (session) {
+                        session.cancel();
+                    }
+                }
+            },
+            onError: (error, ws) => {
+                console.error("WebSocket error:", error.message);
+            },
+        });
+        const url = `http://localhost:${uiServer.port}`;
+        console.log("🌐 Phoenix Insight UI is running!");
+        console.log(`   Local:   ${url}`);
+        console.log("\n💡 Press Ctrl+C to stop the server\n");
+        // Open browser if not disabled
+        if (shouldOpen) {
+            openBrowser(url);
+        }
+        // Handle graceful shutdown
+        let isShuttingDown = false;
+        const shutdown = async (signal) => {
+            if (isShuttingDown)
+                return;
+            isShuttingDown = true;
+            console.log(`\n\n📥 Received ${signal}, shutting down gracefully...`);
+            try {
+                // Close WebSocket connections first
+                await wsServer.close();
+                // Close the UI server
+                await uiServer.close();
+                // Clean up sessions
+                await sessionManager.cleanup();
+                // Clean up execution mode
+                await mode.cleanup();
+                // Shutdown observability if enabled
+                await shutdownObservability();
+                console.log("👋 Server stopped. Goodbye!");
+                process.exit(0);
+            }
+            catch (error) {
+                console.error("Error during shutdown:", error);
+                process.exit(1);
+            }
+        };
+        process.on("SIGINT", () => shutdown("SIGINT"));
+        process.on("SIGTERM", () => shutdown("SIGTERM"));
+        // Keep the process running
+        await new Promise(() => {
+            // This promise never resolves - server runs until SIGINT/SIGTERM
+        });
+    }
+    catch (error) {
+        handleError(error, "starting UI server");
+    }
+}
 async function runInteractiveMode() {
     const config = getConfig();
     console.log("🚀 Phoenix Insight Interactive Mode");

package/dist/commands/index.js

@@ -1,2 +1,3 @@
 export { fetchMoreSpans, } from "./px-fetch-more-spans.js";
 export { fetchMoreTrace, } from "./px-fetch-more-trace.js";
+export { createReportTool, validateReportContent, generateComponentDocs, } from "./report-tool.js";