@cephalization/phoenix-insight 0.1.0

package/src/config/loader.ts

@@ -0,0 +1,173 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import { configSchema, getDefaultConfig, type Config } from "./schema.js";
+
+/**
+ * Default config directory and file path
+ */
+const DEFAULT_CONFIG_DIR = path.join(os.homedir(), ".phoenix-insight");
+const DEFAULT_CONFIG_FILE = path.join(DEFAULT_CONFIG_DIR, "config.json");
+
+/**
+ * Module-level storage for CLI args passed from commander
+ * This is set externally before getConfigPath is called
+ */
+let cliConfigPath: string | undefined;
+
+/**
+ * Set the CLI config path (called from CLI parsing)
+ */
+export function setCliConfigPath(configPath: string | undefined): void {
+  cliConfigPath = configPath;
+}
+
+/**
+ * Get the config file path based on priority:
+ * 1. CLI argument (--config)
+ * 2. Environment variable (PHOENIX_INSIGHT_CONFIG)
+ * 3. Default path (~/.phoenix-insight/config.json)
+ *
+ * @returns The path to the config file and whether it's the default path
+ */
+export function getConfigPath(): { path: string; isDefault: boolean } {
+  // Priority 1: CLI argument
+  if (cliConfigPath) {
+    return { path: cliConfigPath, isDefault: false };
+  }
+
+  // Priority 2: Environment variable
+  const envConfigPath = process.env.PHOENIX_INSIGHT_CONFIG;
+  if (envConfigPath) {
+    return { path: envConfigPath, isDefault: false };
+  }
+
+  // Priority 3: Default path
+  return { path: DEFAULT_CONFIG_FILE, isDefault: true };
+}
+
+/**
+ * Load and parse a config file from disk
+ *
+ * @param configPath - Path to the config file
+ * @returns Parsed JSON object or null if file not found
+ * @throws Error if file exists but cannot be parsed as JSON
+ */
+export async function loadConfigFile(
+  configPath: string
+): Promise<Record<string, unknown> | null> {
+  try {
+    const content = await fs.readFile(configPath, "utf-8");
+    return JSON.parse(content) as Record<string, unknown>;
+  } catch (error) {
+    // File not found is expected - return null
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return null;
+    }
+
+    // JSON parse errors should be reported
+    if (error instanceof SyntaxError) {
+      console.warn(
+        `Warning: Config file at ${configPath} contains invalid JSON: ${error.message}`
+      );
+      return null;
+    }
+
+    // Other errors (permissions, etc.) - warn and return null
+    console.warn(
+      `Warning: Could not read config file at ${configPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return null;
+  }
+}
+
+/**
+ * Validate a raw config object against the schema
+ * Returns validated config or defaults if validation fails
+ *
+ * @param raw - Raw config object (or null/undefined)
+ * @returns Validated config with defaults applied
+ */
+export function validateConfig(
+  raw: Record<string, unknown> | null | undefined
+): Config {
+  // If no raw config, return defaults
+  if (!raw) {
+    return getDefaultConfig();
+  }
+
+  try {
+    // Parse with Zod schema - this applies defaults for missing fields
+    return configSchema.parse(raw);
+  } catch (error) {
+    // Log validation errors as warnings
+    if (error instanceof Error && "issues" in error) {
+      // Zod error with issues array
+      const zodError = error as {
+        issues: Array<{ path: string[]; message: string }>;
+      };
+      zodError.issues.forEach((issue) => {
+        console.warn(
+          `Warning: Config validation error at '${issue.path.join(".")}': ${issue.message}`
+        );
+      });
+    } else {
+      console.warn(
+        `Warning: Config validation failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+
+    // Return defaults on validation failure
+    return getDefaultConfig();
+  }
+}
+
+/**
+ * Create a default config file at the given path
+ * Only creates the file if it doesn't already exist
+ * Only triggers for the default path, not custom paths
+ *
+ * @param configPath - Path where to create the config file
+ * @param isDefault - Whether this is the default path (only create if true)
+ * @returns true if file was created, false otherwise
+ */
+export async function createDefaultConfig(
+  configPath: string,
+  isDefault: boolean
+): Promise<boolean> {
+  // Only create default config for the default path
+  if (!isDefault) {
+    return false;
+  }
+
+  try {
+    // Check if file already exists
+    await fs.access(configPath);
+    // File exists, don't overwrite
+    return false;
+  } catch {
+    // File doesn't exist, create it
+  }
+
+  try {
+    // Create directory if needed
+    const configDir = path.dirname(configPath);
+    await fs.mkdir(configDir, { recursive: true });
+
+    // Get default config and write it
+    const defaultConfig = getDefaultConfig();
+    const content = JSON.stringify(defaultConfig, null, 2);
+    await fs.writeFile(configPath, content, "utf-8");
+
+    // Log informational message to stderr
+    console.error(`Created default config at ${configPath}`);
+
+    return true;
+  } catch (error) {
+    // Log warning but don't fail - config will use defaults
+    console.warn(
+      `Warning: Could not create default config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`
+    );
+    return false;
+  }
+}

package/src/config/schema.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+
+/**
+ * Zod schema for Phoenix Insight CLI configuration
+ *
+ * Configuration values can be set via:
+ * 1. Config file (~/.phoenix-insight/config.json or custom path)
+ * 2. Environment variables (PHOENIX_BASE_URL, PHOENIX_API_KEY, etc.)
+ * 3. CLI arguments (--base-url, --api-key, etc.)
+ *
+ * Priority: config file < env vars < CLI args
+ */
+export const configSchema = z.object({
+  /**
+   * Phoenix server base URL
+   * @default "http://localhost:6006"
+   */
+  baseUrl: z.string().default("http://localhost:6006"),
+
+  /**
+   * Phoenix API key for authentication (optional)
+   */
+  apiKey: z.string().optional(),
+
+  /**
+   * Maximum number of spans to fetch per project
+   * @default 1000
+   */
+  limit: z.number().int().positive().default(1000),
+
+  /**
+   * Enable streaming responses from the agent
+   * @default true
+   */
+  stream: z.boolean().default(true),
+
+  /**
+   * Execution mode: "sandbox" for in-memory filesystem, "local" for real filesystem
+   * @default "sandbox"
+   */
+  mode: z.enum(["sandbox", "local"]).default("sandbox"),
+
+  /**
+   * Force refresh of snapshot data
+   * @default false
+   */
+  refresh: z.boolean().default(false),
+
+  /**
+   * Enable tracing of the agent to Phoenix
+   * @default false
+   */
+  trace: z.boolean().default(false),
+});
+
+/**
+ * Inferred TypeScript type from the config schema
+ */
+export type Config = z.infer<typeof configSchema>;
+
+/**
+ * Get default configuration values
+ */
+export function getDefaultConfig(): Config {
+  return configSchema.parse({});
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./modes/index.js";

package/src/modes/index.ts

@@ -0,0 +1,21 @@
+export * from "./types.js";
+export * from "./sandbox.js";
+export * from "./local.js";
+
+import { SandboxMode } from "./sandbox.js";
+import { LocalMode } from "./local.js";
+import type { ExecutionMode } from "./types.js";
+
+/**
+ * Creates a new sandbox execution mode
+ */
+export function createSandboxMode(): ExecutionMode {
+  return new SandboxMode();
+}
+
+/**
+ * Creates a new local execution mode
+ */
+export async function createLocalMode(): Promise<ExecutionMode> {
+  return new LocalMode();
+}

package/src/modes/local.ts

@@ -0,0 +1,163 @@
+import type { ExecutionMode } from "./types.js";
+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 implements ExecutionMode {
+  private workDir: string;
+  private toolCreated = false;
+  private bashToolPromise: Promise<any> | null = 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
+   */
+  private 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: string, content: string): Promise<void> {
+    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: string
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    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: any) {
+      // 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(): Promise<any> {
+    // Only create the tool once and cache it
+    if (!this.bashToolPromise) {
+      this.bashToolPromise = this.createBashTool();
+    }
+    return this.bashToolPromise;
+  }
+
+  private async createBashTool(): Promise<any> {
+    // 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(): Promise<void> {
+    // 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/src/modes/sandbox.ts

@@ -0,0 +1,144 @@
+import type { ExecutionMode } from "./types.js";
+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 implements ExecutionMode {
+  private bash: any; // Will be typed as Bash from just-bash
+  private initialized = false;
+  private bashToolPromise: Promise<any> | null = null;
+
+  constructor() {
+    // We'll initialize in the init method since we need async imports
+  }
+
+  private 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: string, content: string): Promise<void> {
+    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: string
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    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 as any).stdout || "",
+          stderr: (error as any).stderr || error.toString(),
+          exitCode: (error as any).exitCode || 1,
+        };
+      }
+
+      // Fallback for unexpected errors
+      return {
+        stdout: "",
+        stderr: error?.toString() || "Unknown error",
+        exitCode: 1,
+      };
+    }
+  }
+
+  async getBashTool(): Promise<any> {
+    // Only create the tool once and cache it
+    if (!this.bashToolPromise) {
+      this.bashToolPromise = this.createBashTool();
+    }
+    return this.bashToolPromise;
+  }
+
+  private async createBashTool(): Promise<any> {
+    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(): Promise<void> {
+    // No-op for in-memory mode - garbage collection will handle cleanup
+    // We could optionally clear the filesystem here if needed
+  }
+}

package/src/modes/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Common interface for execution modes (sandbox vs local)
+ */
+export interface ExecutionMode {
+  /**
+   * Write Phoenix data to the filesystem
+   * @param path - The file path relative to the Phoenix root
+   * @param content - The content to write
+   */
+  writeFile(path: string, content: string): Promise<void>;
+
+  /**
+   * Execute a bash command and return output
+   * @param command - The bash command to execute
+   * @returns The command output with stdout, stderr, and exit code
+   */
+  exec(
+    command: string
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+
+  /**
+   * Get the bash tool for the AI SDK agent
+   * @returns A tool that can be used by the AI SDK
+   */
+  getBashTool(): Promise<any>; // Tool type from AI SDK
+
+  /**
+   * Clean up resources
+   */
+  cleanup(): Promise<void>;
+}

package/src/observability/index.ts

@@ -0,0 +1,90 @@
+/**
+ * Phoenix Insight observability configuration
+ */
+
+import { register, type NodeTracerProvider } from "@arizeai/phoenix-otel";
+import { DiagLogLevel } from "@opentelemetry/api";
+
+/**
+ * Options for configuring observability
+ */
+export interface ObservabilityOptions {
+  /** Whether to enable tracing */
+  enabled: boolean;
+  /** Phoenix base URL for sending traces */
+  baseUrl?: string;
+  /** Phoenix API key for authentication */
+  apiKey?: string;
+  /** Phoenix project name for organizing traces */
+  projectName?: string;
+  /** Whether to enable debug logging */
+  debug?: boolean;
+}
+
+/**
+ * Global tracer provider instance
+ */
+let tracerProvider: NodeTracerProvider | null = null;
+
+/**
+ * Check if observability is enabled
+ */
+export function isObservabilityEnabled(): boolean {
+  return tracerProvider !== null;
+}
+
+/**
+ * Initialize observability for the Phoenix Insight agent
+ */
+export function initializeObservability(options: ObservabilityOptions): void {
+  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(): Promise<void> {
+  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(): NodeTracerProvider | null {
+  return tracerProvider;
+}