@compilr-dev/agents 0.0.1

package/dist/tracing/logging.js

@@ -0,0 +1,310 @@
+/**
+ * Structured Logging Helpers
+ *
+ * Provides structured logging utilities for agent execution with:
+ * - JSON-formatted log output
+ * - Correlation IDs (trace, span, session)
+ * - Log levels
+ * - Child loggers with inherited context
+ */
+/**
+ * Log level priorities (lower = more verbose)
+ */
+const LOG_LEVEL_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+/**
+ * Create a structured logger
+ *
+ * @param options - Logger options
+ * @returns StructuredLogger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createStructuredLogger({
+ *   level: 'info',
+ *   serviceName: 'my-agent',
+ *   prettyPrint: process.env.NODE_ENV !== 'production',
+ * });
+ *
+ * logger.info('Agent started', { version: '1.0.0' });
+ * logger.error('Tool failed', new Error('timeout'), { toolName: 'bash' });
+ *
+ * // Create child logger with context
+ * const sessionLogger = logger.child({ sessionId: 'abc123' });
+ * sessionLogger.info('Processing request'); // includes sessionId
+ * ```
+ */
+export function createStructuredLogger(options = {}) {
+    const { level = 'info', serviceName = 'agent', prettyPrint = false, output = defaultOutput, context = {}, } = options;
+    const minLevel = LOG_LEVEL_PRIORITY[level];
+    // Correlation IDs
+    let traceId;
+    let spanId;
+    let sessionId;
+    function shouldLog(msgLevel) {
+        return LOG_LEVEL_PRIORITY[msgLevel] >= minLevel;
+    }
+    function createEntry(msgLevel, message, data, error) {
+        const entry = {
+            level: msgLevel,
+            message,
+            timestamp: new Date().toISOString(),
+            traceId,
+            spanId,
+            sessionId,
+            data: {
+                service: serviceName,
+                ...context,
+                ...data,
+            },
+        };
+        if (error) {
+            entry.error = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack,
+            };
+        }
+        // Remove undefined values
+        if (!entry.traceId)
+            delete entry.traceId;
+        if (!entry.spanId)
+            delete entry.spanId;
+        if (!entry.sessionId)
+            delete entry.sessionId;
+        return entry;
+    }
+    function log(entry) {
+        if (prettyPrint) {
+            output(formatPretty(entry));
+        }
+        else {
+            output(entry);
+        }
+    }
+    const logger = {
+        debug(message, data) {
+            if (shouldLog('debug')) {
+                log(createEntry('debug', message, data));
+            }
+        },
+        info(message, data) {
+            if (shouldLog('info')) {
+                log(createEntry('info', message, data));
+            }
+        },
+        warn(message, data) {
+            if (shouldLog('warn')) {
+                log(createEntry('warn', message, data));
+            }
+        },
+        error(message, error, data) {
+            if (shouldLog('error')) {
+                log(createEntry('error', message, data, error));
+            }
+        },
+        child(childContext) {
+            return createStructuredLogger({
+                level,
+                serviceName,
+                prettyPrint,
+                output,
+                context: { ...context, ...childContext },
+            });
+        },
+        setCorrelation(newTraceId, newSpanId, newSessionId) {
+            traceId = newTraceId;
+            spanId = newSpanId;
+            sessionId = newSessionId;
+        },
+    };
+    return logger;
+}
+/**
+ * Default output function - writes to console with appropriate method
+ */
+function defaultOutput(entry) {
+    const json = JSON.stringify(entry);
+    /* eslint-disable no-console */
+    switch (entry.level) {
+        case 'debug':
+            console.debug(json);
+            break;
+        case 'info':
+            console.info(json);
+            break;
+        case 'warn':
+            console.warn(json);
+            break;
+        case 'error':
+            console.error(json);
+            break;
+    }
+    /* eslint-enable no-console */
+}
+/**
+ * Format a log entry for pretty printing
+ */
+function formatPretty(entry) {
+    const levelColors = {
+        debug: '\x1b[90m', // Gray
+        info: '\x1b[36m', // Cyan
+        warn: '\x1b[33m', // Yellow
+        error: '\x1b[31m', // Red
+    };
+    const reset = '\x1b[0m';
+    const color = levelColors[entry.level];
+    const levelStr = entry.level.toUpperCase().padEnd(5);
+    let line = `${color}${levelStr}${reset} ${entry.timestamp} ${entry.message}`;
+    // Add correlation IDs if present
+    const ids = [];
+    if (entry.traceId)
+        ids.push(`trace=${entry.traceId.slice(0, 8)}`);
+    if (entry.spanId)
+        ids.push(`span=${entry.spanId.slice(0, 8)}`);
+    if (entry.sessionId)
+        ids.push(`session=${entry.sessionId.slice(0, 8)}`);
+    if (ids.length > 0) {
+        line += ` [${ids.join(' ')}]`;
+    }
+    // Add data if present
+    if (entry.data && Object.keys(entry.data).length > 0) {
+        line += '\n  ' + JSON.stringify(entry.data);
+    }
+    // Add error if present
+    if (entry.error) {
+        line += `\n  ${color}Error: ${entry.error.name}: ${entry.error.message}${reset}`;
+        if (entry.error.stack) {
+            line += '\n  ' + entry.error.stack.split('\n').slice(1).join('\n  ');
+        }
+    }
+    // Return modified entry with formatted message for pretty output
+    return {
+        ...entry,
+        message: line,
+    };
+}
+/**
+ * Create a no-op logger (useful for testing or disabling logs)
+ */
+export function createNoopLogger() {
+    const noop = () => { };
+    return {
+        debug: noop,
+        info: noop,
+        warn: noop,
+        error: noop,
+        child: () => createNoopLogger(),
+        setCorrelation: noop,
+    };
+}
+/**
+ * Create a logger that buffers entries (useful for testing)
+ */
+export function createBufferedLogger() {
+    const entries = [];
+    const logger = createStructuredLogger({
+        level: 'debug',
+        output: (entry) => entries.push(entry),
+    });
+    return {
+        ...logger,
+        entries,
+        clear: () => {
+            entries.length = 0;
+        },
+    };
+}
+/**
+ * Format duration in human-readable format
+ */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${String(ms)}ms`;
+    if (ms < 60000)
+        return `${(ms / 1000).toFixed(2)}s`;
+    const minutes = Math.floor(ms / 60000);
+    const seconds = ((ms % 60000) / 1000).toFixed(0);
+    return `${String(minutes)}m ${seconds}s`;
+}
+/**
+ * Format bytes in human-readable format
+ */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${String(bytes)}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(2)}KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(2)}MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)}GB`;
+}
+/**
+ * Redact sensitive data from an object
+ */
+export function redactSensitive(data, sensitiveKeys = ['password', 'token', 'secret', 'apiKey', 'api_key', 'authorization']) {
+    const result = {};
+    for (const [key, value] of Object.entries(data)) {
+        const lowerKey = key.toLowerCase();
+        const isSensitive = sensitiveKeys.some((k) => lowerKey.includes(k.toLowerCase()));
+        if (isSensitive) {
+            result[key] = '[REDACTED]';
+        }
+        else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            result[key] = redactSensitive(value, sensitiveKeys);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Create a logger that integrates with TracingManager
+ *
+ * @param tracingManager - TracingManager instance
+ * @param options - Logger options
+ * @returns StructuredLogger that auto-correlates with traces
+ *
+ * @example
+ * ```typescript
+ * const tracingManager = new TracingManager({ serviceName: 'my-agent' });
+ * const logger = createTracingLogger(tracingManager);
+ *
+ * // Logger automatically includes current trace/span IDs
+ * logger.info('Processing request');
+ * ```
+ */
+export function createTracingLogger(tracingManager, options = {}) {
+    const baseLogger = createStructuredLogger(options);
+    const setCorrelationFromSpan = () => {
+        const span = tracingManager.getCurrentSpan();
+        if (span) {
+            baseLogger.setCorrelation(span.traceId, span.spanId);
+        }
+    };
+    return {
+        debug(message, data) {
+            setCorrelationFromSpan();
+            baseLogger.debug(message, data);
+        },
+        info(message, data) {
+            setCorrelationFromSpan();
+            baseLogger.info(message, data);
+        },
+        warn(message, data) {
+            setCorrelationFromSpan();
+            baseLogger.warn(message, data);
+        },
+        error(message, error, data) {
+            setCorrelationFromSpan();
+            baseLogger.error(message, error, data);
+        },
+        child: baseLogger.child.bind(baseLogger),
+        setCorrelation: baseLogger.setCorrelation.bind(baseLogger),
+    };
+}

package/dist/tracing/manager.d.ts

@@ -0,0 +1,160 @@
+/**
+ * TracingManager - Manages distributed tracing for agent execution
+ *
+ * Provides:
+ * - Trace and span management with correlation IDs
+ * - OpenTelemetry-compatible span structure
+ * - Event emission for observability integrations
+ * - Optional export to OTel backends
+ */
+import type { Span, SpanAttributes, SpanContext, SpanStatus, Trace, TracingManagerOptions, StartSpanOptions, EndSpanOptions, TracingEventHandler, TracingManagerInterface } from './types.js';
+/**
+ * Manages distributed tracing for agent operations
+ *
+ * @example
+ * ```typescript
+ * const tracing = new TracingManager({
+ *   serviceName: 'my-agent',
+ *   defaultAttributes: { environment: 'production' },
+ * });
+ *
+ * // Start a trace
+ * const traceId = tracing.startTrace();
+ *
+ * // Create spans
+ * const span = tracing.startSpan({ name: 'process-request' });
+ * span.attributes['request.id'] = '123';
+ *
+ * // End span and trace
+ * tracing.endSpan(span.spanId, { status: 'ok' });
+ * const trace = tracing.endTrace(traceId);
+ * ```
+ */
+export declare class TracingManager implements TracingManagerInterface {
+    private readonly serviceName;
+    private readonly serviceVersion;
+    private readonly defaultAttributes;
+    private readonly maxSpansPerTrace;
+    private readonly autoGenerateTraceId;
+    private readonly traces;
+    private readonly spans;
+    private readonly activeSpanStack;
+    private readonly eventHandlers;
+    private readonly otelExporter?;
+    private spanIdCounter;
+    private traceIdCounter;
+    constructor(options?: TracingManagerOptions);
+    /**
+     * Start a new trace
+     *
+     * @param attributes - Additional trace-level attributes
+     * @returns Trace ID
+     */
+    startTrace(attributes?: SpanAttributes): string;
+    /**
+     * End a trace and optionally export it
+     *
+     * @param traceId - Trace ID to end
+     * @returns Completed trace or undefined if not found
+     */
+    endTrace(traceId: string): Trace | undefined;
+    /**
+     * Get a trace by ID
+     */
+    getTrace(traceId: string): Trace | undefined;
+    /**
+     * Get all active traces
+     */
+    getActiveTraces(): Trace[];
+    /**
+     * Clear a trace from memory
+     */
+    clearTrace(traceId: string): boolean;
+    /**
+     * Start a new span
+     *
+     * @param options - Span options
+     * @returns Created span
+     */
+    startSpan(options: StartSpanOptions): Span;
+    /**
+     * End a span
+     *
+     * @param spanId - Span ID to end
+     * @param options - End options
+     * @returns Ended span or undefined if not found
+     */
+    endSpan(spanId: string, options?: EndSpanOptions): Span | undefined;
+    /**
+     * Get a span by ID
+     */
+    getSpan(spanId: string): Span | undefined;
+    /**
+     * Get the current active span
+     */
+    getCurrentSpan(): Span | undefined;
+    /**
+     * Get current span context for propagation
+     */
+    getCurrentContext(): SpanContext | undefined;
+    /**
+     * Add an event to a span
+     *
+     * @param spanId - Span ID
+     * @param name - Event name
+     * @param attributes - Event attributes
+     */
+    addSpanEvent(spanId: string, name: string, attributes?: SpanAttributes): void;
+    /**
+     * Set attributes on a span
+     *
+     * @param spanId - Span ID
+     * @param attributes - Attributes to set
+     */
+    setSpanAttributes(spanId: string, attributes: SpanAttributes): void;
+    /**
+     * Set span status
+     *
+     * @param spanId - Span ID
+     * @param status - Status
+     * @param message - Optional status message
+     */
+    setSpanStatus(spanId: string, status: SpanStatus, message?: string): void;
+    /**
+     * Record an error on a span
+     *
+     * @param spanId - Span ID
+     * @param error - Error to record
+     */
+    recordError(spanId: string, error: Error): void;
+    /**
+     * Subscribe to tracing events
+     *
+     * @param handler - Event handler
+     * @returns Unsubscribe function
+     */
+    onEvent(handler: TracingEventHandler): () => void;
+    private emit;
+    /**
+     * Export a trace to configured exporter
+     */
+    private exportTrace;
+    /**
+     * Manually export a trace
+     */
+    export(traceId: string): Promise<void>;
+    private generateTraceId;
+    private generateSpanId;
+    /**
+     * Get tracing statistics
+     */
+    getStats(): {
+        activeTraces: number;
+        totalSpans: number;
+        activeSpans: number;
+    };
+    /**
+     * Clear all traces and spans
+     */
+    clear(): void;
+}