@dexto/core 1.1.11 → 1.2.0

package/dist/telemetry/exporters.cjs

@@ -0,0 +1,108 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var exporters_exports = {};
+__export(exporters_exports, {
+  CompositeExporter: () => CompositeExporter
+});
+module.exports = __toCommonJS(exporters_exports);
+var import_core = require("@opentelemetry/core");
+function normalizeUrlPath(url) {
+  try {
+    const parsedUrl = new URL(url);
+    let pathname = parsedUrl.pathname.toLowerCase().trim();
+    if (pathname.endsWith("/")) {
+      pathname = pathname.slice(0, -1);
+    }
+    return pathname;
+  } catch (_e) {
+    let path = url.toLowerCase().trim();
+    if (path.endsWith("/")) {
+      path = path.slice(0, -1);
+    }
+    return path;
+  }
+}
+class CompositeExporter {
+  exporters;
+  constructor(exporters) {
+    this.exporters = exporters;
+  }
+  export(spans, resultCallback) {
+    const telemetryTraceIds = new Set(
+      spans.filter((span) => {
+        const attrs = span.attributes || {};
+        const relevantHttpAttributes = [
+          attrs["http.target"],
+          attrs["http.route"],
+          attrs["http.url"],
+          attrs["url.path"],
+          attrs["http.request_path"]
+        ];
+        const isTelemetrySpan = relevantHttpAttributes.some((attr) => {
+          if (typeof attr === "string") {
+            const normalizedPath = normalizeUrlPath(attr);
+            return normalizedPath === "/api/telemetry" || normalizedPath.startsWith("/api/telemetry/");
+          }
+          return false;
+        });
+        return isTelemetrySpan;
+      }).map((span) => span.spanContext().traceId)
+    );
+    const filteredSpans = spans.filter(
+      (span) => !telemetryTraceIds.has(span.spanContext().traceId)
+    );
+    if (filteredSpans.length === 0) {
+      resultCallback({ code: import_core.ExportResultCode.SUCCESS });
+      return;
+    }
+    void Promise.all(
+      this.exporters.map(
+        (exporter) => new Promise((resolve) => {
+          if (exporter.export) {
+            exporter.export(filteredSpans, resolve);
+          } else {
+            resolve({ code: import_core.ExportResultCode.FAILED });
+          }
+        })
+      )
+    ).then((results) => {
+      const hasError = results.some((r) => r.code === import_core.ExportResultCode.FAILED);
+      resultCallback({
+        code: hasError ? import_core.ExportResultCode.FAILED : import_core.ExportResultCode.SUCCESS
+      });
+    }).catch((error) => {
+      console.error("[CompositeExporter] Export error:", error);
+      resultCallback({ code: import_core.ExportResultCode.FAILED });
+    });
+  }
+  shutdown() {
+    return Promise.all(this.exporters.map((e) => e.shutdown?.() ?? Promise.resolve())).then(
+      () => void 0
+    );
+  }
+  forceFlush() {
+    return Promise.all(this.exporters.map((e) => e.forceFlush?.() ?? Promise.resolve())).then(
+      () => void 0
+    );
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CompositeExporter
+});

package/dist/telemetry/exporters.d.ts

@@ -0,0 +1,29 @@
+import type { ExportResult } from '@opentelemetry/core';
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+/**
+ * CompositeExporter wraps multiple span exporters and provides two key features:
+ *
+ * 1. **Multi-exporter support**: Exports spans to multiple destinations in parallel
+ *    (e.g., console for development + OTLP for production monitoring)
+ *
+ * 2. **Recursive telemetry filtering**: Prevents telemetry infinity loops by filtering
+ *    out spans from `/api/telemetry` endpoints. Without this, telemetry API calls would
+ *    generate spans, which would be exported via HTTP to `/api/telemetry`, generating
+ *    more spans, creating an infinite loop.
+ *
+ * @example
+ * ```typescript
+ * const exporter = new CompositeExporter([
+ *   new ConsoleSpanExporter(),
+ *   new OTLPHttpExporter({ url: 'http://localhost:4318/v1/traces' })
+ * ]);
+ * ```
+ */
+export declare class CompositeExporter implements SpanExporter {
+    private exporters;
+    constructor(exporters: SpanExporter[]);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+//# sourceMappingURL=exporters.d.ts.map

package/dist/telemetry/exporters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exporters.d.ts","sourceRoot":"","sources":["../../src/telemetry/exporters.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AA0BhF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,iBAAkB,YAAW,YAAY;IAClD,OAAO,CAAC,SAAS,CAAiB;gBAEtB,SAAS,EAAE,YAAY,EAAE;IAIrC,MAAM,CAAC,KAAK,EAAE,YAAY,EAAE,EAAE,cAAc,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI;IAiEnF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAMzB,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAK9B"}

package/dist/telemetry/exporters.js

@@ -0,0 +1,85 @@
+import "../chunk-C6A6W6XS.js";
+import { ExportResultCode } from "@opentelemetry/core";
+function normalizeUrlPath(url) {
+  try {
+    const parsedUrl = new URL(url);
+    let pathname = parsedUrl.pathname.toLowerCase().trim();
+    if (pathname.endsWith("/")) {
+      pathname = pathname.slice(0, -1);
+    }
+    return pathname;
+  } catch (_e) {
+    let path = url.toLowerCase().trim();
+    if (path.endsWith("/")) {
+      path = path.slice(0, -1);
+    }
+    return path;
+  }
+}
+class CompositeExporter {
+  exporters;
+  constructor(exporters) {
+    this.exporters = exporters;
+  }
+  export(spans, resultCallback) {
+    const telemetryTraceIds = new Set(
+      spans.filter((span) => {
+        const attrs = span.attributes || {};
+        const relevantHttpAttributes = [
+          attrs["http.target"],
+          attrs["http.route"],
+          attrs["http.url"],
+          attrs["url.path"],
+          attrs["http.request_path"]
+        ];
+        const isTelemetrySpan = relevantHttpAttributes.some((attr) => {
+          if (typeof attr === "string") {
+            const normalizedPath = normalizeUrlPath(attr);
+            return normalizedPath === "/api/telemetry" || normalizedPath.startsWith("/api/telemetry/");
+          }
+          return false;
+        });
+        return isTelemetrySpan;
+      }).map((span) => span.spanContext().traceId)
+    );
+    const filteredSpans = spans.filter(
+      (span) => !telemetryTraceIds.has(span.spanContext().traceId)
+    );
+    if (filteredSpans.length === 0) {
+      resultCallback({ code: ExportResultCode.SUCCESS });
+      return;
+    }
+    void Promise.all(
+      this.exporters.map(
+        (exporter) => new Promise((resolve) => {
+          if (exporter.export) {
+            exporter.export(filteredSpans, resolve);
+          } else {
+            resolve({ code: ExportResultCode.FAILED });
+          }
+        })
+      )
+    ).then((results) => {
+      const hasError = results.some((r) => r.code === ExportResultCode.FAILED);
+      resultCallback({
+        code: hasError ? ExportResultCode.FAILED : ExportResultCode.SUCCESS
+      });
+    }).catch((error) => {
+      console.error("[CompositeExporter] Export error:", error);
+      resultCallback({ code: ExportResultCode.FAILED });
+    });
+  }
+  shutdown() {
+    return Promise.all(this.exporters.map((e) => e.shutdown?.() ?? Promise.resolve())).then(
+      () => void 0
+    );
+  }
+  forceFlush() {
+    return Promise.all(this.exporters.map((e) => e.forceFlush?.() ?? Promise.resolve())).then(
+      () => void 0
+    );
+  }
+}
+export {
+  CompositeExporter
+};

package/dist/telemetry/index.cjs

@@ -0,0 +1,28 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var telemetry_exports = {};
+__export(telemetry_exports, {
+  Telemetry: () => import_telemetry.Telemetry
+});
+module.exports = __toCommonJS(telemetry_exports);
+var import_telemetry = require("./telemetry.js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Telemetry
+});

package/dist/telemetry/index.d.ts

@@ -0,0 +1,2 @@
+export { Telemetry } from './telemetry.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/telemetry/index.js

@@ -0,0 +1,5 @@
+import "../chunk-C6A6W6XS.js";
+import { Telemetry } from "./telemetry.js";
+export {
+  Telemetry
+};

package/dist/telemetry/schemas.cjs

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var schemas_exports = {};
+__export(schemas_exports, {
+  OtelConfigurationSchema: () => OtelConfigurationSchema
+});
+module.exports = __toCommonJS(schemas_exports);
+var import_zod = require("zod");
+const OtelConfigurationSchema = import_zod.z.object({
+  serviceName: import_zod.z.string().optional(),
+  enabled: import_zod.z.boolean().optional(),
+  tracerName: import_zod.z.string().optional(),
+  // TODO (Telemetry): Implement sampling support in Phase 5
+  // Currently sampling schema is defined but not implemented in telemetry.ts
+  // See feature-plans/telemetry.md Phase 5 for implementation details
+  // sampling: z
+  //     .discriminatedUnion('type', [
+  //         z.object({
+  //             type: z.literal('ratio'),
+  //             probability: z.number().min(0).max(1),
+  //         }),
+  //         z.object({
+  //             type: z.literal('always_on'),
+  //         }),
+  //         z.object({
+  //             type: z.literal('always_off'),
+  //         }),
+  //         z.object({
+  //             type: z.literal('parent_based'),
+  //             root: z.object({
+  //                 probability: z.number().min(0).max(1),
+  //             }),
+  //         }),
+  //     ])
+  //     .optional(),
+  export: import_zod.z.union([
+    import_zod.z.object({
+      type: import_zod.z.literal("otlp"),
+      protocol: import_zod.z.enum(["grpc", "http"]).optional(),
+      endpoint: import_zod.z.union([
+        import_zod.z.string().url(),
+        import_zod.z.string().regex(/^[\w.-]+:\d+$/)
+        // host:port
+      ]).optional(),
+      headers: import_zod.z.record(import_zod.z.string()).optional()
+    }),
+    import_zod.z.object({
+      type: import_zod.z.literal("console")
+    })
+  ]).optional()
+});
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  OtelConfigurationSchema
+});

package/dist/telemetry/schemas.d.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+export declare const OtelConfigurationSchema: z.ZodObject<{
+    serviceName: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    tracerName: z.ZodOptional<z.ZodString>;
+    export: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"otlp">;
+        protocol: z.ZodOptional<z.ZodEnum<["grpc", "http"]>>;
+        endpoint: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodString]>>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "otlp";
+        headers?: Record<string, string> | undefined;
+        protocol?: "http" | "grpc" | undefined;
+        endpoint?: string | undefined;
+    }, {
+        type: "otlp";
+        headers?: Record<string, string> | undefined;
+        protocol?: "http" | "grpc" | undefined;
+        endpoint?: string | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"console">;
+    }, "strip", z.ZodTypeAny, {
+        type: "console";
+    }, {
+        type: "console";
+    }>]>>;
+}, "strip", z.ZodTypeAny, {
+    enabled?: boolean | undefined;
+    serviceName?: string | undefined;
+    tracerName?: string | undefined;
+    export?: {
+        type: "otlp";
+        headers?: Record<string, string> | undefined;
+        protocol?: "http" | "grpc" | undefined;
+        endpoint?: string | undefined;
+    } | {
+        type: "console";
+    } | undefined;
+}, {
+    enabled?: boolean | undefined;
+    serviceName?: string | undefined;
+    tracerName?: string | undefined;
+    export?: {
+        type: "otlp";
+        headers?: Record<string, string> | undefined;
+        protocol?: "http" | "grpc" | undefined;
+        endpoint?: string | undefined;
+    } | {
+        type: "console";
+    } | undefined;
+}>;
+export type OtelConfiguration = z.output<typeof OtelConfigurationSchema>;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/telemetry/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/telemetry/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA6ClC,CAAC;AAEH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,uBAAuB,CAAC,CAAC"}

package/dist/telemetry/schemas.js

@@ -0,0 +1,48 @@
+import "../chunk-C6A6W6XS.js";
+import { z } from "zod";
+const OtelConfigurationSchema = z.object({
+  serviceName: z.string().optional(),
+  enabled: z.boolean().optional(),
+  tracerName: z.string().optional(),
+  // TODO (Telemetry): Implement sampling support in Phase 5
+  // Currently sampling schema is defined but not implemented in telemetry.ts
+  // See feature-plans/telemetry.md Phase 5 for implementation details
+  // sampling: z
+  //     .discriminatedUnion('type', [
+  //         z.object({
+  //             type: z.literal('ratio'),
+  //             probability: z.number().min(0).max(1),
+  //         }),
+  //         z.object({
+  //             type: z.literal('always_on'),
+  //         }),
+  //         z.object({
+  //             type: z.literal('always_off'),
+  //         }),
+  //         z.object({
+  //             type: z.literal('parent_based'),
+  //             root: z.object({
+  //                 probability: z.number().min(0).max(1),
+  //             }),
+  //         }),
+  //     ])
+  //     .optional(),
+  export: z.union([
+    z.object({
+      type: z.literal("otlp"),
+      protocol: z.enum(["grpc", "http"]).optional(),
+      endpoint: z.union([
+        z.string().url(),
+        z.string().regex(/^[\w.-]+:\d+$/)
+        // host:port
+      ]).optional(),
+      headers: z.record(z.string()).optional()
+    }),
+    z.object({
+      type: z.literal("console")
+    })
+  ]).optional()
+});
+export {
+  OtelConfigurationSchema
+};

package/dist/telemetry/telemetry.cjs

@@ -0,0 +1,228 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var telemetry_exports = {};
+__export(telemetry_exports, {
+  Telemetry: () => Telemetry
+});
+module.exports = __toCommonJS(telemetry_exports);
+var import_api = require("@opentelemetry/api");
+var import_sdk_node = require("@opentelemetry/sdk-node");
+var import_sdk_trace_base = require("@opentelemetry/sdk-trace-base");
+var import_exporter_trace_otlp_http = require("@opentelemetry/exporter-trace-otlp-http");
+var import_exporter_trace_otlp_grpc = require("@opentelemetry/exporter-trace-otlp-grpc");
+var import_auto_instrumentations_node = require("@opentelemetry/auto-instrumentations-node");
+var import_resources = require("@opentelemetry/resources");
+var import_semantic_conventions = require("@opentelemetry/semantic-conventions");
+var import_exporters = require("./exporters.js");
+var import_logger = require("../logger/logger.js");
+class Telemetry {
+  tracer = import_api.trace.getTracer("dexto");
+  name = "dexto-service";
+  _isInitialized = false;
+  _sdk;
+  static _initPromise;
+  static _signalHandlers;
+  constructor(config, enabled, sdk) {
+    const serviceName = config.serviceName ?? "dexto-service";
+    const tracerName = config.tracerName ?? serviceName;
+    this.name = serviceName;
+    this.tracer = import_api.trace.getTracer(tracerName);
+    if (sdk) {
+      this._sdk = sdk;
+    }
+    this._isInitialized = enabled && !!sdk;
+  }
+  static buildTraceExporter(config) {
+    const e = config?.export;
+    if (!e || e.type === "console") {
+      return new import_sdk_trace_base.ConsoleSpanExporter();
+    }
+    if (e.type === "otlp") {
+      if (e.protocol === "grpc") {
+        const options2 = {};
+        if (e.endpoint) {
+          options2.url = e.endpoint;
+        }
+        return new import_exporter_trace_otlp_grpc.OTLPTraceExporter(options2);
+      }
+      const options = {};
+      if (e.endpoint) {
+        options.url = e.endpoint;
+      }
+      if (e.headers) {
+        options.headers = e.headers;
+      }
+      return new import_exporter_trace_otlp_http.OTLPTraceExporter(options);
+    }
+    return new import_sdk_trace_base.ConsoleSpanExporter();
+  }
+  /**
+   * Initialize telemetry with the given configuration
+   * @param config - Optional telemetry configuration object
+   * @param exporter - Optional custom span exporter (overrides config.export, useful for testing)
+   * @returns Telemetry instance that can be used for tracing
+   */
+  static async init(config = {}, exporter) {
+    try {
+      if (globalThis.__TELEMETRY__) return globalThis.__TELEMETRY__;
+      if (Telemetry._initPromise) return Telemetry._initPromise;
+      Telemetry._initPromise = (async () => {
+        if (!globalThis.__TELEMETRY__) {
+          const enabled = config.enabled !== false;
+          let sdk;
+          if (enabled) {
+            const resource = new import_resources.Resource({
+              [import_semantic_conventions.ATTR_SERVICE_NAME]: config.serviceName ?? "dexto-service"
+            });
+            const spanExporter = exporter || Telemetry.buildTraceExporter(config);
+            const traceExporter = spanExporter instanceof import_exporters.CompositeExporter ? spanExporter : new import_exporters.CompositeExporter([spanExporter]);
+            sdk = new import_sdk_node.NodeSDK({
+              resource,
+              traceExporter,
+              instrumentations: [(0, import_auto_instrumentations_node.getNodeAutoInstrumentations)()]
+            });
+            await sdk.start();
+            const sigterm = () => {
+              void sdk?.shutdown();
+            };
+            const sigint = () => {
+              void sdk?.shutdown();
+            };
+            process.once("SIGTERM", sigterm);
+            process.once("SIGINT", sigint);
+            Telemetry._signalHandlers = { sigterm, sigint };
+          }
+          globalThis.__TELEMETRY__ = new Telemetry(config, enabled, sdk);
+        }
+        return globalThis.__TELEMETRY__;
+      })();
+      return Telemetry._initPromise;
+    } catch (error) {
+      const wrappedError = new Error(
+        `Failed to initialize telemetry: ${error instanceof Error ? error.message : String(error)}`
+      );
+      Telemetry._initPromise = void 0;
+      throw wrappedError;
+    }
+  }
+  static getActiveSpan() {
+    const span = import_api.trace.getActiveSpan();
+    return span;
+  }
+  /**
+   * Get the global telemetry instance
+   * @throws {Error} If telemetry has not been initialized
+   * @returns {Telemetry} The global telemetry instance
+   */
+  static get() {
+    if (!globalThis.__TELEMETRY__) {
+      throw new Error("Telemetry not initialized");
+    }
+    return globalThis.__TELEMETRY__;
+  }
+  /**
+   * Check if global telemetry instance exists
+   * @returns True if telemetry has been initialized, false otherwise
+   */
+  static hasGlobalInstance() {
+    return globalThis.__TELEMETRY__ !== void 0;
+  }
+  /**
+   * Shutdown global telemetry instance
+   * Used during agent switching to cleanly shutdown old agent's telemetry
+   * before initializing new agent's telemetry with potentially different config
+   * @returns Promise that resolves when shutdown is complete
+   */
+  static async shutdownGlobal() {
+    if (globalThis.__TELEMETRY__) {
+      await globalThis.__TELEMETRY__.shutdown();
+      globalThis.__TELEMETRY__ = void 0;
+    }
+    Telemetry._initPromise = void 0;
+  }
+  /**
+   * Checks if the Telemetry instance has been successfully initialized.
+   * @returns True if the instance is initialized, false otherwise.
+   */
+  isInitialized() {
+    return this._isInitialized;
+  }
+  static setBaggage(baggage, ctx = import_api.context.active()) {
+    const currentBaggage = Object.fromEntries(
+      import_api.propagation.getBaggage(ctx)?.getAllEntries() ?? []
+    );
+    const newCtx = import_api.propagation.setBaggage(
+      ctx,
+      import_api.propagation.createBaggage({
+        ...currentBaggage,
+        ...baggage
+      })
+    );
+    return newCtx;
+  }
+  static withContext(ctx, fn) {
+    return import_api.context.with(ctx, fn);
+  }
+  /**
+   * Forces pending spans to be exported immediately.
+   * Useful for testing to ensure spans are available in exporters.
+   */
+  async forceFlush() {
+    if (this._isInitialized) {
+      const provider = import_api.trace.getTracerProvider();
+      if (provider && typeof provider.forceFlush === "function") {
+        await provider.forceFlush();
+      }
+    }
+  }
+  /**
+   * Shuts down the OpenTelemetry SDK, flushing any pending spans.
+   * This should be called before the application exits.
+   *
+   * Uses two-phase shutdown:
+   * 1. Best-effort flush - Try to export pending spans (can fail if backend unavailable)
+   * 2. Force cleanup - Always clear global state to allow re-initialization
+   *
+   * This ensures agent switching works even when telemetry export fails.
+   */
+  async shutdown() {
+    if (this._sdk) {
+      try {
+        await this._sdk.shutdown();
+      } catch (error) {
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        import_logger.logger.warn(`Telemetry shutdown failed to flush spans (non-blocking): ${errorMsg}`);
+      } finally {
+        this._isInitialized = false;
+        globalThis.__TELEMETRY__ = void 0;
+        if (Telemetry._signalHandlers) {
+          process.off("SIGTERM", Telemetry._signalHandlers.sigterm);
+          process.off("SIGINT", Telemetry._signalHandlers.sigint);
+          Telemetry._signalHandlers = void 0;
+        }
+        this._sdk = void 0;
+        Telemetry._initPromise = void 0;
+      }
+    }
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Telemetry
+});