@dexto/core 1.6.25 → 1.6.26

package/dist/session/session-manager.js

@@ -16,11 +16,13 @@ class SessionManager {
     this.maxSessions = config.maxSessions ?? 100;
     this.sessionTTL = config.sessionTTL ?? 36e5;
     this.sessionLoggerFactory = config.sessionLoggerFactory ?? defaultSessionLoggerFactory;
+    this.languageModelFactory = config.languageModelFactory;
     this.logger = logger.createChild(DextoLogComponent.SESSION);
   }
   sessions = /* @__PURE__ */ new Map();
   maxSessions;
   sessionTTL;
+  static MESSAGE_QUEUE_KEY_PREFIX = "session-message-queue:";
   initialized = false;
   cleanupInterval;
   initializationPromise;
@@ -34,6 +36,16 @@ class SessionManager {
   static FORK_TITLE_PREFIX = "Fork: ";
   static FORK_PARENT_ID_PREVIEW_LENGTH = 8;
   sessionLoggerFactory;
+  languageModelFactory;
+  getChatSessionServices() {
+    return {
+      ...this.services,
+      sessionManager: this,
+      ...this.languageModelFactory !== void 0 && {
+        languageModelFactory: this.languageModelFactory
+      }
+    };
+  }
   /**
    * Initialize the SessionManager with persistent storage.
    * This must be called before using any session operations.
@@ -42,6 +54,7 @@ class SessionManager {
     if (this.initialized) {
       return;
     }
+    await this.clearPersistedQueuedMessages("startup");
     await this.restoreSessionsFromStorage();
     const cleanupIntervalMs = Math.min(this.sessionTTL / 4, 15 * 60 * 1e3);
     this.cleanupInterval = setInterval(
@@ -72,7 +85,11 @@ class SessionManager {
           if (now - lastActivity <= this.sessionTTL) {
             this.logger.debug(`Session ${sessionId} restored from storage`);
           } else {
-            await this.services.storageManager.getDatabase().delete(sessionKey);
+            await Promise.all([
+              this.services.storageManager.getDatabase().delete(sessionKey),
+              this.services.storageManager.getCache().delete(sessionKey),
+              this.deleteSessionInteractionState(sessionId)
+            ]);
             this.logger.debug(`Expired session ${sessionId} cleaned up during restore`);
           }
         }
@@ -83,6 +100,31 @@ class SessionManager {
       );
     }
   }
+  async clearPersistedQueuedMessages(reason) {
+    try {
+      const queueKeys = await this.services.storageManager.getDatabase().list(SessionManager.MESSAGE_QUEUE_KEY_PREFIX);
+      if (queueKeys.length === 0) {
+        return;
+      }
+      await Promise.all(
+        queueKeys.map(
+          (key) => this.services.messageQueueStore.delete(
+            key.slice(SessionManager.MESSAGE_QUEUE_KEY_PREFIX.length)
+          )
+        )
+      );
+      const message = `${reason === "startup" ? "Cleared stale queued follow-up state from previous agent run" : "Cleared queued follow-up state during agent shutdown"} (${queueKeys.length} session bucket(s))`;
+      if (reason === "startup") {
+        this.logger.info(message);
+      } else {
+        this.logger.debug(message);
+      }
+    } catch (error) {
+      this.logger.warn(
+        `Failed to clear persisted queued follow-up state during ${reason}: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
   /**
    * Ensures the SessionManager is initialized before operations.
    */
@@ -274,12 +316,10 @@ class SessionManager {
           this.services.stateManager.updateLLM(restoredConfig, id);
         }
       }
-      const session2 = new ChatSession(
-        { ...this.services, sessionManager: this },
-        id,
-        sessionLogger
-      );
+      const session2 = new ChatSession(this.getChatSessionServices(), id, sessionLogger);
       await session2.init();
+      await this.services.toolManager.restoreSessionState(id);
+      await this.services.approvalManager.restoreSessionState(id);
       this.sessions.set(id, session2);
       this.logger.info(`Restored session from storage: ${id}`);
       return session2;
@@ -288,6 +328,7 @@ class SessionManager {
     if (activeSessionKeys.length >= this.maxSessions) {
       throw SessionError.maxSessionsExceeded(activeSessionKeys.length, this.maxSessions);
     }
+    await this.deleteSessionInteractionState(id);
     const workspace = await this.services.workspaceManager?.getWorkspace();
     const sessionData = {
       id,
@@ -313,11 +354,7 @@ class SessionManager {
         agentId,
         sessionId: id
       });
-      session = new ChatSession(
-        { ...this.services, sessionManager: this },
-        id,
-        sessionLogger
-      );
+      session = new ChatSession(this.getChatSessionServices(), id, sessionLogger);
       await session.init();
       this.sessions.set(id, session);
       await this.services.storageManager.getCache().set(sessionKey, sessionData, this.sessionTTL / 1e3);
@@ -376,11 +413,13 @@ class SessionManager {
           }
         }
         const session = new ChatSession(
-          { ...this.services, sessionManager: this },
+          this.getChatSessionServices(),
           sessionId,
           sessionLogger
         );
         await session.init();
+        await this.services.toolManager.restoreSessionState(sessionId);
+        await this.services.approvalManager.restoreSessionState(sessionId);
         this.sessions.set(sessionId, session);
         return session;
       }
@@ -402,6 +441,7 @@ class SessionManager {
     }
     const sessionKey = `session:${sessionId}`;
     await this.services.storageManager.getCache().delete(sessionKey);
+    this.evictSessionInteractionState(sessionId);
     this.logger.debug(
       `Ended session (removed from memory, chat history preserved): ${sessionId}`
     );
@@ -422,12 +462,13 @@ class SessionManager {
     const sessionKey = `session:${sessionId}`;
     await this.services.storageManager.getDatabase().delete(sessionKey);
     await this.services.storageManager.getCache().delete(sessionKey);
+    await this.deleteSessionInteractionState(sessionId);
     const messagesKey = `messages:${sessionId}`;
     await this.services.storageManager.getDatabase().delete(messagesKey);
     this.logger.debug(`Deleted session and conversation history: ${sessionId}`);
   }
   /**
-   * Resets the conversation history for a session while keeping the session alive.
+   * Resets conversation and session-scoped interaction state while keeping the session alive.
    *
    * @param sessionId The session ID to reset
    * @throws Error if session doesn't exist
@@ -439,6 +480,15 @@ class SessionManager {
       throw SessionError.notFound(sessionId);
     }
     await session.reset();
+    await session.clearMessageQueue();
+    await Promise.all([
+      this.services.toolManager.deleteSessionState(sessionId),
+      this.services.approvalManager.deleteSessionState(sessionId)
+    ]);
+    if (this.services.stateManager.hasSessionLLMOverride(sessionId)) {
+      this.services.stateManager.clearSessionOverride(sessionId);
+      await session.switchLLM(this.services.stateManager.getRuntimeConfig().llm);
+    }
     await this.runWithSessionDataLock(sessionId, async (sessionKey) => {
       const sessionData = await this.services.storageManager.getDatabase().get(sessionKey);
       if (!sessionData) {
@@ -446,6 +496,7 @@ class SessionManager {
       }
       sessionData.messageCount = 0;
       sessionData.lastActivity = Date.now();
+      delete sessionData.llmOverride;
       await this.persistSessionData(sessionKey, sessionData);
     });
     this.logger.debug(`Reset session conversation: ${sessionId}`);
@@ -736,6 +787,7 @@ class SessionManager {
       if (session) {
         session.dispose();
         this.sessions.delete(sessionId);
+        this.evictSessionInteractionState(sessionId);
         this.logger.debug(
           `Removed expired session from memory: ${sessionId} (chat history preserved)`
         );
@@ -760,8 +812,7 @@ class SessionManager {
       const session = await this.getSession(sId);
       if (session) {
         try {
-          this.services.stateManager.updateLLM(newLLMConfig, sId);
-          await session.switchLLM(newLLMConfig);
+          await this.applySessionLLMSwitch(sId, session, newLLMConfig);
         } catch (error) {
           failedSessions.push(sId);
           this.logger.warn(
@@ -790,16 +841,7 @@ class SessionManager {
     if (!session) {
       throw SessionError.notFound(sessionId);
     }
-    await session.switchLLM(newLLMConfig);
-    await this.runWithSessionDataLock(sessionId, async (sessionKey) => {
-      const sessionData = await this.services.storageManager.getDatabase().get(sessionKey);
-      if (!sessionData) {
-        return;
-      }
-      const { apiKey: _apiKey, ...configWithoutApiKey } = newLLMConfig;
-      sessionData.llmOverride = configWithoutApiKey;
-      await this.persistSessionData(sessionKey, sessionData);
-    });
+    await this.applySessionLLMSwitch(sessionId, session, newLLMConfig);
     this.services.agentEventBus.emit("llm:switched", {
       newConfig: newLLMConfig,
       historyRetained: true,
@@ -808,6 +850,68 @@ class SessionManager {
     const message = `Successfully switched to ${newLLMConfig.provider}/${newLLMConfig.model} for session ${sessionId}`;
     return { message, warnings: [] };
   }
+  async applySessionLLMSwitch(sessionId, session, newLLMConfig) {
+    const previousLLMConfig = this.services.stateManager.getRuntimeConfig(sessionId).llm;
+    const previousHadOverride = this.services.stateManager.hasSessionLLMOverride(sessionId);
+    const previousPersistedOverride = await this.getPersistedSessionLLMOverride(sessionId);
+    await this.setPersistedSessionLLMOverride(
+      sessionId,
+      this.toPersistedLLMConfig(newLLMConfig)
+    );
+    try {
+      this.services.stateManager.updateLLM(newLLMConfig, sessionId);
+      await session.switchLLM(newLLMConfig);
+    } catch (error) {
+      await this.setPersistedSessionLLMOverride(sessionId, previousPersistedOverride);
+      if (previousHadOverride) {
+        this.services.stateManager.updateLLM(previousLLMConfig, sessionId);
+      } else {
+        this.services.stateManager.clearSessionOverride(sessionId);
+      }
+      try {
+        await session.switchLLM(previousLLMConfig);
+      } catch (rollbackError) {
+        this.logger.error(
+          `Failed to roll back LLM switch for session ${sessionId}: ${rollbackError instanceof Error ? rollbackError.message : String(rollbackError)}`
+        );
+      }
+      throw error;
+    }
+  }
+  async getPersistedSessionLLMOverride(sessionId) {
+    const sessionData = await this.getSessionData(sessionId);
+    return sessionData?.llmOverride;
+  }
+  toPersistedLLMConfig(newLLMConfig) {
+    const { apiKey: _apiKey, ...configWithoutApiKey } = newLLMConfig;
+    return configWithoutApiKey;
+  }
+  async setPersistedSessionLLMOverride(sessionId, llmOverride) {
+    await this.runWithSessionDataLock(sessionId, async (sessionKey) => {
+      const sessionData = await this.services.storageManager.getDatabase().get(sessionKey);
+      if (!sessionData) {
+        return;
+      }
+      if (llmOverride !== void 0) {
+        sessionData.llmOverride = llmOverride;
+      } else {
+        delete sessionData.llmOverride;
+      }
+      await this.persistSessionData(sessionKey, sessionData);
+    });
+  }
+  async deleteSessionInteractionState(sessionId) {
+    this.services.stateManager.clearSessionOverride(sessionId);
+    await Promise.all([
+      this.services.toolManager.deleteSessionState(sessionId),
+      this.services.approvalManager.deleteSessionState(sessionId),
+      this.services.messageQueueStore.delete(sessionId)
+    ]);
+  }
+  evictSessionInteractionState(sessionId) {
+    this.services.toolManager.evictSessionState(sessionId);
+    this.services.approvalManager.evictSessionState(sessionId);
+  }
   async runWithSessionDataLock(sessionId, fn) {
     const sessionKey = `session:${sessionId}`;
     const previousLock = this.sessionDataLocks.get(sessionKey) ?? Promise.resolve();
@@ -868,6 +972,7 @@ class SessionManager {
       delete this.cleanupInterval;
       this.logger.debug("Periodic session cleanup stopped");
     }
+    await this.clearPersistedQueuedMessages("shutdown");
     const sessionIds = Array.from(this.sessions.keys());
     for (const sessionId of sessionIds) {
       try {

package/dist/session/title-generator.cjs

@@ -25,6 +25,7 @@ module.exports = __toCommonJS(title_generator_exports);
 var import_factory = require("../llm/services/factory.js");
 var import_events = require("../events/index.js");
 var import_memory = require("./history/memory.js");
+var import_message_queue = require("./message-queue.js");
 async function generateSessionTitle(config, toolManager, systemPromptManager, resourceManager, userText, logger, opts = {}) {
   const timeoutMs = opts.timeoutMs;
   const controller = timeoutMs !== void 0 ? new AbortController() : void 0;
@@ -35,15 +36,21 @@ async function generateSessionTitle(config, toolManager, systemPromptManager, re
   try {
     const history = new import_memory.MemoryHistoryProvider(logger);
     const bus = new import_events.SessionEventBus();
+    const sessionId = `titlegen-${Math.random().toString(36).slice(2)}`;
+    const options = {
+      messageQueue: import_message_queue.MessageQueueService.createEphemeral(bus, logger, sessionId)
+    };
     const tempService = (0, import_factory.createLLMService)(
       config,
       toolManager,
       systemPromptManager,
       history,
       bus,
-      `titlegen-${Math.random().toString(36).slice(2)}`,
+      sessionId,
       resourceManager,
-      logger
+      logger,
+      options,
+      opts.languageModelFactory
     );
     const instruction = [
       "Generate a short conversation title from the following user message.",

package/dist/session/title-generator.d.ts

@@ -3,6 +3,7 @@ import type { ToolManager } from '../tools/tool-manager.js';
 import type { SystemPromptManager } from '../systemPrompt/manager.js';
 import type { ResourceManager } from '../resources/index.js';
 import type { Logger } from '../logger/v2/types.js';
+import type { LanguageModelFactory } from '../llm/services/types.js';
 export interface GenerateSessionTitleResult {
     title?: string;
     error?: string;
@@ -14,6 +15,7 @@ export interface GenerateSessionTitleResult {
  */
 export declare function generateSessionTitle(config: ValidatedLLMConfig, toolManager: ToolManager, systemPromptManager: SystemPromptManager, resourceManager: ResourceManager, userText: string, logger: Logger, opts?: {
     timeoutMs?: number;
+    languageModelFactory?: LanguageModelFactory;
 }): Promise<GenerateSessionTitleResult>;
 /**
  * Heuristic fallback when the LLM-based title fails.

package/dist/session/title-generator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"title-generator.d.ts","sourceRoot":"","sources":["../../src/session/title-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAKpD,MAAM,WAAW,0BAA0B;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,WAAW,EACxB,mBAAmB,EAAE,mBAAmB,EACxC,eAAe,EAAE,eAAe,EAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,0BAA0B,CAAC,CAmDrC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA8BzE"}
+{"version":3,"file":"title-generator.d.ts","sourceRoot":"","sources":["../../src/session/title-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAA2B,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAM9F,MAAM,WAAW,0BAA0B;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CACtC,MAAM,EAAE,kBAAkB,EAC1B,WAAW,EAAE,WAAW,EACxB,mBAAmB,EAAE,mBAAmB,EACxC,eAAe,EAAE,eAAe,EAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,oBAAoB,CAAC,EAAE,oBAAoB,CAAA;CAAO,GAC/E,OAAO,CAAC,0BAA0B,CAAC,CAyDrC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CA8BzE"}

package/dist/session/title-generator.js

@@ -2,6 +2,7 @@ import "../chunk-PTJYTZNU.js";
 import { createLLMService } from "../llm/services/factory.js";
 import { SessionEventBus } from "../events/index.js";
 import { MemoryHistoryProvider } from "./history/memory.js";
+import { MessageQueueService } from "./message-queue.js";
 async function generateSessionTitle(config, toolManager, systemPromptManager, resourceManager, userText, logger, opts = {}) {
   const timeoutMs = opts.timeoutMs;
   const controller = timeoutMs !== void 0 ? new AbortController() : void 0;
@@ -12,15 +13,21 @@ async function generateSessionTitle(config, toolManager, systemPromptManager, re
   try {
     const history = new MemoryHistoryProvider(logger);
     const bus = new SessionEventBus();
+    const sessionId = `titlegen-${Math.random().toString(36).slice(2)}`;
+    const options = {
+      messageQueue: MessageQueueService.createEphemeral(bus, logger, sessionId)
+    };
     const tempService = createLLMService(
       config,
       toolManager,
       systemPromptManager,
       history,
       bus,
-      `titlegen-${Math.random().toString(36).slice(2)}`,
+      sessionId,
       resourceManager,
-      logger
+      logger,
+      options,
+      opts.languageModelFactory
     );
     const instruction = [
       "Generate a short conversation title from the following user message.",

package/dist/telemetry/errors.cjs

@@ -80,9 +80,9 @@ class TelemetryError {
       import_error_codes.TelemetryErrorCode.NOT_INITIALIZED,
       import_types.ErrorScope.TELEMETRY,
       import_types.ErrorType.USER,
-      "Telemetry not initialized. Call Telemetry.init() first.",
+      "Telemetry not initialized. Call Telemetry.init() or Telemetry.registerGlobal() first.",
       {
-        hint: "Ensure telemetry is initialized before accessing the global instance."
+        hint: "Ensure telemetry is initialized via Telemetry.init() or Telemetry.registerGlobal() before accessing the global instance."
       }
     );
   }

package/dist/telemetry/errors.js

@@ -58,9 +58,9 @@ class TelemetryError {
       TelemetryErrorCode.NOT_INITIALIZED,
       ErrorScope.TELEMETRY,
       ErrorType.USER,
-      "Telemetry not initialized. Call Telemetry.init() first.",
+      "Telemetry not initialized. Call Telemetry.init() or Telemetry.registerGlobal() first.",
       {
-        hint: "Ensure telemetry is initialized before accessing the global instance."
+        hint: "Ensure telemetry is initialized via Telemetry.init() or Telemetry.registerGlobal() before accessing the global instance."
       }
     );
   }

package/dist/telemetry/index.d.ts

@@ -1,4 +1,4 @@
-export { Telemetry } from './telemetry.js';
+export { Telemetry, type TelemetryRegistrationOptions, type TelemetryShutdownHandler, } from './telemetry.js';
 export { OtelConfigurationSchema } from './schemas.js';
 export type { OtelConfiguration } from './schemas.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/telemetry/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACH,SAAS,EACT,KAAK,4BAA4B,EACjC,KAAK,wBAAwB,GAChC,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/telemetry/index.js

@@ -1,5 +1,7 @@
 import "../chunk-PTJYTZNU.js";
-import { Telemetry } from "./telemetry.js";
+import {
+  Telemetry
+} from "./telemetry.js";
 import { OtelConfigurationSchema } from "./schemas.js";
 export {
   OtelConfigurationSchema,

package/dist/telemetry/telemetry.cjs

@@ -40,17 +40,17 @@ class Telemetry {
   name = "dexto-service";
   _isInitialized = false;
   _sdk;
+  _shutdownHandler;
   static _initPromise;
   static _signalHandlers;
-  constructor(config, enabled, sdk) {
+  constructor(config, options) {
     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;
+    this._sdk = options.sdk;
+    this._shutdownHandler = options.shutdown;
+    this._isInitialized = options.initialized;
   }
   static async buildTraceExporter(config) {
     const e = config?.export;
@@ -178,7 +178,10 @@ class Telemetry {
             process.once("SIGINT", sigint);
             Telemetry._signalHandlers = { sigterm, sigint };
           }
-          globalThis.__TELEMETRY__ = new Telemetry(config, enabled, sdk);
+          globalThis.__TELEMETRY__ = new Telemetry(config, {
+            initialized: enabled && !!sdk,
+            ...sdk !== void 0 && { sdk }
+          });
         }
         return globalThis.__TELEMETRY__;
       })();
@@ -194,6 +197,38 @@ class Telemetry {
       );
     }
   }
+  /**
+   * Register a global telemetry instance after a host installs its own provider/exporter lifecycle.
+   *
+   * This keeps core instrumentation active without forcing the default Node SDK bootstrap path.
+   */
+  static async registerGlobal(options = {}) {
+    try {
+      if (globalThis.__TELEMETRY__) return globalThis.__TELEMETRY__;
+      if (Telemetry._initPromise) return Telemetry._initPromise;
+      const config = options.config ?? {};
+      const initialized = options.initialized ?? true;
+      Telemetry._initPromise = Promise.resolve().then(() => {
+        if (!globalThis.__TELEMETRY__) {
+          globalThis.__TELEMETRY__ = new Telemetry(config, {
+            initialized,
+            ...options.shutdown !== void 0 && { shutdown: options.shutdown }
+          });
+        }
+        return globalThis.__TELEMETRY__;
+      });
+      return await Telemetry._initPromise;
+    } catch (error) {
+      Telemetry._initPromise = void 0;
+      if (error instanceof import_DextoRuntimeError.DextoRuntimeError) {
+        throw error;
+      }
+      throw import_errors.TelemetryError.initializationFailed(
+        error instanceof Error ? error.message : String(error),
+        error
+      );
+    }
+  }
   static getActiveSpan() {
     const span = import_api.trace.getActiveSpan();
     return span;
@@ -275,25 +310,31 @@ class Telemetry {
    * This ensures agent switching works even when telemetry export fails.
    */
   async shutdown() {
-    if (this._sdk) {
-      try {
+    try {
+      if (this._shutdownHandler) {
+        await this._shutdownHandler();
+      } else if (this._sdk) {
         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;
       }
+    } 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.cleanupAfterShutdown();
     }
   }
+  cleanupAfterShutdown() {
+    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;
+    this._shutdownHandler = void 0;
+    Telemetry._initPromise = void 0;
+  }
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/telemetry/telemetry.d.ts

@@ -1,5 +1,11 @@
 import type { Tracer, Context, BaggageEntry } from '@opentelemetry/api';
 import type { OtelConfiguration } from './schemas.js';
+export type TelemetryShutdownHandler = () => Promise<void>;
+export type TelemetryRegistrationOptions = {
+    config?: OtelConfiguration | undefined;
+    initialized?: boolean | undefined;
+    shutdown?: TelemetryShutdownHandler | undefined;
+};
 declare global {
     var __TELEMETRY__: Telemetry | undefined;
 }
@@ -17,6 +23,7 @@ export declare class Telemetry {
     name: string;
     private _isInitialized;
     private _sdk?;
+    private _shutdownHandler?;
     private static _initPromise?;
     private static _signalHandlers?;
     private constructor();
@@ -28,6 +35,12 @@ export declare class Telemetry {
      * @returns Telemetry instance that can be used for tracing
      */
     static init(config?: OtelConfiguration, exporter?: import('@opentelemetry/sdk-trace-base').SpanExporter): Promise<Telemetry>;
+    /**
+     * Register a global telemetry instance after a host installs its own provider/exporter lifecycle.
+     *
+     * This keeps core instrumentation active without forcing the default Node SDK bootstrap path.
+     */
+    static registerGlobal(options?: TelemetryRegistrationOptions): Promise<Telemetry>;
     static getActiveSpan(): import("@opentelemetry/api").Span | undefined;
     /**
      * Get the global telemetry instance
@@ -70,5 +83,6 @@ export declare class Telemetry {
      * This ensures agent switching works even when telemetry export fails.
      */
     shutdown(): Promise<void>;
+    private cleanupAfterShutdown;
 }
 //# sourceMappingURL=telemetry.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAYtD,OAAO,CAAC,MAAM,CAAC;IACX,IAAI,aAAa,EAAE,SAAS,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS;IACX,MAAM,EAAE,MAAM,CAA4B;IACjD,IAAI,EAAE,MAAM,CAAmB;IAC/B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,IAAI,CAAC,CAA0B;IACvC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAiC;IAC7D,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAA0D;IAEzF,OAAO;mBAYc,kBAAkB;IA0DvC;;;;;OAKG;WACU,IAAI,CACb,MAAM,GAAE,iBAAsB,EAC9B,QAAQ,CAAC,EAAE,OAAO,+BAA+B,EAAE,YAAY,GAChE,OAAO,CAAC,SAAS,CAAC;IA8HrB,MAAM,CAAC,aAAa;IAKpB;;;;OAIG;IACH,MAAM,CAAC,GAAG,IAAI,SAAS;IAOvB;;;OAGG;IACH,MAAM,CAAC,iBAAiB,IAAI,OAAO;IAInC;;;;;OAKG;WACU,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5C;;;OAGG;IACI,aAAa,IAAI,OAAO;IAI/B,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,GAAG,GAAE,OAA8B;IAc5F,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,IAAI;IAI/C;;;OAGG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUxC;;;;;;;;;OASG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CA8BzC"}
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAUtD,MAAM,MAAM,wBAAwB,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAE3D,MAAM,MAAM,4BAA4B,GAAG;IACvC,MAAM,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC;IACvC,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;CACnD,CAAC;AASF,OAAO,CAAC,MAAM,CAAC;IACX,IAAI,aAAa,EAAE,SAAS,GAAG,SAAS,CAAC;CAC5C;AAED;;;;;;;;GAQG;AACH,qBAAa,SAAS;IACX,MAAM,EAAE,MAAM,CAA4B;IACjD,IAAI,EAAE,MAAM,CAAmB;IAC/B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,IAAI,CAAC,CAA0B;IACvC,OAAO,CAAC,gBAAgB,CAAC,CAAuC;IAChE,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAiC;IAC7D,OAAO,CAAC,MAAM,CAAC,eAAe,CAAC,CAA0D;IAEzF,OAAO;mBAWc,kBAAkB;IA0DvC;;;;;OAKG;WACU,IAAI,CACb,MAAM,GAAE,iBAAsB,EAC9B,QAAQ,CAAC,EAAE,OAAO,+BAA+B,EAAE,YAAY,GAChE,OAAO,CAAC,SAAS,CAAC;IAiIrB;;;;OAIG;WACU,cAAc,CAAC,OAAO,GAAE,4BAAiC,GAAG,OAAO,CAAC,SAAS,CAAC;IAiC3F,MAAM,CAAC,aAAa;IAKpB;;;;OAIG;IACH,MAAM,CAAC,GAAG,IAAI,SAAS;IAOvB;;;OAGG;IACH,MAAM,CAAC,iBAAiB,IAAI,OAAO;IAInC;;;;;OAKG;WACU,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5C;;;OAGG;IACI,aAAa,IAAI,OAAO;IAI/B,MAAM,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,GAAG,GAAE,OAA8B;IAc5F,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,IAAI;IAI/C;;;OAGG;IACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAUxC;;;;;;;;;OASG;IACU,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAmBtC,OAAO,CAAC,oBAAoB;CAiB/B"}