@juspay/neurolink 9.14.0 → 9.16.0

package/dist/context/budgetChecker.js

@@ -36,7 +36,7 @@ export function checkContextBudget(params) {
         ? toolDefinitions.reduce((sum, tool) => {
             try {
                 const serialized = JSON.stringify(tool);
-                return sum + Math.ceil(serialized.length / 4);
+                return sum + estimateTokens(serialized, provider);
             }
             catch {
                 return sum + TOKENS_PER_TOOL_DEFINITION;

package/dist/context/contextCompactor.js

@@ -8,6 +8,7 @@
  * Stage 3: LLM Summarization (expensive -- requires LLM call)
  * Stage 4: Sliding Window Truncation (fallback -- no LLM call)
  */
+import { trace, SpanStatusCode } from "@opentelemetry/api";
 import { estimateMessagesTokens } from "../utils/tokenEstimation.js";
 import { logger } from "../utils/logger.js";
 import { pruneToolOutputs } from "./stages/toolOutputPruner.js";
@@ -112,15 +113,36 @@ export class ContextCompactor {
                     saved: stageTokensBefore - stageTokensAfter,
                 });
             }
-            catch {
-                logger.info("[Compaction] Stage 3 (summarize)", {
+            catch (error) {
+                // Capture the actual error for debugging
+                const errorMessage = error instanceof Error ? error.message : String(error);
+                const errorName = error instanceof Error ? error.name : "UnknownError";
+                logger.warn("[Compaction] Stage 3 (summarize) FAILED", {
                     requestId,
-                    ran: false,
+                    error: errorMessage,
+                    errorName,
                     tokensBefore: stageTokensBefore,
                     tokensAfter: stageTokensBefore,
                     saved: 0,
                 });
-                // Summarization failed, fall through to truncation
+                // Record on OTel span for trace visibility
+                const activeSpan = trace.getActiveSpan();
+                if (activeSpan) {
+                    activeSpan.addEvent("compaction.stage3.failed", {
+                        "error.message": errorMessage,
+                        "error.name": errorName,
+                        "stage.tokens_before": stageTokensBefore,
+                    });
+                    if (error instanceof Error) {
+                        activeSpan.recordException(error);
+                    }
+                    // NLK-GAP-005 fix: set error status alongside recordException
+                    activeSpan.setStatus({
+                        code: SpanStatusCode.ERROR,
+                        message: `Compaction stage 3 (summarize) failed: ${errorMessage}`,
+                    });
+                }
+                // Fall through to Stage 4 truncation as before
             }
         }
         // Stage 4: Sliding Window Truncation (fallback)
@@ -129,6 +151,11 @@ export class ContextCompactor {
             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;

package/dist/context/emergencyTruncation.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 type { ChatMessage } from "../types/conversation.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 declare function emergencyContentTruncation(messages: ChatMessage[], availableTokensForHistory: number, breakdown: {
+    systemPrompt: number;
+    conversationHistory: number;
+    currentPrompt: number;
+    toolDefinitions: number;
+    fileAttachments: number;
+}, provider?: string): ChatMessage[];

package/dist/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/context/errorDetection.d.ts

@@ -12,3 +12,19 @@ export declare function isContextOverflowError(error: unknown): boolean;
  * Identify which provider produced the context overflow error.
  */
 export declare function getContextOverflowProvider(error: unknown): string | 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 declare function parseProviderOverflowDetails(error: unknown): {
+    actualTokens: number;
+    budgetTokens: number;
+} | null;
+/**
+ * Extract error message from various error formats.
+ */
+export declare function extractErrorMessage(error: unknown): string | null;

package/dist/context/errorDetection.js

@@ -86,10 +86,57 @@ export function getContextOverflowProvider(error) {
     }
     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.
  */
-function extractErrorMessage(error) {
+export function extractErrorMessage(error) {
     if (!error) {
         return null;
     }

package/dist/context/errors.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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 declare class ContextBudgetExceededError extends Error {
+    readonly estimatedTokens: number;
+    readonly availableTokens: number;
+    readonly stagesUsed: string[];
+    readonly breakdown: Record<string, number>;
+    constructor(message: string, details: {
+        estimatedTokens: number;
+        availableTokens: number;
+        stagesUsed: string[];
+        breakdown: Record<string, number>;
+    });
+}

package/dist/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/context/stages/slidingWindowTruncator.d.ts

@@ -4,6 +4,12 @@
  * Non-destructive fallback: tags oldest messages as truncated
  * instead of deleting them. Always preserves first message pair.
  * Removes messages in pairs to maintain role alternation.
+ *
+ * Features:
+ * - Adaptive truncation (PERF-001): calculates fraction from actual overage
+ *   instead of fixed 50%, with iterative refinement up to 3 passes.
+ * - Small conversation handling (BUG-005): for <= 4 messages, truncates
+ *   message content proportionally instead of returning no-op.
  */
 import type { ChatMessage } from "../../types/conversation.js";
 import type { TruncationConfig, TruncationResult } from "../../types/contextTypes.js";

package/dist/context/stages/slidingWindowTruncator.js

@@ -4,39 +4,174 @@
  * Non-destructive fallback: tags oldest messages as truncated
  * instead of deleting them. Always preserves first message pair.
  * Removes messages in pairs to maintain role alternation.
+ *
+ * Features:
+ * - Adaptive truncation (PERF-001): calculates fraction from actual overage
+ *   instead of fixed 50%, with iterative refinement up to 3 passes.
+ * - Small conversation handling (BUG-005): for <= 4 messages, truncates
+ *   message content proportionally instead of returning no-op.
  */
 import { randomUUID } from "crypto";
+import { estimateTokens, estimateMessagesTokens, truncateToTokenBudget, } from "../../utils/tokenEstimation.js";
+import { logger } from "../../utils/logger.js";
 const TRUNCATION_MARKER_CONTENT = "[Earlier conversation history was truncated to fit within context limits]";
+/**
+ * For conversations with <= 4 messages that exceed token budget,
+ * truncate the CONTENT of the longest messages rather than removing messages.
+ *
+ * Strategy:
+ * 1. Calculate each message's proportional share of the token budget
+ * 2. Truncate messages that exceed their share using truncateToTokenBudget()
+ * 3. Never truncate messages below 200 tokens (preserve minimum context)
+ */
+function truncateSmallConversation(messages, config) {
+    // If no target tokens provided, we can't do content truncation
+    if (!config?.targetTokens) {
+        return { truncated: false, messages, messagesRemoved: 0 };
+    }
+    const provider = config.provider;
+    const targetTokens = config.targetTokens;
+    const currentTokens = estimateMessagesTokens(messages, provider);
+    if (currentTokens <= targetTokens) {
+        return { truncated: false, messages, messagesRemoved: 0 };
+    }
+    const MINIMUM_MSG_TOKENS = 200;
+    const FRAMING_OVERHEAD = 24 + messages.length * 4; // conversation + per-message overhead
+    // Available budget for actual content
+    const contentBudget = targetTokens - FRAMING_OVERHEAD;
+    if (contentBudget <= 0) {
+        return { truncated: false, messages, messagesRemoved: 0 };
+    }
+    // Calculate current content tokens per message
+    const msgTokens = messages.map((msg) => estimateTokens(msg.content, provider));
+    const totalContentTokens = msgTokens.reduce((sum, t) => sum + t, 0);
+    // Each message gets a proportional share of the content budget
+    const result = [...messages];
+    let totalSaved = 0;
+    for (let i = 0; i < result.length; i++) {
+        const msg = result[i];
+        // Don't truncate system/summary messages
+        if (msg.role === "system" || msg.metadata?.isSummary) {
+            continue;
+        }
+        const proportionalBudget = Math.floor((msgTokens[i] / totalContentTokens) * contentBudget);
+        const msgBudget = Math.max(MINIMUM_MSG_TOKENS, proportionalBudget);
+        if (msgTokens[i] > msgBudget) {
+            const truncated = truncateToTokenBudget(msg.content, msgBudget, provider);
+            if (truncated.truncated) {
+                totalSaved += msgTokens[i] - estimateTokens(truncated.text, provider);
+                result[i] = {
+                    ...msg,
+                    content: truncated.text,
+                    metadata: { ...msg.metadata, truncated: true },
+                };
+            }
+        }
+    }
+    if (totalSaved > 0) {
+        const finalTokens = estimateMessagesTokens(result, provider);
+        logger.info("[Truncation] Small conversation content truncated", {
+            messageCount: messages.length,
+            tokensSaved: totalSaved,
+            targetTokens,
+            finalTokens,
+        });
+        return {
+            truncated: finalTokens <= targetTokens,
+            messages: result,
+            messagesRemoved: 0, // No messages removed, only content truncated
+        };
+    }
+    return { truncated: false, messages, messagesRemoved: 0 };
+}
 export function truncateWithSlidingWindow(messages, config) {
-    const fraction = config?.fraction ?? 0.5;
     if (messages.length <= 4) {
-        return { truncated: false, messages, messagesRemoved: 0 };
+        // Delegate to content truncation for small conversations (BUG-005)
+        return truncateSmallConversation(messages, config);
+    }
+    // ADAPTIVE MODE: calculate fraction from actual overage (PERF-001)
+    let fraction;
+    if (config?.currentTokens &&
+        config?.targetTokens &&
+        config.currentTokens > config.targetTokens) {
+        const overageRatio = (config.currentTokens - config.targetTokens) / config.currentTokens;
+        const buffer = config?.adaptiveBuffer ?? 0.15;
+        // Required fraction = overage ratio + buffer, clamped to [0.1, 0.9]
+        fraction = Math.min(0.9, Math.max(0.1, overageRatio + buffer));
+        logger.info("[Truncation] Adaptive fraction calculated", {
+            currentTokens: config.currentTokens,
+            targetTokens: config.targetTokens,
+            overageRatio: Math.round(overageRatio * 100),
+            fraction: Math.round(fraction * 100),
+        });
+    }
+    else {
+        // Fallback to configured or default fraction
+        fraction = config?.fraction ?? 0.5;
     }
     // Always preserve first user-assistant pair
     const firstPair = messages.slice(0, 2);
-    // Calculate how many messages to remove from the middle
     const remainingMessages = messages.slice(2);
-    const removeCount = Math.floor(remainingMessages.length * fraction);
-    // Ensure we remove an even number to maintain role alternation
-    const evenRemoveCount = removeCount - (removeCount % 2);
-    if (evenRemoveCount <= 0) {
-        return { truncated: false, messages, messagesRemoved: 0 };
+    // ITERATIVE: if first pass isn't enough, increase fraction
+    const maxIterations = config?.maxIterations ?? 3;
+    let currentFraction = fraction;
+    for (let iteration = 0; iteration < maxIterations; iteration++) {
+        const removeCount = Math.floor(remainingMessages.length * currentFraction);
+        const evenRemoveCount = removeCount - (removeCount % 2);
+        if (evenRemoveCount <= 0) {
+            break;
+        }
+        const keptAfterTruncation = remainingMessages.slice(evenRemoveCount);
+        const truncationMarker = {
+            id: `truncation-${randomUUID()}`,
+            role: "system",
+            content: TRUNCATION_MARKER_CONTENT,
+            timestamp: new Date().toISOString(),
+            metadata: { isSummary: false, truncated: true },
+        };
+        const candidateMessages = [
+            ...firstPair,
+            truncationMarker,
+            ...keptAfterTruncation,
+        ];
+        // If we have token targets, verify the result fits
+        if (config?.targetTokens) {
+            const candidateTokens = estimateMessagesTokens(candidateMessages, config.provider);
+            if (candidateTokens <= config.targetTokens) {
+                return {
+                    truncated: true,
+                    messages: candidateMessages,
+                    messagesRemoved: evenRemoveCount,
+                };
+            }
+            // Not enough -- increase fraction by 25% for next iteration
+            currentFraction = Math.min(0.95, currentFraction + 0.25);
+            continue;
+        }
+        // No token targets -- single-pass with calculated fraction
+        return {
+            truncated: true,
+            messages: candidateMessages,
+            messagesRemoved: evenRemoveCount,
+        };
     }
-    const keptAfterTruncation = remainingMessages.slice(evenRemoveCount);
-    // Create truncation marker
-    const truncationMarker = {
-        id: `truncation-${randomUUID()}`,
-        role: "system",
-        content: TRUNCATION_MARKER_CONTENT,
-        timestamp: new Date().toISOString(),
-        metadata: {
-            isSummary: false,
+    // All iterations exhausted -- return best effort (most aggressive truncation)
+    const maxRemove = Math.floor(remainingMessages.length * 0.95);
+    const evenMaxRemove = maxRemove - (maxRemove % 2);
+    if (evenMaxRemove > 0) {
+        const keptMessages = remainingMessages.slice(evenMaxRemove);
+        const truncationMarker = {
+            id: `truncation-${randomUUID()}`,
+            role: "system",
+            content: TRUNCATION_MARKER_CONTENT,
+            timestamp: new Date().toISOString(),
+            metadata: { isSummary: false, truncated: true },
+        };
+        return {
             truncated: true,
-        },
-    };
-    return {
-        truncated: true,
-        messages: [...firstPair, truncationMarker, ...keptAfterTruncation],
-        messagesRemoved: evenRemoveCount,
-    };
+            messages: [...firstPair, truncationMarker, ...keptMessages],
+            messagesRemoved: evenMaxRemove,
+        };
+    }
+    return { truncated: false, messages, messagesRemoved: 0 };
 }