@mutagent/sdk 0.2.39 → 0.2.42

package/src/tracing/api.ts

@@ -1,63 +0,0 @@
-/**
- * MutagenT SDK -- Low-Level Tracing API
- *
- * Re-exports startSpan, endSpan, getCurrentSpan, getCurrentTraceId
- * from the global SpanManager singleton.
- *
- * These are the primitives used by integration adapters.
- *
- * NOT generated by Speakeasy -- manually maintained.
- */
-
-import type { MutagentSpan, SpanOptions, SpanEndOptions } from "./types.js";
-import { _ensureTracing } from "./init.js";
-
-/**
- * Start a new span. If no trace is active, a new trace is created.
- * Returns the span, or undefined if tracing is not initialized.
- *
- * If tracing hasn't been initialized but the MUTAGENT_API_KEY
- * environment variable is set, tracing is automatically initialized.
- *
- * Use `runInSpanContext` to propagate the span to child calls.
- */
-export function startSpan(options: SpanOptions): MutagentSpan | undefined {
-  return _ensureTracing()?.startSpan(options);
-}
-
-/**
- * End a span, computing duration and delivering to the batch collector.
- * No-op if tracing is not initialized.
- */
-export function endSpan(span: MutagentSpan, endOptions?: SpanEndOptions): void {
-  _ensureTracing()?.endSpan(span, endOptions);
-}
-
-/**
- * Get the currently active span from async context.
- * Returns undefined if no span is active or tracing is not initialized.
- */
-export function getCurrentSpan(): MutagentSpan | undefined {
-  return _ensureTracing()?.getCurrentSpan();
-}
-
-/**
- * Get the currently active trace ID from async context.
- * Returns undefined if no trace is active or tracing is not initialized.
- */
-export function getCurrentTraceId(): string | undefined {
-  return _ensureTracing()?.getCurrentTraceId();
-}
-
-/**
- * Run a function within the async context of a span.
- * This enables getCurrentSpan() / getCurrentTraceId() for nested calls.
- * No-op passthrough if tracing is not initialized.
- */
-export function runInSpanContext<T>(span: MutagentSpan, fn: () => T): T {
-  const manager = _ensureTracing();
-  if (!manager) {
-    return fn();
-  }
-  return manager.runInContext(span, fn);
-}

package/src/tracing/batch-collector.ts

@@ -1,212 +0,0 @@
-/**
- * MutagenT SDK -- Batch Collector
- *
- * Buffers finished spans in memory and flushes them to the trace HTTP client
- * when either the batch size threshold or the flush interval is reached.
- *
- * Retry with exponential backoff on failure.
- *
- * NOT generated by Speakeasy -- manually maintained.
- */
-
-import type {
-  FinishedSpan,
-  TraceHTTPResponse,
-  TracePayload,
-} from "./types.js";
-import type { TraceHTTPClient } from "./http-client.js";
-
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-
-export interface BatchCollectorConfig {
-  httpClient: TraceHTTPClient;
-  /** Number of spans to buffer before auto-flushing. Default: 10. */
-  batchSize?: number;
-  /** Flush interval in milliseconds. Default: 5000. */
-  flushIntervalMs?: number;
-  /** Source identifier for traces. Default: 'sdk'. */
-  source?: string;
-  /** Environment name. */
-  environment?: string;
-  /** Max retries on flush failure. Default: 3. */
-  maxRetries?: number;
-  /** Base delay in ms for exponential backoff. Default: 1000. */
-  retryBaseDelayMs?: number;
-}
-
-// ---------------------------------------------------------------------------
-// BatchCollector
-// ---------------------------------------------------------------------------
-
-export class BatchCollector {
-  private readonly httpClient: TraceHTTPClient;
-  private readonly batchSize: number;
-  private readonly flushIntervalMs: number;
-  private readonly source: string;
-  private readonly environment: string | undefined;
-  private readonly maxRetries: number;
-  private readonly retryBaseDelayMs: number;
-
-  private buffer: FinishedSpan[] = [];
-  private timer: ReturnType<typeof setInterval> | undefined;
-  private flushing = false;
-
-  constructor(config: BatchCollectorConfig) {
-    this.httpClient = config.httpClient;
-    this.batchSize = config.batchSize ?? 10;
-    this.flushIntervalMs = config.flushIntervalMs ?? 5000;
-    this.source = config.source ?? "sdk";
-    this.environment = config.environment;
-    this.maxRetries = config.maxRetries ?? 3;
-    this.retryBaseDelayMs = config.retryBaseDelayMs ?? 1000;
-
-    // Start flush interval timer
-    this.timer = setInterval(() => {
-      void this.flush();
-    }, this.flushIntervalMs);
-
-    // Unref the timer so it does not keep the process alive
-    if (typeof this.timer === "object" && "unref" in this.timer) {
-      this.timer.unref();
-    }
-  }
-
-  /**
-   * Add a finished span to the buffer.
-   * If the buffer reaches batchSize, triggers an async flush.
-   */
-  add(span: FinishedSpan): void {
-    this.buffer.push(span);
-
-    if (this.buffer.length >= this.batchSize) {
-      void this.flush();
-    }
-  }
-
-  /**
-   * Flush all buffered spans to the HTTP client.
-   * Groups spans by traceId into the TracePayload format.
-   * Retries with exponential backoff on failure.
-   */
-  async flush(): Promise<void> {
-    if (this.buffer.length === 0 || this.flushing) {
-      return;
-    }
-
-    this.flushing = true;
-
-    // Drain buffer atomically
-    const spans = this.buffer.splice(0, this.buffer.length);
-
-    try {
-      const payload = this.buildPayload(spans);
-      await this.sendWithRetry(payload);
-    } catch {
-      // All retries exhausted -- spans are lost
-      // In a production system we might persist to disk here.
-    } finally {
-      this.flushing = false;
-    }
-  }
-
-  /**
-   * Shutdown: flush remaining spans, clear interval timer.
-   */
-  async shutdown(): Promise<void> {
-    if (this.timer !== undefined) {
-      clearInterval(this.timer);
-      this.timer = undefined;
-    }
-
-    // Force-flush remaining
-    this.flushing = false; // Reset lock so flush can proceed
-    await this.flush();
-  }
-
-  // -------------------------------------------------------------------------
-  // Private helpers
-  // -------------------------------------------------------------------------
-
-  private buildPayload(spans: FinishedSpan[]): TracePayload {
-    // Group spans by traceId
-    const grouped = new Map<string, FinishedSpan[]>();
-
-    for (const span of spans) {
-      let bucket = grouped.get(span.traceId);
-      if (bucket === undefined) {
-        bucket = [];
-        grouped.set(span.traceId, bucket);
-      }
-      bucket.push(span);
-    }
-
-    const traces: TracePayload["traces"] = [];
-
-    for (const [traceId, traceSpans] of grouped.entries()) {
-      const traceEntry: TracePayload["traces"][number] = {
-        traceId,
-        source: this.source,
-        spans: traceSpans.map((s) => {
-          const span: TracePayload["traces"][number]["spans"][number] = {
-            spanId: s.spanId,
-            name: s.name,
-            kind: s.kind,
-            startTime: s.startTime,
-            endTime: s.endTime,
-            durationMs: s.durationMs,
-            status: s.status,
-          };
-          if (s.parentSpanId !== undefined) span.parentSpanId = s.parentSpanId;
-          if (s.input !== undefined) span.input = s.input;
-          if (s.output !== undefined) span.output = s.output;
-          if (s.model !== undefined) span.model = s.model;
-          if (s.provider !== undefined) span.provider = s.provider;
-          if (s.inputTokens !== undefined) span.inputTokens = s.inputTokens;
-          if (s.outputTokens !== undefined) span.outputTokens = s.outputTokens;
-          if (s.totalTokens !== undefined) span.totalTokens = s.totalTokens;
-          if (s.costUsd !== undefined) span.costUsd = s.costUsd;
-          if (s.statusMessage !== undefined) span.statusMessage = s.statusMessage;
-          if (s.attributes !== undefined && Object.keys(s.attributes).length > 0) {
-            span.attributes = s.attributes;
-          }
-          if (s.events !== undefined && s.events.length > 0) {
-            span.events = s.events;
-          }
-          if (s.metadata !== undefined) span.metadata = s.metadata;
-          return span;
-        }),
-      };
-      if (this.environment !== undefined) {
-        traceEntry.environment = this.environment;
-      }
-      traces.push(traceEntry);
-    }
-
-    return { traces };
-  }
-
-  private async sendWithRetry(payload: TracePayload): Promise<TraceHTTPResponse> {
-    let lastError: unknown;
-
-    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
-      try {
-        return await this.httpClient.send(payload);
-      } catch (err) {
-        lastError = err;
-
-        if (attempt < this.maxRetries) {
-          const delayMs = this.retryBaseDelayMs * Math.pow(2, attempt);
-          await this.sleep(delayMs);
-        }
-      }
-    }
-
-    throw lastError;
-  }
-
-  private sleep(ms: number): Promise<void> {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-}

package/src/tracing/decorators.ts

@@ -1,128 +0,0 @@
-/**
- * MutagenT SDK -- @trace Method Decorator
- *
- * Method decorator that wraps class methods with automatic span creation,
- * input/output capture, and error handling.
- *
- * Uses legacy TypeScript decorator style (PropertyDescriptor) for broad
- * runtime compatibility (Bun, Node, tsc with experimentalDecorators).
- *
- * NOT generated by Speakeasy -- manually maintained.
- */
-
-import type { SpanKind, SpanOptions, MutagentSpan } from "./types.js";
-import { _getSpanManager } from "./init.js";
-
-// ---------------------------------------------------------------------------
-// Decorator Options
-// ---------------------------------------------------------------------------
-
-export interface TraceDecoratorOptions {
-  kind: SpanKind;
-  name?: string;
-  attributes?: Record<string, unknown>;
-}
-
-// ---------------------------------------------------------------------------
-// @trace decorator
-// ---------------------------------------------------------------------------
-
-/**
- * Method decorator that creates a tracing span around the decorated method.
- *
- * - Auto-captures arguments as `input.raw`
- * - Auto-captures return value as `output.raw`
- * - Sets `status: 'ok'` on success, `status: 'error'` on throw
- * - No-op when tracing is not initialized
- * - Works with both sync and async methods
- * - Preserves `this` context
- *
- * Usage:
- * ```ts
- * class Agent {
- *   @trace({ kind: 'agent', name: 'my-agent' })
- *   async run(query: string): Promise<string> { ... }
- * }
- * ```
- */
-export function trace(
-  options: TraceDecoratorOptions,
-): (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor) => PropertyDescriptor {
-  return function (
-    _target: object,
-    propertyKey: string | symbol,
-    descriptor: PropertyDescriptor,
-  ): PropertyDescriptor {
-    const originalMethod = descriptor.value as (...args: unknown[]) => unknown;
-    const methodName =
-      options.name ??
-      (typeof propertyKey === "string" ? propertyKey : options.kind);
-
-    descriptor.value = function (this: unknown, ...args: unknown[]): unknown {
-      const manager = _getSpanManager();
-
-      // No-op when tracing is not initialized
-      if (!manager) {
-        return originalMethod.call(this, ...args);
-      }
-
-      const spanOptions: SpanOptions = {
-        kind: options.kind,
-        name: methodName,
-        input: { raw: args },
-      };
-      if (options.attributes) {
-        spanOptions.attributes = { ...options.attributes };
-      }
-
-      const span: MutagentSpan = manager.startSpan(spanOptions);
-
-      // Execute within async context for parent-child propagation
-      return manager.runInContext(span, () => {
-        try {
-          const result = originalMethod.call(this, ...args);
-
-          // Handle async (Promise-returning) methods
-          if (result instanceof Promise) {
-            return result.then(
-              (value: unknown) => {
-                manager.endSpan(span, {
-                  status: "ok",
-                  output: { raw: value },
-                });
-                return value;
-              },
-              (error: unknown) => {
-                const message =
-                  error instanceof Error ? error.message : String(error);
-                manager.endSpan(span, {
-                  status: "error",
-                  statusMessage: message,
-                });
-                throw error;
-              },
-            );
-          }
-
-          // Sync return
-          manager.endSpan(span, {
-            status: "ok",
-            output: { raw: result },
-          });
-          return result;
-        } catch (error) {
-          // Sync throw
-          const message =
-            error instanceof Error ? error.message : String(error);
-          manager.endSpan(span, {
-            status: "error",
-            statusMessage: message,
-          });
-          throw error;
-        }
-      });
-    };
-
-    return descriptor;
-  };
-}

package/src/tracing/http-client.ts

@@ -1,68 +0,0 @@
-/**
- * MutagenT SDK — Trace HTTP Client
- *
- * Sends trace payloads to the MutagenT API via POST /api/traces.
- * Uses native fetch() with AbortController for timeout.
- *
- * NOT generated by Speakeasy — manually maintained.
- */
-
-import type { TraceHTTPResponse, TracePayload } from "./types.js";
-
-// ---------------------------------------------------------------------------
-// TraceHTTPClient
-// ---------------------------------------------------------------------------
-
-export interface TraceHTTPClientConfig {
-  endpoint: string;
-  apiKey: string;
-  timeoutMs?: number;
-}
-
-export class TraceHTTPClient {
-  private readonly endpoint: string;
-  private readonly apiKey: string;
-  private readonly timeoutMs: number;
-
-  constructor(config: TraceHTTPClientConfig) {
-    this.endpoint = config.endpoint.replace(/\/+$/, ""); // strip trailing slashes
-    this.apiKey = config.apiKey;
-    this.timeoutMs = config.timeoutMs ?? 10_000;
-  }
-
-  /**
-   * Send a trace payload to the server.
-   *
-   * POST ${endpoint}/api/traces
-   * Headers: Content-Type: application/json, x-api-key: ${apiKey}
-   * Timeout: 10s via AbortController
-   */
-  async send(payload: TracePayload): Promise<TraceHTTPResponse> {
-    const url = `${this.endpoint}/api/traces`;
-    const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
-
-    try {
-      const response = await fetch(url, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          "x-api-key": this.apiKey,
-        },
-        body: JSON.stringify(payload),
-        signal: controller.signal,
-      });
-
-      if (!response.ok) {
-        throw new Error(
-          `Trace ingestion failed: HTTP ${response.status} ${response.statusText}`,
-        );
-      }
-
-      const body = (await response.json()) as TraceHTTPResponse;
-      return body;
-    } finally {
-      clearTimeout(timeout);
-    }
-  }
-}

package/src/tracing/index.ts

@@ -1,50 +0,0 @@
-/**
- * MutagenT SDK -- Tracing Module Barrel Export
- *
- * Public API for the tracing subsystem.
- *
- * NOT generated by Speakeasy -- manually maintained.
- */
-
-// ---------------------------------------------------------------------------
-// Initialization
-// ---------------------------------------------------------------------------
-export { initTracing, shutdownTracing, isTracingInitialized } from "./init.js";
-
-// ---------------------------------------------------------------------------
-// Decorator & Wrapper
-// ---------------------------------------------------------------------------
-export { trace } from "./decorators.js";
-export type { TraceDecoratorOptions } from "./decorators.js";
-export { withTrace } from "./wrappers.js";
-export type { WithTraceOptions } from "./wrappers.js";
-
-// ---------------------------------------------------------------------------
-// Low-Level API (for integration adapters)
-// ---------------------------------------------------------------------------
-export {
-  startSpan,
-  endSpan,
-  getCurrentSpan,
-  getCurrentTraceId,
-  runInSpanContext,
-} from "./api.js";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-export type {
-  SpanKind,
-  SpanIO,
-  SpanStatus,
-  SpanEvent,
-  SpanMetrics,
-  SpanOptions,
-  SpanEndOptions,
-  SpanHandle,
-  MutagentSpan,
-  FinishedSpan,
-  TracingConfig,
-  TracePayload,
-  TraceHTTPResponse,
-} from "./types.js";

package/src/tracing/init.ts

@@ -1,150 +0,0 @@
-/**
- * MutagenT SDK -- Tracing Initialization
- *
- * Entry point for setting up tracing: creates singletons for
- * SpanManager, BatchCollector, and TraceHTTPClient.
- *
- * NOT generated by Speakeasy -- manually maintained.
- */
-
-import type { TracingConfig } from "./types.js";
-import { SpanManager } from "./span-manager.js";
-import { BatchCollector, type BatchCollectorConfig } from "./batch-collector.js";
-import { TraceHTTPClient } from "./http-client.js";
-
-// ---------------------------------------------------------------------------
-// Singleton state
-// ---------------------------------------------------------------------------
-
-let spanManager: SpanManager | undefined;
-let batchCollector: BatchCollector | undefined;
-let initialized = false;
-let lazyInitAttempted = false;
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Initialize tracing for the MutagenT SDK.
- *
- * Call once at application startup. Creates the SpanManager,
- * BatchCollector, and TraceHTTPClient singletons.
- *
- * Idempotent: calling again replaces the previous configuration
- * (shuts down old collector first, silently).
- */
-export function initTracing(config: TracingConfig): void {
-  if (!config.apiKey) {
-    throw new Error("initTracing: apiKey is required");
-  }
-
-  // If already initialized, shut down previous silently
-  if (initialized && batchCollector) {
-    void batchCollector.shutdown();
-  }
-
-  const endpoint = config.endpoint ?? "https://api.mutagent.io";
-
-  const httpClient = new TraceHTTPClient({
-    endpoint,
-    apiKey: config.apiKey,
-  });
-
-  const collectorConfig: BatchCollectorConfig = {
-    httpClient,
-    batchSize: config.batchSize ?? 10,
-    flushIntervalMs: config.flushIntervalMs ?? 5000,
-    source: config.source ?? "sdk",
-  };
-  if (config.environment !== undefined) {
-    collectorConfig.environment = config.environment;
-  }
-  const collector = new BatchCollector(collectorConfig);
-
-  const manager = new SpanManager();
-  manager.setDebug(config.debug ?? false);
-  manager.setOnSpanEnd((finishedSpan) => {
-    collector.add(finishedSpan);
-  });
-
-  spanManager = manager;
-  batchCollector = collector;
-  initialized = true;
-}
-
-/**
- * Check if tracing has been initialized.
- */
-export function isTracingInitialized(): boolean {
-  return initialized;
-}
-
-/**
- * Shutdown tracing: flush remaining spans, clear timers, reset state.
- */
-export async function shutdownTracing(): Promise<void> {
-  if (batchCollector) {
-    await batchCollector.shutdown();
-  }
-
-  if (spanManager) {
-    spanManager.clear();
-  }
-
-  spanManager = undefined;
-  batchCollector = undefined;
-  initialized = false;
-  lazyInitAttempted = false;
-}
-
-/**
- * Get the global SpanManager singleton.
- * Returns undefined if tracing is not initialized.
- * @internal Used by decorators, wrappers, and the low-level API.
- */
-export function _getSpanManager(): SpanManager | undefined {
-  return spanManager;
-}
-
-/**
- * Get the SpanManager, attempting lazy initialization from the
- * MUTAGENT_API_KEY environment variable if tracing hasn't been
- * explicitly initialized. Only attempts once per lifecycle.
- * @internal Used by the low-level API (api.ts).
- */
-export function _ensureTracing(): SpanManager | undefined {
-  if (spanManager) return spanManager;
-  if (lazyInitAttempted) return undefined;
-
-  lazyInitAttempted = true;
-
-  const apiKey =
-    typeof process !== "undefined"
-      ? process.env?.["MUTAGENT_API_KEY"]
-      : undefined;
-
-  if (apiKey) {
-    initTracing({ apiKey });
-    return spanManager;
-  }
-
-  return undefined;
-}
-
-/**
- * Get the global BatchCollector singleton.
- * Returns undefined if tracing is not initialized.
- * @internal
- */
-export function _getBatchCollector(): BatchCollector | undefined {
-  return batchCollector;
-}
-
-/**
- * Reset tracing state for tests. Equivalent to shutdownTracing.
- * @internal Test-only utility.
- */
-export async function _resetTracingForTests(): Promise<void> {
-  await shutdownTracing();
-}