@ai-setting/roy-agent-core 1.7.52 → 1.7.53

package/dist/env/debug/debug-component.d.ts

@@ -0,0 +1,160 @@
+/**
+ * @fileoverview Debug Component
+ *
+ * Provides debugging capabilities for roy-agent applications by parsing
+ * trace logs and presenting formatted output.
+ */
+import { BaseComponent, type ComponentConfig } from '../component';
+import { LogReader } from './reader/log-reader';
+import { SpanDbReader } from './reader/span-db-reader';
+import { RegexParser } from './parser/regex-parser';
+import { SpanBuilder } from './parser/span-builder';
+import { TraceFormatter, TreeFormatter } from './formatters';
+import type { ParserOptions, TraceEntry, TraceTreeNode, TraceSummary, FormatOptions } from './types';
+/**
+ * Data source type for trace retrieval
+ */
+export type TraceDataSource = 'log' | 'sqlite';
+/**
+ * Extended parser options with data source support
+ */
+export interface TraceParserOptions extends ParserOptions {
+    /** Data source type: 'log' (default) or 'sqlite' */
+    source?: TraceDataSource;
+    /** SQLite database path (required when source is 'sqlite') */
+    dbPath?: string;
+}
+/**
+ * DebugComponent configuration options
+ */
+export interface DebugComponentOptions {
+    /** Log directory path */
+    logDir?: string;
+    /** Default log file */
+    defaultLogFile?: string;
+}
+/**
+ * Debug Component for trace analysis and debugging
+ */
+export declare class DebugComponent extends BaseComponent {
+    name: string;
+    version: string;
+    private reader;
+    private spanDbReader;
+    private parser;
+    private spanBuilder;
+    private traceFormatter;
+    private treeFormatter;
+    private options;
+    constructor(options?: DebugComponentOptions);
+    /**
+     * Initialize the span database reader
+     */
+    initSpanDbReader(dbPath?: string): Promise<void>;
+    /**
+     * Get the span database reader
+     */
+    getSpanDbReader(): SpanDbReader | null;
+    /**
+     * Get trace by ID from live Tracer storage
+     *
+     * This method retrieves traces directly from the Tracer's span storage,
+     * which includes spans from the current session that may not yet be persisted
+     * to log files.
+     */
+    getLiveTrace(traceId: string): Promise<any | null>;
+    /**
+     * List all available traces from live Tracer storage
+     */
+    listLiveTraces(limit?: number): Promise<any>;
+    /**
+     * Format a live trace for display
+     */
+    formatLiveTrace(traceId: string): Promise<string>;
+    /**
+     * Initialize the component
+     */
+    init(config?: ComponentConfig): Promise<void>;
+    /**
+     * Stop the component
+     */
+    stop(): Promise<void>;
+    /**
+     * Get traces matching the options
+     */
+    getTraces(options?: TraceParserOptions): Promise<TraceEntry[]>;
+    /**
+     * Get traces from SQLite database
+     */
+    private getTracesFromSqlite;
+    /**
+     * List available trace IDs
+     */
+    listTraceIds(options?: TraceParserOptions & {
+        limit?: number;
+    }): Promise<TraceSummary>;
+    /**
+     * List trace IDs from SQLite database
+     */
+    private listTraceIdsFromSqlite;
+    /**
+     * Get call tree for a specific trace
+     */
+    getCallTree(options?: TraceParserOptions): Promise<TraceTreeNode | null>;
+    /**
+     * Get the log reader instance
+     */
+    getReader(): LogReader;
+    /**
+     * Get the parser instance
+     */
+    getParser(): RegexParser;
+    /**
+     * Get the span builder instance
+     */
+    getSpanBuilder(): SpanBuilder;
+    /**
+     * Get the trace formatter instance
+     */
+    getTraceFormatter(): TraceFormatter;
+    /**
+     * Get the tree formatter instance
+     */
+    getTreeFormatter(): TreeFormatter;
+    /**
+     * Format traces for display
+     */
+    formatTraces(entries: TraceEntry[], options?: FormatOptions): string;
+    /**
+     * Format a single trace entry
+     */
+    formatTraceEntry(entry: TraceEntry, options?: FormatOptions): string;
+    /**
+     * Format traces as JSON
+     */
+    tracesToJSON(entries: TraceEntry[]): string;
+    /**
+     * Format traces as summary
+     */
+    tracesToSummary(entries: TraceEntry[]): string;
+    /**
+     * Format call tree for display
+     */
+    formatTree(node: TraceTreeNode): string;
+    /**
+     * Format multiple call trees
+     */
+    formatTrees(trees: TraceTreeNode[]): string;
+    /**
+     * Format trees as JSON
+     */
+    treesToJSON(trees: TraceTreeNode[]): string;
+    /**
+     * Format tree summary (sorted by duration)
+     */
+    formatTreeSummary(node: TraceTreeNode): string;
+    /**
+     * Format tree with timeline visualization
+     */
+    formatTreeTimeline(node: TraceTreeNode): string;
+}

package/dist/env/debug/formatters/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Debug Formatters
+ *
+ * Export all formatters for trace and tree visualization
+ */
+export { TraceFormatter } from './trace-formatter';
+export { TreeFormatter } from './tree-formatter';
+export { ReplFormatter } from './repl-formatter';

package/dist/env/debug/formatters/repl-formatter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview REPL Formatter for Interactive Debugging
+ *
+ * Provides an interactive REPL interface for debugging with:
+ * - Command parsing
+ * - Output formatting
+ * - Help text generation
+ */
+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 declare class ReplFormatter {
+    private context;
+    private history;
+    /**
+     * Get welcome message for REPL
+     */
+    getWelcomeMessage(): string;
+    /**
+     * Format prompt with current context
+     */
+    formatPrompt(context?: Partial<ReplContext>): string;
+    /**
+     * Get help text
+     */
+    getHelpText(): string;
+    /**
+     * Format command result
+     */
+    formatCommandResult(command: string, data: unknown): string;
+    /**
+     * Format list command result
+     */
+    private formatListResult;
+    /**
+     * Format trace command result
+     */
+    private formatTraceResult;
+    /**
+     * Format tree command result
+     */
+    private formatTreeResult;
+    /**
+     * Format a single tree node recursively
+     */
+    private formatTreeNode;
+    /**
+     * Format JSON in compact form
+     */
+    private formatJsonCompact;
+    /**
+     * Parse command string
+     */
+    parseCommand(input: string): ParsedCommand;
+    /**
+     * Update context
+     */
+    setContext(context: Partial<ReplContext>): void;
+    /**
+     * Get current context
+     */
+    getContext(): ReplContext;
+    /**
+     * Add to history
+     */
+    addToHistory(command: string): void;
+    /**
+     * Get history
+     */
+    getHistory(): string[];
+}

package/dist/env/debug/formatters/trace-formatter.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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 declare class TraceFormatter {
+    /**
+     * Format a single trace entry
+     */
+    formatEntry(entry: TraceEntry, options?: FormatOptions): string;
+    /**
+     * Indent all lines after the first one
+     */
+    private indentMultilineContent;
+    /**
+     * Format multiple trace entries
+     */
+    formatEntries(entries: TraceEntry[], options?: FormatOptions): string;
+    /**
+     * Format data with proper indentation for multi-line content
+     */
+    private formatData;
+    /**
+     * Format data with pretty printing and indentation
+     */
+    private formatPretty;
+    /**
+     * Output as JSON
+     */
+    toJSON(entries: TraceEntry[]): string;
+    /**
+     * Generate a summary of trace entries
+     */
+    toSummary(entries: TraceEntry[]): string;
+}

package/dist/env/debug/formatters/tree-formatter.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Tree Formatter
+ *
+ * Formats trace call trees for console output with:
+ * - ANSI color support
+ * - Duration display with percentage
+ * - Time bar visualization
+ * - Proper indentation
+ */
+import type { TraceTreeNode } from '../types';
+/**
+ * Options for tree formatting
+ */
+export interface TreeFormatOptions {
+    /** Show duration percentage (default: true) */
+    showPercent?: boolean;
+    /** Show time bar (default: false) */
+    showTimeBar?: boolean;
+    /** Width of time bar (default: 10) */
+    barWidth?: number;
+}
+/**
+ * Formats trace call trees for human-readable output
+ */
+export declare class TreeFormatter {
+    private options;
+    constructor(options?: TreeFormatOptions);
+    /**
+     * Color function based on percentage
+     */
+    private colorByPercent;
+    /**
+     * Format a single trace tree
+     */
+    formatTree(node: TraceTreeNode): string;
+    /**
+     * Format a single node
+     */
+    private formatNode;
+    /**
+     * Recursively format children
+     */
+    private formatChildren;
+    /**
+     * Render a time bar showing relative duration
+     */
+    private renderTimeBar;
+    /**
+     * Format duration in human-readable form
+     */
+    private formatDuration;
+    /**
+     * Format multiple trace trees
+     */
+    formatTrees(trees: TraceTreeNode[]): string;
+    /**
+     * Output as JSON
+     */
+    toJSON(trees: TraceTreeNode[]): string;
+    /**
+     * Generate a summary table of all spans sorted by duration
+     */
+    formatSummary(node: TraceTreeNode): string;
+    /**
+     * Format tree with timeline visualization
+     */
+    formatTimeline(node: TraceTreeNode): string;
+    /**
+     * Build timeline visualization with absolute positioning
+     */
+    private buildTimeline;
+}

package/dist/env/debug/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Debug Component Index
+ *
+ * Export all debug-related types and classes.
+ */
+export type { TraceEntry, TraceTreeNode, ParserOptions, LogDiscoveryOptions, ParsedLogLine, TraceIdInfo, TraceSummary, FormatOptions, TraceAction, LogLevel, } from './types';
+export type { TraceDataSource, TraceParserOptions } from './debug-component';
+export { DebugComponent } from './debug-component';
+export { LogReader } from './reader/log-reader';
+export { SpanDbReader } from './reader/span-db-reader';
+export { RegexParser } from './parser/regex-parser';
+export { SpanBuilder } from './parser/span-builder';
+export { TraceFormatter } from './formatters/trace-formatter';
+export { TreeFormatter } from './formatters/tree-formatter';
+export { ReplFormatter } from './formatters/repl-formatter';

package/dist/env/debug/index.js

@@ -4,7 +4,7 @@ import {
   RegexParser,
   SpanBuilder,
   SpanDbReader
-} from "../../shared/@ai-setting/roy-agent-core-0cfaqnz9.js";
+} from "../../shared/@ai-setting/roy-agent-core-k25gv86p.js";
 import {
   ReplFormatter,
   TraceFormatter,

package/dist/env/debug/parser/regex-parser.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Regex Parser for Log Lines
+ *
+ * Parses log files with trace format:
+ * [TRACE] >>> {method} enter: {args}
+ * [TRACE] <<< {method} quit: {result}
+ * [TRACE] !!! {method} error: {error}
+ */
+import type { ParsedLogLine, LogLevel } from '../types';
+/**
+ * Regex Parser for trace log lines
+ */
+export declare class RegexParser {
+    /**
+     * Parse a single log line
+     */
+    parseLogLine(line: string): ParsedLogLine | null;
+    /**
+     * Parse arguments from raw args string
+     */
+    parseArgs(raw: string): unknown | unknown[] | null;
+    /**
+     * Check if a line is a trace line
+     */
+    isTraceLine(line: string): boolean;
+    /**
+     * Filter lines by log level
+     */
+    filterByLevel(lines: string[], level?: LogLevel): string[];
+    /**
+     * Filter lines by function name
+     */
+    filterByFunction(lines: string[], functionName?: string): string[];
+    /**
+     * Extract trace ID from log line
+     * Checks for requestId in two places:
+     * 1. Category field: [source][requestId=req_123]
+     * 2. After method name: [requestId=req_abc]
+     */
+    extractTraceId(line: string): string | null;
+    /**
+     * Extract trace IDs from multiple lines
+     */
+    extractTraceIds(lines: string[]): Map<string, string[]>;
+    /**
+     * Parse multiple lines
+     */
+    parseLines(lines: string[]): ParsedLogLine[];
+}

package/dist/env/debug/parser/span-builder.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Span Builder
+ *
+ * Builds TraceEntry objects from parsed log lines and constructs call trees.
+ */
+import type { ParsedLogLine, TraceEntry, TraceTreeNode } from '../types';
+/**
+ * Paired enter/quit entries
+ */
+interface PairedSpan {
+    enter: TraceEntry;
+    quit: TraceEntry;
+    durationMs: number;
+}
+/**
+ * Span Builder for constructing trace entries and call trees
+ */
+export declare class SpanBuilder {
+    private parser;
+    constructor();
+    /**
+     * Build trace entries from parsed log lines
+     */
+    buildTraceEntries(lines: ParsedLogLine[]): TraceEntry[];
+    /**
+     * Build a single trace entry from a parsed log line
+     */
+    private buildTraceEntry;
+    /**
+     * Generate a virtual trace ID when no real traceId is present
+     * Uses function name and timestamp to create a pseudo-traceId
+     */
+    generateVirtualTraceId(functionName: string, timestamp: string): string;
+    /**
+     * Extract trace ID from log line
+     */
+    private extractTraceId;
+    /**
+     * Calculate duration between enter and quit entries
+     */
+    calculateDuration(enter: TraceEntry, quit: TraceEntry): number;
+    /**
+     * Pair enter and quit entries
+     */
+    pairEnterQuit(entries: TraceEntry[]): PairedSpan[];
+    /**
+     * Build a call tree from trace entries using call stack tracking
+     *
+     * Enhanced to support both:
+     * 1. Traditional enter/quit pair-based tree building (from log files)
+     * 2. Parent-child hierarchy-based tree building (from SQLite spans)
+     */
+    buildCallTree(entries: TraceEntry[]): TraceTreeNode | null;
+    /**
+     * Build call tree from parent-child span hierarchy (for SQLite spans)
+     */
+    buildCallTreeFromHierarchy(entries: TraceEntry[]): TraceTreeNode | null;
+    /**
+     * Build call tree from traditional enter/quit pairs (for log files)
+     */
+    buildCallTreeFromPairs(entries: TraceEntry[]): TraceTreeNode | null;
+    /**
+     * Build a tree node from a paired span
+     */
+    private buildNodeFromPaired;
+    /**
+     * Merge entries from multiple functions into a single call tree
+     */
+    buildMergedTree(entriesByFunction: Map<string, TraceEntry[]>): TraceTreeNode | null;
+    /**
+     * Get duration summary for entries
+     */
+    getDurationSummary(entries: TraceEntry[]): Map<string, {
+        count: number;
+        totalMs: number;
+        avgMs: number;
+    }>;
+}
+export {};

package/dist/env/debug/reader/log-reader.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @fileoverview Log Reader
+ *
+ * Reads log files with support for streaming and filtering.
+ */
+import type { ParserOptions } from '../types';
+/**
+ * Get XDG data home directory
+ */
+export declare function getXDGDataHome(): string;
+/**
+ * Log Reader for reading and parsing log files
+ */
+export declare class LogReader {
+    private logDir;
+    constructor(options?: {
+        logDir?: string;
+    });
+    /**
+     * Get the full path to a log file
+     */
+    getLogPath(filename?: string): string;
+    /**
+     * 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.
+     */
+    findLogFiles(pattern?: string): Promise<string[]>;
+    /**
+     * Get default log directory
+     */
+    getDefaultLogDir(): string;
+    /**
+     * Read lines from a log file with optional filtering
+     */
+    readLines(filepath: string, options?: ParserOptions): AsyncGenerator<string>;
+    /**
+     * Extract timestamp from a log line
+     */
+    extractTimestamp(line: string): number | null;
+    /**
+     * Parse time string to timestamp
+     * Supports ISO format and relative time like "1h", "30m"
+     */
+    parseTime(timeStr: string): number;
+    /**
+     * Read file content directly (for small files)
+     */
+    readFile(filepath: string): Promise<string>;
+    /**
+     * Check if a log file exists
+     */
+    exists(filepath: string): boolean;
+}

package/dist/env/debug/reader/span-db-reader.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @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, TraceSummary } from '../types';
+import type { SpanStorage } from '../../log-trace/types';
+/**
+ * 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 declare class SpanDbReader {
+    private storage;
+    private dbPath;
+    private sqliteDb;
+    constructor(options?: SpanDbReaderOptions);
+    /**
+     * Initialize the reader with storage
+     */
+    initialize(): Promise<void>;
+    /**
+     * Initialize SQLite storage directly
+     */
+    private initSqliteStorage;
+    /**
+     * Get trace entries for a specific traceId
+     */
+    getTraceEntries(traceId: string): Promise<TraceEntry[]>;
+    /**
+     * List all trace IDs
+     */
+    listTraceIds(limit?: number): Promise<TraceSummary>;
+    /**
+     * Convert spans to TraceEntry format
+     *
+     * Now properly extracts spanId and parentSpanId for tree building
+     */
+    private spansToEntries;
+    /**
+     * Convert span attributes to params format
+     */
+    private attributesToParams;
+    /**
+     * Get the underlying storage
+     */
+    getStorage(): SpanStorage | null;
+    /**
+     * Close the reader and cleanup resources
+     */
+    close(): void;
+}
+/**
+ * Create a SpanDbReader from a database path
+ */
+export declare function createSpanDbReader(dbPath: string): Promise<SpanDbReader>;
+/**
+ * Create a SpanDbReader from an existing storage instance
+ */
+export declare function createSpanDbReaderFromStorage(storage: SpanStorage): SpanDbReader;