@ai-setting/roy-agent-core 1.0.0

package/src/env/debug/formatters/repl-formatter.ts

@@ -0,0 +1,358 @@
+/**
+ * @fileoverview REPL Formatter for Interactive Debugging
+ * 
+ * Provides an interactive REPL interface for debugging with:
+ * - Command parsing
+ * - Output formatting
+ * - Help text generation
+ */
+
+import type { TraceEntry, TraceTreeNode, TraceIdInfo } from '../types';
+
+export interface ReplContext {
+  traceId?: string;
+  function?: string;
+  limit?: number;
+}
+
+export interface ParsedCommand {
+  command: string;
+  args: Record<string, string>;
+}
+
+/**
+ * Formats output for REPL interface and provides command parsing
+ */
+export class ReplFormatter {
+  private context: ReplContext = {};
+  private history: string[] = [];
+
+  /**
+   * Get welcome message for REPL
+   */
+  getWelcomeMessage(): string {
+    return `========================================
+  Debug REPL - Interactive Debugger
+========================================
+
+Commands:
+  list [limit]     - List trace IDs
+  trace [options]  - Show trace details
+  tree [options]   - Show call tree
+  help             - Show this help
+  exit             - Exit REPL
+
+Examples:
+  list 10
+  trace --func llm.invoke
+  tree --trace trace-001
+
+========================================
+`;
+  }
+
+  /**
+   * Format prompt with current context
+   */
+  formatPrompt(context?: Partial<ReplContext>): string {
+    const ctx = { ...this.context, ...context };
+    let prompt = 'debug';
+    
+    if (ctx.traceId) {
+      prompt += `:${ctx.traceId}`;
+    } else if (ctx.function) {
+      prompt += `:${ctx.function}`;
+    }
+    
+    return `${prompt}> `;
+  }
+
+  /**
+   * Get help text
+   */
+  getHelpText(): string {
+    return `
+Available Commands:
+==================
+list [n]              - List recent trace IDs (default: 10)
+trace [options]       - Show trace details
+  --func <name>       - Filter by function name
+  --trace <id>        - Show specific trace
+  --pretty            - Pretty print output
+  --limit <n>         - Limit results
+tree [options]        - Show call tree
+  --func <name>       - Show tree for function
+  --trace <id>        - Show tree for trace
+clear                 - Clear screen
+help                  - Show this help
+exit                  - Exit REPL
+`;
+  }
+
+  /**
+   * Format command result
+   */
+  formatCommandResult(command: string, data: unknown): string {
+    switch (command) {
+      case 'list':
+        return this.formatListResult(data as { traceIds: TraceIdInfo[]; count: number });
+      case 'trace':
+        return this.formatTraceResult(data as TraceEntry[]);
+      case 'tree':
+        return this.formatTreeResult(data as TraceTreeNode[]);
+      default:
+        return `Unknown command: ${command}`;
+    }
+  }
+
+  /**
+   * Format list command result
+   */
+  private formatListResult(data: { traceIds: TraceIdInfo[]; count: number }): string {
+    const { traceIds, count } = data;
+    
+    if (traceIds.length === 0) {
+      return 'No traces found.';
+    }
+    
+    let output = '\n';
+    output += '  TraceId            First Time              Count\n';
+    output += '  ' + '-'.repeat(70) + '\n';
+    
+    for (const trace of traceIds) {
+      const time = trace.firstTime.replace('T', ' ').substring(0, 19);
+      output += `  ${trace.traceId.padEnd(18)} ${time.padEnd(22)} ${trace.count}\n`;
+    }
+    
+    output += `\n  Total: ${count} traces\n`;
+    return output;
+  }
+
+  /**
+   * Format trace command result
+   */
+  private formatTraceResult(entries: TraceEntry[]): string {
+    if (entries.length === 0) {
+      return 'No traces found.';
+    }
+    
+    let output = '';
+    let currentTraceId: string | null = null;
+    
+    for (const entry of entries) {
+      if (entry.traceId !== currentTraceId) {
+        currentTraceId = entry.traceId;
+        output += `\n=== Trace: ${entry.traceId} ===\n\n`;
+      }
+      
+      if (entry.action === 'enter') {
+        output += `>>> ${entry.function} enter:`;
+        if (entry.params) {
+          output += '\n' + this.formatJsonCompact(entry.params);
+        }
+        output += '\n';
+      } else if (entry.action === 'quit') {
+        output += `<<< ${entry.function} quit`;
+        if (entry.durationMs !== undefined) {
+          output += ` (${entry.durationMs}ms)`;
+        }
+        if (entry.result) {
+          output += ':\n' + this.formatJsonCompact(entry.result);
+        }
+        output += '\n';
+      } else if (entry.action === 'error') {
+        output += `!!! ${entry.function} error: ${entry.error}\n`;
+      }
+    }
+    
+    return output;
+  }
+
+  /**
+   * Format tree command result
+   */
+  private formatTreeResult(trees: TraceTreeNode[]): string {
+    if (trees.length === 0) {
+      return 'No trees found.';
+    }
+    
+    let output = '';
+    
+    for (const tree of trees) {
+      output += this.formatTreeNode(tree, '');
+    }
+    
+    return output;
+  }
+
+  /**
+   * Format a single tree node recursively
+   */
+  private formatTreeNode(node: TraceTreeNode, prefix: string): string {
+    const duration = node.durationMs !== undefined ? ` (${node.durationMs}ms)` : '';
+    let output = `${prefix}${node.function}${duration}\n`;
+    
+    const childPrefix = prefix + '  ';
+    for (let i = 0; i < node.children.length; i++) {
+      const isLast = i === node.children.length - 1;
+      const connector = isLast ? '└── ' : '├── ';
+      output += this.formatTreeNode(node.children[i], childPrefix + connector);
+    }
+    
+    return output;
+  }
+
+  /**
+   * Format JSON in compact form
+   */
+  private formatJsonCompact(data: unknown, indent: number = 2): string {
+    const spaces = '  '.repeat(indent);
+    
+    if (data === null || data === undefined) {
+      return `${spaces}null\n`;
+    }
+    
+    if (typeof data === 'string') {
+      // Handle long strings
+      if (data.length > 200) {
+        return `${spaces}"${data.substring(0, 200)}..."\n`;
+      }
+      return `${spaces}"${data}"\n`;
+    }
+    
+    if (typeof data === 'number' || typeof data === 'boolean') {
+      return `${spaces}${data}\n`;
+    }
+    
+    if (Array.isArray(data)) {
+      if (data.length === 0) return `${spaces}[]\n`;
+      
+      let output = `${spaces}[\n`;
+      for (const item of data) {
+        output += this.formatJsonCompact(item, indent + 1);
+      }
+      output += `${spaces}]\n`;
+      return output;
+    }
+    
+    if (typeof data === 'object') {
+      const entries = Object.entries(data as Record<string, unknown>);
+      if (entries.length === 0) return `${spaces}{}\n`;
+      
+      let output = `${spaces}{\n`;
+      for (const [key, val] of entries) {
+        output += `${spaces}  ${key}: ${JSON.stringify(val).substring(0, 50)}`;
+        if (JSON.stringify(val).length > 50) {
+          output += '...';
+        }
+        output += '\n';
+      }
+      output += `${spaces}}\n`;
+      return output;
+    }
+    
+    return `${spaces}${String(data)}\n`;
+  }
+
+  /**
+   * Parse command string
+   */
+  parseCommand(input: string): ParsedCommand {
+    const trimmed = input.trim();
+    
+    if (!trimmed) {
+      return { command: 'help', args: {} };
+    }
+    
+    // Handle exit commands
+    if (['exit', 'quit', 'q'].includes(trimmed.toLowerCase())) {
+      return { command: 'exit', args: {} };
+    }
+    
+    // Handle clear
+    if (trimmed.toLowerCase() === 'clear') {
+      return { command: 'clear', args: {} };
+    }
+    
+    // Handle help
+    if (['help', '?', 'h'].includes(trimmed.toLowerCase())) {
+      return { command: 'help', args: {} };
+    }
+    
+    // Parse command and args
+    const parts = trimmed.match(/(?:[^\s"]+|"[^"]*")+/g) || [];
+    
+    if (parts.length === 0) {
+      return { command: 'help', args: {} };
+    }
+    
+    const command = parts[0]?.toLowerCase() ?? '';
+    const args: Record<string, string> = {};
+    
+    // Parse named arguments
+    for (let i = 1; i < parts.length; i++) {
+      const part = parts[i];
+      
+      if (part.startsWith('--')) {
+        const key = part.substring(2);
+        const next = parts[i + 1];
+        if (next && !next.startsWith('--')) {
+          args[key] = next;
+          i++;
+        } else {
+          args[key] = 'true';
+        }
+      } else if (part.startsWith('-')) {
+        const key = part.substring(1);
+        const next = parts[i + 1];
+        if (next && !next.startsWith('-')) {
+          args[key] = next;
+          i++;
+        } else {
+          args[key] = 'true';
+        }
+      } else {
+        // Positional arguments
+        if (command === 'list' && !args.limit) {
+          args.limit = part;
+        } else if (command === 'trace' && !args.func) {
+          args.func = part;
+        } else if (command === 'tree' && !args.func) {
+          args.func = part;
+        }
+      }
+    }
+    
+    return { command, args };
+  }
+
+  /**
+   * Update context
+   */
+  setContext(context: Partial<ReplContext>): void {
+    this.context = { ...this.context, ...context };
+  }
+
+  /**
+   * Get current context
+   */
+  getContext(): ReplContext {
+    return { ...this.context };
+  }
+
+  /**
+   * Add to history
+   */
+  addToHistory(command: string): void {
+    if (command.trim() && this.history[this.history.length - 1] !== command) {
+      this.history.push(command);
+    }
+  }
+
+  /**
+   * Get history
+   */
+  getHistory(): string[] {
+    return [...this.history];
+  }
+}

package/src/env/debug/formatters/trace-formatter.test.ts

@@ -0,0 +1,119 @@
+import { describe, test, expect } from 'bun:test';
+import { TraceFormatter } from './trace-formatter';
+import type { TraceEntry, FormatOptions } from '../types';
+
+describe('TraceFormatter', () => {
+  const formatter = new TraceFormatter();
+
+  const mockEnterEntry: TraceEntry = {
+    traceId: 'trace-001',
+    timestamp: '2026-04-08T10:00:00.000',
+    function: 'llm.component.invoke',
+    action: 'enter',
+    params: [
+      [{ role: 'user', content: 'Hello' }],
+      { providerId: 'openai', model: 'gpt-4' }
+    ],
+  };
+
+  const mockQuitEntry: TraceEntry = {
+    traceId: 'trace-001',
+    timestamp: '2026-04-08T10:00:01.000',
+    function: 'llm.component.invoke',
+    action: 'quit',
+    result: { content: 'Hi there!', finishReason: 'stop' },
+    durationMs: 1000,
+  };
+
+  test('formatEntry - should format enter entry', () => {
+    const result = formatter.formatEntry(mockEnterEntry);
+    expect(result).toContain('>>>');
+    expect(result).toContain('llm.component.invoke');
+    expect(result).toContain('enter');
+  });
+
+  test('formatEntry - should format quit entry with duration', () => {
+    const result = formatter.formatEntry(mockQuitEntry);
+    expect(result).toContain('<<<');
+    expect(result).toContain('llm.component.invoke');
+    expect(result).toContain('1000ms');
+  });
+
+  test('formatEntry - should handle multi-line content without breaking layout', () => {
+    const entryWithMultiline: TraceEntry = {
+      ...mockQuitEntry,
+      result: {
+        content: 'This is a\nmulti-line\nresponse',
+        finishReason: 'stop'
+      },
+    };
+    
+    const result = formatter.formatEntry(entryWithMultiline, { pretty: true });
+    // Should handle newlines gracefully - indent continuation lines
+    const lines = result.split('\n');
+    expect(lines.length).toBeGreaterThan(1);
+    // Second line onwards should be indented
+    for (let i = 1; i < lines.length; i++) {
+      expect(lines[i].startsWith('  ')).toBe(true);
+    }
+  });
+
+  test('formatEntry - should handle deep nesting', () => {
+    const deepEntry: TraceEntry = {
+      ...mockQuitEntry,
+      result: {
+        level1: {
+          level2: {
+            level3: {
+              level4: 'deep value'
+            }
+          }
+        }
+      },
+    };
+    
+    const result = formatter.formatEntry(deepEntry, { pretty: true, maxDepth: 2 });
+    // Should truncate at maxDepth
+    expect(result).toContain('level1');
+    expect(result).toContain('...');
+  });
+
+  test('formatEntries - should format multiple entries', () => {
+    const entries = [mockEnterEntry, mockQuitEntry];
+    const result = formatter.formatEntries(entries);
+    expect(result).toContain('>>>');
+    expect(result).toContain('<<<');
+  });
+
+  test('formatEntries - should respect pretty option', () => {
+    const entries = [mockEnterEntry, mockQuitEntry];
+    
+    const prettyResult = formatter.formatEntries(entries, { pretty: true });
+    const jsonResult = formatter.formatEntries(entries, { pretty: false });
+    
+    // Pretty should have newlines and indentation
+    expect(prettyResult).toContain('\n');
+    // Pretty should have separator line
+    expect(prettyResult).toContain('-'.repeat(40));
+    // JSON should be compact (no separator line between entries)
+    expect(jsonResult).not.toContain('-'.repeat(40));
+  });
+
+  test('toJSON - should output valid JSON', () => {
+    const entries = [mockEnterEntry, mockQuitEntry];
+    const result = formatter.toJSON(entries);
+    
+    const parsed = JSON.parse(result);
+    expect(parsed).toHaveLength(2);
+    expect(parsed[0].action).toBe('enter');
+    expect(parsed[1].action).toBe('quit');
+  });
+
+  test('toSummary - should return trace summary', () => {
+    const entries = [mockEnterEntry, mockQuitEntry];
+    const result = formatter.toSummary(entries);
+    
+    expect(result).toContain('llm.component.invoke');
+    expect(result).toContain('2 entries');
+  });
+});

package/src/env/debug/formatters/trace-formatter.ts

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview Trace Formatter
+ * 
+ * Formats trace entries for console output with support for:
+ * - Pretty printing with indentation
+ * - Multi-line content handling
+ * - JSON output
+ * - Depth-limited nested object display
+ */
+
+import type { TraceEntry, FormatOptions } from '../types';
+
+/**
+ * Formats trace entries for human-readable output
+ */
+export class TraceFormatter {
+  /**
+   * Format a single trace entry
+   */
+  formatEntry(entry: TraceEntry, options: FormatOptions = {}): string {
+    const { pretty = false } = options;
+    const actionSymbol = entry.action === 'enter' ? '>>>' : 
+                         entry.action === 'error' ? '!!!' : '<<<';
+    
+    let output = `${actionSymbol} ${entry.function} ${entry.action}`;
+    
+    if (entry.action === 'enter' && entry.params) {
+      output += '\n' + this.formatData(entry.params, options);
+    } else if (entry.action === 'quit') {
+      if (entry.durationMs !== undefined) {
+        output += ` (${entry.durationMs}ms)`;
+      }
+      if (entry.result) {
+        output += '\n' + this.formatData(entry.result, options);
+      }
+    } else if (entry.action === 'error' && entry.error) {
+      output += `: ${entry.error}`;
+    }
+    
+    // Handle multi-line content by indenting continuation lines
+    if (pretty) {
+      output = this.indentMultilineContent(output);
+    }
+    
+    return output;
+  }
+  
+  /**
+   * Indent all lines after the first one
+   */
+  private indentMultilineContent(text: string, indent: string = '  '): string {
+    const lines = text.split('\n');
+    if (lines.length <= 1) return text;
+    
+    return lines.map((line, i) => i === 0 ? line : `${indent}${line}`).join('\n');
+  }
+
+  /**
+   * Format multiple trace entries
+   */
+  formatEntries(entries: TraceEntry[], options: FormatOptions = {}): string {
+    if (entries.length === 0) {
+      return 'No trace entries';
+    }
+    
+    const formatted = entries.map(entry => this.formatEntry(entry, options));
+    
+    // Use separator only for pretty mode, otherwise join without separator
+    if (options.pretty) {
+      return formatted.join('\n' + '-'.repeat(80) + '\n');
+    }
+    
+    return formatted.join('\n');
+  }
+
+  /**
+   * Format data with proper indentation for multi-line content
+   */
+  private formatData(data: unknown, options: FormatOptions = {}): string {
+    const { pretty = false, maxDepth = 10 } = options;
+    
+    if (pretty) {
+      return this.formatPretty(data, 0, maxDepth);
+    }
+    
+    // Compact JSON - no newlines
+    return JSON.stringify(data);
+  }
+
+  /**
+   * Format data with pretty printing and indentation
+   */
+  private formatPretty(data: unknown, indent: number = 0, maxDepth: number): string {
+    const baseIndent = '  '.repeat(indent);
+    const nextIndent = '  '.repeat(indent + 1);
+    
+    if (data === null || data === undefined) {
+      return String(data);
+    }
+    
+    if (typeof data === 'string') {
+      // Handle multi-line strings - indent each line
+      if (data.includes('\n')) {
+        return data.split('\n').map((line, i) => 
+          i === 0 ? line : `${nextIndent}${line}`
+        ).join('\n');
+      }
+      return data;
+    }
+    
+    if (typeof data === 'number' || typeof data === 'boolean') {
+      return String(data);
+    }
+    
+    if (Array.isArray(data)) {
+      if (data.length === 0) return '[]';
+      
+      const items = data.map(item => {
+        const formatted = this.formatPretty(item, indent + 1, maxDepth);
+        // Indent each line of the formatted item
+        return formatted.split('\n').map(line => `  ${line}`).join('\n');
+      });
+      
+      return '[\n' + items.join(',\n') + '\n' + baseIndent + ']';
+    }
+    
+    if (typeof data === 'object') {
+      const obj = data as Record<string, unknown>;
+      const keys = Object.keys(obj);
+      
+      if (keys.length === 0) return '{}';
+      
+      if (indent >= maxDepth) {
+        return '{...}';
+      }
+      
+      const entries = keys.map(key => {
+        const value = obj[key];
+        let formatted: string;
+        
+        if (typeof value === 'object' && value !== null) {
+          formatted = this.formatPretty(value, indent + 1, maxDepth);
+        } else if (typeof value === 'string' && value.includes('\n')) {
+          // Handle multi-line string values - indent each line
+          formatted = value.split('\n').map((line, i) => 
+            i === 0 ? line : `${nextIndent}${line}`
+          ).join('\n');
+        } else {
+          formatted = JSON.stringify(value);
+        }
+        
+        // Indent all lines of the formatted value
+        return `  ${key}: ` + formatted.split('\n').map((line, i) => 
+          i === 0 ? line : nextIndent + line
+        ).join('\n');
+      });
+      
+      return '{\n' + entries.join(',\n') + '\n' + baseIndent + '}';
+    }
+    
+    return JSON.stringify(data);
+  }
+
+  /**
+   * Output as JSON
+   */
+  toJSON(entries: TraceEntry[]): string {
+    return JSON.stringify(entries, null, 2);
+  }
+
+  /**
+   * Generate a summary of trace entries
+   */
+  toSummary(entries: TraceEntry[]): string {
+    if (entries.length === 0) {
+      return 'No trace entries';
+    }
+    
+    const functions = new Set(entries.map(e => e.function));
+    const actions = entries.reduce((acc, e) => {
+      acc[e.action] = (acc[e.action] || 0) + 1;
+      return acc;
+    }, {} as Record<string, number>);
+    
+    let summary = `Trace Summary (${entries.length} entries)\n`;
+    summary += `Functions: ${[...functions].join(', ')}\n`;
+    summary += `Actions: ${Object.entries(actions).map(([k, v]) => `${k}=${v}`).join(', ')}`;
+    
+    return summary;
+  }
+}