@ai-setting/roy-agent-core 1.0.0

package/src/env/debug/reader/log-reader.ts

@@ -0,0 +1,186 @@
+/**
+ * @fileoverview Log Reader
+ * 
+ * Reads log files with support for streaming and filtering.
+ */
+
+import * as fs from 'fs';
+import * as readline from 'readline';
+import * as path from 'path';
+import { glob } from 'glob';
+import type { ParserOptions } from '../types';
+
+/**
+ * Default XDG log directory
+ */
+const DEFAULT_LOG_DIR = '.local/share/roy-agent/logs';
+
+/**
+ * Get XDG data home directory
+ */
+export function getXDGDataHome(): string {
+  return process.env.XDG_DATA_HOME || 
+    path.join(process.env.HOME || '/home/' + (process.env.USER || 'user'), '.local', 'share');
+}
+
+/**
+ * Log Reader for reading and parsing log files
+ */
+export class LogReader {
+  private logDir: string;
+
+  constructor(options?: { logDir?: string }) {
+    this.logDir = options?.logDir || 
+      path.join(getXDGDataHome(), 'roy-agent', 'logs');
+  }
+
+  /**
+   * Get the full path to a log file
+   */
+  getLogPath(filename?: string): string {
+    if (!filename) {
+      return path.join(this.logDir, 'app.log');
+    }
+    // If absolute path, use directly
+    if (path.isAbsolute(filename)) {
+      return filename;
+    }
+    return path.join(this.logDir, filename);
+  }
+
+  /**
+   * Find log files matching a pattern
+   * 
+   * Uses forward slashes for glob patterns to ensure cross-platform compatibility.
+   * The glob library requires forward slashes regardless of OS.
+   */
+  async findLogFiles(pattern: string = '*.log'): Promise<string[]> {
+    try {
+      // Use forward slashes for glob pattern to ensure Windows compatibility
+      const normalizedDir = this.logDir.replace(/\\/g, "/");
+      const fullPattern = `${normalizedDir}/${pattern}`;
+      const files = await glob(fullPattern);
+      return files.sort(); // Sort by name
+    } catch {
+      return [];
+    }
+  }
+
+  /**
+   * Get default log directory
+   */
+  getDefaultLogDir(): string {
+    return this.logDir;
+  }
+
+  /**
+   * Read lines from a log file with optional filtering
+   */
+  async *readLines(
+    filepath: string,
+    options?: ParserOptions
+  ): AsyncGenerator<string> {
+    const sinceTime = options?.since ? this.parseTime(options.since) : null;
+    const untilTime = options?.until ? this.parseTime(options.until) : null;
+
+    // Check if file exists
+    if (!fs.existsSync(filepath)) {
+      return;
+    }
+
+    const fileStream = fs.createReadStream(filepath, { encoding: 'utf-8' });
+    const rl = readline.createInterface({
+      input: fileStream,
+      crlfDelay: Infinity,
+    });
+
+    try {
+      for await (const line of rl) {
+        if (!line.trim()) continue;
+
+        // Filter by time if specified
+        if (sinceTime || untilTime) {
+          const lineTime = this.extractTimestamp(line);
+          if (lineTime) {
+            if (sinceTime && lineTime < sinceTime) continue;
+            if (untilTime && lineTime > untilTime) continue;
+          }
+        }
+
+        yield line;
+      }
+    } finally {
+      rl.close();
+      fileStream.destroy();
+    }
+  }
+
+  /**
+   * Extract timestamp from a log line
+   */
+  extractTimestamp(line: string): number | null {
+    // Match format: 2026-04-08 19:12:36.134 or 2026-04-08T19:12:36.134
+    const match = line.match(/^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2})/);
+    if (!match) return null;
+
+    const datePart = match[1];
+    const timePart = match[2]; // Keep original format (10:00:00)
+    const isoString = `${datePart}T${timePart}`;
+
+    const timestamp = new Date(isoString).getTime();
+    return isNaN(timestamp) ? null : timestamp;
+  }
+
+  /**
+   * Parse time string to timestamp
+   * Supports ISO format and relative time like "1h", "30m"
+   */
+  parseTime(timeStr: string): number {
+    const now = Date.now();
+
+    // Normalize the time string (replace T with space for parsing)
+    const normalizedStr = timeStr.replace('T', ' ');
+
+    // Try parsing as absolute time
+    const absoluteTime = new Date(normalizedStr).getTime();
+    if (!isNaN(absoluteTime) && absoluteTime > 0) {
+      return absoluteTime;
+    }
+
+    // Also try original format
+    const originalTime = new Date(timeStr).getTime();
+    if (!isNaN(originalTime) && originalTime > 0) {
+      return originalTime;
+    }
+
+    // Parse relative time
+    const relativeMatch = timeStr.match(/^(\d+)([hms])$/);
+    if (relativeMatch) {
+      const value = parseInt(relativeMatch[1], 10);
+      const unit = relativeMatch[2];
+
+      switch (unit) {
+        case 'h': return now - value * 60 * 60 * 1000;
+        case 'm': return now - value * 60 * 1000;
+        case 's': return now - value * 1000;
+      }
+    }
+
+    // Default to current time if parsing fails
+    return now;
+  }
+
+  /**
+   * Read file content directly (for small files)
+   */
+  async readFile(filepath: string): Promise<string> {
+    return fs.promises.readFile(filepath, 'utf-8');
+  }
+
+  /**
+   * Check if a log file exists
+   */
+  exists(filepath: string): boolean {
+    return fs.existsSync(filepath);
+  }
+}

package/src/env/debug/reader/span-db-reader.test.ts

@@ -0,0 +1,118 @@
+/**
+ * @fileoverview SpanDbReader Test
+ */
+
+import { describe, test, expect, beforeAll, afterAll } from 'bun:test';
+import { SpanDbReader } from './span-db-reader';
+import { SQLiteSpanStorage } from '../../log-trace/span-storage';
+import type { Span } from '../../log-trace/types';
+import { SpanKind, SpanStatus } from '../../log-trace/types';
+import * as fs from 'fs';
+import * as path from 'path';
+
+// Test data
+const testSpan1: Span = {
+  traceId: 'trace_test_001',
+  spanId: 'span_1',
+  name: 'testFunction',
+  kind: SpanKind.INTERNAL,
+  status: SpanStatus.OK,
+  startTime: Date.now() - 1000,
+  endTime: Date.now(),
+  attributes: { arg1: 'value1', arg2: 123 },
+  children: [],
+};
+
+const testSpan2: Span = {
+  traceId: 'trace_test_002',
+  spanId: 'span_2',
+  name: 'anotherFunction',
+  kind: SpanKind.INTERNAL,
+  status: SpanStatus.OK,
+  startTime: Date.now() - 500,
+  endTime: Date.now() - 100,
+  attributes: {},
+  children: [],
+};
+
+describe('SpanDbReader', () => {
+  let storage: SQLiteSpanStorage;
+  let reader: SpanDbReader;
+  let tempDbPath: string;
+
+  beforeAll(async () => {
+    // 清除环境变量中的 trace context，避免继承外部上下文
+    delete process.env['TRACEPARENT'];
+    delete process.env['TRACE_ID'];
+    delete process.env['LOG_TRACE_REQUEST_ID'];
+    
+    // Create temporary database file
+    tempDbPath = `/tmp/test_span_db_${Date.now()}.sqlite`;
+    storage = new SQLiteSpanStorage(tempDbPath);
+    await storage.initialize();
+
+    // Insert test data
+    storage.save(testSpan1);
+    storage.save(testSpan2);
+
+    // Create reader with storage
+    reader = new SpanDbReader({ storage });
+  });
+
+  afterAll(() => {
+    reader.close();
+    storage.close();
+    // Cleanup temp file
+    if (fs.existsSync(tempDbPath)) {
+      fs.unlinkSync(tempDbPath);
+    }
+  });
+
+  test('should list trace IDs', async () => {
+    const summary = await reader.listTraceIds(10);
+
+    expect(summary.count).toBeGreaterThanOrEqual(2);
+    expect(summary.traceIds.length).toBeGreaterThanOrEqual(2);
+
+    const traceIds = summary.traceIds.map(t => t.traceId);
+    expect(traceIds).toContain('trace_test_001');
+    expect(traceIds).toContain('trace_test_002');
+  });
+
+  test('should get trace entries by traceId', async () => {
+    const entries = await reader.getTraceEntries('trace_test_001');
+
+    expect(entries.length).toBeGreaterThanOrEqual(2); // enter and quit
+    expect(entries[0].traceId).toBe('trace_test_001');
+    expect(entries[0].function).toBe('testFunction');
+    expect(entries[0].action).toBe('enter');
+  });
+
+  test('should return empty array for non-existent trace', async () => {
+    const entries = await reader.getTraceEntries('non_existent_trace');
+    expect(entries).toHaveLength(0);
+  });
+
+  test('should limit trace list', async () => {
+    const summary = await reader.listTraceIds(1);
+    expect(summary.traceIds.length).toBeLessThanOrEqual(1);
+  });
+});
+
+describe('SpanDbReader with dbPath', () => {
+  test('should initialize from dbPath', async () => {
+    const tempPath = `/tmp/test_span_db_${Date.now()}.sqlite`;
+    const reader = new SpanDbReader({ dbPath: tempPath });
+    
+    await reader.initialize();
+    
+    expect(reader.getStorage()).toBeTruthy();
+    
+    reader.close();
+    
+    // Cleanup
+    if (fs.existsSync(tempPath)) {
+      fs.unlinkSync(tempPath);
+    }
+  });
+});

package/src/env/debug/reader/span-db-reader.ts

@@ -0,0 +1,201 @@
+/**
+ * @fileoverview Span DB Reader - Read spans from SQLite database
+ * 
+ * This reader fetches trace data directly from SQLite span storage,
+ * which is used for persisting spans in production environments.
+ */
+
+import type { TraceEntry, TraceIdInfo, TraceSummary } from '../types';
+import type { Span, SpanStorage } from '../../log-trace/types';
+
+// ============================================================================
+// SpanDbReader
+// ============================================================================
+
+/**
+ * Options for SpanDbReader
+ */
+export interface SpanDbReaderOptions {
+  /** Database path (for file-based SQLite) */
+  dbPath?: string;
+  /** Storage instance to use directly */
+  storage?: SpanStorage;
+}
+
+/**
+ * Span Database Reader
+ * 
+ * Reads span data from SQLite storage for trace debugging and analysis.
+ */
+export class SpanDbReader {
+  private storage: SpanStorage | null = null;
+  private dbPath: string | null = null;
+  private sqliteDb: any = null;
+
+  constructor(options?: SpanDbReaderOptions) {
+    if (options?.storage) {
+      this.storage = options.storage;
+    } else if (options?.dbPath) {
+      this.dbPath = options.dbPath;
+    }
+  }
+
+  /**
+   * Initialize the reader with storage
+   */
+  async initialize(): Promise<void> {
+    if (this.storage) {
+      await this.storage.initialize();
+    } else if (this.dbPath) {
+      // Lazy load SQLite storage
+      await this.initSqliteStorage();
+    }
+  }
+
+  /**
+   * Initialize SQLite storage directly
+   */
+  private async initSqliteStorage(): Promise<void> {
+    try {
+      // Dynamic import to avoid hard dependency
+      const { SQLiteSpanStorage } = await import('../../log-trace/span-storage');
+      this.storage = new SQLiteSpanStorage(this.dbPath!);
+      await this.storage.initialize();
+    } catch (error) {
+      throw new Error(`Failed to initialize SQLite storage: ${error}`);
+    }
+  }
+
+  /**
+   * Get trace entries for a specific traceId
+   */
+  async getTraceEntries(traceId: string): Promise<TraceEntry[]> {
+    if (!this.storage) {
+      throw new Error('Storage not initialized. Call initialize() first.');
+    }
+
+    const spans = this.storage.findByTraceId(traceId);
+    if (spans.length === 0) {
+      return [];
+    }
+
+    // Convert spans to TraceEntry format
+    return this.spansToEntries(spans);
+  }
+
+  /**
+   * List all trace IDs
+   */
+  async listTraceIds(limit: number = 20): Promise<TraceSummary> {
+    if (!this.storage) {
+      throw new Error('Storage not initialized. Call initialize() first.');
+    }
+
+    const traceInfos = this.storage.listTraces(limit);
+    
+    const traceIds: TraceIdInfo[] = traceInfos.map(info => ({
+      traceId: info.traceId,
+      firstTime: new Date(info.startTime).toISOString(),
+      lastTime: info.endTime ? new Date(info.endTime).toISOString() : undefined,
+      count: info.spanCount,
+    }));
+
+    return {
+      traceIds,
+      count: traceInfos.length,
+    };
+  }
+
+  /**
+   * Convert spans to TraceEntry format
+   * 
+   * Now properly extracts spanId and parentSpanId for tree building
+   */
+  private spansToEntries(spans: Span[]): TraceEntry[] {
+    const entries: TraceEntry[] = [];
+
+    // Create entries for each span (enter event)
+    for (const span of spans) {
+      entries.push({
+        traceId: span.traceId,
+        timestamp: new Date(span.startTime).toISOString(),
+        function: span.name,
+        action: 'enter',
+        params: this.attributesToParams(span.attributes),
+        spanId: span.spanId,
+        parentSpanId: span.parentSpanId,
+      });
+
+      if (span.endTime) {
+        entries.push({
+          traceId: span.traceId,
+          timestamp: new Date(span.endTime).toISOString(),
+          function: span.name,
+          action: 'quit',
+          result: span.result,
+          error: span.error,
+          durationMs: span.endTime - span.startTime,
+          spanId: span.spanId,
+          parentSpanId: span.parentSpanId,
+        });
+      }
+    }
+
+    // Sort by timestamp
+    entries.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+
+    return entries;
+  }
+
+  /**
+   * Convert span attributes to params format
+   */
+  private attributesToParams(attributes: Record<string, unknown> | undefined): unknown[] {
+    if (!attributes) return [];
+    return Object.entries(attributes).map(([key, value]) => ({
+      key,
+      value,
+    }));
+  }
+
+  /**
+   * Get the underlying storage
+   */
+  getStorage(): SpanStorage | null {
+    return this.storage;
+  }
+
+  /**
+   * Close the reader and cleanup resources
+   */
+  close(): void {
+    if (this.storage) {
+      this.storage.close();
+      this.storage = null;
+    }
+    if (this.sqliteDb) {
+      this.sqliteDb.close();
+      this.sqliteDb = null;
+    }
+  }
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Create a SpanDbReader from a database path
+ */
+export async function createSpanDbReader(dbPath: string): Promise<SpanDbReader> {
+  const reader = new SpanDbReader({ dbPath });
+  await reader.initialize();
+  return reader;
+}
+
+/**
+ * Create a SpanDbReader from an existing storage instance
+ */
+export function createSpanDbReaderFromStorage(storage: SpanStorage): SpanDbReader {
+  return new SpanDbReader({ storage });
+}

package/src/env/debug/types.test.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test } from 'bun:test';
+import type {
+  TraceEntry,
+  TraceTreeNode,
+  ParserOptions,
+  LogDiscoveryOptions,
+  TraceIdInfo,
+  ParsedLogLine,
+} from './types';
+
+describe('Debug Types', () => {
+  describe('TraceEntry', () => {
+    test('should have correct structure for enter action', () => {
+      const entry: TraceEntry = {
+        traceId: 'req_123_abc',
+        timestamp: '2026-04-08T19:12:36.134',
+        function: 'llm.component.invoke',
+        action: 'enter',
+        params: [
+          { messages: [{ role: 'system', content: 'You are Roy...' }] },
+          { providerId: 'minimax', model: 'MiniMax-M2.7' },
+        ],
+      };
+
+      expect(entry.traceId).toBe('req_123_abc');
+      expect(entry.function).toBe('llm.component.invoke');
+      expect(entry.action).toBe('enter');
+      expect(entry.params).toHaveLength(2);
+    });
+
+    test('should have correct structure for quit action', () => {
+      const entry: TraceEntry = {
+        traceId: 'req_123_abc',
+        timestamp: '2026-04-08T19:12:39.213',
+        function: 'llm.component.invoke',
+        action: 'quit',
+        result: {
+          output: { content: 'Hello!', finishReason: 'stop' },
+          latencyMs: 3077,
+        },
+        durationMs: 3077,
+      };
+
+      expect(entry.action).toBe('quit');
+      expect(entry.durationMs).toBe(3077);
+      expect(entry.result).toBeDefined();
+    });
+
+    test('should have correct structure for error action', () => {
+      const entry: TraceEntry = {
+        traceId: 'req_123_abc',
+        timestamp: '2026-04-08T19:12:39.213',
+        function: 'llm.component.invoke',
+        action: 'error',
+        error: 'Connection timeout',
+      };
+
+      expect(entry.action).toBe('error');
+      expect(entry.error).toBe('Connection timeout');
+    });
+  });
+
+  describe('TraceTreeNode', () => {
+    test('should have correct structure', () => {
+      const node: TraceTreeNode = {
+        traceId: 'req_123_abc',
+        function: 'llm.component.invoke',
+        startTime: '2026-04-08T19:12:36.134',
+        endTime: '2026-04-08T19:12:39.213',
+        durationMs: 3077,
+        children: [],
+        entry: {
+          traceId: 'req_123_abc',
+          timestamp: '2026-04-08T19:12:36.134',
+          function: 'llm.component.invoke',
+          action: 'enter',
+        },
+      };
+
+      expect(node.children).toHaveLength(0);
+      expect(node.durationMs).toBe(3077);
+    });
+
+    test('should support nested children', () => {
+      const childNode: TraceTreeNode = {
+        traceId: 'req_123_abc',
+        function: 'tool.execute',
+        startTime: '2026-04-08T19:12:37.000',
+        endTime: '2026-04-08T19:12:37.500',
+        durationMs: 500,
+        children: [],
+        entry: {
+          traceId: 'req_123_abc',
+          timestamp: '2026-04-08T19:12:37.000',
+          function: 'tool.execute',
+          action: 'enter',
+        },
+      };
+
+      const rootNode: TraceTreeNode = {
+        traceId: 'req_123_abc',
+        function: 'llm.component.invoke',
+        startTime: '2026-04-08T19:12:36.134',
+        endTime: '2026-04-08T19:12:39.213',
+        durationMs: 3077,
+        children: [childNode],
+        entry: {
+          traceId: 'req_123_abc',
+          timestamp: '2026-04-08T19:12:36.134',
+          function: 'llm.component.invoke',
+          action: 'enter',
+        },
+      };
+
+      expect(rootNode.children).toHaveLength(1);
+      expect(rootNode.children[0].function).toBe('tool.execute');
+    });
+  });
+
+  describe('ParserOptions', () => {
+    test('should support all optional fields', () => {
+      const options: ParserOptions = {
+        logFile: '/path/to/app.log',
+        traceId: 'req_123',
+        function: 'llm.component.invoke',
+        since: '2026-04-08T10:00:00',
+        until: '2026-04-08T12:00:00',
+        level: 'info',
+      };
+
+      expect(options.logFile).toBe('/path/to/app.log');
+      expect(options.level).toBe('info');
+    });
+
+    test('should allow empty options', () => {
+      const options: ParserOptions = {};
+      expect(options.logFile).toBeUndefined();
+      expect(options.traceId).toBeUndefined();
+    });
+  });
+
+  describe('LogDiscoveryOptions', () => {
+    test('should have default pattern', () => {
+      const options: LogDiscoveryOptions = {
+        logDir: '/custom/logs',
+        pattern: '*.log',
+      };
+
+      expect(options.pattern).toBe('*.log');
+    });
+  });
+
+  describe('TraceIdInfo', () => {
+    test('should have correct structure', () => {
+      const info: TraceIdInfo = {
+        traceId: 'req_123_abc',
+        firstTime: '2026-04-08T19:12:36',
+        lastTime: '2026-04-08T19:12:45',
+        count: 15,
+      };
+
+      expect(info.traceId).toBe('req_123_abc');
+      expect(info.count).toBe(15);
+    });
+  });
+
+  describe('ParsedLogLine', () => {
+    test('should have correct structure', () => {
+      const line: ParsedLogLine = {
+        raw: '2026-04-08 19:12:36.134 [INFO] [cli/src/bin/roy.js:80752][traced:llm.component.invoke] [TRACE] >>> llm.component.invoke enter: [{}]',
+        timestamp: '2026-04-08 19:12:36.134',
+        level: 'INFO',
+        source: 'cli/src/bin/roy.js:80752',
+        category: 'traced:llm.component.invoke',
+        action: '>>>',
+        method: 'llm.component.invoke',
+        actionType: 'enter',
+        rawArgs: '[{}]',
+      };
+
+      expect(line.timestamp).toBe('2026-04-08 19:12:36.134');
+      expect(line.level).toBe('INFO');
+      expect(line.action).toBe('>>>');
+      expect(line.method).toBe('llm.component.invoke');
+    });
+  });
+});