@juspay/neurolink 9.30.0 → 9.31.1

package/dist/client/context/contextCompactor.js

@@ -0,0 +1,205 @@
+/**
+ * ContextCompactor
+ *
+ * Orchestrates multi-stage context reduction:
+ *
+ * Stage 1: Tool Output Pruning (cheapest -- no LLM call)
+ * Stage 2: File Read Deduplication (cheap -- no LLM call)
+ * Stage 3: LLM Summarization (expensive -- requires LLM call)
+ * Stage 4: Sliding Window Truncation (fallback -- no LLM call)
+ */
+import { estimateMessagesTokens } from "../utils/tokenEstimation.js";
+import { logger } from "../utils/logger.js";
+import { withTimeout } from "../utils/async/withTimeout.js";
+import { SpanSerializer, SpanType, SpanStatus, } from "../observability/index.js";
+import { getMetricsAggregator } from "../observability/index.js";
+import { pruneToolOutputs } from "./stages/toolOutputPruner.js";
+import { deduplicateFileReads } from "./stages/fileReadDeduplicator.js";
+import { truncateWithSlidingWindow } from "./stages/slidingWindowTruncator.js";
+import { summarizeMessages } from "./stages/structuredSummarizer.js";
+const DEFAULT_CONFIG = {
+    enablePrune: true,
+    enableDeduplicate: true,
+    enableSummarize: true,
+    enableTruncate: true,
+    pruneProtectTokens: 40_000,
+    pruneMinimumSavings: 20_000,
+    pruneProtectedTools: ["skill"],
+    summarizationProvider: "vertex",
+    summarizationModel: "gemini-2.5-flash",
+    keepRecentRatio: 0.3,
+    truncationFraction: 0.5,
+    provider: "",
+};
+export class ContextCompactor {
+    config;
+    constructor(config) {
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    /**
+     * Run the multi-stage compaction pipeline until messages fit within budget.
+     */
+    async compact(messages, targetTokens, memoryConfig, requestId) {
+        let span = SpanSerializer.createSpan(SpanType.CONTEXT_COMPACTION, "context.compact", {
+            "context.operation": "compact",
+            "context.targetTokens": targetTokens,
+        });
+        const spanStartTime = Date.now();
+        try {
+            const provider = this.config.provider || undefined;
+            const tokensBefore = estimateMessagesTokens(messages, provider);
+            const stagesUsed = [];
+            let currentMessages = [...messages];
+            logger.info("[Compaction] Starting", {
+                requestId,
+                estimatedTokens: tokensBefore,
+                budgetTokens: targetTokens,
+            });
+            // Stage 1: Tool Output Pruning
+            if (this.config.enablePrune &&
+                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                const pruneResult = pruneToolOutputs(currentMessages, {
+                    protectTokens: this.config.pruneProtectTokens,
+                    minimumSavings: this.config.pruneMinimumSavings,
+                    protectedTools: this.config.pruneProtectedTools,
+                    provider,
+                });
+                if (pruneResult.pruned) {
+                    currentMessages = pruneResult.messages;
+                    stagesUsed.push("prune");
+                }
+                const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                logger.info("[Compaction] Stage 1 (prune)", {
+                    requestId,
+                    ran: pruneResult.pruned,
+                    tokensBefore: stageTokensBefore,
+                    tokensAfter: stageTokensAfter,
+                    saved: stageTokensBefore - stageTokensAfter,
+                });
+            }
+            // Stage 2: File Read Deduplication
+            if (this.config.enableDeduplicate &&
+                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                const dedupResult = deduplicateFileReads(currentMessages);
+                if (dedupResult.deduplicated) {
+                    currentMessages = dedupResult.messages;
+                    stagesUsed.push("deduplicate");
+                }
+                const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                logger.info("[Compaction] Stage 2 (deduplicate)", {
+                    requestId,
+                    ran: dedupResult.deduplicated,
+                    tokensBefore: stageTokensBefore,
+                    tokensAfter: stageTokensAfter,
+                    saved: stageTokensBefore - stageTokensAfter,
+                });
+            }
+            // Stage 3: LLM Summarization
+            if (this.config.enableSummarize &&
+                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                try {
+                    const summarizeResult = await withTimeout(summarizeMessages(currentMessages, {
+                        provider: this.config.summarizationProvider,
+                        model: this.config.summarizationModel,
+                        keepRecentRatio: this.config.keepRecentRatio,
+                        memoryConfig,
+                        targetTokens,
+                    }), 120_000, "LLM summarization timed out after 120s");
+                    if (summarizeResult.summarized) {
+                        currentMessages = summarizeResult.messages;
+                        stagesUsed.push("summarize");
+                    }
+                    const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                    logger.info("[Compaction] Stage 3 (summarize)", {
+                        requestId,
+                        ran: summarizeResult.summarized,
+                        tokensBefore: stageTokensBefore,
+                        tokensAfter: stageTokensAfter,
+                        saved: stageTokensBefore - stageTokensAfter,
+                    });
+                }
+                catch (error) {
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    logger.warn("[Compaction] Stage 3 (summarize) FAILED", {
+                        requestId,
+                        error: err.message,
+                        errorName: err.name,
+                        tokensBefore: stageTokensBefore,
+                        tokensAfter: stageTokensBefore,
+                        saved: 0,
+                    });
+                    // Record failure on the compaction span for trace visibility
+                    span = SpanSerializer.updateAttributes(span, {
+                        "compaction.stage3.error": err.message,
+                        "compaction.stage3.errorName": err.name,
+                        "compaction.stage3.tokensBefore": stageTokensBefore,
+                        "compaction.stage3_failed": true,
+                    });
+                    // Fall through to Stage 4 truncation as before
+                }
+            }
+            // Stage 4: Sliding Window Truncation (fallback)
+            if (this.config.enableTruncate &&
+                estimateMessagesTokens(currentMessages, provider) > targetTokens) {
+                const stageTokensBefore = estimateMessagesTokens(currentMessages, provider);
+                const truncResult = truncateWithSlidingWindow(currentMessages, {
+                    fraction: this.config.truncationFraction,
+                    currentTokens: stageTokensBefore,
+                    targetTokens: targetTokens,
+                    provider: provider,
+                    adaptiveBuffer: 0.15,
+                    maxIterations: 3,
+                });
+                if (truncResult.truncated) {
+                    currentMessages = truncResult.messages;
+                    stagesUsed.push("truncate");
+                }
+                const stageTokensAfter = estimateMessagesTokens(currentMessages, provider);
+                logger.info("[Compaction] Stage 4 (truncate)", {
+                    requestId,
+                    ran: truncResult.truncated,
+                    tokensBefore: stageTokensBefore,
+                    tokensAfter: stageTokensAfter,
+                    saved: stageTokensBefore - stageTokensAfter,
+                });
+            }
+            const tokensAfter = estimateMessagesTokens(currentMessages, provider);
+            logger.info("[Compaction] Complete", {
+                requestId,
+                tokensBefore,
+                tokensAfter,
+                totalSaved: tokensBefore - tokensAfter,
+                stagesUsed,
+                durationMs: Date.now() - spanStartTime,
+            });
+            const result = {
+                compacted: stagesUsed.length > 0,
+                stagesUsed,
+                tokensBefore,
+                tokensAfter,
+                tokensSaved: tokensBefore - tokensAfter,
+                messages: currentMessages,
+            };
+            span.durationMs = Date.now() - spanStartTime;
+            const endedSpan = SpanSerializer.endSpan(SpanSerializer.updateAttributes(span, {
+                "context.stage": stagesUsed.join(",") || "none",
+                "context.tokensBefore": tokensBefore,
+                "context.tokensAfter": tokensAfter,
+                "context.tokensSaved": tokensBefore - tokensAfter,
+            }), SpanStatus.OK);
+            getMetricsAggregator().recordSpan(endedSpan);
+            return result;
+        }
+        catch (error) {
+            span.durationMs = Date.now() - spanStartTime;
+            const endedSpan = SpanSerializer.endSpan(span, SpanStatus.ERROR);
+            endedSpan.statusMessage =
+                error instanceof Error ? error.message : String(error);
+            getMetricsAggregator().recordSpan(endedSpan);
+            throw error;
+        }
+    }
+}

package/dist/client/context/emergencyTruncation.js

@@ -0,0 +1,88 @@
+/**
+ * Emergency Content Truncation
+ *
+ * When message-level removal (sliding window) can't fit context into budget,
+ * this truncates the CONTENT of the longest messages as a last resort.
+ */
+import { estimateTokens, estimateMessagesTokens, truncateToTokenBudget, } from "../utils/tokenEstimation.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Emergency content truncation: truncate the content of the longest messages
+ * to fit within the available token budget.
+ *
+ * Strategy: Sort messages by content length (descending), truncate each
+ * to a proportional share of the available budget until total fits.
+ */
+export function emergencyContentTruncation(messages, availableTokensForHistory, breakdown, provider) {
+    // Budget available for conversation history specifically
+    const historyBudget = availableTokensForHistory -
+        breakdown.systemPrompt -
+        breakdown.currentPrompt -
+        breakdown.toolDefinitions -
+        breakdown.fileAttachments;
+    if (historyBudget <= 0) {
+        // No room for history: return empty to guarantee budget safety
+        return [];
+    }
+    const currentHistoryTokens = estimateMessagesTokens(messages, provider);
+    if (currentHistoryTokens <= historyBudget) {
+        return messages; // Already fits
+    }
+    // Calculate per-message budgets proportional to original size,
+    // but cap large messages to free space for others
+    const result = [...messages];
+    const reductionNeeded = currentHistoryTokens - historyBudget;
+    const reductionRatio = reductionNeeded / currentHistoryTokens;
+    // Sort indices by content length descending (truncate biggest first)
+    const sortedIndices = result
+        .map((msg, idx) => ({ idx, len: msg.content.length }))
+        .sort((a, b) => b.len - a.len);
+    let tokensSaved = 0;
+    for (const { idx } of sortedIndices) {
+        if (tokensSaved >= reductionNeeded) {
+            break;
+        }
+        const msg = result[idx];
+        // Don't truncate system messages or very short messages
+        if (msg.role === "system" || msg.content.length < 200) {
+            continue;
+        }
+        const msgTokens = estimateTokens(msg.content, provider);
+        const targetTokens = Math.floor(msgTokens * (1 - reductionRatio - 0.05));
+        if (targetTokens < msgTokens && targetTokens > 50) {
+            const truncated = truncateToTokenBudget(msg.content, targetTokens, provider);
+            if (truncated.truncated) {
+                const savedThisMsg = msgTokens - estimateTokens(truncated.text, provider);
+                tokensSaved += savedThisMsg;
+                result[idx] = {
+                    ...msg,
+                    content: truncated.text,
+                    metadata: { ...msg.metadata, truncated: true },
+                };
+            }
+        }
+    }
+    logger.info("[EmergencyTruncation] Content truncation complete", {
+        tokensSaved,
+        reductionNeeded,
+        messagesModified: result.filter((m, i) => m !== messages[i]).length,
+    });
+    // Final safety check: guarantee returned history fits budget
+    if (estimateMessagesTokens(result, provider) <= historyBudget) {
+        return result;
+    }
+    // Hard fallback: keep newest non-system messages that fit
+    const fallback = [];
+    for (let i = result.length - 1; i >= 0; i--) {
+        const msg = result[i];
+        if (msg.role === "system") {
+            continue;
+        }
+        fallback.unshift(msg);
+        if (estimateMessagesTokens(fallback, provider) > historyBudget) {
+            fallback.shift();
+            break;
+        }
+    }
+    return fallback;
+}

package/dist/client/context/errorDetection.js

@@ -0,0 +1,171 @@
+/**
+ * Context Overflow Error Detection
+ *
+ * Cross-provider regex patterns to detect context window overflow errors.
+ * Modeled on Cline + pi-mono patterns.
+ */
+/**
+ * Provider-specific error patterns for context overflow.
+ *
+ * IMPORTANT: Order matters for getContextOverflowProvider - more specific
+ * patterns should be checked first. OpenAI patterns are very specific
+ * (e.g., "This model's maximum context length is") so they come first.
+ */
+const OVERFLOW_PATTERNS = [
+    {
+        provider: "openai",
+        patterns: [
+            /This model's maximum context length is/i,
+            /tokens\. However, (?:your messages|you requested)/i,
+            /reduce the length of the messages/i,
+            /Please reduce the length/i,
+        ],
+    },
+    {
+        provider: "azure",
+        patterns: [/content_length_exceeded/i],
+    },
+    {
+        provider: "google",
+        patterns: [
+            /RESOURCE_EXHAUSTED/i,
+            /exceeds the maximum number of tokens/i,
+            /content is too long/i,
+            /request payload size exceeds/i,
+            /input token limit/i,
+        ],
+    },
+    {
+        provider: "bedrock",
+        patterns: [
+            /ValidationException.*token/i,
+            /Input is too long/i,
+            /exceeds the model's maximum/i,
+        ],
+    },
+    {
+        provider: "mistral",
+        patterns: [/context length exceeded/i, /maximum number of tokens/i],
+    },
+    {
+        provider: "openrouter",
+        patterns: [/context_length_exceeded/i],
+    },
+    {
+        provider: "anthropic",
+        patterns: [
+            /prompt is too long/i,
+            /input is too long/i,
+            /too many tokens/i,
+            /maximum context length/i,
+        ],
+    },
+];
+/**
+ * Check if an error is a context overflow error from any provider.
+ */
+export function isContextOverflowError(error) {
+    const errorMessage = extractErrorMessage(error);
+    if (!errorMessage) {
+        return false;
+    }
+    return OVERFLOW_PATTERNS.some(({ patterns }) => patterns.some((pattern) => pattern.test(errorMessage)));
+}
+/**
+ * Identify which provider produced the context overflow error.
+ */
+export function getContextOverflowProvider(error) {
+    const errorMessage = extractErrorMessage(error);
+    if (!errorMessage) {
+        return null;
+    }
+    for (const { provider, patterns } of OVERFLOW_PATTERNS) {
+        if (patterns.some((pattern) => pattern.test(errorMessage))) {
+            return provider;
+        }
+    }
+    return null;
+}
+/**
+ * Extract actual token counts from provider overflow error messages.
+ *
+ * Many providers include the actual/max token counts in their error messages:
+ * - OpenAI: "This model's maximum context length is 128000 tokens. However, your messages resulted in 145000 tokens."
+ * - Anthropic: "prompt is too long: 180000 tokens > 200000 token limit"
+ * - Google: "exceeds the maximum number of tokens (180000 > 100000)"
+ */
+export function parseProviderOverflowDetails(error) {
+    const message = extractErrorMessage(error);
+    if (!message) {
+        return null;
+    }
+    // Guard against excessively long inputs that could slow regex matching
+    if (message.length > 2000) {
+        return null;
+    }
+    // OpenAI pattern: "resulted in X tokens" + "maximum context length is Y"
+    // Use single character-class number groups to prevent ReDoS (CodeQL: js/polynomial-redos)
+    const openaiActual = message.match(/resulted\s+in\s+(\d[\d,]{0,19})\s*tokens/i);
+    const openaiMax = message.match(/maximum\s+context\s+length\s+is\s+(\d[\d,]{0,19})/i);
+    if (openaiActual && openaiMax) {
+        return {
+            actualTokens: parseInt(openaiActual[1].replace(/,/g, ""), 10),
+            budgetTokens: parseInt(openaiMax[1].replace(/,/g, ""), 10),
+        };
+    }
+    // Anthropic pattern: "X tokens > Y token limit" or "X tokens, limit Y"
+    // Use single character-class number groups to prevent ReDoS (CodeQL: js/polynomial-redos)
+    const anthropicMatch = message.match(/(\d[\d,]{0,19})\s*tokens?\s*[>:]\s*(\d[\d,]{0,19})/i);
+    if (anthropicMatch) {
+        return {
+            actualTokens: parseInt(anthropicMatch[1].replace(/,/g, ""), 10),
+            budgetTokens: parseInt(anthropicMatch[2].replace(/,/g, ""), 10),
+        };
+    }
+    // Google pattern: "X > Y" or "X exceeds Y"
+    // Use single character-class number groups to prevent ReDoS (CodeQL: js/polynomial-redos)
+    const googleMatch = message.match(/(\d[\d,]{0,19})\s*(?:>|exceeds)\s*(\d[\d,]{0,19})/i);
+    if (googleMatch) {
+        return {
+            actualTokens: parseInt(googleMatch[1].replace(/,/g, ""), 10),
+            budgetTokens: parseInt(googleMatch[2].replace(/,/g, ""), 10),
+        };
+    }
+    return null;
+}
+/**
+ * Extract error message from various error formats.
+ */
+export function extractErrorMessage(error) {
+    if (!error) {
+        return null;
+    }
+    if (typeof error === "string") {
+        return error;
+    }
+    if (error instanceof Error) {
+        // Check nested error messages too
+        const msg = error.message;
+        const cause = error?.cause;
+        if (cause instanceof Error) {
+            return `${msg} ${cause.message}`;
+        }
+        return msg;
+    }
+    if (typeof error === "object") {
+        const obj = error;
+        if (typeof obj.message === "string") {
+            return obj.message;
+        }
+        if (typeof obj.error === "string") {
+            return obj.error;
+        }
+        if (typeof obj.error === "object" && obj.error !== null) {
+            const nested = obj.error;
+            if (typeof nested.message === "string") {
+                return nested.message;
+            }
+        }
+    }
+    return null;
+}

package/dist/client/context/errors.js

@@ -0,0 +1,21 @@
+/**
+ * Context-specific error classes for budget and overflow scenarios.
+ */
+/**
+ * Thrown when context exceeds model budget after all compaction stages,
+ * preventing wasteful API calls to providers that will reject the request.
+ */
+export class ContextBudgetExceededError extends Error {
+    estimatedTokens;
+    availableTokens;
+    stagesUsed;
+    breakdown;
+    constructor(message, details) {
+        super(message);
+        this.name = "ContextBudgetExceededError";
+        this.estimatedTokens = details.estimatedTokens;
+        this.availableTokens = details.availableTokens;
+        this.stagesUsed = details.stagesUsed;
+        this.breakdown = details.breakdown;
+    }
+}

package/dist/client/context/fileTokenBudget.js

@@ -0,0 +1,127 @@
+/**
+ * File Token Budget System
+ *
+ * Calculates how much of the remaining context window budget
+ * can be used for file reads. Implements fast-path for small files
+ * and preview mode for very large files.
+ */
+/** Percentage of remaining context to allocate for file reads */
+export const FILE_READ_BUDGET_PERCENT = 0.6;
+/** Files below this size skip budget validation (100KB) */
+export const FILE_FAST_PATH_SIZE = 100 * 1024;
+/** Files above this size get preview-only mode (5MB) */
+export const FILE_PREVIEW_MODE_SIZE = 5 * 1024 * 1024;
+/** Default preview size in characters */
+export const FILE_PREVIEW_CHARS = 2000;
+/**
+ * Calculate available token budget for file reads.
+ *
+ * @param contextWindow - Total context window for the model
+ * @param currentTokens - Tokens already used (conversation + system prompt)
+ * @param maxOutputTokens - Reserved output tokens
+ * @returns Available tokens for file content
+ */
+export function calculateFileTokenBudget(contextWindow, currentTokens, maxOutputTokens) {
+    const remainingTokens = contextWindow - currentTokens - maxOutputTokens;
+    if (remainingTokens <= 0) {
+        return 0;
+    }
+    return Math.floor(remainingTokens * FILE_READ_BUDGET_PERCENT);
+}
+/**
+ * Determine how a file should be handled based on its size and the budget.
+ */
+export function shouldTruncateFile(fileSize, budget) {
+    // Very large files: preview mode
+    if (fileSize > FILE_PREVIEW_MODE_SIZE) {
+        return {
+            shouldTruncate: true,
+            maxChars: FILE_PREVIEW_CHARS,
+            previewMode: true,
+        };
+    }
+    // Small files: skip validation
+    if (fileSize < FILE_FAST_PATH_SIZE) {
+        return { shouldTruncate: false };
+    }
+    // Estimate tokens (4 chars per token, rough)
+    const estimatedTokens = Math.ceil(fileSize / 4);
+    if (estimatedTokens <= budget) {
+        return { shouldTruncate: false };
+    }
+    // Truncate to fit budget
+    const maxChars = budget * 4; // Convert back to chars
+    return {
+        shouldTruncate: true,
+        maxChars: Math.max(FILE_PREVIEW_CHARS, maxChars),
+        previewMode: false,
+    };
+}
+/**
+ * Estimate post-processing token count based on file type.
+ *
+ * Different file types produce vastly different amounts of text after
+ * processing.  A 50 MB video file yields ~200-500 tokens of metadata,
+ * while a 50 MB text file yields ~12.5 M tokens.  Using the raw byte
+ * size for all types causes media files to be wrongly excluded by the
+ * aggregate budget check.
+ *
+ * @param sizeBytes  Raw file size in bytes
+ * @param fileType   Detected file type (e.g. "video", "audio", "image")
+ * @returns Estimated token count after processing
+ */
+export function estimatePostProcessingTokens(sizeBytes, fileType) {
+    switch (fileType) {
+        // Media files produce only metadata text (~100-500 tokens)
+        case "video":
+            return 500;
+        case "audio":
+            return 300;
+        // Images are sent as base64 — provider counts them as ~1500 tokens each
+        case "image":
+            return 1500;
+        // Archives produce a file listing (~500-2000 tokens)
+        case "archive":
+            return 1000;
+        // Unknown binary files produce metadata + extracted strings (~200-1000 tokens)
+        case "unknown":
+            return 500;
+        // PDFs are sent natively on some providers; estimate ~1 token per 100 bytes, capped
+        case "pdf":
+            return Math.min(Math.ceil(sizeBytes / 100), 50_000);
+        // Structured documents (Excel, Word, PPTX) extract text — roughly 15% of raw size
+        case "xlsx":
+        case "docx":
+        case "pptx":
+            return Math.ceil((sizeBytes * 0.15) / 4);
+        // SVG is sanitized markup — usually small
+        case "svg":
+            return Math.ceil(sizeBytes / 4);
+        // CSV, text, code — raw text roughly 1 token per 4 bytes
+        case "csv":
+        case "text":
+        default:
+            // Original formula: base64-inflate then divide by 4
+            return Math.ceil((sizeBytes * 1.33) / 4);
+    }
+}
+export function enforceAggregateFileBudget(files, availableTokens) {
+    const TOKEN_BUDGET_FOR_FILES = Math.floor(availableTokens * FILE_READ_BUDGET_PERCENT);
+    let usedTokens = 0;
+    const included = [];
+    const excluded = [];
+    const notices = [];
+    const sorted = [...files].sort((a, b) => a.sizeBytes - b.sizeBytes);
+    for (const file of sorted) {
+        const estimatedTokens = estimatePostProcessingTokens(file.sizeBytes, file.fileType);
+        if (usedTokens + estimatedTokens <= TOKEN_BUDGET_FOR_FILES) {
+            usedTokens += estimatedTokens;
+            included.push(file);
+        }
+        else {
+            excluded.push(file);
+            notices.push(`Skipped "${file.name}" (${(file.sizeBytes / 1024).toFixed(0)} KB) — exceeds context budget`);
+        }
+    }
+    return { included, excluded, notices };
+}