@juspay/neurolink 9.15.0 → 9.16.0

package/dist/rag/chunking/markdownChunker.d.ts

@@ -14,6 +14,22 @@ export declare class MarkdownChunker implements Chunker {
     chunk(text: string, config?: MarkdownChunkerConfig): Promise<Chunk[]>;
     private splitByHeaders;
     private splitContent;
+    /**
+     * Detect contiguous table blocks in lines.
+     * Returns array of { start, end } line index ranges (inclusive).
+     */
+    private detectTableRanges;
+    /** Check if a line is a markdown table separator (e.g. |---|---|). */
+    private isTableSeparator;
+    /**
+     * Split content while preserving markdown tables.
+     */
+    private splitContentTableAware;
+    /**
+     * Split a table on row boundaries, repeating header + separator in each chunk.
+     */
+    private splitTableByRows;
+    private splitPlainContent;
     private stripMarkdown;
     validateConfig(config: BaseChunkerConfig): ChunkerValidationResult;
 }

package/dist/rag/chunking/markdownChunker.js

@@ -129,10 +129,182 @@ export class MarkdownChunker {
         if (content.length <= effectiveMaxSize) {
             return [content];
         }
+        // Use table-aware splitting
+        const lines = content.split("\n");
+        const tableRanges = this.detectTableRanges(lines);
+        if (tableRanges.length > 0) {
+            return this.splitContentTableAware(content, lines, tableRanges, effectiveMaxSize, effectiveOverlap);
+        }
+        return this.splitPlainContent(content, effectiveMaxSize, effectiveOverlap);
+    }
+    /**
+     * Detect contiguous table blocks in lines.
+     * Returns array of { start, end } line index ranges (inclusive).
+     */
+    detectTableRanges(lines) {
+        // Simple pipe-prefixed line check (single character class — no backtracking)
+        const TABLE_ROW_RE = /^\|[^\r\n]{1,10000}/;
+        // Per-cell separator regex applied AFTER splitting on "|" — safe because
+        // each cell is short and bounded by pipe delimiters (CodeQL: js/polynomial-redos)
+        const SEPARATOR_CELL_RE = /^[\t ]*:?-+:?[\t ]*$/;
+        const ranges = [];
+        let i = 0;
+        while (i < lines.length) {
+            if (i + 1 < lines.length &&
+                TABLE_ROW_RE.test(lines[i]) &&
+                this.isTableSeparator(lines[i + 1], SEPARATOR_CELL_RE)) {
+                const start = i;
+                i += 2;
+                while (i < lines.length && TABLE_ROW_RE.test(lines[i])) {
+                    i++;
+                }
+                ranges.push({ start, end: i - 1 });
+            }
+            else {
+                i++;
+            }
+        }
+        return ranges;
+    }
+    /** Check if a line is a markdown table separator (e.g. |---|---|). */
+    isTableSeparator(line, cellRe) {
+        const trimmed = line.trimEnd();
+        if (!trimmed.startsWith("|")) {
+            return false;
+        }
+        // Split by "|" → ["", "---", "---", ""] for "|---|---|"
+        const cells = trimmed.split("|");
+        cells.shift(); // remove leading empty element
+        if (cells.length > 0 && cells[cells.length - 1].trim() === "") {
+            cells.pop(); // remove trailing empty element
+        }
+        if (cells.length === 0) {
+            return false;
+        }
+        return cells.every((cell) => cellRe.test(cell));
+    }
+    /**
+     * Split content while preserving markdown tables.
+     */
+    splitContentTableAware(content, lines, tableRanges, maxSize, overlap) {
+        // Build segments: alternating non-table and table blocks
+        const segments = [];
+        let lineIdx = 0;
+        for (const range of tableRanges) {
+            if (lineIdx < range.start) {
+                const text = lines.slice(lineIdx, range.start).join("\n").trim();
+                if (text) {
+                    segments.push({ text, isTable: false });
+                }
+            }
+            const tableText = lines.slice(range.start, range.end + 1).join("\n");
+            segments.push({ text: tableText, isTable: true });
+            lineIdx = range.end + 1;
+        }
+        if (lineIdx < lines.length) {
+            const text = lines.slice(lineIdx).join("\n").trim();
+            if (text) {
+                segments.push({ text, isTable: false });
+            }
+        }
+        const result = [];
+        let current = "";
+        for (const seg of segments) {
+            if (!seg.isTable) {
+                const pieces = this.splitPlainContent(seg.text, maxSize, overlap);
+                for (const piece of pieces) {
+                    if (current.length === 0) {
+                        current = piece;
+                    }
+                    else if (current.length + 1 + piece.length <= maxSize) {
+                        current += "\n" + piece;
+                    }
+                    else {
+                        result.push(current);
+                        current = piece;
+                    }
+                }
+            }
+            else {
+                if (seg.text.length <= maxSize) {
+                    if (current.length === 0) {
+                        current = seg.text;
+                    }
+                    else if (current.length + 2 + seg.text.length <= maxSize) {
+                        current += "\n\n" + seg.text;
+                    }
+                    else {
+                        result.push(current);
+                        current = seg.text;
+                    }
+                }
+                else {
+                    if (current) {
+                        result.push(current);
+                        current = "";
+                    }
+                    const tableChunks = this.splitTableByRows(seg.text, maxSize);
+                    result.push(...tableChunks);
+                }
+            }
+        }
+        if (current) {
+            result.push(current);
+        }
+        return result.length > 0 ? result : [content];
+    }
+    /**
+     * Split a table on row boundaries, repeating header + separator in each chunk.
+     */
+    splitTableByRows(tableText, maxSize) {
+        const rows = tableText.split("\n");
+        if (rows.length < 3) {
+            return [tableText];
+        }
+        const headerRow = rows[0];
+        const separatorRow = rows[1];
+        const headerBlock = headerRow + "\n" + separatorRow;
+        const dataRows = rows.slice(2);
+        if (headerBlock.length > maxSize) {
+            return this.splitPlainContent(tableText, maxSize, 0);
+        }
+        const chunks = [];
+        let currentChunk = headerBlock;
+        for (const row of dataRows) {
+            // Guard: single row exceeds budget — flush and emit as standalone chunk
+            const singleRowChunk = `${headerBlock}\n${row}`;
+            if (singleRowChunk.length > maxSize) {
+                if (currentChunk.length > headerBlock.length) {
+                    chunks.push(currentChunk);
+                }
+                chunks.push(singleRowChunk);
+                currentChunk = headerBlock;
+                continue;
+            }
+            const candidate = currentChunk + "\n" + row;
+            if (candidate.length <= maxSize) {
+                currentChunk = candidate;
+            }
+            else {
+                if (currentChunk.length > headerBlock.length) {
+                    chunks.push(currentChunk);
+                }
+                currentChunk = headerBlock + "\n" + row;
+            }
+        }
+        if (currentChunk.length > headerBlock.length) {
+            chunks.push(currentChunk);
+        }
+        return chunks.length > 0 ? chunks : [tableText];
+    }
+    splitPlainContent(content, maxSize, overlap) {
+        if (content.length <= maxSize) {
+            return [content];
+        }
         const chunks = [];
         let start = 0;
         while (start < content.length) {
-            let end = Math.min(start + effectiveMaxSize, content.length);
+            let end = Math.min(start + maxSize, content.length);
             // Try to break at a paragraph or sentence boundary
             if (end < content.length) {
                 const searchStart = Math.max(start, end - 200);
@@ -151,7 +323,7 @@ export class MarkdownChunker {
                 }
             }
             chunks.push(content.slice(start, end));
-            start = Math.max(start + 1, end - effectiveOverlap);
+            start = Math.max(start + 1, end - overlap);
         }
         return chunks;
     }

package/dist/rag/pipeline/contextAssembly.js

@@ -12,6 +12,7 @@
  * - Context summarization
  */
 import { logger } from "../../utils/logger.js";
+import { estimateTokens } from "../../utils/tokenEstimation.js";
 /**
  * Assemble context from retrieved results
  *
@@ -184,7 +185,7 @@ export function createContextWindow(results, options) {
         text,
         chunkCount,
         charCount: text.length,
-        tokenCount: Math.ceil(text.length / 4),
+        tokenCount: estimateTokens(text),
         truncatedChunks,
         citations,
     };

package/dist/rag/ragIntegration.d.ts

@@ -7,7 +7,20 @@
  * so developers only need to pass `rag: { files: [...] }`.
  */
 import type { Tool } from "ai";
-import type { RAGConfig } from "./types.js";
+import type { RAGConfig, VectorQueryResult } from "./types.js";
+/**
+ * Generate deterministic embeddings for chunks.
+ * Combines character-frequency (40%) with word-level hash features (60%)
+ * for better semantic discrimination than pure character frequency.
+ * When a real embedding provider is configured, it will be used instead.
+ */
+declare function generateSimpleEmbedding(text: string, dimension: number): number[];
+/**
+ * Diversify retrieval results via round-robin across source files.
+ * Ensures at least one chunk per source file appears in the top-K results,
+ * preventing any single file from dominating retrieval.
+ */
+declare function diversifyResults(results: VectorQueryResult[], topK: number): VectorQueryResult[];
 /**
  * Result of preparing RAG for a generate/stream call
  */
@@ -36,3 +49,7 @@ export type RAGPreparedTool = {
  * @returns Prepared RAG tool to inject into the tools record
  */
 export declare function prepareRAGTool(ragConfig: RAGConfig, fallbackProvider?: string): Promise<RAGPreparedTool>;
+/** @internal Exported for testing only */
+export { generateSimpleEmbedding as _generateSimpleEmbedding };
+/** @internal Exported for testing only */
+export { diversifyResults as _diversifyResults };

package/dist/rag/ragIntegration.js

@@ -10,7 +10,7 @@ import { existsSync, readFileSync } from "fs";
 import { extname, resolve } from "path";
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
-import { ChunkerRegistry } from "./chunking/index.js";
+import { createChunker } from "./ChunkerFactory.js";
 import { createVectorQueryTool, InMemoryVectorStore, } from "./retrieval/vectorQueryTool.js";
 /**
  * Maps file extensions to recommended chunking strategies
@@ -48,27 +48,91 @@ function detectStrategy(filePath) {
     const ext = extname(filePath).toLowerCase();
     return EXTENSION_TO_STRATEGY[ext] || "recursive";
 }
+/**
+ * Simple hash function for strings (FNV-1a variant).
+ * Maps a word to a bucket index deterministically.
+ */
+function hashWord(word, buckets) {
+    let hash = 2166136261;
+    for (let i = 0; i < word.length; i++) {
+        hash ^= word.charCodeAt(i);
+        hash = (hash * 16777619) >>> 0;
+    }
+    return hash % buckets;
+}
 /**
  * Generate deterministic embeddings for chunks.
- * Uses a simple hash-based approach for the in-memory vector store.
+ * Combines character-frequency (40%) with word-level hash features (60%)
+ * for better semantic discrimination than pure character frequency.
  * When a real embedding provider is configured, it will be used instead.
  */
 function generateSimpleEmbedding(text, dimension) {
-    const embedding = new Array(dimension).fill(0);
-    // Simple character-frequency based embedding
+    const charEmbedding = new Array(dimension).fill(0);
+    const wordEmbedding = new Array(dimension).fill(0);
+    // Character-frequency features
     for (let i = 0; i < text.length; i++) {
         const charCode = text.charCodeAt(i);
         const idx = charCode % dimension;
-        embedding[idx] += 1;
+        charEmbedding[idx] += 1;
+    }
+    // Word-level hash features (TF-IDF-like)
+    const words = text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, "")
+        .split(/\s+/)
+        .filter((w) => w.length > 1);
+    for (const word of words) {
+        const idx = hashWord(word, dimension);
+        wordEmbedding[idx] += 1;
+    }
+    // Combine: 40% character, 60% word
+    const combined = new Array(dimension);
+    for (let i = 0; i < dimension; i++) {
+        combined[i] = 0.4 * charEmbedding[i] + 0.6 * wordEmbedding[i];
     }
     // Normalize to unit vector
-    const magnitude = Math.sqrt(embedding.reduce((sum, v) => sum + v * v, 0));
+    const magnitude = Math.sqrt(combined.reduce((sum, v) => sum + v * v, 0));
     if (magnitude > 0) {
         for (let i = 0; i < dimension; i++) {
-            embedding[i] /= magnitude;
+            combined[i] /= magnitude;
         }
     }
-    return embedding;
+    return combined;
+}
+/**
+ * Diversify retrieval results via round-robin across source files.
+ * Ensures at least one chunk per source file appears in the top-K results,
+ * preventing any single file from dominating retrieval.
+ */
+function diversifyResults(results, topK) {
+    // Group by source file
+    const byFile = new Map();
+    for (const r of results) {
+        const source = r.metadata?.source || "unknown";
+        if (!byFile.has(source)) {
+            byFile.set(source, []);
+        }
+        const sourceGroup = byFile.get(source);
+        if (sourceGroup) {
+            sourceGroup.push(r);
+        }
+    }
+    // If only one source file, no diversification needed
+    if (byFile.size <= 1) {
+        return results.slice(0, topK);
+    }
+    // Round-robin selection from each source file group
+    const diversified = [];
+    const iterators = [...byFile.values()].map((arr) => ({ arr, idx: 0 }));
+    while (diversified.length < topK &&
+        iterators.some((it) => it.idx < it.arr.length)) {
+        for (const it of iterators) {
+            if (it.idx < it.arr.length && diversified.length < topK) {
+                diversified.push(it.arr[it.idx++]);
+            }
+        }
+    }
+    return diversified;
 }
 /**
  * Prepare RAG tools from the provided configuration.
@@ -85,7 +149,7 @@ function generateSimpleEmbedding(text, dimension) {
  * @returns Prepared RAG tool to inject into the tools record
  */
 export async function prepareRAGTool(ragConfig, fallbackProvider) {
-    const { files, strategy: userStrategy, chunkSize = 1000, chunkOverlap = 200, topK = 5, toolName = "search_knowledge_base", toolDescription = "REQUIRED: Search through pre-loaded local documents to find relevant information. Use this tool FIRST before any web search or other tools. This searches an indexed knowledge base of documents the user has provided.", embeddingProvider, embeddingModel, } = ragConfig;
+    const { files, strategy: userStrategy, chunkSize = 1000, chunkOverlap = 200, topK: userTopK = 5, toolName = "search_knowledge_base", toolDescription = "REQUIRED: Search through pre-loaded local documents to find relevant information. Use this tool FIRST before any web search or other tools. This searches an indexed knowledge base of documents the user has provided.", embeddingProvider, embeddingModel, } = ragConfig;
     if (!files || files.length === 0) {
         throw new Error("RAG config requires at least one file path in 'files'");
     }
@@ -106,6 +170,11 @@ export async function prepareRAGTool(ragConfig, fallbackProvider) {
             logger.warn(`[RAG] Failed to read file: ${resolvedPath}: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    // Auto-increase topK for multi-file scenarios to ensure coverage
+    // (computed after loading so it reflects only files that actually exist)
+    const topK = fileContents.length > 1
+        ? Math.max(userTopK, fileContents.length * 3)
+        : userTopK;
     if (fileContents.length === 0) {
         throw new Error("RAG: No files could be loaded. Check that file paths exist and are readable.");
     }
@@ -114,10 +183,11 @@ export async function prepareRAGTool(ragConfig, fallbackProvider) {
     const allChunks = [];
     for (const { path, content, strategy } of fileContents) {
         try {
-            const chunker = ChunkerRegistry.get(strategy);
-            const chunks = await chunker.chunk(content, {
+            const chunker = await createChunker(strategy, {
                 maxSize: chunkSize,
-                overlap: chunkOverlap,
+                overlap: Math.min(chunkOverlap, Math.floor(chunkSize * 0.5)),
+            });
+            const chunks = await chunker.chunk(content, {
                 metadata: { source: path },
             });
             for (const chunk of chunks) {
@@ -175,11 +245,17 @@ export async function prepareRAGTool(ragConfig, fallbackProvider) {
             // For the in-memory store with simple embeddings,
             // generate a query embedding using the same method
             const queryEmbedding = generateSimpleEmbedding(query, EMBEDDING_DIMENSION);
-            const results = await vectorStore.query({
+            // Fetch more candidates than needed so diversity can select across files
+            const fetchK = fileContents.length > 1 ? topK * 3 : topK;
+            const rawResults = await vectorStore.query({
                 indexName,
                 queryVector: queryEmbedding,
-                topK,
+                topK: fetchK,
             });
+            // Apply source-file diversity for multi-file RAG
+            const results = fileContents.length > 1
+                ? diversifyResults(rawResults, topK)
+                : rawResults.slice(0, topK);
             if (results.length === 0) {
                 return {
                     relevantContext: "No relevant documents found for the query.",
@@ -209,3 +285,7 @@ export async function prepareRAGTool(ragConfig, fallbackProvider) {
         filesLoaded: fileContents.length,
     };
 }
+/** @internal Exported for testing only */
+export { generateSimpleEmbedding as _generateSimpleEmbedding };
+/** @internal Exported for testing only */
+export { diversifyResults as _diversifyResults };

package/dist/rag/retrieval/vectorQueryTool.js

@@ -253,10 +253,27 @@ export class InMemoryVectorStore {
                             !fieldValue.includes(ops.$contains))) {
                         return false;
                     }
-                    if ("$regex" in ops &&
-                        (typeof fieldValue !== "string" ||
-                            !new RegExp(ops.$regex).test(fieldValue))) {
-                        return false;
+                    if ("$regex" in ops) {
+                        const pattern = ops.$regex;
+                        let regexMatches = false;
+                        // Guard against ReDoS: reject excessively long patterns and limit
+                        // the tested string length to prevent pathological backtracking.
+                        if (pattern.length <= 200) {
+                            try {
+                                const re = new RegExp(pattern);
+                                const testValue = typeof fieldValue === "string"
+                                    ? fieldValue.slice(0, 10_000)
+                                    : "";
+                                regexMatches = re.test(testValue);
+                            }
+                            catch {
+                                // Invalid regex pattern — treat as non-match
+                                regexMatches = false;
+                            }
+                        }
+                        if (!regexMatches) {
+                            return false;
+                        }
                     }
                 }
                 else {

package/dist/server/abstract/baseServerAdapter.js

@@ -166,7 +166,10 @@ export class BaseServerAdapter extends EventEmitter {
         }
         // Register all routes in the group with prefix applied
         for (const route of group.routes) {
-            const prefixedPath = this.normalizePath(`${group.prefix}${route.path}`);
+            // Only prepend prefix if route path doesn't already start with it
+            // (route definitions include full paths like /api/agent/execute)
+            const needsPrefix = !route.path.startsWith(group.prefix);
+            const prefixedPath = this.normalizePath(needsPrefix ? `${group.prefix}${route.path}` : route.path);
             const prefixedRoute = {
                 ...route,
                 path: prefixedPath,

package/dist/server/adapters/fastifyAdapter.js

@@ -5,6 +5,7 @@
  */
 import { logger } from "../../utils/logger.js";
 import { AlreadyRunningError, ServerStartError, ServerStopError, wrapError, } from "../errors.js";
+import { withTimeout } from "../../utils/errorHandling.js";
 import { BaseServerAdapter } from "../abstract/baseServerAdapter.js";
 import { isErrorResponse } from "../utils/validation.js";
 /**
@@ -12,7 +13,7 @@ import { isErrorResponse } from "../utils/validation.js";
  * Provides high-performance HTTP server with schema validation
  */
 export class FastifyServerAdapter extends BaseServerAdapter {
-    app;
+    app = null;
     frameworkInitialized = false;
     constructor(neurolink, config = {}) {
         super(neurolink, config);
@@ -174,7 +175,15 @@ export class FastifyServerAdapter extends BaseServerAdapter {
      * Register route with Fastify
      */
     registerFrameworkRoute(route) {
+        if (!this.app) {
+            throw new Error("Fastify app not initialized. Call initialize() before registering routes.");
+        }
         const method = route.method.toUpperCase();
+        // Fastify does not allow duplicate method+path registrations.
+        // Skip if route already exists (e.g., built-in health routes).
+        if (this.app.hasRoute({ method, url: route.path })) {
+            return;
+        }
         this.app.route({
             method,
             url: route.path,
@@ -307,6 +316,9 @@ export class FastifyServerAdapter extends BaseServerAdapter {
      * Register middleware with Fastify
      */
     registerFrameworkMiddleware(middleware) {
+        if (!this.app) {
+            throw new Error("Fastify app not initialized. Call initialize() before registering middleware.");
+        }
         this.app.addHook("preHandler", async (request, _reply) => {
             // Skip excluded paths
             if (middleware.excludePaths?.some((p) => request.url.startsWith(p))) {
@@ -357,50 +369,39 @@ export class FastifyServerAdapter extends BaseServerAdapter {
         if (this.isRunning) {
             throw new AlreadyRunningError(this.config.port, this.config.host);
         }
+        if (!this.app) {
+            throw new Error("Fastify app not initialized. Call initialize() before starting.");
+        }
+        // Capture non-null reference for use in closures below
+        const app = this.app;
         this.lifecycleState = "starting";
         const { port, host } = this.config;
         const startupTimeout = this.config.timeout || 30000;
-        const startPromise = (async () => {
-            await this.app.listen({ port, host });
+        // Track connections via Fastify hooks (must be registered before listen)
+        app.addHook("onRequest", async (request) => {
+            const connectionId = `conn-${request.id}`;
+            this.trackConnection(connectionId, request.raw.socket, request.id);
+        });
+        app.addHook("onResponse", async (request) => {
+            const connectionId = `conn-${request.id}`;
+            this.untrackConnection(connectionId);
+        });
+        try {
+            await withTimeout(app.listen({ port, host }), startupTimeout, new ServerStartError(`Fastify server startup timed out after ${startupTimeout}ms`, undefined, port, host));
             this.isRunning = true;
             this.startTime = new Date();
             this.lifecycleState = "running";
-            // Track connections via Fastify hooks
-            this.app.addHook("onRequest", async (request) => {
-                const connectionId = `conn-${request.id}`;
-                this.trackConnection(connectionId, request.raw.socket, request.id);
-            });
-            this.app.addHook("onResponse", async (request) => {
-                const connectionId = `conn-${request.id}`;
-                this.untrackConnection(connectionId);
-            });
             logger.info(`[FastifyAdapter] Server started on ${host}:${port}`);
             this.emit("started", {
                 port,
                 host,
                 timestamp: this.startTime,
             });
-        })();
-        let startupTimer;
-        const timeoutPromise = new Promise((_, reject) => {
-            startupTimer = setTimeout(() => {
-                this.lifecycleState = "error";
-                reject(new ServerStartError(`Fastify server startup timed out after ${startupTimeout}ms`, undefined, port, host));
-            }, startupTimeout);
-        });
-        try {
-            await Promise.race([startPromise, timeoutPromise]);
         }
         catch (error) {
             this.lifecycleState = "error";
             throw error;
         }
-        finally {
-            // Always clear the timeout to prevent memory leak
-            if (startupTimer) {
-                clearTimeout(startupTimer);
-            }
-        }
     }
     /**
      * Stop the Fastify server with graceful shutdown
@@ -421,6 +422,7 @@ export class FastifyServerAdapter extends BaseServerAdapter {
             // Reset state for restart capability
             this.resetServerState();
             this.frameworkInitialized = false;
+            this.app = null;
         }
         catch (error) {
             const wrappedError = wrapError(error);
@@ -441,7 +443,10 @@ export class FastifyServerAdapter extends BaseServerAdapter {
      * Close the underlying server
      */
     async closeServer() {
-        await this.app.close();
+        if (this.app) {
+            const closeTimeout = this.shutdownConfig.gracefulShutdownTimeoutMs;
+            await withTimeout(this.app.close(), closeTimeout, new Error(`Fastify server close timed out after ${closeTimeout}ms`));
+        }
     }
     /**
      * Force close all active connections
@@ -451,7 +456,7 @@ export class FastifyServerAdapter extends BaseServerAdapter {
             count: this.activeConnections.size,
         });
         // Get the underlying server and destroy all sockets
-        const server = this.app.server;
+        const server = this.app?.server;
         if (server) {
             // Force close by destroying the server
             server.closeAllConnections?.();

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

@@ -177,6 +177,38 @@ export declare function setLangfuseContext<T = void>(context: {
  * console.log(context?.userId, context?.sessionId);
  */
 export declare function getLangfuseContext(): LangfuseContext | undefined;
+/**
+ * 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);
+ */
+export declare function runWithCurrentLangfuseContext<T>(fn: () => Promise<T>): () => Promise<T>;
 /**
  * Get an OpenTelemetry Tracer for creating custom spans
  *