@cephalization/phoenix-insight 0.1.0

package/dist/modes/local.js

@@ -0,0 +1,134 @@
+import { exec as execCallback } from "node:child_process";
+import { promisify } from "node:util";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { tool } from "ai";
+import { z } from "zod";
+const execAsync = promisify(execCallback);
+/**
+ * Local execution mode using real bash and persistent filesystem
+ * - Real bash execution via child_process
+ * - Persistent storage in ~/.phoenix-insight/
+ * - Full system access
+ */
+export class LocalMode {
+    workDir;
+    toolCreated = false;
+    bashToolPromise = null;
+    constructor() {
+        // Create a timestamped directory for this snapshot
+        // Add a small random component to ensure uniqueness even if created at the same millisecond
+        const timestamp = Date.now().toString() + "-" + Math.random().toString(36).substring(7);
+        this.workDir = path.join(os.homedir(), ".phoenix-insight", "snapshots", timestamp, "phoenix");
+    }
+    /**
+     * Initialize the working directory
+     */
+    async init() {
+        try {
+            // Create the directory structure if it doesn't exist
+            await fs.mkdir(this.workDir, { recursive: true });
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize local mode directory at ${this.workDir}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async writeFile(filePath, content) {
+        await this.init();
+        // Ensure the path is relative to phoenix root
+        const cleanPath = filePath.startsWith("/phoenix")
+            ? filePath.substring(8) // Remove /phoenix prefix
+            : filePath.startsWith("/")
+                ? filePath.substring(1) // Remove leading slash
+                : filePath;
+        const fullPath = path.join(this.workDir, cleanPath);
+        // Create parent directories if they don't exist
+        const dirname = path.dirname(fullPath);
+        await fs.mkdir(dirname, { recursive: true });
+        // Write the file
+        await fs.writeFile(fullPath, content, "utf-8");
+    }
+    async exec(command) {
+        await this.init();
+        try {
+            // Execute the command in the phoenix directory with a timeout
+            const { stdout, stderr } = await execAsync(command, {
+                cwd: this.workDir,
+                shell: "/bin/bash",
+                encoding: "utf-8",
+                timeout: 60000, // 60 second timeout for bash commands
+            });
+            return {
+                stdout: stdout || "",
+                stderr: stderr || "",
+                exitCode: 0,
+            };
+        }
+        catch (error) {
+            // Handle command execution errors
+            if (error.code !== undefined) {
+                return {
+                    stdout: error.stdout || "",
+                    stderr: error.stderr || error.message || "Command failed",
+                    exitCode: error.code || 1,
+                };
+            }
+            // Handle other errors
+            return {
+                stdout: "",
+                stderr: error.message || "Unknown error",
+                exitCode: 1,
+            };
+        }
+    }
+    async getBashTool() {
+        // Only create the tool once and cache it
+        if (!this.bashToolPromise) {
+            this.bashToolPromise = this.createBashTool();
+        }
+        return this.bashToolPromise;
+    }
+    async createBashTool() {
+        // We can't use bash-tool directly for local mode since it's designed for just-bash
+        // Instead, we'll create a tool using the AI SDK's tool function
+        // This ensures compatibility with the AI SDK
+        // Return a bash tool that executes real bash commands
+        return tool({
+            description: "Execute bash commands in the local filesystem",
+            inputSchema: z.object({
+                command: z.string().describe("The bash command to execute"),
+            }),
+            execute: async ({ command }) => {
+                const result = await this.exec(command);
+                // Return result in a format similar to bash-tool
+                if (result.exitCode !== 0) {
+                    // Include error details in the response
+                    return {
+                        success: false,
+                        stdout: result.stdout,
+                        stderr: result.stderr,
+                        exitCode: result.exitCode,
+                        error: `Command failed with exit code ${result.exitCode}`,
+                    };
+                }
+                return {
+                    success: true,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    exitCode: result.exitCode,
+                };
+            },
+        });
+    }
+    async cleanup() {
+        // Optional: Clean up old snapshots
+        // For now, we'll keep all snapshots for user reference
+        // Users can manually clean ~/.phoenix-insight/ if needed
+        // We could implement logic to:
+        // 1. Keep only the last N snapshots
+        // 2. Delete snapshots older than X days
+        // 3. Provide a separate cleanup command
+        // For this implementation, we do nothing
+    }
+}

package/dist/modes/sandbox.js

@@ -0,0 +1,121 @@
+import { tool } from "ai";
+import { z } from "zod";
+/**
+ * Sandbox execution mode using just-bash for isolated execution
+ * - In-memory filesystem
+ * - Simulated bash commands
+ * - No disk or network access
+ */
+export class SandboxMode {
+    bash; // Will be typed as Bash from just-bash
+    initialized = false;
+    bashToolPromise = null;
+    constructor() {
+        // We'll initialize in the init method since we need async imports
+    }
+    async init() {
+        if (this.initialized)
+            return;
+        try {
+            // Dynamic imports for ESM modules
+            const { Bash } = await import("just-bash");
+            // Initialize just-bash with /phoenix as the working directory
+            this.bash = new Bash({ cwd: "/phoenix" });
+            this.initialized = true;
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize sandbox mode: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async writeFile(path, content) {
+        await this.init();
+        try {
+            // Ensure the path starts with /phoenix
+            const fullPath = path.startsWith("/phoenix")
+                ? path
+                : `/phoenix${path.startsWith("/") ? "" : "/"}${path}`;
+            // Create parent directories if they don't exist
+            const dirname = fullPath.substring(0, fullPath.lastIndexOf("/"));
+            if (dirname) {
+                await this.bash.exec(`mkdir -p ${dirname}`);
+            }
+            // Write the file using just-bash's filesystem
+            // We'll use the InMemoryFs directly for better performance
+            this.bash.fs.writeFileSync(fullPath, content);
+        }
+        catch (error) {
+            throw new Error(`Failed to write file ${path}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    async exec(command) {
+        await this.init();
+        try {
+            const result = await this.bash.exec(command);
+            // just-bash returns a different structure, so we need to normalize it
+            return {
+                stdout: result.stdout || "",
+                stderr: result.stderr || "",
+                exitCode: result.exitCode || 0,
+            };
+        }
+        catch (error) {
+            // If the command fails, just-bash throws an error
+            // Extract what we can from the error
+            if (error && typeof error === "object" && "exitCode" in error) {
+                return {
+                    stdout: error.stdout || "",
+                    stderr: error.stderr || error.toString(),
+                    exitCode: error.exitCode || 1,
+                };
+            }
+            // Fallback for unexpected errors
+            return {
+                stdout: "",
+                stderr: error?.toString() || "Unknown error",
+                exitCode: 1,
+            };
+        }
+    }
+    async getBashTool() {
+        // Only create the tool once and cache it
+        if (!this.bashToolPromise) {
+            this.bashToolPromise = this.createBashTool();
+        }
+        return this.bashToolPromise;
+    }
+    async createBashTool() {
+        await this.init();
+        // Create a bash tool compatible with the AI SDK
+        // Similar to local mode, we'll create it directly using the tool function
+        return tool({
+            description: "Execute bash commands in the sandbox filesystem",
+            inputSchema: z.object({
+                command: z.string().describe("The bash command to execute"),
+            }),
+            execute: async ({ command }) => {
+                const result = await this.exec(command);
+                // Return result in a format similar to bash-tool
+                if (result.exitCode !== 0) {
+                    // Include error details in the response
+                    return {
+                        success: false,
+                        stdout: result.stdout,
+                        stderr: result.stderr,
+                        exitCode: result.exitCode,
+                        error: `Command failed with exit code ${result.exitCode}`,
+                    };
+                }
+                return {
+                    success: true,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    exitCode: result.exitCode,
+                };
+            },
+        });
+    }
+    async cleanup() {
+        // No-op for in-memory mode - garbage collection will handle cleanup
+        // We could optionally clear the filesystem here if needed
+    }
+}

package/dist/modes/types.js

@@ -0,0 +1 @@
+export {};

package/dist/observability/index.js

@@ -0,0 +1,65 @@
+/**
+ * Phoenix Insight observability configuration
+ */
+import { register } from "@arizeai/phoenix-otel";
+import { DiagLogLevel } from "@opentelemetry/api";
+/**
+ * Global tracer provider instance
+ */
+let tracerProvider = null;
+/**
+ * Check if observability is enabled
+ */
+export function isObservabilityEnabled() {
+    return tracerProvider !== null;
+}
+/**
+ * Initialize observability for the Phoenix Insight agent
+ */
+export function initializeObservability(options) {
+    if (!options.enabled) {
+        return;
+    }
+    // If already initialized, skip
+    if (tracerProvider) {
+        return;
+    }
+    try {
+        // Configure the tracer provider
+        tracerProvider = register({
+            projectName: options.projectName || "phoenix-insight",
+            url: options.baseUrl,
+            apiKey: options.apiKey,
+            batch: true,
+            global: true,
+            diagLogLevel: options.debug ? DiagLogLevel.DEBUG : undefined,
+        });
+        if (options.debug) {
+            console.error("🔭 Observability enabled - traces will be sent to Phoenix");
+        }
+    }
+    catch (error) {
+        console.error("⚠️  Failed to initialize observability:", error);
+        // Don't throw - observability should not break the main functionality
+    }
+}
+/**
+ * Shutdown observability and cleanup resources
+ */
+export async function shutdownObservability() {
+    if (tracerProvider) {
+        try {
+            await tracerProvider.shutdown();
+            tracerProvider = null;
+        }
+        catch (error) {
+            console.error("⚠️  Error shutting down observability:", error);
+        }
+    }
+}
+/**
+ * Get the current tracer provider
+ */
+export function getTracerProvider() {
+    return tracerProvider;
+}

package/dist/progress.js

@@ -0,0 +1,209 @@
+/**
+ * Progress indicators for Phoenix Insight CLI
+ */
+import ora, {} from "ora";
+/**
+ * Progress indicator for snapshot operations
+ */
+export class SnapshotProgress {
+    spinner = null;
+    enabled;
+    currentPhase = null;
+    totalSteps = 6;
+    currentStep = 0;
+    constructor(enabled = true) {
+        this.enabled = enabled;
+    }
+    /**
+     * Start the progress indicator
+     */
+    start(message = "Creating Phoenix data snapshot") {
+        if (!this.enabled)
+            return;
+        this.currentStep = 0;
+        this.spinner = ora({
+            text: message,
+            spinner: "dots",
+            color: "blue",
+        }).start();
+    }
+    /**
+     * Update progress with a new phase
+     */
+    update(phase, detail) {
+        if (!this.enabled || !this.spinner)
+            return;
+        this.currentStep++;
+        this.currentPhase = phase;
+        const progress = Math.round((this.currentStep / this.totalSteps) * 100);
+        const progressBar = this.createProgressBar(progress);
+        const message = detail
+            ? `${progressBar} ${phase}: ${detail}`
+            : `${progressBar} ${phase}`;
+        this.spinner.text = message;
+    }
+    /**
+     * Complete a phase successfully
+     */
+    succeed(message) {
+        if (!this.enabled || !this.spinner)
+            return;
+        const finalMessage = message || `✓ ${this.currentPhase || "Snapshot"} complete`;
+        this.spinner.succeed(finalMessage);
+        this.spinner = null;
+    }
+    /**
+     * Fail with an error
+     */
+    fail(message) {
+        if (!this.enabled || !this.spinner)
+            return;
+        const finalMessage = message || `✗ ${this.currentPhase || "Snapshot"} failed`;
+        this.spinner.fail(finalMessage);
+        this.spinner = null;
+    }
+    /**
+     * Stop without success/fail status
+     */
+    stop() {
+        if (!this.enabled || !this.spinner)
+            return;
+        this.spinner.stop();
+        this.spinner = null;
+    }
+    /**
+     * Create a progress bar string
+     */
+    createProgressBar(percentage) {
+        const width = 20;
+        const filled = Math.round((percentage / 100) * width);
+        const empty = width - filled;
+        const bar = "█".repeat(filled) + "░".repeat(empty);
+        return `[${bar}] ${percentage}%`;
+    }
+}
+/**
+ * Progress indicator for agent thinking
+ */
+export class AgentProgress {
+    spinner = null;
+    enabled;
+    stepCount = 0;
+    currentTool = null;
+    constructor(enabled = true) {
+        this.enabled = enabled;
+    }
+    /**
+     * Start thinking indicator
+     */
+    startThinking() {
+        if (!this.enabled)
+            return;
+        this.stepCount = 0;
+        this.currentTool = null;
+        this.spinner = ora({
+            text: "🤔 Analyzing...",
+            spinner: "dots",
+            color: "cyan",
+        }).start();
+    }
+    /**
+     * Update with current tool usage
+     */
+    updateTool(toolName, detail) {
+        if (!this.enabled || !this.spinner)
+            return;
+        this.stepCount++;
+        this.currentTool = toolName;
+        // Map tool names to more user-friendly descriptions
+        const friendlyNames = {
+            bash: "Running command",
+            px_fetch_more_spans: "Fetching additional spans",
+            px_fetch_more_trace: "Fetching trace details",
+        };
+        const displayName = friendlyNames[toolName] || toolName;
+        const message = detail
+            ? `🔧 ${displayName}: ${detail}`
+            : `🔧 ${displayName} (step ${this.stepCount})`;
+        this.spinner.text = message;
+    }
+    /**
+     * Update with tool result
+     */
+    updateToolResult(toolName, success = true) {
+        if (!this.enabled || !this.spinner)
+            return;
+        const icon = success ? "✓" : "✗";
+        const status = success ? "completed" : "failed";
+        // More informative messages for each tool
+        const toolMessages = {
+            bash: "Command executed",
+            px_fetch_more_spans: "Additional spans fetched",
+            px_fetch_more_trace: "Trace details fetched",
+        };
+        const baseMessage = toolMessages[toolName] || `Tool ${toolName}`;
+        const message = `${icon} ${baseMessage} ${status}`;
+        // Brief flash of the result before moving on
+        this.spinner.text = message;
+    }
+    /**
+     * Show progress for a specific action
+     */
+    updateAction(action) {
+        if (!this.enabled || !this.spinner)
+            return;
+        this.spinner.text = `🔍 ${action}...`;
+    }
+    /**
+     * Stop the thinking indicator
+     */
+    stop() {
+        if (!this.enabled || !this.spinner)
+            return;
+        this.spinner.stop();
+        this.spinner = null;
+    }
+    /**
+     * Complete with a success message
+     */
+    succeed(message = "✨ Analysis complete") {
+        if (!this.enabled || !this.spinner)
+            return;
+        this.spinner.succeed(message);
+        this.spinner = null;
+    }
+}
+/**
+ * Simple progress logger for when spinners aren't appropriate
+ */
+export class SimpleProgress {
+    enabled;
+    constructor(enabled = true) {
+        this.enabled = enabled;
+    }
+    log(message) {
+        if (!this.enabled)
+            return;
+        console.log(`[Phoenix Insight] ${message}`);
+    }
+    info(message) {
+        if (!this.enabled)
+            return;
+        console.log(`ℹ️  ${message}`);
+    }
+    success(message) {
+        if (!this.enabled)
+            return;
+        console.log(`✅ ${message}`);
+    }
+    warning(message) {
+        if (!this.enabled)
+            return;
+        console.log(`⚠️  ${message}`);
+    }
+    error(message) {
+        if (!this.enabled)
+            return;
+        console.log(`❌ ${message}`);
+    }
+}

package/dist/prompts/index.js

@@ -0,0 +1 @@
+export { INSIGHT_SYSTEM_PROMPT } from "./system.js";

package/dist/prompts/system.js

@@ -0,0 +1,30 @@
+/**
+ * System prompt for the Phoenix Insight AI agent
+ * This prompt teaches the agent about the filesystem layout and available commands
+ */
+export const INSIGHT_SYSTEM_PROMPT = `You are an expert at analyzing Phoenix observability data.
+
+**START by reading /phoenix/_context.md** - it contains a summary of what's available.
+
+You have access to a bash shell with Phoenix data organized as files:
+
+/phoenix/
+  _context.md                    - READ THIS FIRST: summary of available data
+  /projects/{name}/spans/        - Span data (JSONL format, may be sampled)
+  /datasets/                     - Datasets and examples
+  /experiments/                  - Experiment runs and results
+  /prompts/                      - Prompt templates and versions
+
+Use commands like:
+- cat, head, tail: Read file contents  
+- grep: Search for patterns
+- jq: Query and transform JSON/JSONL
+- ls, find: Navigate and discover data
+- sort, uniq, wc: Aggregate and count
+- awk: Complex text processing
+
+If you need MORE data than what's in the snapshot:
+- px-fetch-more spans --project <name> --limit 500
+- px-fetch-more trace --trace-id <id>
+
+This is a READ-ONLY snapshot. Start with _context.md, then explore to answer the question.`;

package/dist/snapshot/client.js

@@ -0,0 +1,74 @@
+import { createClient } from "@arizeai/phoenix-client";
+export class PhoenixClientError extends Error {
+    code;
+    originalError;
+    constructor(message, code, originalError) {
+        super(message);
+        this.name = "PhoenixClientError";
+        this.code = code;
+        this.originalError = originalError;
+    }
+}
+/**
+ * Creates a wrapped Phoenix client with error handling
+ */
+export function createPhoenixClient(config = {}) {
+    const headers = {};
+    if (config.apiKey) {
+        headers["api_key"] = config.apiKey;
+    }
+    const clientOptions = {
+        options: {
+            baseUrl: config.baseURL,
+            headers: Object.keys(headers).length > 0 ? headers : undefined,
+        },
+    };
+    return createClient(clientOptions);
+}
+/**
+ * Wraps an async operation with standardized error handling
+ */
+export async function withErrorHandling(operation, context) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        // Network errors
+        if (error instanceof TypeError && error.message.includes("fetch")) {
+            throw new PhoenixClientError(`Network error during ${context}: Unable to connect to Phoenix server`, "NETWORK_ERROR", error);
+        }
+        // HTTP errors from the middleware
+        if (error instanceof Error && error.message.includes(": ")) {
+            const parts = error.message.split(": ", 2);
+            if (parts.length === 2 && parts[1]) {
+                const [url, statusInfo] = parts;
+                const statusParts = statusInfo.split(" ");
+                const statusCode = statusParts[0];
+                const statusText = statusParts.slice(1).join(" ");
+                if (statusCode === "401" || statusCode === "403") {
+                    throw new PhoenixClientError(`Authentication error during ${context}: ${statusText}`, "AUTH_ERROR", error);
+                }
+                if (statusCode && statusCode.startsWith("4")) {
+                    throw new PhoenixClientError(`Client error during ${context}: ${statusCode} ${statusText}`, "INVALID_RESPONSE", error);
+                }
+                if (statusCode && statusCode.startsWith("5")) {
+                    throw new PhoenixClientError(`Server error during ${context}: ${statusCode} ${statusText}`, "NETWORK_ERROR", error);
+                }
+            }
+        }
+        // Unknown errors
+        throw new PhoenixClientError(`Unexpected error during ${context}: ${error instanceof Error ? error.message : String(error)}`, "UNKNOWN_ERROR", error);
+    }
+}
+/**
+ * Helper to safely extract data from API responses
+ */
+export function extractData(response) {
+    if (response.error) {
+        throw response.error;
+    }
+    if (!response.data) {
+        throw new PhoenixClientError("Invalid API response: missing data", "INVALID_RESPONSE");
+    }
+    return response.data;
+}