@juspay/neurolink 12.59.0 → 13.0.1

package/dist/server/routes/healthRoutes.js

@@ -28,7 +28,7 @@ export function createHealthRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/health`,
-                handler: tracedHealthHandler("neurolink.http.health.check", `${basePath}/health`, async () => {
+                handler: tracedHealthHandler("http.health.check", `${basePath}/health`, async () => {
                     return {
                         status: "ok",
                         timestamp: new Date().toISOString(),
@@ -42,7 +42,7 @@ export function createHealthRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/health/live`,
-                handler: tracedHealthHandler("neurolink.http.health.live", `${basePath}/health/live`, async () => {
+                handler: tracedHealthHandler("http.health.live", `${basePath}/health/live`, async () => {
                     // Liveness probe - just checks if the server is running
                     return {
                         status: "alive",
@@ -56,7 +56,7 @@ export function createHealthRoutes(basePath = "/api") {
                 method: "GET",
                 path: `${basePath}/health/ready`,
                 handler: (ctx) => withSpan({
-                    name: "neurolink.http.health.ready",
+                    name: "http.health.ready",
                     tracer: tracers.http,
                     attributes: {
                         "http.route": `${basePath}/health/ready`,
@@ -99,7 +99,7 @@ export function createHealthRoutes(basePath = "/api") {
                 method: "GET",
                 path: `${basePath}/health/startup`,
                 handler: (ctx) => withSpan({
-                    name: "neurolink.http.health.startup",
+                    name: "http.health.startup",
                     tracer: tracers.http,
                     attributes: {
                         "http.route": `${basePath}/health/startup`,
@@ -126,7 +126,7 @@ export function createHealthRoutes(basePath = "/api") {
                 method: "GET",
                 path: `${basePath}/health/detailed`,
                 handler: (ctx) => withSpan({
-                    name: "neurolink.http.health.detailed",
+                    name: "http.health.detailed",
                     tracer: tracers.http,
                     attributes: {
                         "http.route": `${basePath}/health/detailed`,
@@ -217,7 +217,7 @@ export function createHealthRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/version`,
-                handler: tracedHealthHandler("neurolink.http.version", `${basePath}/version`, async () => {
+                handler: tracedHealthHandler("http.version", `${basePath}/version`, async () => {
                     return {
                         name: "@juspay/neurolink",
                         version: process.env.npm_package_version || "unknown",

package/dist/server/routes/mcpRoutes.js

@@ -324,49 +324,49 @@ export function createMCPRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers`,
-                handler: tracedMcpHandler("neurolink.http.mcp.listServers", `${basePath}/mcp/servers`, handleListServers),
+                handler: tracedMcpHandler("http.mcp.listServers", `${basePath}/mcp/servers`, handleListServers),
                 description: "List all MCP servers",
                 tags: ["mcp"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers/:name`,
-                handler: tracedMcpHandler("neurolink.http.mcp.getServer", `${basePath}/mcp/servers/:name`, handleGetServer),
+                handler: tracedMcpHandler("http.mcp.getServer", `${basePath}/mcp/servers/:name`, handleGetServer),
                 description: "Get MCP server status",
                 tags: ["mcp"],
             },
             {
                 method: "POST",
                 path: `${basePath}/mcp/servers/:name/reconnect`,
-                handler: tracedMcpHandler("neurolink.http.mcp.reconnectServer", `${basePath}/mcp/servers/:name/reconnect`, handleReconnectServer),
+                handler: tracedMcpHandler("http.mcp.reconnectServer", `${basePath}/mcp/servers/:name/reconnect`, handleReconnectServer),
                 description: "Reconnect to an MCP server",
                 tags: ["mcp"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/mcp/servers/:name`,
-                handler: tracedMcpHandler("neurolink.http.mcp.removeServer", `${basePath}/mcp/servers/:name`, handleRemoveServer),
+                handler: tracedMcpHandler("http.mcp.removeServer", `${basePath}/mcp/servers/:name`, handleRemoveServer),
                 description: "Remove an MCP server",
                 tags: ["mcp"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/servers/:name/tools`,
-                handler: tracedMcpHandler("neurolink.http.mcp.listServerTools", `${basePath}/mcp/servers/:name/tools`, handleListServerTools),
+                handler: tracedMcpHandler("http.mcp.listServerTools", `${basePath}/mcp/servers/:name/tools`, handleListServerTools),
                 description: "List tools from a specific MCP server",
                 tags: ["mcp", "tools"],
             },
             {
                 method: "POST",
                 path: `${basePath}/mcp/servers/:name/tools/:toolName/execute`,
-                handler: tracedMcpHandler("neurolink.http.mcp.executeTool", `${basePath}/mcp/servers/:name/tools/:toolName/execute`, handleExecuteTool),
+                handler: tracedMcpHandler("http.mcp.executeTool", `${basePath}/mcp/servers/:name/tools/:toolName/execute`, handleExecuteTool),
                 description: "Execute a tool from a specific MCP server",
                 tags: ["mcp", "tools"],
             },
             {
                 method: "GET",
                 path: `${basePath}/mcp/health`,
-                handler: tracedMcpHandler("neurolink.http.mcp.health", `${basePath}/mcp/health`, handleMCPHealth),
+                handler: tracedMcpHandler("http.mcp.health", `${basePath}/mcp/health`, handleMCPHealth),
                 description: "Health check for all MCP servers",
                 tags: ["mcp", "health"],
             },

package/dist/server/routes/memoryRoutes.js

@@ -312,7 +312,7 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions/:id/messages`,
-                handler: tracedMemoryHandler("neurolink.http.memory.getSessionMessages", `${basePath}/memory/sessions/:id/messages`, handleGetSessionMessages),
+                handler: tracedMemoryHandler("http.memory.getSessionMessages", `${basePath}/memory/sessions/:id/messages`, handleGetSessionMessages),
                 description: "Get messages for a session",
                 tags: ["memory"],
             },
@@ -320,7 +320,7 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions/:id`,
-                handler: tracedMemoryHandler("neurolink.http.memory.getSession", `${basePath}/memory/sessions/:id`, handleGetSession),
+                handler: tracedMemoryHandler("http.memory.getSession", `${basePath}/memory/sessions/:id`, handleGetSession),
                 description: "Get session by ID",
                 tags: ["memory"],
             },
@@ -328,35 +328,35 @@ export function createMemoryRoutes(basePath = "/api") {
             {
                 method: "GET",
                 path: `${basePath}/memory/sessions`,
-                handler: tracedMemoryHandler("neurolink.http.memory.listSessions", `${basePath}/memory/sessions`, handleListSessions),
+                handler: tracedMemoryHandler("http.memory.listSessions", `${basePath}/memory/sessions`, handleListSessions),
                 description: "List all conversation sessions",
                 tags: ["memory"],
             },
             {
                 method: "GET",
                 path: `${basePath}/memory/stats`,
-                handler: tracedMemoryHandler("neurolink.http.memory.stats", `${basePath}/memory/stats`, handleGetStats),
+                handler: tracedMemoryHandler("http.memory.stats", `${basePath}/memory/stats`, handleGetStats),
                 description: "Get memory statistics",
                 tags: ["memory"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/memory/sessions/:sessionId`,
-                handler: tracedMemoryHandler("neurolink.http.memory.clearSession", `${basePath}/memory/sessions/:sessionId`, handleClearSession),
+                handler: tracedMemoryHandler("http.memory.clearSession", `${basePath}/memory/sessions/:sessionId`, handleClearSession),
                 description: "Clear a conversation session",
                 tags: ["memory"],
             },
             {
                 method: "DELETE",
                 path: `${basePath}/memory/sessions`,
-                handler: tracedMemoryHandler("neurolink.http.memory.clearAllSessions", `${basePath}/memory/sessions`, handleClearAllSessions),
+                handler: tracedMemoryHandler("http.memory.clearAllSessions", `${basePath}/memory/sessions`, handleClearAllSessions),
                 description: "Clear all conversation sessions",
                 tags: ["memory"],
             },
             {
                 method: "GET",
                 path: `${basePath}/memory/health`,
-                handler: tracedMemoryHandler("neurolink.http.memory.health", `${basePath}/memory/health`, handleMemoryHealth),
+                handler: tracedMemoryHandler("http.memory.health", `${basePath}/memory/health`, handleMemoryHealth),
                 description: "Check memory system health",
                 tags: ["memory", "health"],
             },

package/dist/server/routes/openApiRoutes.js

@@ -47,7 +47,7 @@ export function createOpenApiRoutes(basePath = "/api", getRoutes) {
                 method: "GET",
                 path: `${basePath}/openapi.json`,
                 handler: async () => withSpan({
-                    name: "neurolink.http.openapi.json",
+                    name: "http.openapi.json",
                     tracer: tracers.http,
                     attributes: {
                         "http.route": `${basePath}/openapi.json`,
@@ -76,7 +76,7 @@ export function createOpenApiRoutes(basePath = "/api", getRoutes) {
                 method: "GET",
                 path: `${basePath}/openapi.yaml`,
                 handler: async () => withSpan({
-                    name: "neurolink.http.openapi.yaml",
+                    name: "http.openapi.yaml",
                     tracer: tracers.http,
                     attributes: {
                         "http.route": `${basePath}/openapi.yaml`,
@@ -109,7 +109,7 @@ export function createOpenApiRoutes(basePath = "/api", getRoutes) {
                 method: "GET",
                 path: `${basePath}/docs`,
                 handler: async () => withSpan({
-                    name: "neurolink.http.openapi.docs",
+                    name: "http.openapi.docs",
                     tracer: tracers.http,
                     attributes: {
                         "http.route": `${basePath}/docs`,

package/dist/server/routes/toolRoutes.js

@@ -23,7 +23,7 @@ export function createToolRoutes(basePath = "/api") {
                 method: "GET",
                 path: `${basePath}/tools`,
                 handler: async (ctx) => withSpan({
-                    name: "neurolink.http.tools.list",
+                    name: "http.tools.list",
                     tracer: tracers.http,
                     attributes: { "http.route": `${basePath}/tools` },
                 }, async (span) => {
@@ -47,7 +47,7 @@ export function createToolRoutes(basePath = "/api") {
                 method: "GET",
                 path: `${basePath}/tools/search`,
                 handler: async (ctx) => withSpan({
-                    name: "neurolink.http.tools.search",
+                    name: "http.tools.search",
                     tracer: tracers.http,
                     attributes: {
                         "http.route": `${basePath}/tools/search`,
@@ -96,7 +96,7 @@ export function createToolRoutes(basePath = "/api") {
                     }
                     const request = validation.data;
                     return withSpan({
-                        name: "neurolink.http.tools.execute",
+                        name: "http.tools.execute",
                         tracer: tracers.http,
                         attributes: {
                             "http.route": `${basePath}/tools/execute`,
@@ -170,7 +170,7 @@ export function createToolRoutes(basePath = "/api") {
                     }
                     const args = bodyValidation.data;
                     return withSpan({
-                        name: "neurolink.http.tools.executeByName",
+                        name: "http.tools.executeByName",
                         tracer: tracers.http,
                         attributes: {
                             "http.route": `${basePath}/tools/:name/execute`,
@@ -237,7 +237,7 @@ export function createToolRoutes(basePath = "/api") {
                     }
                     const { name } = paramValidation.data;
                     return withSpan({
-                        name: "neurolink.http.tools.get",
+                        name: "http.tools.get",
                         tracer: tracers.http,
                         attributes: {
                             "http.route": `${basePath}/tools/:name`,

package/dist/server/routes/transcribeRoutes.js

@@ -223,7 +223,7 @@ function classifyError(error) {
 }
 async function runTranscription(ctx, route, options) {
     return withSpan({
-        name: "neurolink.http.transcribe",
+        name: "http.transcribe",
         tracer: tracers.http,
         attributes: {
             "http.route": route,

package/dist/server/utils/validation.d.ts

@@ -192,8 +192,8 @@ export declare const TranscribeConfigSchema: z.ZodObject<{
     correction: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         guard: z.ZodOptional<z.ZodEnum<{
-            none: "none";
             decide: "decide";
+            none: "none";
         }>>;
         decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
         rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
@@ -242,8 +242,8 @@ export declare const TranscribeRequestSchema: z.ZodObject<{
     correction: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         guard: z.ZodOptional<z.ZodEnum<{
-            none: "none";
             decide: "decide";
+            none: "none";
         }>>;
         decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
         rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{
@@ -308,8 +308,8 @@ export declare const TranscribeStreamConfigSchema: z.ZodObject<{
     correction: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         guard: z.ZodOptional<z.ZodEnum<{
-            none: "none";
             decide: "decide";
+            none: "none";
         }>>;
         decideTimeoutMs: z.ZodOptional<z.ZodNumber>;
         rewrite: z.ZodOptional<z.ZodUnion<readonly [z.ZodLiteral<false>, z.ZodObject<{

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

@@ -1,229 +1,62 @@
+import { type Context } from "@opentelemetry/api";
+import type { NeurolinkTraceContext, ObservabilityConfig, SpanContent } from "../../../../types/index.js";
 /**
- * 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
+ * @description Starts NeuroLink's tracing once per process, synchronously. Every span created through the shared tracers calls it first, so direct provider calls without a NeuroLink instance are traced too. Langfuse is enabled unless `config.langfuse` is `false`, when an options object is given or `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` are set; an OTLP exporter is added when `OTEL_EXPORTER_OTLP_ENDPOINT` is set. When the host already registered a TracerProvider no provider is created; the Langfuse exporter, if configured, is registered on the shared exporter registry and the host adds `createExporterSpanProcessor()` to its provider. The first call that finds tracing configured decides the setup and a later `config` is ignored; calls made before anything is configured start nothing, so a later config or environment can still start tracing, unless `langfuse: false` was passed. After `shutdownOpenTelemetry` it does nothing.
+ * @param config {ObservabilityConfig | undefined} - Observability options, honoured only when this is the first call.
+ * @returns {void} Nothing; a failed setup is logged and recorded in `getLangfuseHealthStatus`.
  */
-import { trace, type Span as ApiSpan } from "@opentelemetry/api";
-import type { LoggerProvider } from "@opentelemetry/sdk-logs";
-import type { SpanProcessor } from "@opentelemetry/sdk-trace-base";
-import type { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
-import type { LangfuseConfig, LangfuseContext } from "../../../../types/index.js";
+export declare function ensureTelemetry(config?: ObservabilityConfig): void;
 /**
- * True when a span is an internal NeuroLink wrapper that should NOT be sent to
- * Langfuse. Internal wrappers carry the `langfuse.internal: true` attribute.
- *
- * Exposed so host apps that bring their own `LangfuseSpanProcessor` (e.g.
- * `skipLangfuseSpanProcessor: true`, or manual registration on an existing
- * TracerProvider) can apply the same filter and avoid duplicate observations.
+ * @description Registers a holder of the process-wide telemetry and starts it if needed. Pair every call with `releaseTelemetry`.
+ * @param config {ObservabilityConfig | undefined} - Observability options forwarded to `ensureTelemetry`.
+ * @returns {void} Nothing.
  */
-export declare function isLangfuseInternalSpan(span: {
-    attributes?: Record<string, unknown>;
-}): boolean;
+export declare function acquireTelemetry(config?: ObservabilityConfig): void;
 /**
- * Drop-in `shouldExportSpan` predicate for a `LangfuseSpanProcessor` that
- * filters out NeuroLink internal wrapper spans.
- *
- * Usage in host apps:
- * ```ts
- * import { langfuseShouldExportSpan } from "@juspay/neurolink";
- * new LangfuseSpanProcessor({ ..., shouldExportSpan: langfuseShouldExportSpan });
- * ```
+ * @description Releases one holder registered by `acquireTelemetry` and flushes pending spans. The provider stays registered for the process so cached tracers keep working and later instances reuse it.
+ * @returns {Promise<void>} Resolves when pending spans are flushed.
+ * @throws {Error} When any provider fails to flush.
  */
-export declare function langfuseShouldExportSpan({ otelSpan, }: {
-    otelSpan: {
-        attributes?: Record<string, unknown>;
-    };
-}): boolean;
+export declare function releaseTelemetry(): Promise<void>;
 /**
- * Initialize OpenTelemetry once and let concurrent callers share the work.
- *
- * NeuroLink constructors intentionally start this asynchronously. Keeping the
- * in-flight promise here lets another constructor join it and lets an immediate
- * flush or shutdown wait for the same initialization before touching providers.
- */
-export declare function initializeOpenTelemetry(config: LangfuseConfig): Promise<void>;
-/**
- * Flush all pending spans to Langfuse
+ * @description Exports pending spans and metrics from the providers NeuroLink owns and flushes its Langfuse exporter. A host provider is never flushed.
+ * @returns {Promise<void>} Resolves when every owned provider has flushed.
+ * @throws {Error} When any provider fails to flush.
  */
 export declare function flushOpenTelemetry(): Promise<void>;
 /**
- * Shutdown OpenTelemetry and Langfuse span processor
- *
- * Concurrent callers share one in-flight teardown, the same way concurrent
- * initializers share one in-flight `initializeOpenTelemetry`: a second
- * shutdown call joins the first instead of tearing down the same provider
- * instances a second time.
+ * @description Terminally shuts down the providers NeuroLink owns once no `acquireTelemetry` holder remains; while holders remain it only flushes. Telemetry cannot be restarted in this process afterwards. A host provider is never shut down; with one, only NeuroLink's Langfuse exporter is shut down and unregistered.
+ * @returns {Promise<void>} Resolves when telemetry is flushed or shut down.
  */
 export declare function shutdownOpenTelemetry(): Promise<void>;
 /**
- * Get the Langfuse span processor
- */
-export declare function getLangfuseSpanProcessor(): SpanProcessor | null;
-/**
- * Get the tracer provider
- */
-export declare function getTracerProvider(): NodeTracerProvider | null;
-/**
- * Get the logger provider for emitting OTLP log records.
- * Returns null if OTLP is not configured or LoggerProvider was not created.
- */
-export declare function getLoggerProvider(): LoggerProvider | null;
-/**
- * Check if OpenTelemetry is initialized
+ * @description Reports whether NeuroLink's tracing is active, either on its own provider or alongside a host provider.
+ * @returns {boolean} `true` once `ensureTelemetry` has set tracing up.
  */
 export declare function isOpenTelemetryInitialized(): boolean;
 /**
- * Get health status for Langfuse observability
- *
- * @returns Health status object with initialization and configuration details
+ * @description Summarizes the Langfuse export state for health checks.
+ * @returns {{ isHealthy: boolean; initialized: boolean; hasProcessor: boolean; usingExternalProvider: boolean; error?: string }} `isHealthy` and `hasProcessor` are `true` only while a Langfuse exporter is registered, on NeuroLink's own provider or beside a host provider (where it still needs `createExporterSpanProcessor()` on the host provider to receive spans); `error` carries the message of a failed initialization.
  */
 export declare function getLangfuseHealthStatus(): {
     isHealthy: boolean;
     initialized: boolean;
-    credentialsValid: boolean;
-    enabled: boolean;
     hasProcessor: boolean;
     usingExternalProvider: boolean;
-    config?: {
-        baseUrl: string;
-        environment: string;
-        release: string;
-    };
+    error?: string;
 };
 /**
- * Set user and session context for Langfuse spans in the current async context
- *
- * Merges the provided context with existing AsyncLocalStorage context. If a callback is provided,
- * the context is scoped to that callback execution and returns the callback's result.
- * Without a callback, the context applies to the current execution context and its children.
- *
- * Uses AsyncLocalStorage to properly scope context per request, avoiding race conditions
- * in concurrent scenarios.
- *
- * @param context - Object containing context fields to merge with existing context
- * @param callback - Optional callback to run within the context scope. If omitted, context applies to current execution
- * @returns The callback's return value if provided, otherwise void
- *
- * @example
- * // With callback - returns the result
- * const result = await setLangfuseContext({ userId: "user123" }, async () => {
- *   return await generateText({ model: "gpt-4", prompt: "Hello" });
- * });
- *
- * @example
- * // Without callback - sets context for current execution
- * await setLangfuseContext({ sessionId: "session456", traceName: "chat-completion" });
- */
-export declare function setLangfuseContext<T = void>(context: {
-    userId?: string | null;
-    sessionId?: string | null;
-    conversationId?: string | null;
-    requestId?: string | null;
-    traceName?: string | null;
-    metadata?: Record<string, unknown> | null;
-    /** Langfuse trace tags, set on the trace's root span */
-    tags?: string[] | null;
-    /** Explicit operation name (overrides auto-detection) */
-    operationName?: string | null;
-    /** Override global autoDetectOperationName for this context */
-    autoDetectOperationName?: boolean;
-    /** Custom attributes to set on all spans within this context */
-    customAttributes?: Record<string, string | number | boolean>;
-}, callback?: () => T | Promise<T>): Promise<T | void>;
-/**
- * Get the current Langfuse context from AsyncLocalStorage
- *
- * Returns the current context including userId, sessionId, conversationId,
- * requestId, traceName, and metadata. Returns undefined if no context is set.
- *
- * @returns The current LangfuseContext or undefined
- *
- * @example
- * const context = getLangfuseContext();
- * console.log(context?.userId, context?.sessionId);
- */
-export declare function getLangfuseContext(): LangfuseContext | undefined;
-/**
- * Fill a span's Langfuse identity when the caller's context would otherwise
- * fall back to "guest". Identity (user.id / session.id) is set additively —
- * only fields ambient context didn't already provide, so a host's own context
- * is never overridden. trace.name (the title) is rescued only when no ambient
- * name source exists AND this span is the trace root, mirroring
- * ContextEnricher.onStart so a host wrapper span isn't relabelled.
- */
-export declare function stampGuestRescueIdentity(span: ApiSpan, callContext: unknown, isRootSpan: boolean): void;
-/**
- * Capture the current Langfuse AsyncLocalStorage context and return a wrapper
- * that re-enters that context when executing the provided callback.
- *
- * This is essential for preserving trace context across async boundaries that
- * break the automatic ALS propagation chain, such as `setImmediate()`,
- * `setTimeout()`, or event-emitter callbacks. Without this, spans created
- * inside those callbacks become orphaned traces in Langfuse.
- *
- * **How it works:**
- * 1. Captures the current ALS store at call time (synchronously).
- * 2. Returns an async function that, when invoked, re-enters the captured
- *    context via `contextStorage.run()` before executing the callback.
- * 3. If no context exists at capture time, the callback runs without
- *    ALS wrapping (no-op passthrough).
- *
- * @param fn - The async function to execute within the captured context
- * @returns A new async function that preserves the Langfuse ALS context
- *
- * @example
- * // Before (broken — setImmediate loses ALS context):
- * setImmediate(async () => {
- *   await this.checkAndSummarize(session, threshold);
- * });
- *
- * // After (fixed — context is captured and re-entered):
- * const wrappedFn = runWithCurrentLangfuseContext(async () => {
- *   await this.checkAndSummarize(session, threshold);
- * });
- * setImmediate(wrappedFn);
+ * @description Reads the full trace metadata that `setLangfuseContext` stored on a context.
+ * @param ctx {Context} - Context to read, normally the active one.
+ * @returns {Record<string, SpanContent>} Metadata set by enclosing `setLangfuseContext` calls, inner keys winning; empty when none was set.
  */
-export declare function runWithCurrentLangfuseContext<T>(fn: () => Promise<T>): () => Promise<T>;
+export declare function traceMetadataFromContext(ctx: Context): Record<string, SpanContent>;
 /**
- * Get an OpenTelemetry Tracer for creating custom spans
- *
- * This allows applications to create their own spans that will be
- * processed by the same span processors (ContextEnricher + LangfuseSpanProcessor).
- *
- * @param name - Tracer name, defaults to "neurolink"
- * @param version - Tracer version, optional
- * @returns OpenTelemetry Tracer instance
- *
+ * @description Runs `fn` with trace attributes propagated to every span it creates. `conversationId` and `requestId` become metadata; empty values are dropped. Metadata values of up to 200 characters once stringified are on every observation; longer values and arrays are recorded in full on the trace only, written by the trace root.
+ * @param params {NeurolinkTraceContext} - User, session, trace name, tags and metadata for the trace.
+ * @param fn {() => T} - Work to run inside the propagated context.
+ * @returns {T} Whatever `fn` returns.
  * @example
- * const tracer = getTracer("my-app");
- * const span = tracer.startSpan("custom-operation");
- * try {
- *   // ... do work
- * } finally {
- *   span.end();
- * }
- */
-export declare function getTracer(name?: string, version?: string): ReturnType<typeof trace.getTracer>;
-/**
- * Create a new ContextEnricher span processor
- * Use this when useExternalTracerProvider is true to add to your own TracerProvider
- *
- * @returns A new ContextEnricher instance
- */
-export declare function createContextEnricher(): SpanProcessor;
-/**
- * Get all span processors that NeuroLink would use
- * Convenience function that returns [ContextEnricher, LangfuseSpanProcessor]
- *
- * @returns Array of span processors, or empty array if not initialized
- */
-export declare function getSpanProcessors(): SpanProcessor[];
-/**
- * Check if using external TracerProvider mode
- *
- * @returns true if operating in external TracerProvider mode
+ * await setLangfuseContext({ userId: "u1", sessionId: "s1" }, () => neurolink.generate({ input: { text: "hi" } }));
  */
-export declare function isUsingExternalTracerProvider(): boolean;
+export declare function setLangfuseContext<T>(params: NeurolinkTraceContext, fn: () => T): T;