@compilr-dev/agents 0.0.1

package/dist/tracing/otel.js

@@ -0,0 +1,246 @@
+/**
+ * OpenTelemetry Integration
+ *
+ * Provides optional integration with OpenTelemetry for exporting traces
+ * to OTel-compatible backends (Jaeger, Zipkin, etc.)
+ *
+ * Requires optional peer dependency: @opentelemetry/api
+ */
+/**
+ * Error thrown when OpenTelemetry SDK is not installed
+ */
+export class OTelNotInstalledError extends Error {
+    constructor() {
+        super('OpenTelemetry SDK is not installed. ' +
+            'Install it with: npm install @opentelemetry/api @opentelemetry/sdk-trace-node');
+        this.name = 'OTelNotInstalledError';
+    }
+}
+/**
+ * Check if a value is an OTelNotInstalledError
+ */
+export function isOTelNotInstalledError(error) {
+    return error instanceof Error && error.name === 'OTelNotInstalledError';
+}
+// Cache for OTel SDK
+let otelCache = null;
+/**
+ * Dynamically load OpenTelemetry SDK
+ *
+ * @throws OTelNotInstalledError if SDK is not installed
+ */
+async function getOTelSDK() {
+    if (otelCache)
+        return otelCache;
+    try {
+        // Use dynamic import with string to avoid TypeScript trying to resolve the module
+        const modulePath = '@opentelemetry/api';
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const api = await import(modulePath);
+        otelCache = {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
+            trace: api.trace,
+        };
+        return otelCache;
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            (error.message.includes('Cannot find module') ||
+                error.message.includes('ERR_MODULE_NOT_FOUND'))) {
+            throw new OTelNotInstalledError();
+        }
+        throw error;
+    }
+}
+/**
+ * Create an OpenTelemetry exporter that wraps OTel spans
+ *
+ * This exporter converts our internal Span format to OpenTelemetry spans
+ * and uses the configured OTel tracer to export them.
+ *
+ * @param tracerName - Name for the OTel tracer
+ * @param tracerVersion - Version for the OTel tracer
+ * @returns OTelExporter instance
+ *
+ * @example
+ * ```typescript
+ * // First, set up OpenTelemetry in your application:
+ * // import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+ * // const provider = new NodeTracerProvider();
+ * // provider.register();
+ *
+ * // Then use with TracingManager:
+ * const exporter = await createOTelExporter('my-agent', '1.0.0');
+ * const tracingManager = new TracingManager({
+ *   serviceName: 'my-agent',
+ *   otelExporter: exporter,
+ * });
+ * ```
+ */
+export async function createOTelExporter(tracerName = 'agent-tracing', tracerVersion = '1.0.0') {
+    const sdk = await getOTelSDK();
+    const tracer = sdk.trace.getTracer(tracerName, tracerVersion);
+    return {
+        name: 'opentelemetry',
+        async export(spans) {
+            await Promise.resolve(); // Ensure async function has await
+            // Convert our spans to OTel spans
+            // Note: This creates new OTel spans which will be exported by the configured OTel exporter
+            for (const span of spans) {
+                const otelSpan = tracer.startSpan(span.name, {
+                    startTime: span.startTime,
+                });
+                // Set attributes
+                for (const [key, value] of Object.entries(span.attributes)) {
+                    otelSpan.setAttribute(key, value);
+                }
+                // Add events
+                for (const event of span.events) {
+                    otelSpan.addEvent(event.name, event.attributes);
+                }
+                // Set status
+                const statusCode = span.status === 'ok' ? 1 : span.status === 'error' ? 2 : 0;
+                otelSpan.setStatus({
+                    code: statusCode,
+                    message: span.statusMessage,
+                });
+                // End span
+                otelSpan.end(span.endTime);
+            }
+        },
+        async shutdown() {
+            // OTel handles shutdown through the provider
+        },
+    };
+}
+/**
+ * Create a console exporter for debugging
+ *
+ * This exporter simply logs spans to the console in a readable format.
+ * Useful for development and debugging.
+ *
+ * @param options - Console exporter options
+ * @returns OTelExporter instance
+ *
+ * @example
+ * ```typescript
+ * const exporter = createConsoleExporter({ prettyPrint: true });
+ * const tracingManager = new TracingManager({
+ *   serviceName: 'my-agent',
+ *   otelExporter: exporter,
+ * });
+ * ```
+ */
+export function createConsoleExporter(options = {}) {
+    // eslint-disable-next-line no-console
+    const { prettyPrint = true, output = console.log } = options;
+    return {
+        name: 'console',
+        async export(spans) {
+            await Promise.resolve(); // Ensure async function has await
+            for (const span of spans) {
+                const data = {
+                    traceId: span.traceId,
+                    spanId: span.spanId,
+                    parentSpanId: span.parentSpanId,
+                    name: span.name,
+                    kind: span.kind,
+                    status: span.status,
+                    durationMs: span.durationMs,
+                    attributes: span.attributes,
+                    events: span.events,
+                };
+                if (prettyPrint) {
+                    output(`[SPAN] ${span.name} (${String(span.durationMs ?? 0)}ms) - ${span.status}`);
+                    output(JSON.stringify(data, null, 2));
+                }
+                else {
+                    output(JSON.stringify(data));
+                }
+            }
+        },
+    };
+}
+/**
+ * Create a batch exporter that buffers spans and exports in batches
+ *
+ * @param innerExporter - The actual exporter to use
+ * @param options - Batch options
+ * @returns OTelExporter instance
+ *
+ * @example
+ * ```typescript
+ * const otelExporter = await createOTelExporter();
+ * const batchExporter = createBatchExporter(otelExporter, {
+ *   maxBatchSize: 100,
+ *   flushIntervalMs: 5000,
+ * });
+ * ```
+ */
+export function createBatchExporter(innerExporter, options = {}) {
+    const { maxBatchSize = 100, flushIntervalMs = 5000 } = options;
+    let buffer = [];
+    let flushTimer = null;
+    const flush = async () => {
+        if (buffer.length === 0)
+            return;
+        const spans = buffer;
+        buffer = [];
+        await innerExporter.export(spans);
+    };
+    // Start flush timer
+    flushTimer = setInterval(() => {
+        flush().catch(() => {
+            // Ignore flush errors
+        });
+    }, flushIntervalMs);
+    return {
+        name: `batch:${innerExporter.name}`,
+        async export(spans) {
+            buffer.push(...spans);
+            // Flush if buffer is full
+            if (buffer.length >= maxBatchSize) {
+                await flush();
+            }
+        },
+        async shutdown() {
+            // Clear timer
+            if (flushTimer) {
+                clearInterval(flushTimer);
+                flushTimer = null;
+            }
+            // Final flush
+            await flush();
+            // Shutdown inner exporter
+            await innerExporter.shutdown?.();
+        },
+    };
+}
+/**
+ * Create a multi-exporter that sends to multiple backends
+ *
+ * @param exporters - List of exporters to use
+ * @returns OTelExporter instance
+ *
+ * @example
+ * ```typescript
+ * const multiExporter = createMultiExporter([
+ *   createConsoleExporter(),
+ *   await createOTelExporter(),
+ * ]);
+ * ```
+ */
+export function createMultiExporter(exporters) {
+    return {
+        name: `multi:[${exporters.map((e) => e.name).join(',')}]`,
+        async export(spans) {
+            await Promise.all(exporters.map((e) => e.export(spans)));
+        },
+        async shutdown() {
+            const shutdowns = exporters
+                .map((e) => e.shutdown?.())
+                .filter((p) => p !== undefined);
+            await Promise.all(shutdowns);
+        },
+    };
+}

package/dist/tracing/types.d.ts

@@ -0,0 +1,346 @@
+/**
+ * Tracing System Types
+ *
+ * Provides types for distributed tracing, structured logging, and observability.
+ */
+/**
+ * Span status indicating success, error, or unset
+ */
+export type SpanStatus = 'unset' | 'ok' | 'error';
+/**
+ * Span kind indicating the type of operation
+ */
+export type SpanKind = 'internal' | 'client' | 'server' | 'producer' | 'consumer';
+/**
+ * Attribute value types (compatible with OpenTelemetry)
+ */
+export type AttributeValue = string | number | boolean | string[] | number[] | boolean[];
+/**
+ * Span attributes map
+ */
+export type SpanAttributes = Record<string, AttributeValue>;
+/**
+ * A trace span representing a unit of work
+ */
+export interface Span {
+    /** Unique span identifier */
+    spanId: string;
+    /** Trace ID this span belongs to */
+    traceId: string;
+    /** Parent span ID (undefined for root spans) */
+    parentSpanId?: string;
+    /** Human-readable span name */
+    name: string;
+    /** Span kind */
+    kind: SpanKind;
+    /** Start time in milliseconds since epoch */
+    startTime: number;
+    /** End time in milliseconds since epoch (undefined if still active) */
+    endTime?: number;
+    /** Duration in milliseconds (undefined if still active) */
+    durationMs?: number;
+    /** Span status */
+    status: SpanStatus;
+    /** Status message (typically for errors) */
+    statusMessage?: string;
+    /** Span attributes */
+    attributes: SpanAttributes;
+    /** Span events (timestamped annotations) */
+    events: SpanEvent[];
+}
+/**
+ * Event within a span (timestamped annotation)
+ */
+export interface SpanEvent {
+    /** Event name */
+    name: string;
+    /** Timestamp in milliseconds since epoch */
+    timestamp: number;
+    /** Event attributes */
+    attributes?: SpanAttributes;
+}
+/**
+ * Context for creating a new span
+ */
+export interface SpanContext {
+    /** Trace ID */
+    traceId: string;
+    /** Parent span ID */
+    parentSpanId?: string;
+}
+/**
+ * A complete trace containing multiple spans
+ */
+export interface Trace {
+    /** Unique trace identifier */
+    traceId: string;
+    /** Root span ID */
+    rootSpanId: string;
+    /** All spans in this trace */
+    spans: Span[];
+    /** Trace start time */
+    startTime: number;
+    /** Trace end time (undefined if still active) */
+    endTime?: number;
+    /** Total duration in milliseconds */
+    durationMs?: number;
+    /** Trace-level attributes */
+    attributes: SpanAttributes;
+}
+/**
+ * Standard attribute names following OpenTelemetry semantic conventions
+ */
+export declare const SemanticAttributes: {
+    readonly AGENT_SESSION_ID: "agent.session_id";
+    readonly AGENT_ITERATION: "agent.iteration";
+    readonly AGENT_MAX_ITERATIONS: "agent.max_iterations";
+    readonly LLM_PROVIDER: "llm.provider";
+    readonly LLM_MODEL: "llm.model";
+    readonly LLM_INPUT_TOKENS: "llm.input_tokens";
+    readonly LLM_OUTPUT_TOKENS: "llm.output_tokens";
+    readonly LLM_TOTAL_TOKENS: "llm.total_tokens";
+    readonly LLM_CACHE_READ_TOKENS: "llm.cache_read_tokens";
+    readonly LLM_CACHE_CREATION_TOKENS: "llm.cache_creation_tokens";
+    readonly TOOL_NAME: "tool.name";
+    readonly TOOL_INPUT: "tool.input";
+    readonly TOOL_SUCCESS: "tool.success";
+    readonly TOOL_ERROR: "tool.error";
+    readonly TOOL_RESULT: "tool.result";
+    readonly MESSAGE_ROLE: "message.role";
+    readonly MESSAGE_COUNT: "message.count";
+    readonly ERROR_TYPE: "error.type";
+    readonly ERROR_MESSAGE: "error.message";
+    readonly ERROR_STACK: "error.stack";
+};
+/**
+ * Options for creating a TracingManager
+ */
+export interface TracingManagerOptions {
+    /** Service name for traces */
+    serviceName?: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Default attributes added to all spans */
+    defaultAttributes?: SpanAttributes;
+    /** Maximum spans per trace (prevents memory issues) */
+    maxSpansPerTrace?: number;
+    /** Whether to auto-generate trace IDs */
+    autoGenerateTraceId?: boolean;
+    /** Event handler for tracing events */
+    onEvent?: TracingEventHandler;
+    /** Optional OpenTelemetry exporter */
+    otelExporter?: OTelExporter;
+}
+/**
+ * Options for starting a span
+ */
+export interface StartSpanOptions {
+    /** Span name */
+    name: string;
+    /** Span kind (default: internal) */
+    kind?: SpanKind;
+    /** Parent span context (if not provided, uses current context) */
+    parentContext?: SpanContext;
+    /** Initial attributes */
+    attributes?: SpanAttributes;
+    /** Start time override (default: now) */
+    startTime?: number;
+}
+/**
+ * Options for ending a span
+ */
+export interface EndSpanOptions {
+    /** End time override (default: now) */
+    endTime?: number;
+    /** Final status */
+    status?: SpanStatus;
+    /** Status message */
+    statusMessage?: string;
+    /** Additional attributes to add */
+    attributes?: SpanAttributes;
+}
+/**
+ * Events emitted by TracingManager
+ */
+export type TracingEvent = {
+    type: 'trace:started';
+    traceId: string;
+    timestamp: number;
+} | {
+    type: 'trace:ended';
+    traceId: string;
+    durationMs: number;
+    spanCount: number;
+} | {
+    type: 'span:started';
+    spanId: string;
+    traceId: string;
+    name: string;
+    parentSpanId?: string;
+} | {
+    type: 'span:ended';
+    spanId: string;
+    traceId: string;
+    durationMs: number;
+    status: SpanStatus;
+} | {
+    type: 'span:event';
+    spanId: string;
+    traceId: string;
+    eventName: string;
+} | {
+    type: 'span:error';
+    spanId: string;
+    traceId: string;
+    error: Error;
+} | {
+    type: 'export:success';
+    traceId: string;
+    exporter: string;
+} | {
+    type: 'export:error';
+    traceId: string;
+    exporter: string;
+    error: Error;
+};
+/**
+ * Handler for tracing events
+ */
+export type TracingEventHandler = (event: TracingEvent) => void;
+/**
+ * OpenTelemetry exporter interface (simplified)
+ * Allows integration with any OTel-compatible backend
+ */
+export interface OTelExporter {
+    /** Exporter name for logging */
+    name: string;
+    /** Export spans */
+    export(spans: Span[]): Promise<void>;
+    /** Shutdown the exporter */
+    shutdown?(): Promise<void>;
+}
+/**
+ * OpenTelemetry SDK types (defined here to avoid importing optional dependency)
+ */
+export type OTelSDK = {
+    trace: {
+        getTracer(name: string, version?: string): OTelTracer;
+    };
+};
+export type OTelTracer = {
+    startSpan(name: string, options?: unknown): OTelSpan;
+};
+export type OTelSpan = {
+    setAttribute(key: string, value: AttributeValue): void;
+    setStatus(status: {
+        code: number;
+        message?: string;
+    }): void;
+    addEvent(name: string, attributes?: Record<string, unknown>): void;
+    end(endTime?: number): void;
+    spanContext(): {
+        traceId: string;
+        spanId: string;
+    };
+};
+/**
+ * Log levels
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Structured log entry
+ */
+export interface LogEntry {
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** Timestamp in ISO format */
+    timestamp: string;
+    /** Trace ID for correlation */
+    traceId?: string;
+    /** Span ID for correlation */
+    spanId?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Additional structured data */
+    data?: Record<string, unknown>;
+    /** Error information */
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Logger interface for structured logging
+ */
+export interface StructuredLogger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, error?: Error, data?: Record<string, unknown>): void;
+    /** Create a child logger with additional context */
+    child(context: Record<string, unknown>): StructuredLogger;
+    /** Set correlation IDs */
+    setCorrelation(traceId?: string, spanId?: string, sessionId?: string): void;
+}
+/**
+ * Options for creating a structured logger
+ */
+export interface StructuredLoggerOptions {
+    /** Minimum log level */
+    level?: LogLevel;
+    /** Service name */
+    serviceName?: string;
+    /** Pretty print JSON (default: false for production) */
+    prettyPrint?: boolean;
+    /** Output function (default: console.log) */
+    output?: (entry: LogEntry) => void;
+    /** Initial context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Configuration for built-in tracing hooks
+ */
+export interface TracingHooksConfig {
+    /** Trace LLM calls */
+    traceLLM?: boolean;
+    /** Trace tool executions */
+    traceTools?: boolean;
+    /** Trace iterations */
+    traceIterations?: boolean;
+    /** Include input/output in attributes (may be verbose) */
+    includeIO?: boolean;
+    /** Truncate long values at this length */
+    truncateAt?: number;
+    /** Custom attribute mapper */
+    attributeMapper?: (phase: 'llm' | 'tool' | 'iteration', data: Record<string, unknown>) => SpanAttributes;
+}
+/**
+ * Context passed to tracing hooks
+ */
+export interface TracingHookContext {
+    /** Tracing manager instance */
+    manager: TracingManagerInterface;
+    /** Current trace ID */
+    traceId: string;
+    /** Current span context */
+    spanContext?: SpanContext;
+    /** Session ID */
+    sessionId: string;
+}
+/**
+ * Interface for TracingManager (for type references without circular deps)
+ */
+export interface TracingManagerInterface {
+    startTrace(attributes?: SpanAttributes): string;
+    endTrace(traceId: string): Trace | undefined;
+    startSpan(options: StartSpanOptions): Span;
+    endSpan(spanId: string, options?: EndSpanOptions): Span | undefined;
+    addSpanEvent(spanId: string, name: string, attributes?: SpanAttributes): void;
+    setSpanAttributes(spanId: string, attributes: SpanAttributes): void;
+    setSpanStatus(spanId: string, status: SpanStatus, message?: string): void;
+    getCurrentSpan(): Span | undefined;
+    getTrace(traceId: string): Trace | undefined;
+}

package/dist/tracing/types.js

@@ -0,0 +1,38 @@
+/**
+ * Tracing System Types
+ *
+ * Provides types for distributed tracing, structured logging, and observability.
+ */
+// ============================================================================
+// Semantic Conventions
+// ============================================================================
+/**
+ * Standard attribute names following OpenTelemetry semantic conventions
+ */
+export const SemanticAttributes = {
+    // Agent attributes
+    AGENT_SESSION_ID: 'agent.session_id',
+    AGENT_ITERATION: 'agent.iteration',
+    AGENT_MAX_ITERATIONS: 'agent.max_iterations',
+    // LLM attributes
+    LLM_PROVIDER: 'llm.provider',
+    LLM_MODEL: 'llm.model',
+    LLM_INPUT_TOKENS: 'llm.input_tokens',
+    LLM_OUTPUT_TOKENS: 'llm.output_tokens',
+    LLM_TOTAL_TOKENS: 'llm.total_tokens',
+    LLM_CACHE_READ_TOKENS: 'llm.cache_read_tokens',
+    LLM_CACHE_CREATION_TOKENS: 'llm.cache_creation_tokens',
+    // Tool attributes
+    TOOL_NAME: 'tool.name',
+    TOOL_INPUT: 'tool.input',
+    TOOL_SUCCESS: 'tool.success',
+    TOOL_ERROR: 'tool.error',
+    TOOL_RESULT: 'tool.result',
+    // Message attributes
+    MESSAGE_ROLE: 'message.role',
+    MESSAGE_COUNT: 'message.count',
+    // Error attributes
+    ERROR_TYPE: 'error.type',
+    ERROR_MESSAGE: 'error.message',
+    ERROR_STACK: 'error.stack',
+};

package/dist/utils/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Utility functions
+ */
+/**
+ * Generate a unique ID for tool uses
+ */
+export declare function generateId(): string;
+/**
+ * Sleep for a specified duration
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Retry a function with exponential backoff
+ */
+export declare function retry<T>(fn: () => Promise<T>, options?: {
+    maxRetries?: number;
+    baseDelay?: number;
+    maxDelay?: number;
+}): Promise<T>;
+/**
+ * Truncate a string to a maximum length
+ */
+export declare function truncate(str: string, maxLength: number, suffix?: string): string;

package/dist/utils/index.js

@@ -0,0 +1,44 @@
+/**
+ * Utility functions
+ */
+/**
+ * Generate a unique ID for tool uses
+ */
+export function generateId() {
+    return `toolu_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 9)}`;
+}
+/**
+ * Sleep for a specified duration
+ */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Retry a function with exponential backoff
+ */
+export async function retry(fn, options = {}) {
+    const { maxRetries = 3, baseDelay = 1000, maxDelay = 10000 } = options;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (attempt < maxRetries) {
+                const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
+                await sleep(delay);
+            }
+        }
+    }
+    throw lastError ?? new Error('Retry failed with no error captured');
+}
+/**
+ * Truncate a string to a maximum length
+ */
+export function truncate(str, maxLength, suffix = '...') {
+    if (str.length <= maxLength) {
+        return str;
+    }
+    return str.slice(0, maxLength - suffix.length) + suffix;
+}