@juspay/neurolink 9.10.1 → 9.12.0

package/dist/lib/constants/contextWindows.js

@@ -10,6 +10,8 @@
  * - Google: https://ai.google.dev/gemini-api/docs/models
  * - Others: Provider documentation as of Feb 2026
  */
+import { DynamicModelProvider } from "../core/dynamicModels.js";
+import { logger } from "../utils/logger.js";
 /** Default context window when provider/model is unknown */
 export const DEFAULT_CONTEXT_WINDOW = 128_000;
 /** Maximum output reserve when maxTokens not specified */
@@ -67,6 +69,10 @@ export const MODEL_CONTEXT_WINDOWS = {
         "gemini-2.0-flash": 1_048_576,
         "gemini-1.5-pro": 2_097_152,
         "gemini-1.5-flash": 1_048_576,
+        "claude-sonnet-4-5": 200_000,
+        "claude-sonnet-4-20250514": 200_000,
+        "claude-opus-4": 200_000,
+        "claude-opus-4-20250514": 200_000,
     },
     bedrock: {
         _default: 200_000,
@@ -109,11 +115,32 @@ export const MODEL_CONTEXT_WINDOWS = {
  * Resolve context window size for a provider/model combination.
  *
  * Priority:
- *  1. Exact model match under provider
- *  2. Provider's _default
- *  3. Global DEFAULT_CONTEXT_WINDOW
+ *  0. Dynamic model registry (DynamicModelProvider) — resolves cross-provider
+ *     models (e.g. Claude on Vertex) that the static table cannot handle
+ *  1. Exact model match under provider in static registry
+ *  2. Prefix match under provider in static registry
+ *  3. Provider's _default in static registry
+ *  4. Global DEFAULT_CONTEXT_WINDOW
  */
 export function getContextWindowSize(provider, model) {
+    // Step 0: Check dynamic model registry first.
+    // This resolves cases where the runtime provider differs from the model's
+    // origin (e.g. Claude running via Vertex would hit Vertex's Gemini default
+    // in the static table). The dynamic registry knows the actual model metadata.
+    if (model) {
+        try {
+            const dynamicProvider = DynamicModelProvider.getInstance();
+            const modelConfig = dynamicProvider.resolveModel(provider, model);
+            if (modelConfig?.contextWindow) {
+                logger.debug(`[ContextWindow] Resolved via dynamic registry: provider=${provider}, model=${model}, contextWindow=${modelConfig.contextWindow}`);
+                return modelConfig.contextWindow;
+            }
+        }
+        catch {
+            // Dynamic registry not initialized yet — fall through to static lookup
+        }
+    }
+    // Static fallback chain
     const providerWindows = MODEL_CONTEXT_WINDOWS[provider];
     if (!providerWindows) {
         return DEFAULT_CONTEXT_WINDOW;

package/dist/lib/constants/index.d.ts

@@ -58,7 +58,7 @@ export declare const PROVIDER_OPERATION_CONFIGS: {
     };
     readonly OLLAMA: {
         readonly timeout: 10000;
-        readonly maxRetries: 2;
+        readonly maxRetries: 1;
         readonly retryDelay: 200;
     };
 };
@@ -83,7 +83,7 @@ export declare const MCP_OPERATION_CONFIGS: {
     };
     readonly HEALTH_CHECK: {
         readonly timeout: 5000;
-        readonly maxRetries: 2;
+        readonly maxRetries: 1;
         readonly retryDelay: 200;
     };
 };
@@ -140,7 +140,7 @@ export declare function getProviderRetryConfig(provider: string): {
     readonly maxDelay: 30000;
     readonly multiplier: 1.5;
 } | {
-    readonly maxAttempts: 2;
+    readonly maxAttempts: 1;
     readonly baseDelay: 200;
     readonly maxDelay: 5000;
     readonly multiplier: 1.5;

package/dist/lib/constants/retry.d.ts

@@ -18,7 +18,7 @@ export declare const RETRY_ATTEMPTS: {
     /** Critical operations that must succeed */
     readonly CRITICAL: 5;
     /** Quick operations that should fail fast */
-    readonly QUICK: 2;
+    readonly QUICK: 1;
     /** Network operations prone to transient failures */
     readonly NETWORK: 4;
     /** Authentication operations */
@@ -122,7 +122,7 @@ export declare const PROVIDER_RETRY: {
     };
     /** Ollama retry configuration (local service) */
     readonly OLLAMA: {
-        readonly maxAttempts: 2;
+        readonly maxAttempts: 1;
         readonly baseDelay: 200;
         readonly maxDelay: 5000;
         readonly multiplier: 1.5;
@@ -141,7 +141,7 @@ export declare const OPERATION_RETRY: {
     };
     /** MCP operation retry config */
     readonly MCP_OPERATION: {
-        readonly maxAttempts: 2;
+        readonly maxAttempts: 1;
         readonly baseDelay: 200;
         readonly circuitBreaker: false;
     };
@@ -210,7 +210,7 @@ export declare const RetryUtils: {
         readonly maxDelay: 30000;
         readonly multiplier: 1.5;
     } | {
-        readonly maxAttempts: 2;
+        readonly maxAttempts: 1;
         readonly baseDelay: 200;
         readonly maxDelay: 5000;
         readonly multiplier: 1.5;

package/dist/lib/constants/retry.js

@@ -18,7 +18,7 @@ export const RETRY_ATTEMPTS = {
     /** Critical operations that must succeed */
     CRITICAL: 5, // 5 attempts - High-importance operations
     /** Quick operations that should fail fast */
-    QUICK: 2, // 2 attempts - Fast operations, minimal retry
+    QUICK: 1, // 1 attempt, no retries — fail fast
     /** Network operations prone to transient failures */
     NETWORK: 4, // 4 attempts - Network operations
     /** Authentication operations */

package/dist/lib/context/contextCompactor.d.ts

@@ -18,5 +18,5 @@ export declare class ContextCompactor {
     /**
      * Run the multi-stage compaction pipeline until messages fit within budget.
      */
-    compact(messages: ChatMessage[], targetTokens: number, memoryConfig?: Partial<ConversationMemoryConfig>): Promise<CompactionResult>;
+    compact(messages: ChatMessage[], targetTokens: number, memoryConfig?: Partial<ConversationMemoryConfig>, requestId?: string): Promise<CompactionResult>;
 }

package/dist/lib/context/contextCompactor.js

@@ -9,6 +9,7 @@
  * Stage 4: Sliding Window Truncation (fallback -- no LLM call)
  */
 import { estimateMessagesTokens } from "../utils/tokenEstimation.js";
+import { logger } from "../utils/logger.js";
 import { pruneToolOutputs } from "./stages/toolOutputPruner.js";
 import { deduplicateFileReads } from "./stages/fileReadDeduplicator.js";
 import { summarizeMessages } from "./stages/structuredSummarizer.js";
@@ -35,14 +36,21 @@ export class ContextCompactor {
     /**
      * Run the multi-stage compaction pipeline until messages fit within budget.
      */
-    async compact(messages, targetTokens, memoryConfig) {
+    async compact(messages, targetTokens, memoryConfig, requestId) {
+        const compactionStartTime = Date.now();
         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,
@@ -53,19 +61,37 @@ export class ContextCompactor {
                 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 summarizeMessages(currentMessages, {
                     provider: this.config.summarizationProvider,
@@ -77,14 +103,30 @@ export class ContextCompactor {
                     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 {
+                logger.info("[Compaction] Stage 3 (summarize)", {
+                    requestId,
+                    ran: false,
+                    tokensBefore: stageTokensBefore,
+                    tokensAfter: stageTokensBefore,
+                    saved: 0,
+                });
                 // Summarization failed, fall through to truncation
             }
         }
         // 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,
             });
@@ -92,8 +134,24 @@ export class ContextCompactor {
                 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() - compactionStartTime,
+        });
         return {
             compacted: stagesUsed.length > 0,
             stagesUsed,

package/dist/lib/context/summarizationEngine.d.ts

@@ -18,7 +18,7 @@ export declare class SummarizationEngine {
      * @param logPrefix - Prefix for log messages
      * @returns True if summarization was performed
      */
-    checkAndSummarize(session: SessionMemory, threshold: number, config: Partial<ConversationMemoryConfig>, logPrefix?: string): Promise<boolean>;
+    checkAndSummarize(session: SessionMemory, threshold: number, config: Partial<ConversationMemoryConfig>, logPrefix?: string, requestId?: string): Promise<boolean>;
     /**
      * Perform token-based summarization on a session.
      * Uses pointer-based, non-destructive approach.
@@ -27,7 +27,7 @@ export declare class SummarizationEngine {
      * @param config - Conversation memory configuration (partial allowed)
      * @param logPrefix - Prefix for log messages
      */
-    summarizeSession(session: SessionMemory, threshold: number, config: Partial<ConversationMemoryConfig>, logPrefix?: string): Promise<void>;
+    summarizeSession(session: SessionMemory, threshold: number, config: Partial<ConversationMemoryConfig>, logPrefix?: string, requestId?: string): Promise<void>;
     /**
      * Estimate total tokens for a message array.
      * @param messages - Array of chat messages

package/dist/lib/context/summarizationEngine.js

@@ -21,19 +21,20 @@ export class SummarizationEngine {
      * @param logPrefix - Prefix for log messages
      * @returns True if summarization was performed
      */
-    async checkAndSummarize(session, threshold, config, logPrefix = "[SummarizationEngine]") {
-        const contextMessages = buildContextFromPointer(session);
+    async checkAndSummarize(session, threshold, config, logPrefix = "[SummarizationEngine]", requestId) {
+        const contextMessages = buildContextFromPointer(session, requestId);
         const tokenCount = this.estimateTokens(contextMessages);
         session.lastTokenCount = tokenCount;
         session.lastCountedAt = Date.now();
-        logger.debug(`${logPrefix} Token count check`, {
+        logger.info("[Summarization] Check", {
+            requestId,
             sessionId: session.sessionId,
             tokenCount,
             threshold,
-            needsSummarization: tokenCount >= threshold,
+            willSummarize: tokenCount >= threshold,
         });
         if (tokenCount >= threshold) {
-            await this.summarizeSession(session, threshold, config, logPrefix);
+            await this.summarizeSession(session, threshold, config, logPrefix, requestId);
             return true;
         }
         return false;
@@ -46,7 +47,8 @@ export class SummarizationEngine {
      * @param config - Conversation memory configuration (partial allowed)
      * @param logPrefix - Prefix for log messages
      */
-    async summarizeSession(session, threshold, config, logPrefix = "[SummarizationEngine]") {
+    async summarizeSession(session, threshold, config, logPrefix = "[SummarizationEngine]", requestId) {
+        const startTime = Date.now();
         const startIndex = session.summarizedUpToMessageId
             ? session.messages.findIndex((m) => m.id === session.summarizedUpToMessageId) + 1
             : 0;
@@ -60,21 +62,45 @@ export class SummarizationEngine {
         if (messagesToSummarize.length === 0) {
             return;
         }
-        const summary = await generateSummary(messagesToSummarize, config, logPrefix, session.summarizedMessage);
-        if (!summary) {
-            logger.warn(`${logPrefix} Summary generation failed`, {
+        const recentToKeep = recentMessages.length - messagesToSummarize.length;
+        logger.info("[Summarization] Starting", {
+            requestId,
+            sessionId: session.sessionId,
+            messagesToSummarize: messagesToSummarize.length,
+            recentToKeep,
+            hasPreviousSummary: !!session.summarizedMessage,
+        });
+        try {
+            const summary = await generateSummary(messagesToSummarize, config, logPrefix, session.summarizedMessage, requestId);
+            if (!summary) {
+                logger.warn(`${logPrefix} Summary generation failed`, {
+                    requestId,
+                    sessionId: session.sessionId,
+                    durationMs: Date.now() - startTime,
+                });
+                return;
+            }
+            const lastSummarized = messagesToSummarize[messagesToSummarize.length - 1];
+            session.summarizedUpToMessageId = lastSummarized.id;
+            session.summarizedMessage = summary;
+            logger.info("[Summarization] Complete", {
+                requestId,
                 sessionId: session.sessionId,
+                summaryChars: summary.length,
+                newPointerId: lastSummarized.id,
+                durationMs: Date.now() - startTime,
             });
-            return;
         }
-        const lastSummarized = messagesToSummarize[messagesToSummarize.length - 1];
-        session.summarizedUpToMessageId = lastSummarized.id;
-        session.summarizedMessage = summary;
-        logger.info(`${logPrefix} Summarization complete`, {
-            sessionId: session.sessionId,
-            summarizedCount: messagesToSummarize.length,
-            totalMessages: session.messages.length,
-        });
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            logger.error("[Summarization] Error", {
+                requestId,
+                sessionId: session.sessionId,
+                error: errorMessage,
+                durationMs: Date.now() - startTime,
+            });
+            throw err;
+        }
     }
     /**
      * Estimate total tokens for a message array.

package/dist/lib/context/toolOutputLimits.d.ts

@@ -1,17 +1,26 @@
 /**
- * Tool Output Size Limits
- *
- * Truncates tool outputs exceeding size limits.
- * Can save full output to disk with a pointer.
- * Modeled on OpenCode's approach.
+ * Tool output preview generation.
+ * Generates head/tail previews of large tool outputs for context-efficient LLM calls.
+ * @module
  */
-/** Maximum tool output size in bytes (50KB) */
-export declare const MAX_TOOL_OUTPUT_BYTES: number;
-/** Maximum tool output lines */
-export declare const MAX_TOOL_OUTPUT_LINES = 2000;
-import type { TruncateOptions, TruncateResult } from "../types/contextTypes.js";
-export type { TruncateOptions, TruncateResult } from "../types/contextTypes.js";
+import type { ToolOutputPreviewOptions, ToolOutputPreviewResult } from "../types/contextTypes.js";
+export type { ToolOutputPreviewOptions, ToolOutputPreviewResult, } from "../types/contextTypes.js";
+/** Default maximum preview size in bytes (50KB) */
+export declare const DEFAULT_MAX_PREVIEW_BYTES: number;
+/** Default maximum preview lines */
+export declare const DEFAULT_MAX_PREVIEW_LINES = 2000;
+/** Default head ratio (25% of preview budget) */
+export declare const DEFAULT_HEAD_RATIO = 0.25;
+/** Tool name referenced in truncation notices for on-demand full-output access */
+export declare const RETRIEVE_CONTEXT_TOOL_NAME = "retrieve_context";
+/** Default tail ratio (75% of preview budget) */
+export declare const DEFAULT_TAIL_RATIO = 0.75;
 /**
- * Truncate tool output if it exceeds size limits.
+ * Generate a head/tail preview of a tool output string.
+ * If the output is within limits, returns it unchanged with truncated: false.
+ * If over limits, keeps the first 25% and last 75% with an omission notice.
+ *
+ * Industry pattern: 25/75 head/tail split. Head captures schema/headers/structure,
+ * tail captures the most recent and typically most relevant data.
  */
-export declare function truncateToolOutput(output: string, options?: TruncateOptions): TruncateResult;
+export declare function generateToolOutputPreview(output: string, options?: ToolOutputPreviewOptions): ToolOutputPreviewResult;

package/dist/lib/context/toolOutputLimits.js

@@ -1,84 +1,78 @@
 /**
- * Tool Output Size Limits
- *
- * Truncates tool outputs exceeding size limits.
- * Can save full output to disk with a pointer.
- * Modeled on OpenCode's approach.
+ * Tool output preview generation.
+ * Generates head/tail previews of large tool outputs for context-efficient LLM calls.
+ * @module
  */
-import { writeFileSync, mkdirSync } from "fs";
-import { join } from "path";
-import { randomUUID } from "crypto";
-import { tmpdir } from "os";
-/** Maximum tool output size in bytes (50KB) */
-export const MAX_TOOL_OUTPUT_BYTES = 50 * 1024;
-/** Maximum tool output lines */
-export const MAX_TOOL_OUTPUT_LINES = 2_000;
+/** Default maximum preview size in bytes (50KB) */
+export const DEFAULT_MAX_PREVIEW_BYTES = 50 * 1024;
+/** Default maximum preview lines */
+export const DEFAULT_MAX_PREVIEW_LINES = 2_000;
+/** Default head ratio (25% of preview budget) */
+export const DEFAULT_HEAD_RATIO = 0.25;
+/** Tool name referenced in truncation notices for on-demand full-output access */
+export const RETRIEVE_CONTEXT_TOOL_NAME = "retrieve_context";
+/** Default tail ratio (75% of preview budget) */
+export const DEFAULT_TAIL_RATIO = 0.75;
 /**
- * Truncate tool output if it exceeds size limits.
+ * Generate a head/tail preview of a tool output string.
+ * If the output is within limits, returns it unchanged with truncated: false.
+ * If over limits, keeps the first 25% and last 75% with an omission notice.
+ *
+ * Industry pattern: 25/75 head/tail split. Head captures schema/headers/structure,
+ * tail captures the most recent and typically most relevant data.
  */
-export function truncateToolOutput(output, options) {
-    const maxBytes = options?.maxBytes ?? MAX_TOOL_OUTPUT_BYTES;
-    const maxLines = options?.maxLines ?? MAX_TOOL_OUTPUT_LINES;
-    const direction = options?.direction ?? "tail";
-    const saveToDisk = options?.saveToDisk ?? false;
+export function generateToolOutputPreview(output, options) {
+    const maxBytes = options?.maxBytes ?? DEFAULT_MAX_PREVIEW_BYTES;
+    const maxLines = options?.maxLines ?? DEFAULT_MAX_PREVIEW_LINES;
+    const rawHeadRatio = options?.headRatio ?? DEFAULT_HEAD_RATIO;
+    const rawTailRatio = options?.tailRatio ?? DEFAULT_TAIL_RATIO;
+    // Clamp ratios to valid range to avoid negative omittedBytes
+    const headRatio = Math.max(0, Math.min(1, rawHeadRatio));
+    const tailRatio = Math.max(0, Math.min(1, rawTailRatio));
     const originalSize = Buffer.byteLength(output, "utf-8");
-    // Check byte limit
-    const exceedsBytes = originalSize > maxBytes;
-    // Check line limit
     const lines = output.split("\n");
+    const exceedsBytes = originalSize > maxBytes;
     const exceedsLines = lines.length > maxLines;
     if (!exceedsBytes && !exceedsLines) {
-        return { content: output, truncated: false, originalSize };
+        return { preview: output, truncated: false, originalSize };
     }
-    // Save to disk if requested
-    let savedPath;
-    if (saveToDisk) {
-        try {
-            const saveDir = options?.saveDir ?? join(tmpdir(), "neurolink-tool-output");
-            mkdirSync(saveDir, { recursive: true });
-            savedPath = join(saveDir, `tool-output-${randomUUID()}.txt`);
-            writeFileSync(savedPath, output, "utf-8");
-        }
-        catch {
-            // Silently fail disk save
-        }
-    }
-    // Apply truncation
-    let truncated;
+    // Line-based split
+    const headLineCount = Math.max(1, Math.floor(maxLines * headRatio));
+    const tailLineCount = Math.max(1, maxLines - headLineCount);
+    let head;
+    let tail;
     if (exceedsLines) {
-        if (direction === "head") {
-            truncated = lines.slice(0, maxLines).join("\n");
-        }
-        else {
-            truncated = lines.slice(-maxLines).join("\n");
-        }
+        head = lines.slice(0, headLineCount).join("\n");
+        tail = lines.slice(-tailLineCount).join("\n");
     }
     else {
-        truncated = output;
-    }
-    // Apply byte limit
-    if (Buffer.byteLength(truncated, "utf-8") > maxBytes) {
-        if (direction === "head") {
-            truncated = truncated.slice(0, maxBytes);
-        }
-        else {
-            truncated = truncated.slice(-maxBytes);
-        }
+        head = lines
+            .slice(0, Math.max(1, Math.floor(lines.length * headRatio)))
+            .join("\n");
+        tail = lines
+            .slice(-Math.max(1, Math.ceil(lines.length * tailRatio)))
+            .join("\n");
     }
-    // Add truncation notice
-    const notice = savedPath
-        ? `\n\n[Output truncated from ${originalSize} bytes to ${Buffer.byteLength(truncated, "utf-8")} bytes. Full output saved to: ${savedPath}]`
-        : `\n\n[Output truncated from ${originalSize} bytes to ${Buffer.byteLength(truncated, "utf-8")} bytes]`;
-    if (direction === "head") {
-        truncated = truncated + notice;
+    // Byte-based cap on each portion
+    const headMaxBytes = Math.floor(maxBytes * headRatio);
+    const tailMaxBytes = maxBytes - headMaxBytes;
+    if (Buffer.byteLength(head, "utf-8") > headMaxBytes) {
+        head = Buffer.from(head, "utf-8")
+            .subarray(0, headMaxBytes)
+            .toString("utf-8");
     }
-    else {
-        truncated = notice + "\n" + truncated;
+    if (Buffer.byteLength(tail, "utf-8") > tailMaxBytes) {
+        const tailBuf = Buffer.from(tail, "utf-8");
+        tail = tailBuf.subarray(tailBuf.length - tailMaxBytes).toString("utf-8");
     }
+    const omittedBytes = Math.max(0, originalSize -
+        Buffer.byteLength(head, "utf-8") -
+        Buffer.byteLength(tail, "utf-8"));
+    const notice = `\n\n[... ${omittedBytes} bytes omitted. ` +
+        `Use ${RETRIEVE_CONTEXT_TOOL_NAME} tool to access full output ...]\n\n`;
     return {
-        content: truncated,
+        preview: head + notice + tail,
         truncated: true,
-        savedPath,
         originalSize,
     };
 }

package/dist/lib/core/baseProvider.d.ts

@@ -218,9 +218,18 @@ export declare abstract class BaseProvider implements AIProvider {
      */
     setSessionContext(sessionId?: string, userId?: string): void;
     /**
-     * Provider-specific error handling
+     * Provider-specific error formatting.
+     * Subclasses implement this to produce human-readable error messages
+     * (e.g., "❌ Google Vertex AI Provider Error\n\n...").
      */
-    protected abstract handleProviderError(error: unknown): Error;
+    protected abstract formatProviderError(error: unknown): Error;
+    /**
+     * Handle provider errors with abort passthrough.
+     * AbortErrors are never wrapped — they must propagate with their
+     * original identity so that isAbortError() can detect them in
+     * retry/fallback loops (directProviderGeneration, performMCPGenerationRetries).
+     */
+    protected handleProviderError(error: unknown): Error;
     /**
      * Image generation method. Providers that support it should override this.
      * By default, it throws an error indicating that the functionality is not supported.

package/dist/lib/core/baseProvider.js

@@ -174,7 +174,7 @@ export class BaseProvider {
                 temperature: options.temperature,
                 maxTokens: options.maxTokens,
                 tools: options.tools, // 🔧 FIX: Pass user-provided tools (including RAG tools) to generation pipeline
-                disableTools: false,
+                disableTools: !!options.disableTools,
                 maxSteps: options.maxSteps || 5,
                 provider: options.provider,
                 model: options.model,
@@ -767,6 +767,21 @@ export class BaseProvider {
         this.userId = userId;
         this.toolsManager.setSessionContext(sessionId, userId);
     }
+    /**
+     * Handle provider errors with abort passthrough.
+     * AbortErrors are never wrapped — they must propagate with their
+     * original identity so that isAbortError() can detect them in
+     * retry/fallback loops (directProviderGeneration, performMCPGenerationRetries).
+     */
+    handleProviderError(error) {
+        if (isAbortError(error)) {
+            // Preserve AbortError identity — never wrap in provider-specific formatting
+            return error instanceof Error
+                ? error
+                : new DOMException("The operation was aborted", "AbortError");
+        }
+        return this.formatProviderError(error);
+    }
     /**
      * Image generation method. Providers that support it should override this.
      * By default, it throws an error indicating that the functionality is not supported.

package/dist/lib/core/conversationMemoryManager.d.ts

@@ -50,7 +50,7 @@ export declare class ConversationMemoryManager implements IConversationMemoryMan
      * Returns messages from pointer onwards (or all if no pointer)
      * Now consistently async to match Redis implementation
      */
-    buildContextMessages(sessionId: string): Promise<ChatMessage[]>;
+    buildContextMessages(sessionId: string, _userId?: string, _enableSummarization?: boolean, requestId?: string): Promise<ChatMessage[]>;
     getSession(sessionId: string, _userId?: string): SessionMemory | undefined;
     createSummarySystemMessage(content: string, summarizesFrom?: string, summarizesTo?: string): ChatMessage;
     private ensureInitialized;
@@ -59,4 +59,16 @@ export declare class ConversationMemoryManager implements IConversationMemoryMan
     getStats(): Promise<ConversationMemoryStats>;
     clearSession(sessionId: string): Promise<boolean>;
     clearAllSessions(): Promise<void>;
+    /**
+     * Get the raw messages array for a session.
+     * Returns the full messages list without context filtering or summarization.
+     * Returns a deep copy to prevent external mutation of internal state.
+     */
+    getSessionMessages(sessionId: string, _userId?: string): Promise<ChatMessage[]>;
+    /**
+     * Replace the entire messages array for a session.
+     * Creates the session if it does not exist.
+     * Resets summary pointers since old pointers may reference messages that no longer exist.
+     */
+    setSessionMessages(sessionId: string, messages: ChatMessage[], userId?: string): Promise<void>;
 }