attocode 0.1.0

package/dist/src/observability/tracer.js

@@ -0,0 +1,300 @@
+/**
+ * Lesson 19: Tracer
+ *
+ * OpenTelemetry-style distributed tracing for agents.
+ * Tracks operations as spans with parent-child relationships.
+ */
+import { webcrypto } from 'node:crypto';
+// Use webcrypto directly - it's compatible with Web Crypto API
+const crypto = webcrypto;
+// =============================================================================
+// ID GENERATION
+// =============================================================================
+/**
+ * Generate a trace ID (128-bit hex string).
+ */
+function generateTraceId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes).map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Generate a span ID (64-bit hex string).
+ */
+function generateSpanId() {
+    const bytes = new Uint8Array(8);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes).map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Current context stack (for nested spans).
+ */
+const contextStack = [];
+/**
+ * Get current span context.
+ */
+export function getCurrentContext() {
+    return contextStack[contextStack.length - 1];
+}
+/**
+ * Set current span context.
+ */
+function pushContext(context) {
+    contextStack.push(context);
+}
+/**
+ * Remove current span context.
+ */
+function popContext() {
+    return contextStack.pop();
+}
+// =============================================================================
+// TRACER
+// =============================================================================
+/**
+ * Creates and manages spans for distributed tracing.
+ */
+export class Tracer {
+    spans = new Map();
+    traces = new Map();
+    listeners = new Set();
+    serviceName;
+    sampleRate;
+    constructor(serviceName = 'agent', sampleRate = 1.0) {
+        this.serviceName = serviceName;
+        this.sampleRate = sampleRate;
+    }
+    // ===========================================================================
+    // SPAN CREATION
+    // ===========================================================================
+    /**
+     * Start a new span.
+     */
+    startSpan(name, options = {}) {
+        const parentContext = options.parent || getCurrentContext();
+        // Determine if this span should be sampled
+        const sampled = parentContext?.sampled ?? Math.random() < this.sampleRate;
+        const traceId = parentContext?.traceId || generateTraceId();
+        const spanId = generateSpanId();
+        const span = {
+            traceId,
+            spanId,
+            parentId: parentContext?.spanId,
+            name,
+            startTime: Date.now(),
+            kind: options.kind || 'internal',
+            status: { code: 'unset' },
+            attributes: {
+                'service.name': this.serviceName,
+                ...options.attributes,
+            },
+            events: [],
+            links: [],
+        };
+        this.spans.set(spanId, span);
+        // Push context for nested spans
+        pushContext({ traceId, spanId, sampled });
+        // Ensure trace exists
+        if (!this.traces.has(traceId)) {
+            this.traces.set(traceId, {
+                traceId,
+                rootSpan: span,
+                spans: [],
+                attributes: {},
+                startTime: span.startTime,
+            });
+        }
+        this.traces.get(traceId).spans.push(span);
+        this.emit({ type: 'span.start', span });
+        return span;
+    }
+    /**
+     * End a span.
+     */
+    endSpan(span, status) {
+        span.endTime = Date.now();
+        span.duration = span.endTime - span.startTime;
+        span.status = status || { code: 'ok' };
+        // Pop context
+        popContext();
+        // Update trace end time
+        const trace = this.traces.get(span.traceId);
+        if (trace) {
+            trace.endTime = span.endTime;
+            trace.duration = (trace.endTime - trace.startTime);
+        }
+        this.emit({ type: 'span.end', span });
+    }
+    /**
+     * Mark span as error.
+     */
+    setError(span, error) {
+        span.status = {
+            code: 'error',
+            message: error.message,
+        };
+        this.addEvent(span, 'exception', {
+            'exception.type': error.name,
+            'exception.message': error.message,
+            'exception.stacktrace': error.stack || '',
+        });
+    }
+    // ===========================================================================
+    // SPAN ATTRIBUTES AND EVENTS
+    // ===========================================================================
+    /**
+     * Set span attribute.
+     */
+    setAttribute(span, key, value) {
+        span.attributes[key] = value;
+    }
+    /**
+     * Set multiple span attributes.
+     */
+    setAttributes(span, attributes) {
+        Object.assign(span.attributes, attributes);
+    }
+    /**
+     * Add an event to a span.
+     */
+    addEvent(span, name, attributes) {
+        const event = {
+            name,
+            timestamp: Date.now(),
+            attributes,
+        };
+        span.events.push(event);
+    }
+    // ===========================================================================
+    // CONVENIENCE METHODS
+    // ===========================================================================
+    /**
+     * Wrap an async function with a span.
+     */
+    async withSpan(name, fn, options = {}) {
+        const span = this.startSpan(name, options);
+        try {
+            const result = await fn(span);
+            this.endSpan(span, { code: 'ok' });
+            return result;
+        }
+        catch (error) {
+            this.setError(span, error);
+            this.endSpan(span, { code: 'error', message: error.message });
+            throw error;
+        }
+    }
+    /**
+     * Wrap a sync function with a span.
+     */
+    withSpanSync(name, fn, options = {}) {
+        const span = this.startSpan(name, options);
+        try {
+            const result = fn(span);
+            this.endSpan(span, { code: 'ok' });
+            return result;
+        }
+        catch (error) {
+            this.setError(span, error);
+            this.endSpan(span, { code: 'error', message: error.message });
+            throw error;
+        }
+    }
+    // ===========================================================================
+    // TRACE RETRIEVAL
+    // ===========================================================================
+    /**
+     * Get a trace by ID.
+     */
+    getTrace(traceId) {
+        return this.traces.get(traceId);
+    }
+    /**
+     * Get all traces.
+     */
+    getAllTraces() {
+        return Array.from(this.traces.values());
+    }
+    /**
+     * Get a span by ID.
+     */
+    getSpan(spanId) {
+        return this.spans.get(spanId);
+    }
+    /**
+     * Get child spans of a span.
+     */
+    getChildSpans(spanId) {
+        return Array.from(this.spans.values()).filter((s) => s.parentId === spanId);
+    }
+    /**
+     * Clear all traces and spans.
+     */
+    clear() {
+        this.spans.clear();
+        this.traces.clear();
+        contextStack.length = 0;
+    }
+    // ===========================================================================
+    // EVENT HANDLING
+    // ===========================================================================
+    /**
+     * Subscribe to tracer events.
+     */
+    on(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /**
+     * Emit an event.
+     */
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch (err) {
+                console.error('Error in tracer listener:', err);
+            }
+        }
+    }
+}
+// =============================================================================
+// TRACE VISUALIZATION
+// =============================================================================
+/**
+ * Format a trace as a tree.
+ */
+export function formatTraceTree(trace) {
+    const lines = [];
+    const spanMap = new Map(trace.spans.map((s) => [s.spanId, s]));
+    function formatSpan(span, indent, isLast) {
+        const prefix = isLast ? '└── ' : '├── ';
+        const duration = span.duration !== undefined ? `${span.duration}ms` : 'ongoing';
+        const status = span.status.code === 'error' ? '❌' : span.status.code === 'ok' ? '✓' : '○';
+        lines.push(`${indent}${prefix}${status} ${span.name} (${duration})`);
+        const childIndent = indent + (isLast ? '    ' : '│   ');
+        const children = trace.spans.filter((s) => s.parentId === span.spanId);
+        children.forEach((child, i) => {
+            formatSpan(child, childIndent, i === children.length - 1);
+        });
+    }
+    formatSpan(trace.rootSpan, '', true);
+    return lines.join('\n');
+}
+/**
+ * Format span attributes.
+ */
+export function formatSpanAttributes(span) {
+    return Object.entries(span.attributes)
+        .map(([k, v]) => `  ${k}: ${JSON.stringify(v)}`)
+        .join('\n');
+}
+// =============================================================================
+// EXPORTS
+// =============================================================================
+export function createTracer(serviceName = 'agent', sampleRate = 1.0) {
+    return new Tracer(serviceName, sampleRate);
+}
+export const globalTracer = new Tracer();
+//# sourceMappingURL=tracer.js.map

package/dist/src/observability/tracer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracer.js","sourceRoot":"","sources":["../../../src/observability/tracer.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * Lesson 19: Observability & Tracing Types
+ *
+ * Type definitions for tracing, metrics, and logging.
+ */
+/**
+ * A single span in a trace.
+ */
+export interface Span {
+    /** Unique trace identifier (shared by all spans in trace) */
+    traceId: string;
+    /** Unique span identifier */
+    spanId: string;
+    /** Parent span ID (if nested) */
+    parentId?: string;
+    /** Span name (operation being performed) */
+    name: string;
+    /** Start time (Unix timestamp ms) */
+    startTime: number;
+    /** End time (Unix timestamp ms) */
+    endTime?: number;
+    /** Duration in ms */
+    duration?: number;
+    /** Span kind */
+    kind: SpanKind;
+    /** Status */
+    status: SpanStatus;
+    /** Key-value attributes */
+    attributes: Record<string, SpanAttributeValue>;
+    /** Events that occurred during the span */
+    events: SpanEvent[];
+    /** Links to other spans */
+    links: SpanLink[];
+}
+/**
+ * Type of span.
+ */
+export type SpanKind = 'internal' | 'client' | 'server' | 'producer' | 'consumer';
+/**
+ * Span status.
+ */
+export interface SpanStatus {
+    code: 'ok' | 'error' | 'unset';
+    message?: string;
+}
+/**
+ * Attribute value types.
+ */
+export type SpanAttributeValue = string | number | boolean | string[] | number[] | boolean[];
+/**
+ * An event within a span.
+ */
+export interface SpanEvent {
+    /** Event name */
+    name: string;
+    /** Event timestamp */
+    timestamp: number;
+    /** Event attributes */
+    attributes?: Record<string, SpanAttributeValue>;
+}
+/**
+ * Link to another span.
+ */
+export interface SpanLink {
+    /** Linked trace ID */
+    traceId: string;
+    /** Linked span ID */
+    spanId: string;
+    /** Link attributes */
+    attributes?: Record<string, SpanAttributeValue>;
+}
+/**
+ * A complete trace.
+ */
+export interface Trace {
+    /** Trace ID */
+    traceId: string;
+    /** Root span */
+    rootSpan: Span;
+    /** All spans in the trace */
+    spans: Span[];
+    /** Trace-level attributes */
+    attributes: Record<string, SpanAttributeValue>;
+    /** When trace started */
+    startTime: number;
+    /** When trace ended */
+    endTime?: number;
+    /** Total duration */
+    duration?: number;
+}
+/**
+ * Agent-specific metrics.
+ */
+export interface AgentMetrics {
+    /** Input tokens consumed */
+    inputTokens: number;
+    /** Output tokens generated */
+    outputTokens: number;
+    /** Tokens read from cache */
+    cacheReadTokens: number;
+    /** Tokens written to cache */
+    cacheWriteTokens: number;
+    /** Estimated cost in USD */
+    estimatedCost: number;
+    /** Number of tool calls made */
+    toolCalls: number;
+    /** Number of LLM API calls */
+    llmCalls: number;
+    /** Total duration in ms */
+    duration: number;
+    /** Number of errors */
+    errors: number;
+    /** Number of retries */
+    retries: number;
+}
+/**
+ * A metric data point.
+ */
+export interface MetricPoint {
+    /** Metric name */
+    name: string;
+    /** Metric value */
+    value: number;
+    /** Timestamp */
+    timestamp: number;
+    /** Labels */
+    labels: Record<string, string>;
+    /** Metric type */
+    type: MetricType;
+}
+/**
+ * Types of metrics.
+ */
+export type MetricType = 'counter' | 'gauge' | 'histogram' | 'summary';
+/**
+ * Metric aggregations.
+ */
+export interface MetricAggregation {
+    /** Sum of all values */
+    sum: number;
+    /** Number of data points */
+    count: number;
+    /** Minimum value */
+    min: number;
+    /** Maximum value */
+    max: number;
+    /** Average value */
+    avg: number;
+    /** Percentiles */
+    percentiles: {
+        p50: number;
+        p90: number;
+        p95: number;
+        p99: number;
+    };
+}
+/**
+ * Log levels.
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * A log entry.
+ */
+export interface LogEntry {
+    /** Log level */
+    level: LogLevel;
+    /** Log message */
+    message: string;
+    /** Timestamp */
+    timestamp: number;
+    /** Trace ID (for correlation) */
+    traceId?: string;
+    /** Span ID (for correlation) */
+    spanId?: string;
+    /** Structured data */
+    data?: Record<string, unknown>;
+    /** Logger name */
+    logger?: string;
+    /** Error details */
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+}
+/**
+ * Export format.
+ */
+export type ExportFormat = 'console' | 'json' | 'jsonl' | 'otlp';
+/**
+ * Exporter interface.
+ */
+export interface Exporter {
+    /** Export spans */
+    exportSpans(spans: Span[]): Promise<void>;
+    /** Export metrics */
+    exportMetrics(metrics: MetricPoint[]): Promise<void>;
+    /** Export logs */
+    exportLogs(logs: LogEntry[]): Promise<void>;
+    /** Flush pending exports */
+    flush(): Promise<void>;
+}
+/**
+ * Exporter configuration.
+ */
+export interface ExporterConfig {
+    /** Export format */
+    format: ExportFormat;
+    /** Output destination */
+    destination: 'stdout' | 'file' | 'http';
+    /** File path (if destination is 'file') */
+    filePath?: string;
+    /** HTTP endpoint (if destination is 'http') */
+    endpoint?: string;
+    /** Batch size */
+    batchSize: number;
+    /** Flush interval (ms) */
+    flushIntervalMs: number;
+}
+/**
+ * Observability configuration.
+ */
+export interface ObservabilityConfig {
+    /** Enable tracing */
+    tracingEnabled: boolean;
+    /** Enable metrics */
+    metricsEnabled: boolean;
+    /** Enable logging */
+    loggingEnabled: boolean;
+    /** Minimum log level */
+    logLevel: LogLevel;
+    /** Sample rate for traces (0-1) */
+    sampleRate: number;
+    /** Service name */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Environment (dev, staging, prod) */
+    environment: string;
+    /** Exporter configuration */
+    exporter: ExporterConfig;
+}
+/**
+ * Default observability configuration.
+ */
+export declare const DEFAULT_OBSERVABILITY_CONFIG: ObservabilityConfig;
+/**
+ * Observability events.
+ */
+export type ObservabilityEvent = {
+    type: 'span.start';
+    span: Span;
+} | {
+    type: 'span.end';
+    span: Span;
+} | {
+    type: 'metric.recorded';
+    metric: MetricPoint;
+} | {
+    type: 'log.written';
+    log: LogEntry;
+} | {
+    type: 'export.completed';
+    format: ExportFormat;
+    count: number;
+};
+/**
+ * Event listener.
+ */
+export type ObservabilityEventListener = (event: ObservabilityEvent) => void;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/observability/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/observability/types.ts"],"names":[],"mappings":"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"}

package/dist/src/observability/types.js

@@ -0,0 +1,24 @@
+/**
+ * Lesson 19: Observability & Tracing Types
+ *
+ * Type definitions for tracing, metrics, and logging.
+ */
+/**
+ * Default observability configuration.
+ */
+export const DEFAULT_OBSERVABILITY_CONFIG = {
+    tracingEnabled: true,
+    metricsEnabled: true,
+    loggingEnabled: true,
+    logLevel: 'info',
+    sampleRate: 1.0,
+    serviceName: 'agent',
+    environment: 'development',
+    exporter: {
+        format: 'console',
+        destination: 'stdout',
+        batchSize: 100,
+        flushIntervalMs: 5000,
+    },
+};
+//# sourceMappingURL=types.js.map

package/dist/src/observability/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/observability/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqWH;;GAEG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAwB;IAC/D,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,IAAI;IACpB,cAAc,EAAE,IAAI;IACpB,QAAQ,EAAE,MAAM;IAChB,UAAU,EAAE,GAAG;IACf,WAAW,EAAE,OAAO;IACpB,WAAW,EAAE,aAAa;IAC1B,QAAQ,EAAE;QACR,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,QAAQ;QACrB,SAAS,EAAE,GAAG;QACd,eAAe,EAAE,IAAI;KACtB;CACF,CAAC"}