@juspay/neurolink 7.49.0 → 7.50.0

package/dist/neurolink.js

@@ -39,6 +39,7 @@ import { directToolsServer } from "./mcp/servers/agent/directToolsServer.js";
 // Import orchestration components
 import { ModelRouter } from "./utils/modelRouter.js";
 import { BinaryTaskClassifier } from "./utils/taskClassifier.js";
+import { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, } from "./services/server/ai/observability/instrumentation.js";
 import { isNonNullObject } from "./utils/typeUtils.js";
 import { isZodSchema } from "./utils/schemaConversion.js";
 // Core types imported from "./types/index.js"
@@ -178,8 +179,10 @@ export class NeuroLink {
      * @throws {Error} When external server manager initialization fails
      * @throws {Error} When HITL configuration is invalid (if enabled)
      */
+    observabilityConfig;
     constructor(config) {
         this.toolRegistry = config?.toolRegistry || new MCPToolRegistry();
+        this.observabilityConfig = config?.observability;
         // Initialize orchestration setting
         this.enableOrchestration = config?.enableOrchestration ?? false;
         // Read tool cache duration from environment variables, with a default
@@ -194,6 +197,7 @@ export class NeuroLink {
         this.initializeConversationMemory(config, constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeExternalServerManager(constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeHITL(config, constructorId, constructorStartTime, constructorHrTimeStart);
+        this.initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart);
         this.logConstructorComplete(constructorId, constructorStartTime, constructorHrTimeStart);
     }
     /**
@@ -494,6 +498,81 @@ export class NeuroLink {
             this.unregisterExternalMCPToolFromRegistry(event.toolName);
         });
     }
+    /**
+     * Initialize Langfuse observability for AI operations tracking
+     */
+    initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart) {
+        const langfuseInitStartTime = process.hrtime.bigint();
+        try {
+            const langfuseConfig = this.observabilityConfig?.langfuse;
+            if (langfuseConfig?.enabled) {
+                logger.debug(`[NeuroLink] 📊 LOG_POINT_C019_LANGFUSE_INIT_START`, {
+                    logPoint: "C019_LANGFUSE_INIT_START",
+                    constructorId,
+                    timestamp: new Date().toISOString(),
+                    elapsedMs: Date.now() - constructorStartTime,
+                    elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                    langfuseInitStartTimeNs: langfuseInitStartTime.toString(),
+                    message: "Starting Langfuse observability initialization",
+                });
+                // Initialize OpenTelemetry FIRST (required for Langfuse v4)
+                initializeOpenTelemetry(langfuseConfig);
+                const healthStatus = getLangfuseHealthStatus();
+                const langfuseInitDurationNs = process.hrtime.bigint() - langfuseInitStartTime;
+                if (healthStatus.initialized &&
+                    healthStatus.hasProcessor &&
+                    healthStatus.isHealthy) {
+                    logger.debug(`[NeuroLink] ✅ LOG_POINT_C020_LANGFUSE_INIT_SUCCESS`, {
+                        logPoint: "C020_LANGFUSE_INIT_SUCCESS",
+                        constructorId,
+                        timestamp: new Date().toISOString(),
+                        elapsedMs: Date.now() - constructorStartTime,
+                        elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                        langfuseInitDurationNs: langfuseInitDurationNs.toString(),
+                        langfuseInitDurationMs: Number(langfuseInitDurationNs) / 1_000_000,
+                        healthStatus,
+                        message: "Langfuse observability initialized successfully",
+                    });
+                }
+                else {
+                    logger.warn(`[NeuroLink] ⚠️ LOG_POINT_C021_LANGFUSE_INIT_WARNING`, {
+                        logPoint: "C021_LANGFUSE_INIT_WARNING",
+                        constructorId,
+                        timestamp: new Date().toISOString(),
+                        elapsedMs: Date.now() - constructorStartTime,
+                        elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                        langfuseInitDurationNs: langfuseInitDurationNs.toString(),
+                        healthStatus,
+                        message: "Langfuse initialized but not healthy",
+                    });
+                }
+            }
+            else {
+                logger.debug(`[NeuroLink] 🚫 LOG_POINT_C022_LANGFUSE_DISABLED`, {
+                    logPoint: "C022_LANGFUSE_DISABLED",
+                    constructorId,
+                    timestamp: new Date().toISOString(),
+                    elapsedMs: Date.now() - constructorStartTime,
+                    elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                    message: "Langfuse observability not enabled - skipping initialization",
+                });
+            }
+        }
+        catch (error) {
+            const langfuseInitErrorDurationNs = process.hrtime.bigint() - langfuseInitStartTime;
+            logger.error(`[NeuroLink] ❌ LOG_POINT_C023_LANGFUSE_INIT_ERROR`, {
+                logPoint: "C023_LANGFUSE_INIT_ERROR",
+                constructorId,
+                timestamp: new Date().toISOString(),
+                elapsedMs: Date.now() - constructorStartTime,
+                elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
+                langfuseInitDurationNs: langfuseInitErrorDurationNs.toString(),
+                errorMessage: error instanceof Error ? error.message : String(error),
+                errorStack: error instanceof Error ? error.stack : undefined,
+                message: "Langfuse observability initialization failed",
+            });
+        }
+    }
     /**
      * Log constructor completion with final state summary
      */
@@ -992,6 +1071,68 @@ export class NeuroLink {
      * @throws {Error} When all providers fail to generate content
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
+    /**
+     * Get observability configuration
+     */
+    getObservabilityConfig() {
+        return this.observabilityConfig;
+    }
+    /**
+     * Check if Langfuse telemetry is enabled
+     * Centralized utility to avoid duplication across providers
+     */
+    isTelemetryEnabled() {
+        return this.observabilityConfig?.langfuse?.enabled || false;
+    }
+    /**
+     * Public method to initialize Langfuse observability
+     * This method can be called externally to ensure Langfuse is properly initialized
+     */
+    async initializeLangfuseObservability() {
+        try {
+            const langfuseConfig = this.observabilityConfig?.langfuse;
+            if (langfuseConfig?.enabled) {
+                initializeOpenTelemetry(langfuseConfig);
+                logger.debug("[NeuroLink] Langfuse observability initialized via public method");
+            }
+            else {
+                logger.debug("[NeuroLink] Langfuse not enabled, skipping initialization");
+            }
+        }
+        catch (error) {
+            logger.warn("[NeuroLink] Failed to initialize Langfuse observability:", error);
+        }
+    }
+    /**
+     * Gracefully shutdown NeuroLink and all MCP connections
+     */
+    async shutdown() {
+        try {
+            logger.debug("[NeuroLink] Starting graceful shutdown");
+            try {
+                await flushOpenTelemetry();
+                await shutdownOpenTelemetry();
+                logger.debug("[NeuroLink] OpenTelemetry shutdown completed");
+            }
+            catch (error) {
+                logger.warn("[NeuroLink] OpenTelemetry shutdown failed:", error);
+            }
+            if (this.externalServerManager) {
+                try {
+                    await this.externalServerManager.shutdown();
+                    logger.debug("[NeuroLink] MCP servers shutdown completed");
+                }
+                catch (error) {
+                    logger.warn("[NeuroLink] MCP servers shutdown failed:", error);
+                }
+            }
+            logger.debug("[NeuroLink] Graceful shutdown completed");
+        }
+        catch (error) {
+            logger.error("[NeuroLink] Shutdown failed:", error);
+            throw error;
+        }
+    }
     async generate(optionsOrPrompt) {
         const originalPrompt = this._extractOriginalPrompt(optionsOrPrompt);
         // Convert string prompt to full options

package/dist/providers/anthropic.js

@@ -147,6 +147,7 @@ export class AnthropicProvider extends BaseProvider {
                 maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 toolChoice: shouldUseTools ? "auto" : "none",
                 abortSignal: timeoutController?.controller.signal,
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                         logger.warn("[AnthropicProvider] Failed to store tool executions", {

package/dist/providers/azureOpenai.js

@@ -162,6 +162,7 @@ export class AzureOpenAIProvider extends BaseProvider {
                     : {}),
                 tools,
                 toolChoice: shouldUseTools ? "auto" : "none",
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                         logger.warn("[AzureOpenaiProvider] Failed to store tool executions", {

package/dist/providers/googleAiStudio.js

@@ -141,6 +141,7 @@ export class GoogleAIStudioProvider extends BaseProvider {
                 maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 toolChoice: shouldUseTools ? "auto" : "none",
                 abortSignal: timeoutController?.controller.signal,
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     this.handleToolExecutionStorage(toolCalls, toolResults, options, new Date()).catch((error) => {
                         logger.warn("[GoogleAiStudioProvider] Failed to store tool executions", {

package/dist/providers/googleVertex.js

@@ -666,6 +666,7 @@ export class GoogleVertexProvider extends BaseProvider {
                     maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 }),
                 abortSignal: timeoutController?.controller.signal,
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onError: (event) => {
                     const error = event.error;
                     const errorMessage = error instanceof Error ? error.message : String(error);

package/dist/providers/openAI.js

@@ -316,6 +316,7 @@ export class OpenAIProvider extends BaseProvider {
                 maxSteps: options.maxSteps || DEFAULT_MAX_STEPS,
                 toolChoice: shouldUseTools && Object.keys(tools).length > 0 ? "auto" : "none",
                 abortSignal: timeoutController?.controller.signal,
+                experimental_telemetry: this.getStreamTelemetryConfig(options),
                 onStepFinish: ({ toolCalls, toolResults }) => {
                     logger.info("Tool execution completed", { toolResults, toolCalls });
                     // Handle tool execution storage

package/dist/services/server/ai/observability/instrumentation.d.ts

@@ -0,0 +1,57 @@
+/**
+ * OpenTelemetry Instrumentation for Langfuse v4
+ *
+ * Configures OpenTelemetry TracerProvider with LangfuseSpanProcessor to capture
+ * traces from Vercel AI SDK's experimental_telemetry feature.
+ *
+ * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
+ */
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import type { LangfuseConfig } from "../../../../types/observability.js";
+/**
+ * Initialize OpenTelemetry with Langfuse span processor
+ *
+ * This connects Vercel AI SDK's experimental_telemetry to Langfuse by:
+ * 1. Creating LangfuseSpanProcessor with Langfuse credentials
+ * 2. Creating a NodeTracerProvider with service metadata and span processor
+ * 3. Registering the provider globally for AI SDK to use
+ *
+ * @param config - Langfuse configuration passed from parent application
+ */
+export declare function initializeOpenTelemetry(config: LangfuseConfig): void;
+/**
+ * Flush all pending spans to Langfuse
+ */
+export declare function flushOpenTelemetry(): Promise<void>;
+/**
+ * Shutdown OpenTelemetry and Langfuse span processor
+ */
+export declare function shutdownOpenTelemetry(): Promise<void>;
+/**
+ * Get the Langfuse span processor
+ */
+export declare function getLangfuseSpanProcessor(): LangfuseSpanProcessor | null;
+/**
+ * Get the tracer provider
+ */
+export declare function getTracerProvider(): NodeTracerProvider | null;
+/**
+ * Check if OpenTelemetry is initialized
+ */
+export declare function isOpenTelemetryInitialized(): boolean;
+/**
+ * Get health status for Langfuse observability
+ */
+export declare function getLangfuseHealthStatus(): {
+    isHealthy: boolean | undefined;
+    initialized: boolean;
+    credentialsValid: boolean;
+    enabled: boolean;
+    hasProcessor: boolean;
+    config: {
+        baseUrl: string;
+        environment: string;
+        release: string;
+    } | undefined;
+};

package/dist/services/server/ai/observability/instrumentation.js

@@ -0,0 +1,170 @@
+/**
+ * OpenTelemetry Instrumentation for Langfuse v4
+ *
+ * Configures OpenTelemetry TracerProvider with LangfuseSpanProcessor to capture
+ * traces from Vercel AI SDK's experimental_telemetry feature.
+ *
+ * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
+ */
+import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
+import { LangfuseSpanProcessor } from "@langfuse/otel";
+import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { logger } from "../../../../utils/logger.js";
+const LOG_PREFIX = "[OpenTelemetry]";
+let tracerProvider = null;
+let langfuseProcessor = null;
+let isInitialized = false;
+let isCredentialsValid = false;
+let currentConfig = null;
+/**
+ * Initialize OpenTelemetry with Langfuse span processor
+ *
+ * This connects Vercel AI SDK's experimental_telemetry to Langfuse by:
+ * 1. Creating LangfuseSpanProcessor with Langfuse credentials
+ * 2. Creating a NodeTracerProvider with service metadata and span processor
+ * 3. Registering the provider globally for AI SDK to use
+ *
+ * @param config - Langfuse configuration passed from parent application
+ */
+export function initializeOpenTelemetry(config) {
+    if (isInitialized) {
+        logger.debug(`${LOG_PREFIX} Already initialized`);
+        return;
+    }
+    if (!config.enabled) {
+        logger.debug(`${LOG_PREFIX} Langfuse disabled, skipping initialization`);
+        isInitialized = true;
+        return;
+    }
+    if (!config.publicKey || !config.secretKey) {
+        logger.warn(`${LOG_PREFIX} Langfuse enabled but missing credentials, skipping initialization`);
+        isInitialized = true;
+        isCredentialsValid = false;
+        return;
+    }
+    try {
+        currentConfig = config;
+        isCredentialsValid = true;
+        // Create Langfuse span processor with configuration
+        langfuseProcessor = new LangfuseSpanProcessor({
+            publicKey: config.publicKey,
+            secretKey: config.secretKey,
+            baseUrl: config.baseUrl || "https://cloud.langfuse.com",
+            environment: config.environment || "dev",
+            release: config.release || "v1.0.0",
+        });
+        // Create resource with service metadata (v2.x API)
+        const resource = resourceFromAttributes({
+            [ATTR_SERVICE_NAME]: "neurolink",
+            [ATTR_SERVICE_VERSION]: config.release || "v1.0.0",
+            "deployment.environment": config.environment || "dev",
+        });
+        // Initialize tracer provider with span processor and resource
+        tracerProvider = new NodeTracerProvider({
+            resource,
+            spanProcessors: [langfuseProcessor],
+        });
+        // Register provider globally so Vercel AI SDK can use it
+        tracerProvider.register();
+        isInitialized = true;
+        logger.info(`${LOG_PREFIX} Initialized with Langfuse span processor`, {
+            baseUrl: config.baseUrl || "https://cloud.langfuse.com",
+            environment: config.environment || "dev",
+            release: config.release || "v1.0.0",
+        });
+    }
+    catch (error) {
+        logger.error(`${LOG_PREFIX} Initialization failed`, {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        throw error;
+    }
+}
+/**
+ * Flush all pending spans to Langfuse
+ */
+export async function flushOpenTelemetry() {
+    if (!isInitialized) {
+        logger.debug(`${LOG_PREFIX} Not initialized, skipping flush`);
+        return;
+    }
+    if (!langfuseProcessor) {
+        logger.debug(`${LOG_PREFIX} No processor to flush (Langfuse disabled)`);
+        return;
+    }
+    try {
+        logger.info(`${LOG_PREFIX} Flushing pending spans to Langfuse...`);
+        await langfuseProcessor.forceFlush();
+        logger.info(`${LOG_PREFIX} Successfully flushed spans to Langfuse`);
+    }
+    catch (error) {
+        logger.error(`${LOG_PREFIX} Flush failed`, {
+            error: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+        });
+        throw error;
+    }
+}
+/**
+ * Shutdown OpenTelemetry and Langfuse span processor
+ */
+export async function shutdownOpenTelemetry() {
+    if (!isInitialized || !tracerProvider) {
+        return;
+    }
+    try {
+        await tracerProvider.shutdown();
+        tracerProvider = null;
+        langfuseProcessor = null;
+        isInitialized = false;
+        isCredentialsValid = false;
+        logger.debug(`${LOG_PREFIX} Shutdown complete`);
+    }
+    catch (error) {
+        logger.error(`${LOG_PREFIX} Shutdown failed`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+/**
+ * Get the Langfuse span processor
+ */
+export function getLangfuseSpanProcessor() {
+    return langfuseProcessor;
+}
+/**
+ * Get the tracer provider
+ */
+export function getTracerProvider() {
+    return tracerProvider;
+}
+/**
+ * Check if OpenTelemetry is initialized
+ */
+export function isOpenTelemetryInitialized() {
+    return isInitialized;
+}
+/**
+ * Get health status for Langfuse observability
+ */
+export function getLangfuseHealthStatus() {
+    return {
+        isHealthy: currentConfig?.enabled &&
+            isInitialized &&
+            isCredentialsValid &&
+            langfuseProcessor !== null,
+        initialized: isInitialized,
+        credentialsValid: isCredentialsValid,
+        enabled: currentConfig?.enabled || false,
+        hasProcessor: langfuseProcessor !== null,
+        config: currentConfig
+            ? {
+                baseUrl: currentConfig.baseUrl || "https://cloud.langfuse.com",
+                environment: currentConfig.environment || "dev",
+                release: currentConfig.release || "v1.0.0",
+            }
+            : undefined,
+    };
+}

package/dist/session/globalSessionState.js

@@ -1,5 +1,31 @@
 import { nanoid } from "nanoid";
 import { NeuroLink } from "../neurolink.js";
+/**
+ * Build observability config from environment variables
+ * Used by CLI to configure NeuroLink instances
+ */
+function buildObservabilityConfigFromEnv() {
+    const langfuseEnabled = process.env.LANGFUSE_ENABLED?.trim().toLowerCase() === "true";
+    const publicKey = process.env.LANGFUSE_PUBLIC_KEY?.trim();
+    const secretKey = process.env.LANGFUSE_SECRET_KEY?.trim();
+    if (!langfuseEnabled || !publicKey || !secretKey) {
+        return undefined;
+    }
+    return {
+        langfuse: {
+            enabled: langfuseEnabled,
+            publicKey,
+            secretKey,
+            baseUrl: process.env.LANGFUSE_BASE_URL?.trim() || "https://cloud.langfuse.com",
+            environment: process.env.LANGFUSE_ENVIRONMENT?.trim() ||
+                process.env.PUBLIC_APP_ENVIRONMENT?.trim() ||
+                "dev",
+            release: process.env.PUBLIC_APP_VERSION?.trim() ||
+                process.env.npm_package_version?.trim() ||
+                "v1.0.0",
+        },
+    };
+}
 export class GlobalSessionManager {
     static instance;
     loopSession = null;
@@ -19,6 +45,11 @@ export class GlobalSessionManager {
                 maxTurnsPerSession: config.maxTurnsPerSession,
             };
         }
+        // Add observability config from environment variables (CLI usage)
+        const observabilityConfig = buildObservabilityConfigFromEnv();
+        if (observabilityConfig) {
+            neurolinkOptions.observability = observabilityConfig;
+        }
         this.loopSession = {
             neurolinkInstance: new NeuroLink(neurolinkOptions),
             sessionId,
@@ -88,7 +119,12 @@ export class GlobalSessionManager {
     }
     getOrCreateNeuroLink() {
         const session = this.getLoopSession();
-        return session ? session.neurolinkInstance : new NeuroLink();
+        if (session) {
+            return session.neurolinkInstance;
+        }
+        // Create new NeuroLink with observability config from environment (CLI usage)
+        const observabilityConfig = buildObservabilityConfigFromEnv();
+        return new NeuroLink(observabilityConfig ? { observability: observabilityConfig } : undefined);
     }
     getCurrentSessionId() {
         return this.getLoopSession()?.sessionId;

package/dist/telemetry/index.d.ts

@@ -9,6 +9,7 @@ export declare function initializeTelemetry(): Promise<import("./telemetryServic
  */
 export declare function getTelemetryStatus(): Promise<{
     enabled: boolean;
+    initialized: boolean;
     endpoint?: string;
     service?: string;
     version?: string;

package/dist/telemetry/telemetryService.d.ts

@@ -10,6 +10,7 @@ export declare class TelemetryService {
     private static instance;
     private sdk?;
     private enabled;
+    private initialized;
     private meter?;
     private tracer?;
     private aiRequestCounter?;
@@ -43,6 +44,7 @@ export declare class TelemetryService {
     isEnabled(): boolean;
     getStatus(): {
         enabled: boolean;
+        initialized: boolean;
         endpoint?: string;
         service?: string;
         version?: string;

package/dist/telemetry/telemetryService.js

@@ -1,14 +1,14 @@
 import { NodeSDK } from "@opentelemetry/sdk-node";
 import { metrics, trace, } from "@opentelemetry/api";
 import { getNodeAutoInstrumentations } from "@opentelemetry/auto-instrumentations-node";
-import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
-import { Resource } from "@opentelemetry/resources";
+import { resourceFromAttributes } from "@opentelemetry/resources";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
 import { logger } from "../utils/logger.js";
 export class TelemetryService {
     static instance;
     sdk;
     enabled = false;
+    initialized = false;
     meter;
     tracer;
     // Optional Metrics (only created when enabled)
@@ -47,16 +47,12 @@ export class TelemetryService {
     }
     initializeTelemetry() {
         try {
-            const resource = new Resource({
+            const resource = resourceFromAttributes({
                 [ATTR_SERVICE_NAME]: process.env.OTEL_SERVICE_NAME || "neurolink-ai",
                 [ATTR_SERVICE_VERSION]: process.env.OTEL_SERVICE_VERSION || "3.0.1",
             });
             this.sdk = new NodeSDK({
                 resource,
-                traceExporter: new OTLPTraceExporter({
-                    url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT ||
-                        `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`,
-                }),
                 // Note: Metric reader configured separately
                 instrumentations: [getNodeAutoInstrumentations()],
             });
@@ -102,11 +98,13 @@ export class TelemetryService {
         }
         try {
             await this.sdk?.start();
+            this.initialized = true;
             logger.debug("[Telemetry] SDK started successfully");
         }
         catch (error) {
             logger.error("[Telemetry] Failed to start SDK:", error);
             this.enabled = false;
+            this.initialized = false;
         }
     }
     // AI Operation Tracing (NO-OP when disabled)
@@ -250,6 +248,7 @@ export class TelemetryService {
     getStatus() {
         return {
             enabled: this.enabled,
+            initialized: this.initialized,
             endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
             service: process.env.OTEL_SERVICE_NAME || "neurolink-ai",
             version: process.env.OTEL_SERVICE_VERSION || "3.0.1",
@@ -285,6 +284,7 @@ export class TelemetryService {
         if (this.enabled && this.sdk) {
             try {
                 await this.sdk.shutdown();
+                this.initialized = false;
                 logger.debug("[Telemetry] SDK shutdown completed");
             }
             catch (error) {

package/dist/types/conversation.d.ts

@@ -157,6 +157,8 @@ export interface NeurolinkOptions {
     conversationMemory?: ConversationMemoryConfig;
     /** Session identifier for conversation context */
     sessionId?: string;
+    /** Observability configuration */
+    observability?: import("./observability.js").ObservabilityConfig;
 }
 /**
  * Session identifier for Redis storage operations

package/dist/types/observability.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Observability Configuration Types
+ * These configs are passed from the parent application (e.g., Lighthouse)
+ * to enable telemetry and observability features in Neurolink SDK
+ */
+/**
+ * Langfuse observability configuration
+ */
+export interface LangfuseConfig {
+    /** Whether Langfuse is enabled */
+    enabled: boolean;
+    /** Langfuse public key */
+    publicKey: string;
+    /**
+     * Langfuse secret key
+     * @sensitive
+     * WARNING: This is a sensitive credential. Handle securely.
+     * Do NOT log, expose, or share this key. Follow best practices for secret management.
+     */
+    secretKey: string;
+    /** Langfuse base URL (default: https://cloud.langfuse.com) */
+    baseUrl?: string;
+    /** Environment name (e.g., dev, staging, prod) */
+    environment?: string;
+    /** Release/version identifier */
+    release?: string;
+}
+/**
+ * OpenTelemetry configuration
+ */
+export interface OpenTelemetryConfig {
+    /** Whether OpenTelemetry is enabled */
+    enabled: boolean;
+    /** OTLP endpoint URL */
+    endpoint?: string;
+    /** Service name for traces */
+    serviceName?: string;
+    /** Service version */
+    serviceVersion?: string;
+}
+/**
+ * Complete observability configuration for Neurolink SDK
+ */
+export interface ObservabilityConfig {
+    /** Langfuse configuration */
+    langfuse?: LangfuseConfig;
+    /** OpenTelemetry configuration */
+    openTelemetry?: OpenTelemetryConfig;
+}

package/dist/types/observability.js

@@ -0,0 +1,6 @@
+/**
+ * Observability Configuration Types
+ * These configs are passed from the parent application (e.g., Lighthouse)
+ * to enable telemetry and observability features in Neurolink SDK
+ */
+export {};