@traccia2/sdk 0.0.1

package/src/__tests__/tracer.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Tests for tracer and provider.
+ */
+
+import { TracerProvider } from '../tracer/provider';
+import { Sampler } from '../processor/sampler';
+
+describe('TracerProvider', () => {
+  it('should create and cache tracers', () => {
+    const provider = new TracerProvider();
+    const tracer1 = provider.getTracer('scope1');
+    const tracer2 = provider.getTracer('scope1');
+
+    expect(tracer1).toBe(tracer2);
+  });
+
+  it('should support multiple tracers', () => {
+    const provider = new TracerProvider();
+    const tracer1 = provider.getTracer('scope1');
+    const tracer2 = provider.getTracer('scope2');
+
+    expect(tracer1).not.toBe(tracer2);
+  });
+
+  it('should set and get sampler', () => {
+    const provider = new TracerProvider();
+    const sampler = new Sampler(0.5);
+
+    provider.setSampler(sampler);
+    expect(provider.getSampler()).toBe(sampler);
+  });
+
+  it('should generate unique IDs', () => {
+    const provider = new TracerProvider();
+    const traceId1 = provider.generateTraceId();
+    const traceId2 = provider.generateTraceId();
+
+    expect(traceId1).not.toBe(traceId2);
+    expect(traceId1).toHaveLength(32);
+    expect(traceId2).toHaveLength(32);
+  });
+});
+
+describe('Tracer', () => {
+  let provider: TracerProvider;
+
+  beforeEach(() => {
+    provider = new TracerProvider();
+  });
+
+  it('should create spans', () => {
+    const tracer = provider.getTracer('test');
+    const span = tracer.startSpan('test-span');
+
+    expect(span.name).toBe('test-span');
+    expect(span.context.traceId).toBeTruthy();
+    expect(span.context.spanId).toBeTruthy();
+  });
+
+  it('should create child spans', () => {
+    const tracer = provider.getTracer('test');
+    const parent = tracer.startSpan('parent');
+    const child = tracer.startSpan('child', { parent });
+
+    expect(child.context.traceId).toBe(parent.context.traceId);
+    expect(child.parentSpanId).toBe(parent.context.spanId);
+  });
+
+  it('should respect sampling', () => {
+    const provider2 = new TracerProvider();
+    const sampler = new Sampler(0); // Never sample
+    provider2.setSampler(sampler);
+
+    const tracer = provider2.getTracer('test');
+    const span = tracer.startSpan('test-span');
+
+    expect(span.context.traceFlags).toBe(0);
+  });
+
+  it('should support active spans', async () => {
+    const tracer = provider.getTracer('test');
+    const result = await tracer.startActiveSpan('active-span', async (span) => {
+      span.setAttribute('test', 'value');
+      return 'result';
+    });
+
+    expect(result).toBe('result');
+  });
+});

package/src/auto.ts

@@ -0,0 +1,198 @@
+/**
+ * SDK initialization and global tracer management.
+ */
+
+import { TracerProvider } from './tracer/provider';
+import { BatchSpanProcessor } from './processor/batch-processor';
+import { Sampler } from './processor/sampler';
+import { TokenCountingProcessor } from './processor/token-counter';
+import { CostAnnotatingProcessor } from './processor/cost-processor';
+import { LoggingSpanProcessor } from './processor/logging-processor';
+import { HttpExporter, DEFAULT_ENDPOINT } from './exporter/http-exporter';
+import { ConsoleExporter } from './exporter/console-exporter';
+import { loadEnvFile, loadEnvConfig, findAgentConfigPath } from './config/env-config';
+import { loadPricingWithSource } from './config/pricing-config';
+import {
+  updateConfig,
+  setSessionId,
+  setUserId,
+  setTenantId,
+  setProjectId,
+} from './config/runtime-config';
+import { SDKConfig, ISpanExporter, ITracer } from './types';
+
+let globalProvider: TracerProvider | null = null;
+let started = false;
+
+/**
+ * Get the global tracer provider.
+ */
+export function getTracerProvider(): TracerProvider {
+  if (!globalProvider) {
+    globalProvider = new TracerProvider();
+  }
+  return globalProvider;
+}
+
+/**
+ * Set the global tracer provider.
+ */
+export function setTracerProvider(provider: TracerProvider): void {
+  globalProvider = provider;
+}
+
+/**
+ * Get a tracer from the global provider.
+ */
+export function getTracer(name: string, version?: string): ITracer {
+  return getTracerProvider().getTracer(name, version);
+}
+
+/**
+ * Initialize tracing with automatic setup.
+ */
+export async function startTracing(config: SDKConfig = {}): Promise<TracerProvider> {
+  if (started) {
+    return getTracerProvider();
+  }
+
+  started = true;
+
+  // Load environment
+  if (config.loadEnv !== false) {
+    loadEnvFile();
+  }
+
+  const overrides: Record<string, string> = {};
+  if (config.apiKey) overrides.apiKey = config.apiKey;
+  if (config.endpoint) overrides.endpoint = config.endpoint;
+  if (config.sampleRate !== undefined) overrides.sampleRate = config.sampleRate.toString();
+
+  const envConfig = loadEnvConfig(overrides);
+
+  // Find agent config
+  const agentConfigPath = findAgentConfigPath();
+  if (agentConfigPath) {
+    process.env.AGENT_DASHBOARD_AGENT_CONFIG = agentConfigPath;
+  }
+
+  // Set up runtime config
+  updateConfig({
+    autoInstrumentTools: config.autoInstrument ?? false,
+    toolInclude: config.toolInclude || [],
+    maxToolSpans: config.maxToolSpans ?? 100,
+    maxSpanDepth: config.maxSpanDepth ?? 10,
+    debug: config.debug ?? false,
+    attrTruncationLimit: config.attrTruncationLimit,
+  });
+
+  setSessionId(config.sessionId);
+  setUserId(config.userId);
+  setTenantId(config.tenantId);
+  setProjectId(config.projectId);
+
+  // Get or create provider
+  const provider = getTracerProvider();
+
+  // Set sampler
+  const sampleRate = config.sampleRate ?? (envConfig.sampleRate || 1.0);
+  const sampler = new Sampler(Math.min(1, Math.max(0, sampleRate)));
+  provider.setSampler(sampler);
+
+  // Create exporter
+  const apiKey = config.apiKey || envConfig.apiKey || '';
+  const endpoint = config.endpoint || envConfig.endpoint || DEFAULT_ENDPOINT;
+  let exporter: ISpanExporter = new HttpExporter({
+    endpoint,
+    apiKey,
+  });
+
+  if (config.enableConsoleExporter) {
+    const consoleExporter = new ConsoleExporter();
+    exporter = new CompositeExporter([exporter, consoleExporter]);
+  }
+
+  // Add processors
+  if (config.enableTokenCounting !== false) {
+    provider.addSpanProcessor(new TokenCountingProcessor());
+  }
+
+  if (config.enableCostTracking !== false) {
+    const pricingTable = config.pricingOverride
+      ? (config.pricingOverride as Record<string, { inputCost: number; outputCost: number }>)
+      : undefined;
+    const [pricing] = await loadPricingWithSource(pricingTable);
+    provider.addSpanProcessor(new CostAnnotatingProcessor(pricing));
+  }
+
+  if (config.enableSpanLogging) {
+    provider.addSpanProcessor(new LoggingSpanProcessor());
+  }
+
+  // Add batch processor with exporter
+  const processor = new BatchSpanProcessor({
+    exporter,
+    maxQueueSize: config.maxQueueSize ?? 5000,
+    maxExportBatchSize: config.maxExportBatchSize ?? 512,
+    scheduleDelayMs: config.scheduleDelayMs ?? 5000,
+    sampler,
+  });
+
+  provider.addSpanProcessor(processor);
+  registerShutdown(provider, processor);
+
+  return provider;
+}
+
+/**
+ * Stop tracing and shutdown all processors.
+ */
+export async function stopTracing(): Promise<void> {
+  if (!globalProvider) {
+    return;
+  }
+
+  await globalProvider.shutdown();
+  started = false;
+  globalProvider = null;
+}
+
+/**
+ * Register shutdown hooks.
+ */
+function registerShutdown(provider: TracerProvider, _processor: BatchSpanProcessor): void {
+  const shutdown = async (): Promise<void> => {
+    try {
+      await provider.shutdown();
+    } catch {
+      // Silently fail
+    }
+  };
+
+  // eslint-disable-next-line @typescript-eslint/no-misused-promises
+  process.on('SIGTERM', shutdown);
+  // eslint-disable-next-line @typescript-eslint/no-misused-promises
+  process.on('SIGINT', shutdown);
+}
+
+/**
+ * Composite exporter combining multiple exporters.
+ */
+class CompositeExporter implements ISpanExporter {
+  private exporters: ISpanExporter[];
+
+  public constructor(exporters: ISpanExporter[]) {
+    this.exporters = exporters;
+  }
+
+  public async export(spans: any[]): Promise<boolean> {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-call,@typescript-eslint/no-unsafe-member-access,@typescript-eslint/no-unsafe-argument
+    const results = await Promise.all(this.exporters.map((e) => e.export(spans)));
+    return results.every((r) => r);
+  }
+
+  public async shutdown(): Promise<void> {
+    await Promise.all(this.exporters.map((e) => e.shutdown()));
+  }
+}
+export { getTracerProvider as initSDK };

package/src/config/env-config.ts

@@ -0,0 +1,93 @@
+/**
+ * Environment configuration loading.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Load .env file into process.env.
+ */
+export function loadEnvFile(envPath: string = '.env'): void {
+  if (!fs.existsSync(envPath)) {
+    return;
+  }
+
+  try {
+    const content = fs.readFileSync(envPath, 'utf-8');
+    const lines = content.split('\n');
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) {
+        continue;
+      }
+
+      const eqIndex = trimmed.indexOf('=');
+      if (eqIndex === -1) {
+        continue;
+      }
+
+      const key = trimmed.substring(0, eqIndex).trim();
+      const value = trimmed.substring(eqIndex + 1).trim().replace(/^["']|["']$/g, '');
+
+      if (key && !(key in process.env)) {
+        process.env[key] = value;
+      }
+    }
+  } catch {
+    // Silently fail; best-effort loading
+  }
+}
+
+/**
+ * Load configuration from environment variables.
+ */
+export interface EnvConfig {
+  apiKey?: string;
+  endpoint?: string;
+  sampleRate?: number;
+}
+
+export function loadEnvConfig(overrides?: Record<string, string>): EnvConfig {
+  const config: EnvConfig = {
+    apiKey: process.env.AGENT_DASHBOARD_API_KEY,
+    endpoint: process.env.AGENT_DASHBOARD_ENDPOINT,
+    sampleRate: process.env.AGENT_DASHBOARD_SAMPLE_RATE
+      ? parseFloat(process.env.AGENT_DASHBOARD_SAMPLE_RATE)
+      : undefined,
+  };
+
+  if (overrides) {
+    if (overrides.apiKey !== undefined) {
+      config.apiKey = overrides.apiKey;
+    }
+    if (overrides.endpoint !== undefined) {
+      config.endpoint = overrides.endpoint;
+    }
+    if (overrides.sampleRate !== undefined) {
+      config.sampleRate = parseFloat(overrides.sampleRate);
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Find agent config file automatically.
+ */
+export function findAgentConfigPath(): string | undefined {
+  const candidates = [
+    './agent_config.json',
+    './agent-config.json',
+    './.config/agent_config.json',
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return path.resolve(candidate);
+    }
+  }
+
+  return undefined;
+}

package/src/config/pricing-config.ts

@@ -0,0 +1,84 @@
+/**
+ * Pricing configuration management.
+ */
+
+export interface PricingTable {
+  [model: string]: {
+    inputCost: number;
+    outputCost: number;
+  };
+}
+
+export type PricingSource = 'default' | 'env' | 'override';
+
+/**
+ * Default pricing table.
+ */
+export const DEFAULT_PRICING: PricingTable = {
+  'gpt-3.5-turbo': {
+    inputCost: 0.0005,
+    outputCost: 0.0015,
+  },
+  'gpt-4': {
+    inputCost: 0.03,
+    outputCost: 0.06,
+  },
+  'gpt-4-turbo': {
+    inputCost: 0.01,
+    outputCost: 0.03,
+  },
+  'claude-2': {
+    inputCost: 0.008,
+    outputCost: 0.024,
+  },
+  'claude-3-opus': {
+    inputCost: 0.015,
+    outputCost: 0.075,
+  },
+};
+
+/**
+ * Fetch remote pricing (placeholder).
+ */
+export function fetchRemotePricing(): Promise<PricingTable> {
+  // In production, this would fetch from a backend service
+  return Promise.resolve(DEFAULT_PRICING);
+}
+
+/**
+ * Load pricing configuration with source tracking.
+ */
+export function loadPricingWithSource(
+  override?: PricingTable
+): Promise<[PricingTable, PricingSource]> {
+  let pricing = { ...DEFAULT_PRICING };
+  let source: PricingSource = 'default';
+
+  const envOverride = process.env.AGENT_DASHBOARD_PRICING_JSON;
+  if (envOverride) {
+    try {
+      const envPricing = JSON.parse(envOverride) as PricingTable;
+      if (typeof envPricing === 'object') {
+        pricing = { ...pricing, ...envPricing };
+        source = 'env';
+      }
+    } catch {
+      // Ignore parsing errors
+    }
+  }
+
+  if (override) {
+    pricing = { ...pricing, ...override };
+    source = 'override';
+  }
+
+  return Promise.resolve([pricing, source]);
+}
+
+/**
+ * Load pricing configuration.
+ */
+export async function loadPricing(override?: PricingTable): Promise<PricingTable> {
+  const [pricing] = await loadPricingWithSource(override);
+  return pricing;
+}

package/src/config/runtime-config.ts

@@ -0,0 +1,108 @@
+/**
+ * Runtime configuration management.
+ */
+
+interface RuntimeConfig {
+  autoInstrumentTools: boolean;
+  toolInclude: string[];
+  maxToolSpans: number;
+  maxSpanDepth: number;
+  sessionId?: string;
+  userId?: string;
+  tenantId?: string;
+  projectId?: string;
+  debug: boolean;
+  attrTruncationLimit?: number;
+}
+
+let config: RuntimeConfig = {
+  autoInstrumentTools: false,
+  toolInclude: [],
+  maxToolSpans: 100,
+  maxSpanDepth: 10,
+  debug: false,
+};
+
+/**
+ * Get the current runtime configuration.
+ */
+export function getConfig(): RuntimeConfig {
+  return config;
+}
+
+/**
+ * Update the runtime configuration.
+ */
+export function updateConfig(partial: Partial<RuntimeConfig>): void {
+  config = { ...config, ...partial };
+}
+
+/**
+ * Set auto-instrument tools flag.
+ */
+export function setAutoInstrumentTools(value: boolean): void {
+  config.autoInstrumentTools = value;
+}
+
+/**
+ * Set tool include list.
+ */
+export function setToolInclude(tools: string[]): void {
+  config.toolInclude = tools;
+}
+
+/**
+ * Set max tool spans.
+ */
+export function setMaxToolSpans(max: number): void {
+  config.maxToolSpans = max;
+}
+
+/**
+ * Set max span depth.
+ */
+export function setMaxSpanDepth(max: number): void {
+  config.maxSpanDepth = max;
+}
+
+/**
+ * Set session ID.
+ */
+export function setSessionId(id?: string): void {
+  config.sessionId = id;
+}
+
+/**
+ * Set user ID.
+ */
+export function setUserId(id?: string): void {
+  config.userId = id;
+}
+
+/**
+ * Set tenant ID.
+ */
+export function setTenantId(id?: string): void {
+  config.tenantId = id;
+}
+
+/**
+ * Set project ID.
+ */
+export function setProjectId(id?: string): void {
+  config.projectId = id;
+}
+
+/**
+ * Set debug flag.
+ */
+export function setDebug(value: boolean): void {
+  config.debug = value;
+}
+
+/**
+ * Set attribute truncation limit.
+ */
+export function setAttrTruncationLimit(limit?: number): void {
+  config.attrTruncationLimit = limit;
+}

package/src/context/context.ts

@@ -0,0 +1,52 @@
+/**
+ * Context management for spans using async local storage.
+ */
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { ISpan } from '../types';
+
+interface SpanContext {
+  span?: ISpan;
+}
+
+const spanContext = new AsyncLocalStorage<SpanContext>();
+
+/**
+ * Get the current span from context.
+ */
+export function getCurrentSpan(): ISpan | undefined {
+  const ctx = spanContext.getStore();
+  return ctx?.span;
+}
+
+/**
+ * Set the current span in context.
+ */
+export function setCurrentSpan(span: ISpan | undefined): void {
+  const ctx = spanContext.getStore() || {};
+  ctx.span = span;
+  if (ctx) {
+    spanContext.enterWith(ctx);
+  }
+}
+
+/**
+ * Run a function with a specific span as the current span.
+ */
+export function runWithSpan<T>(span: ISpan, fn: () => T): T {
+  return spanContext.run({ span }, fn);
+}
+
+/**
+ * Run a function with a specific span as the current span (async).
+ */
+export function runWithSpanAsync<T>(span: ISpan, fn: () => Promise<T>): Promise<T> {
+  return spanContext.run({ span }, fn);
+}
+
+/**
+ * Get the current context store.
+ */
+export function getContext(): SpanContext {
+  return spanContext.getStore() || {};
+}

package/src/exporter/console-exporter.ts

@@ -0,0 +1,38 @@
+/**
+ * Console Exporter for debugging purposes.
+ */
+
+import { ISpan, ISpanExporter } from '../types';
+
+/**
+ * Console Exporter for printing spans to console.
+ */
+export class ConsoleExporter implements ISpanExporter {
+  /**
+   * Export spans to console.
+   */
+  public export(spans: ISpan[]): Promise<boolean> {
+    for (const span of spans) {
+      console.log('=== Span ===');
+      console.log(`Name: ${span.name}`);
+      console.log(`TraceId: ${span.context.traceId}`);
+      console.log(`SpanId: ${span.context.spanId}`);
+      console.log(`ParentSpanId: ${span.parentSpanId || 'none'}`);
+      console.log(`Duration: ${span.durationNs}ns`);
+      console.log(`Status: ${span.status}`);
+      if (span.statusDescription) {
+        console.log(`Status Description: ${span.statusDescription}`);
+      }
+      console.log('Attributes:', span.attributes);
+      console.log('Events:', span.events);
+    }
+    return Promise.resolve(true);
+  }
+
+  /**
+   * Shutdown the exporter.
+   */
+  public async shutdown(): Promise<void> {
+    // No-op
+  }
+}