@compilr-dev/agents 0.0.1

package/dist/tracing/hooks.js

@@ -0,0 +1,377 @@
+/**
+ * Built-in Tracing Hooks
+ *
+ * Pre-built hooks for common tracing patterns that integrate with the HooksManager.
+ * These hooks automatically create spans for LLM calls, tool executions, and iterations.
+ */
+import { SemanticAttributes } from './types.js';
+/**
+ * Truncate a value to a maximum length
+ */
+function truncate(value, maxLength) {
+    const str = typeof value === 'string' ? value : JSON.stringify(value);
+    if (str.length <= maxLength)
+        return str;
+    return str.slice(0, maxLength - 3) + '...';
+}
+/**
+ * Create tracing hooks that automatically instrument agent execution
+ *
+ * @param manager - TracingManager instance
+ * @param config - Tracing hooks configuration
+ * @returns HooksConfig with tracing hooks
+ *
+ * @example
+ * ```typescript
+ * const tracingManager = new TracingManager({ serviceName: 'my-agent' });
+ * const tracingHooks = createTracingHooks(tracingManager, {
+ *   traceLLM: true,
+ *   traceTools: true,
+ *   traceIterations: true,
+ * });
+ *
+ * const agent = new Agent({
+ *   provider,
+ *   hooks: tracingHooks,
+ * });
+ * ```
+ */
+export function createTracingHooks(manager, config = {}) {
+    const { traceLLM = true, traceTools = true, traceIterations = true, includeIO = false, truncateAt = 1000, attributeMapper, } = config;
+    // Track active spans per session
+    const activeContexts = new Map();
+    // Get or create context for a session
+    const getContext = (sessionId) => {
+        let ctx = activeContexts.get(sessionId);
+        if (!ctx) {
+            ctx = {};
+            activeContexts.set(sessionId, ctx);
+        }
+        return ctx;
+    };
+    const hooks = {};
+    // ============================================================================
+    // Iteration Hooks
+    // ============================================================================
+    if (traceIterations) {
+        const beforeIteration = async (ctx) => {
+            await Promise.resolve(); // Ensure async function has await
+            const spanCtx = getContext(ctx.sessionId);
+            // Start iteration span
+            const span = manager.startSpan({
+                name: `iteration-${String(ctx.iteration)}`,
+                kind: 'internal',
+                attributes: {
+                    [SemanticAttributes.AGENT_SESSION_ID]: ctx.sessionId,
+                    [SemanticAttributes.AGENT_ITERATION]: ctx.iteration,
+                    [SemanticAttributes.AGENT_MAX_ITERATIONS]: ctx.maxIterations,
+                    [SemanticAttributes.MESSAGE_COUNT]: ctx.messages.length,
+                    ...(attributeMapper?.('iteration', { iteration: ctx.iteration }) ?? {}),
+                },
+            });
+            spanCtx.iterationSpanId = span.spanId;
+            return undefined;
+        };
+        const afterIteration = async (ctx) => {
+            await Promise.resolve(); // Ensure async function has await
+            const spanCtx = getContext(ctx.sessionId);
+            if (spanCtx.iterationSpanId) {
+                manager.setSpanAttributes(spanCtx.iterationSpanId, {
+                    'iteration.tool_calls': ctx.toolCalls.length,
+                    'iteration.completed_with_text': ctx.completedWithText,
+                });
+                manager.endSpan(spanCtx.iterationSpanId, {
+                    status: 'ok',
+                });
+                spanCtx.iterationSpanId = undefined;
+            }
+            return undefined;
+        };
+        hooks.beforeIteration = [beforeIteration];
+        hooks.afterIteration = [afterIteration];
+    }
+    // ============================================================================
+    // LLM Hooks
+    // ============================================================================
+    if (traceLLM) {
+        const beforeLLM = async (ctx) => {
+            await Promise.resolve(); // Ensure async function has await
+            const spanCtx = getContext(ctx.sessionId);
+            const attributes = {
+                [SemanticAttributes.AGENT_SESSION_ID]: ctx.sessionId,
+                [SemanticAttributes.MESSAGE_COUNT]: ctx.messages.length,
+                'llm.tool_count': ctx.tools.length,
+                ...(attributeMapper?.('llm', { messageCount: ctx.messages.length }) ?? {}),
+            };
+            // Optionally include messages (can be verbose)
+            if (includeIO && ctx.messages.length > 0) {
+                const lastMessage = ctx.messages[ctx.messages.length - 1];
+                attributes['llm.last_message_role'] = lastMessage.role;
+                if (typeof lastMessage.content === 'string') {
+                    attributes['llm.last_message_content'] = truncate(lastMessage.content, truncateAt);
+                }
+            }
+            const span = manager.startSpan({
+                name: 'llm-call',
+                kind: 'client',
+                attributes,
+                parentContext: spanCtx.iterationSpanId
+                    ? {
+                        traceId: manager.getSpan(spanCtx.iterationSpanId)?.traceId ?? '',
+                        parentSpanId: spanCtx.iterationSpanId,
+                    }
+                    : undefined,
+            });
+            spanCtx.llmSpanId = span.spanId;
+            return undefined;
+        };
+        const afterLLM = async (ctx) => {
+            await Promise.resolve(); // Ensure async function has await
+            const spanCtx = getContext(ctx.sessionId);
+            if (spanCtx.llmSpanId) {
+                const attributes = {
+                    'llm.has_tool_calls': ctx.toolUses.length > 0,
+                    'llm.tool_call_count': ctx.toolUses.length,
+                };
+                // Add usage if available
+                if (ctx.usage) {
+                    attributes[SemanticAttributes.LLM_INPUT_TOKENS] = ctx.usage.inputTokens;
+                    attributes[SemanticAttributes.LLM_OUTPUT_TOKENS] = ctx.usage.outputTokens;
+                    attributes[SemanticAttributes.LLM_TOTAL_TOKENS] =
+                        ctx.usage.inputTokens + ctx.usage.outputTokens;
+                }
+                // Optionally include response text
+                if (includeIO && ctx.text) {
+                    attributes['llm.response_text'] = truncate(ctx.text, truncateAt);
+                }
+                manager.setSpanAttributes(spanCtx.llmSpanId, attributes);
+                manager.endSpan(spanCtx.llmSpanId, {
+                    status: 'ok',
+                    attributes: {
+                        'llm.duration_ms': ctx.durationMs,
+                    },
+                });
+                spanCtx.llmSpanId = undefined;
+            }
+            return undefined;
+        };
+        hooks.beforeLLM = [beforeLLM];
+        hooks.afterLLM = [afterLLM];
+    }
+    // ============================================================================
+    // Tool Hooks
+    // ============================================================================
+    if (traceTools) {
+        const beforeTool = async (ctx) => {
+            await Promise.resolve(); // Ensure async function has await
+            const spanCtx = getContext(ctx.sessionId);
+            const attributes = {
+                [SemanticAttributes.AGENT_SESSION_ID]: ctx.sessionId,
+                [SemanticAttributes.TOOL_NAME]: ctx.toolName,
+                ...(attributeMapper?.('tool', { toolName: ctx.toolName }) ?? {}),
+            };
+            // Optionally include input
+            if (includeIO) {
+                attributes[SemanticAttributes.TOOL_INPUT] = truncate(ctx.input, truncateAt);
+            }
+            // Determine parent span (prefer LLM span, fall back to iteration span)
+            let parentContext;
+            if (spanCtx.llmSpanId) {
+                const llmSpan = manager.getSpan(spanCtx.llmSpanId);
+                if (llmSpan) {
+                    parentContext = { traceId: llmSpan.traceId, parentSpanId: llmSpan.spanId };
+                }
+            }
+            else if (spanCtx.iterationSpanId) {
+                const iterSpan = manager.getSpan(spanCtx.iterationSpanId);
+                if (iterSpan) {
+                    parentContext = { traceId: iterSpan.traceId, parentSpanId: iterSpan.spanId };
+                }
+            }
+            const span = manager.startSpan({
+                name: `tool:${ctx.toolName}`,
+                kind: 'internal',
+                attributes,
+                parentContext,
+            });
+            spanCtx.toolSpanId = span.spanId;
+            return undefined;
+        };
+        const afterTool = async (ctx) => {
+            await Promise.resolve(); // Ensure async function has await
+            const spanCtx = getContext(ctx.sessionId);
+            if (spanCtx.toolSpanId) {
+                const attributes = {
+                    [SemanticAttributes.TOOL_SUCCESS]: ctx.result.success,
+                    'tool.duration_ms': ctx.durationMs,
+                };
+                if (!ctx.result.success && ctx.result.error) {
+                    attributes[SemanticAttributes.TOOL_ERROR] = ctx.result.error;
+                }
+                // Optionally include result
+                if (includeIO && ctx.result.result !== undefined) {
+                    attributes[SemanticAttributes.TOOL_RESULT] = truncate(ctx.result.result, truncateAt);
+                }
+                manager.setSpanAttributes(spanCtx.toolSpanId, attributes);
+                manager.endSpan(spanCtx.toolSpanId, {
+                    status: ctx.result.success ? 'ok' : 'error',
+                    statusMessage: ctx.result.error,
+                });
+                spanCtx.toolSpanId = undefined;
+            }
+            return undefined;
+        };
+        hooks.beforeTool = [beforeTool];
+        hooks.afterTool = [afterTool];
+    }
+    // ============================================================================
+    // Error Hooks
+    // ============================================================================
+    const onError = async (ctx) => {
+        await Promise.resolve(); // Ensure async function has await
+        const spanCtx = getContext(ctx.sessionId);
+        // Record error on the appropriate span
+        const spanId = spanCtx.toolSpanId ?? spanCtx.llmSpanId ?? spanCtx.iterationSpanId;
+        if (spanId) {
+            manager.recordError(spanId, ctx.error);
+        }
+        return undefined;
+    };
+    hooks.onError = [onError];
+    return hooks;
+}
+/**
+ * Create a simple logging hook that logs all agent events
+ *
+ * @param logger - Logger function (default: console.log)
+ * @returns HooksConfig with logging hooks
+ *
+ * @example
+ * ```typescript
+ * const loggingHooks = createLoggingHooks((msg) => myLogger.info(msg));
+ * const agent = new Agent({ provider, hooks: loggingHooks });
+ * ```
+ */
+export function createLoggingHooks(
+// eslint-disable-next-line no-console
+logger = console.log) {
+    return {
+        beforeIteration: [
+            async (ctx) => {
+                await Promise.resolve();
+                logger(`[iteration:${String(ctx.iteration)}] Starting`, {
+                    sessionId: ctx.sessionId,
+                    messageCount: ctx.messages.length,
+                });
+                return undefined;
+            },
+        ],
+        afterIteration: [
+            async (ctx) => {
+                await Promise.resolve();
+                logger(`[iteration:${String(ctx.iteration)}] Completed`, {
+                    sessionId: ctx.sessionId,
+                    toolCalls: ctx.toolCalls.length,
+                    completedWithText: ctx.completedWithText,
+                });
+                return undefined;
+            },
+        ],
+        beforeLLM: [
+            async (ctx) => {
+                await Promise.resolve();
+                logger('[llm] Calling LLM', {
+                    sessionId: ctx.sessionId,
+                    messageCount: ctx.messages.length,
+                    toolCount: ctx.tools.length,
+                });
+                return undefined;
+            },
+        ],
+        afterLLM: [
+            async (ctx) => {
+                await Promise.resolve();
+                logger('[llm] LLM responded', {
+                    sessionId: ctx.sessionId,
+                    durationMs: ctx.durationMs,
+                    hasToolUses: ctx.toolUses.length > 0,
+                    usage: ctx.usage,
+                });
+                return undefined;
+            },
+        ],
+        beforeTool: [
+            async (ctx) => {
+                await Promise.resolve();
+                logger(`[tool:${ctx.toolName}] Executing`, {
+                    sessionId: ctx.sessionId,
+                    toolName: ctx.toolName,
+                });
+                return undefined;
+            },
+        ],
+        afterTool: [
+            async (ctx) => {
+                await Promise.resolve();
+                logger(`[tool:${ctx.toolName}] Completed`, {
+                    sessionId: ctx.sessionId,
+                    toolName: ctx.toolName,
+                    durationMs: ctx.durationMs,
+                    success: ctx.result.success,
+                });
+                return undefined;
+            },
+        ],
+        onError: [
+            async (ctx) => {
+                await Promise.resolve();
+                logger(`[error:${ctx.phase}] Error occurred`, {
+                    sessionId: ctx.sessionId,
+                    phase: ctx.phase,
+                    toolName: ctx.toolName,
+                    error: ctx.error.message,
+                });
+                return undefined;
+            },
+        ],
+    };
+}
+/**
+ * Merge multiple HooksConfig objects
+ *
+ * @param configs - HooksConfig objects to merge
+ * @returns Merged HooksConfig
+ *
+ * @example
+ * ```typescript
+ * const hooks = mergeHooks(tracingHooks, loggingHooks, customHooks);
+ * const agent = new Agent({ provider, hooks });
+ * ```
+ */
+export function mergeHooks(...configs) {
+    const merged = {};
+    for (const config of configs) {
+        if (config.beforeIteration) {
+            merged.beforeIteration = [...(merged.beforeIteration ?? []), ...config.beforeIteration];
+        }
+        if (config.afterIteration) {
+            merged.afterIteration = [...(merged.afterIteration ?? []), ...config.afterIteration];
+        }
+        if (config.beforeLLM) {
+            merged.beforeLLM = [...(merged.beforeLLM ?? []), ...config.beforeLLM];
+        }
+        if (config.afterLLM) {
+            merged.afterLLM = [...(merged.afterLLM ?? []), ...config.afterLLM];
+        }
+        if (config.beforeTool) {
+            merged.beforeTool = [...(merged.beforeTool ?? []), ...config.beforeTool];
+        }
+        if (config.afterTool) {
+            merged.afterTool = [...(merged.afterTool ?? []), ...config.afterTool];
+        }
+        if (config.onError) {
+            merged.onError = [...(merged.onError ?? []), ...config.onError];
+        }
+    }
+    return merged;
+}

package/dist/tracing/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Tracing System - Observability and distributed tracing for agents
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   TracingManager,
+ *   createTracingHooks,
+ *   createStructuredLogger,
+ *   SemanticAttributes,
+ * } from '@compilr-dev/agents';
+ *
+ * // Create tracing manager
+ * const tracingManager = new TracingManager({
+ *   serviceName: 'my-agent',
+ *   defaultAttributes: { environment: 'production' },
+ * });
+ *
+ * // Create tracing hooks for automatic instrumentation
+ * const tracingHooks = createTracingHooks(tracingManager, {
+ *   traceLLM: true,
+ *   traceTools: true,
+ *   traceIterations: true,
+ * });
+ *
+ * // Create structured logger
+ * const logger = createStructuredLogger({
+ *   level: 'info',
+ *   serviceName: 'my-agent',
+ * });
+ *
+ * // Use with Agent
+ * const agent = new Agent({
+ *   provider,
+ *   hooks: tracingHooks,
+ * });
+ *
+ * // Manual tracing
+ * const traceId = tracingManager.startTrace();
+ * const span = tracingManager.startSpan({ name: 'process-request' });
+ * // ... do work ...
+ * tracingManager.endSpan(span.spanId, { status: 'ok' });
+ * tracingManager.endTrace(traceId);
+ * ```
+ */
+export { TracingManager } from './manager.js';
+export { createTracingHooks, createLoggingHooks, mergeHooks } from './hooks.js';
+export { createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, } from './logging.js';
+export { createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, } from './otel.js';
+export type { Span, SpanStatus, SpanKind, SpanAttributes, SpanContext, SpanEvent, AttributeValue, Trace, TracingManagerOptions, StartSpanOptions, EndSpanOptions, TracingHooksConfig, TracingEvent, TracingEventHandler, OTelExporter, OTelSDK, OTelTracer, OTelSpan, LogLevel, LogEntry, StructuredLogger, StructuredLoggerOptions, TracingHookContext, TracingManagerInterface, } from './types.js';
+export { SemanticAttributes } from './types.js';

package/dist/tracing/index.js

@@ -0,0 +1,55 @@
+/**
+ * Tracing System - Observability and distributed tracing for agents
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   TracingManager,
+ *   createTracingHooks,
+ *   createStructuredLogger,
+ *   SemanticAttributes,
+ * } from '@compilr-dev/agents';
+ *
+ * // Create tracing manager
+ * const tracingManager = new TracingManager({
+ *   serviceName: 'my-agent',
+ *   defaultAttributes: { environment: 'production' },
+ * });
+ *
+ * // Create tracing hooks for automatic instrumentation
+ * const tracingHooks = createTracingHooks(tracingManager, {
+ *   traceLLM: true,
+ *   traceTools: true,
+ *   traceIterations: true,
+ * });
+ *
+ * // Create structured logger
+ * const logger = createStructuredLogger({
+ *   level: 'info',
+ *   serviceName: 'my-agent',
+ * });
+ *
+ * // Use with Agent
+ * const agent = new Agent({
+ *   provider,
+ *   hooks: tracingHooks,
+ * });
+ *
+ * // Manual tracing
+ * const traceId = tracingManager.startTrace();
+ * const span = tracingManager.startSpan({ name: 'process-request' });
+ * // ... do work ...
+ * tracingManager.endSpan(span.spanId, { status: 'ok' });
+ * tracingManager.endTrace(traceId);
+ * ```
+ */
+// Main manager
+export { TracingManager } from './manager.js';
+// Built-in hooks
+export { createTracingHooks, createLoggingHooks, mergeHooks } from './hooks.js';
+// Structured logging
+export { createStructuredLogger, createNoopLogger, createBufferedLogger, createTracingLogger, formatDuration, formatBytes, redactSensitive, } from './logging.js';
+// OpenTelemetry integration
+export { createOTelExporter, createConsoleExporter, createBatchExporter, createMultiExporter, OTelNotInstalledError, isOTelNotInstalledError, } from './otel.js';
+// Semantic conventions
+export { SemanticAttributes } from './types.js';

package/dist/tracing/logging.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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
+ */
+import type { LogEntry, StructuredLogger, StructuredLoggerOptions } from './types.js';
+/**
+ * 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 declare function createStructuredLogger(options?: StructuredLoggerOptions): StructuredLogger;
+/**
+ * Create a no-op logger (useful for testing or disabling logs)
+ */
+export declare function createNoopLogger(): StructuredLogger;
+/**
+ * Create a logger that buffers entries (useful for testing)
+ */
+export declare function createBufferedLogger(): StructuredLogger & {
+    entries: LogEntry[];
+    clear: () => void;
+};
+/**
+ * Format duration in human-readable format
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Format bytes in human-readable format
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * Redact sensitive data from an object
+ */
+export declare function redactSensitive(data: Record<string, unknown>, sensitiveKeys?: string[]): Record<string, unknown>;
+/**
+ * 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 declare function createTracingLogger(tracingManager: {
+    getCurrentSpan: () => {
+        spanId: string;
+        traceId: string;
+    } | undefined;
+}, options?: StructuredLoggerOptions): StructuredLogger;