@orka-js/devtools 1.1.0 → 1.2.0

package/dist/index.cjs

@@ -31,12 +31,17 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   DevToolsServer: () => DevToolsServer,
+  OpenTelemetryExporter: () => OpenTelemetryExporter,
+  ReplayDebugger: () => ReplayDebugger,
   Trace: () => Trace,
   TraceCollector: () => TraceCollector,
   createDevToolsHook: () => createDevToolsHook,
+  createOTLPExporter: () => createOTLPExporter,
+  createReplayDebugger: () => createReplayDebugger,
   createTracerWithDevTools: () => createTracerWithDevTools,
   devtools: () => devtools,
   getCollector: () => getCollector,
+  getReplayDebugger: () => getReplayDebugger,
   resetCollector: () => resetCollector,
   trace: () => trace,
   withTrace: () => withTrace
@@ -754,6 +759,358 @@ function createTracerWithDevTools(options = {}) {
   };
 }
 
+// src/opentelemetry.ts
+var OpenTelemetryExporter = class {
+  config;
+  spanBuffer = [];
+  flushTimer;
+  unsubscribe;
+  constructor(config) {
+    this.config = {
+      endpoint: config.endpoint,
+      serviceName: config.serviceName ?? "orkajs-app",
+      serviceVersion: config.serviceVersion ?? "1.0.0",
+      headers: config.headers ?? {},
+      batchSize: config.batchSize ?? 100,
+      flushIntervalMs: config.flushIntervalMs ?? 5e3,
+      enabled: config.enabled ?? true
+    };
+  }
+  /**
+   * Start the exporter - subscribes to trace events
+   */
+  start() {
+    if (!this.config.enabled) return;
+    const collector = getCollector();
+    this.unsubscribe = collector.subscribe((event) => {
+      if (event.type === "run:end" && event.run) {
+        this.addSpan(event.run, event.sessionId);
+      }
+    });
+    this.flushTimer = setInterval(() => {
+      this.flush();
+    }, this.config.flushIntervalMs);
+  }
+  /**
+   * Stop the exporter
+   */
+  async stop() {
+    if (this.flushTimer) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = void 0;
+    }
+    if (this.unsubscribe) {
+      this.unsubscribe();
+      this.unsubscribe = void 0;
+    }
+    await this.flush();
+  }
+  /**
+   * Convert a TraceRun to OTLP span
+   */
+  addSpan(run, traceId) {
+    const span = this.runToSpan(run, traceId);
+    this.spanBuffer.push(span);
+    for (const child of run.children) {
+      this.addSpan(child, traceId);
+    }
+    if (this.spanBuffer.length >= this.config.batchSize) {
+      this.flush();
+    }
+  }
+  /**
+   * Convert TraceRun to OTLP Span format
+   */
+  runToSpan(run, traceId) {
+    const attributes = [
+      { key: "orka.run.type", value: { stringValue: run.type } },
+      { key: "orka.run.name", value: { stringValue: run.name } },
+      { key: "orka.run.status", value: { stringValue: run.status } }
+    ];
+    if (run.metadata) {
+      if (run.metadata.model) {
+        attributes.push({ key: "llm.model", value: { stringValue: run.metadata.model } });
+      }
+      if (run.metadata.provider) {
+        attributes.push({ key: "llm.provider", value: { stringValue: run.metadata.provider } });
+      }
+      if (run.metadata.totalTokens !== void 0) {
+        attributes.push({ key: "llm.tokens.total", value: { intValue: String(run.metadata.totalTokens) } });
+      }
+      if (run.metadata.promptTokens !== void 0) {
+        attributes.push({ key: "llm.tokens.prompt", value: { intValue: String(run.metadata.promptTokens) } });
+      }
+      if (run.metadata.completionTokens !== void 0) {
+        attributes.push({ key: "llm.tokens.completion", value: { intValue: String(run.metadata.completionTokens) } });
+      }
+      if (run.metadata.cost !== void 0) {
+        attributes.push({ key: "llm.cost", value: { doubleValue: run.metadata.cost } });
+      }
+      if (run.metadata.toolName) {
+        attributes.push({ key: "tool.name", value: { stringValue: run.metadata.toolName } });
+      }
+    }
+    if (run.latencyMs !== void 0) {
+      attributes.push({ key: "orka.latency_ms", value: { intValue: String(run.latencyMs) } });
+    }
+    if (run.error) {
+      attributes.push({ key: "error.message", value: { stringValue: run.error } });
+    }
+    return {
+      traceId: this.toHex(traceId, 32),
+      spanId: this.toHex(run.id, 16),
+      parentSpanId: run.parentId ? this.toHex(run.parentId, 16) : void 0,
+      name: `${run.type}/${run.name}`,
+      kind: this.getSpanKind(run.type),
+      startTimeUnixNano: String(run.startTime * 1e6),
+      endTimeUnixNano: String((run.endTime ?? run.startTime) * 1e6),
+      attributes,
+      status: {
+        code: run.status === "error" ? 2 : 1,
+        message: run.error
+      }
+    };
+  }
+  /**
+   * Get OTLP span kind based on run type
+   */
+  getSpanKind(type) {
+    switch (type) {
+      case "llm":
+      case "embedding":
+        return 3;
+      // CLIENT
+      case "tool":
+        return 3;
+      // CLIENT
+      case "agent":
+      case "chain":
+      case "workflow":
+      case "graph":
+        return 0;
+      // INTERNAL
+      default:
+        return 0;
+    }
+  }
+  /**
+   * Convert string ID to hex format
+   */
+  toHex(id, length) {
+    let hash = 0;
+    for (let i = 0; i < id.length; i++) {
+      const char = id.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    const hex = Math.abs(hash).toString(16).padStart(length, "0");
+    return hex.slice(0, length);
+  }
+  /**
+   * Flush spans to OTLP endpoint
+   */
+  async flush() {
+    if (this.spanBuffer.length === 0) return;
+    const spans = [...this.spanBuffer];
+    this.spanBuffer = [];
+    const payload = {
+      resourceSpans: [{
+        resource: {
+          attributes: [
+            { key: "service.name", value: { stringValue: this.config.serviceName } },
+            { key: "service.version", value: { stringValue: this.config.serviceVersion } },
+            { key: "telemetry.sdk.name", value: { stringValue: "@orka-js/devtools" } },
+            { key: "telemetry.sdk.version", value: { stringValue: "1.1.0" } }
+          ]
+        },
+        scopeSpans: [{
+          scope: {
+            name: "@orka-js/devtools",
+            version: "1.1.0"
+          },
+          spans
+        }]
+      }]
+    };
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/traces`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          ...this.config.headers
+        },
+        body: JSON.stringify(payload)
+      });
+      if (!response.ok) {
+        console.error(`[DevTools] OTLP export failed: ${response.status} ${response.statusText}`);
+        this.spanBuffer.unshift(...spans);
+      }
+    } catch (error) {
+      console.error("[DevTools] OTLP export error:", error);
+      this.spanBuffer.unshift(...spans);
+    }
+  }
+};
+function createOTLPExporter(config) {
+  const exporter = new OpenTelemetryExporter(config);
+  exporter.start();
+  return exporter;
+}
+
+// src/replay.ts
+var ReplayDebugger = class {
+  /**
+   * Replay a trace run with optionally modified input
+   */
+  async replay(options) {
+    const collector = getCollector();
+    const originalRun = collector.findRun(options.runId, options.sessionId);
+    if (!originalRun) {
+      throw new Error(`Run not found: ${options.runId}`);
+    }
+    const modifiedInput = options.modifyInput ? options.modifyInput(originalRun.input) : originalRun.input;
+    const replaySessionId = collector.startSession(`Replay: ${originalRun.name}`);
+    const replayRunId = collector.startRun(
+      originalRun.type,
+      `replay:${originalRun.name}`,
+      modifiedInput,
+      {
+        ...originalRun.metadata,
+        replayOf: originalRun.id,
+        originalSessionId: options.sessionId
+      }
+    );
+    const replayedOutput = originalRun.output;
+    collector.endRun(replayRunId, replayedOutput, originalRun.metadata);
+    collector.endSession(replaySessionId);
+    const replayedRun = collector.findRun(replayRunId);
+    if (!replayedRun) {
+      throw new Error("Failed to create replayed run");
+    }
+    const inputChanged = JSON.stringify(originalRun.input) !== JSON.stringify(modifiedInput);
+    const outputChanged = JSON.stringify(originalRun.output) !== JSON.stringify(replayedRun.output);
+    const latencyDiff = (replayedRun.latencyMs ?? 0) - (originalRun.latencyMs ?? 0);
+    return {
+      originalRun,
+      replayedRun,
+      diff: {
+        inputChanged,
+        outputChanged,
+        latencyDiff
+      }
+    };
+  }
+  /**
+   * Fork a trace to create a new branch for experimentation
+   */
+  fork(runId, sessionId) {
+    const collector = getCollector();
+    const originalRun = collector.findRun(runId, sessionId);
+    if (!originalRun) {
+      throw new Error(`Run not found: ${runId}`);
+    }
+    const forkSessionId = collector.startSession(`Fork: ${originalRun.name}`);
+    this.cloneRunTree(originalRun, forkSessionId);
+    collector.endSession(forkSessionId);
+    return forkSessionId;
+  }
+  /**
+   * Clone a run and its children
+   */
+  cloneRunTree(run, _sessionId, parentId) {
+    const collector = getCollector();
+    const newRunId = collector.startRun(
+      run.type,
+      `fork:${run.name}`,
+      run.input,
+      {
+        ...run.metadata,
+        forkedFrom: run.id,
+        originalParentId: parentId
+      }
+    );
+    for (const child of run.children) {
+      this.cloneRunTree(child, _sessionId, newRunId);
+    }
+    if (run.status === "error") {
+      collector.errorRun(newRunId, run.error ?? "Unknown error");
+    } else {
+      collector.endRun(newRunId, run.output, run.metadata);
+    }
+    return newRunId;
+  }
+  /**
+   * Compare two runs and return detailed diff
+   */
+  compare(runId1, runId2, sessionId) {
+    const collector = getCollector();
+    const run1 = collector.findRun(runId1, sessionId);
+    const run2 = collector.findRun(runId2, sessionId);
+    if (!run1 || !run2) {
+      throw new Error("One or both runs not found");
+    }
+    return {
+      run1: {
+        id: run1.id,
+        name: run1.name,
+        type: run1.type,
+        latencyMs: run1.latencyMs,
+        status: run1.status,
+        tokenCount: run1.metadata?.totalTokens
+      },
+      run2: {
+        id: run2.id,
+        name: run2.name,
+        type: run2.type,
+        latencyMs: run2.latencyMs,
+        status: run2.status,
+        tokenCount: run2.metadata?.totalTokens
+      },
+      diff: {
+        latencyDiff: (run2.latencyMs ?? 0) - (run1.latencyMs ?? 0),
+        latencyDiffPercent: run1.latencyMs ? ((run2.latencyMs ?? 0) - run1.latencyMs) / run1.latencyMs * 100 : 0,
+        tokenDiff: (run2.metadata?.totalTokens ?? 0) - (run1.metadata?.totalTokens ?? 0),
+        statusChanged: run1.status !== run2.status,
+        inputChanged: JSON.stringify(run1.input) !== JSON.stringify(run2.input),
+        outputChanged: JSON.stringify(run1.output) !== JSON.stringify(run2.output)
+      }
+    };
+  }
+  /**
+   * Export a run as a reproducible test case
+   */
+  exportTestCase(runId, sessionId) {
+    const collector = getCollector();
+    const run = collector.findRun(runId, sessionId);
+    if (!run) {
+      throw new Error(`Run not found: ${runId}`);
+    }
+    return {
+      name: `test_${run.name}_${run.id.slice(0, 8)}`,
+      description: `Exported from DevTools trace ${run.id}`,
+      type: run.type,
+      input: run.input,
+      expectedOutput: run.output,
+      metadata: run.metadata,
+      assertions: [
+        { type: "status", expected: run.status },
+        { type: "latency_max", expected: (run.latencyMs ?? 0) * 1.5 }
+      ],
+      createdAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+};
+function createReplayDebugger() {
+  return new ReplayDebugger();
+}
+var replayDebugger;
+function getReplayDebugger() {
+  if (!replayDebugger) {
+    replayDebugger = new ReplayDebugger();
+  }
+  return replayDebugger;
+}
+
 // src/index.ts
 async function devtools(config = {}) {
   const collector = getCollector(config);
@@ -844,12 +1201,17 @@ var trace = {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DevToolsServer,
+  OpenTelemetryExporter,
+  ReplayDebugger,
   Trace,
   TraceCollector,
   createDevToolsHook,
+  createOTLPExporter,
+  createReplayDebugger,
   createTracerWithDevTools,
   devtools,
   getCollector,
+  getReplayDebugger,
   resetCollector,
   trace,
   withTrace