@juspay/neurolink 9.25.2 → 9.26.0

package/dist/lib/agent/directTools.js

@@ -6,9 +6,18 @@ import { tool } from "ai";
 import { z } from "zod";
 import * as fs from "fs";
 import * as path from "path";
+import { execFile } from "child_process";
 import { logger } from "../utils/logger.js";
 import { VertexAI } from "@google-cloud/vertexai";
 import { CSVProcessor } from "../utils/csvProcessor.js";
+import { shouldEnableBashTool } from "../utils/toolUtils.js";
+const MAX_OUTPUT_BYTES = 102400; // 100KB
+function truncateOutput(output) {
+    if (output.length > MAX_OUTPUT_BYTES) {
+        return (output.slice(0, MAX_OUTPUT_BYTES) + "\n... [output truncated at 100KB]");
+    }
+    return output;
+}
 // Runtime Google Search tool creation - bypasses TypeScript strict typing
 function createGoogleSearchTools() {
     const searchTool = {};
@@ -534,6 +543,9 @@ export const directAgentTools = {
             }
         },
     }),
+    // NOTE: executeBashCommand was moved to a separate opt-in export (bashTool) for security.
+    // It is only included in directAgentTools when NEUROLINK_ENABLE_BASH_TOOL=true or
+    // toolConfig.enableBashTool is explicitly set to true. See shouldEnableBashTool() in toolUtils.ts.
     websearchGrounding: tool({
         description: "Search the web for current information using Google Search grounding. Returns raw search data for AI processing.",
         parameters: z.object({
@@ -657,6 +669,116 @@ export const directAgentTools = {
         },
     }),
 };
+/**
+ * Bash command execution tool - exported separately for opt-in use.
+ *
+ * SECURITY: This tool is NOT included in directAgentTools by default.
+ * It must be explicitly enabled via:
+ *   - Environment variable: NEUROLINK_ENABLE_BASH_TOOL=true
+ *   - Config: toolConfig.enableBashTool = true
+ *
+ * Import this directly when you need bash execution capabilities:
+ *   import { bashTool } from '../agent/directTools.js';
+ */
+export const bashTool = tool({
+    description: "Execute a bash/shell command and return stdout, stderr, and exit code. Supports full shell syntax including pipes, redirects, and variable expansion. Requires HITL confirmation when enabled.",
+    parameters: z.object({
+        command: z
+            .string()
+            .describe("The shell command to execute (supports pipes, redirects, etc.)"),
+        timeout: z
+            .number()
+            .optional()
+            .default(30000)
+            .describe("Timeout in milliseconds (default: 30000, max: 120000)"),
+        cwd: z
+            .string()
+            .optional()
+            .describe("Working directory (defaults to process.cwd())"),
+    }),
+    execute: async ({ command, timeout = 30000, cwd }) => {
+        try {
+            const effectiveTimeout = Math.min(Math.max(timeout, 100), 120000);
+            const resolvedCwd = cwd ? path.resolve(cwd) : process.cwd();
+            const currentCwd = process.cwd();
+            // Verify cwd exists before resolving symlinks
+            if (!fs.existsSync(resolvedCwd) ||
+                !fs.statSync(resolvedCwd).isDirectory()) {
+                return {
+                    success: false,
+                    code: -1,
+                    stdout: "",
+                    stderr: "",
+                    error: `Directory does not exist: ${resolvedCwd}`,
+                };
+            }
+            // Security: resolve symlinks and prevent execution outside current directory
+            try {
+                const realCwd = fs.realpathSync(currentCwd);
+                const realResolvedCwd = fs.realpathSync(resolvedCwd);
+                if (!realResolvedCwd.startsWith(realCwd)) {
+                    return {
+                        success: false,
+                        code: -1,
+                        stdout: "",
+                        stderr: "",
+                        error: "Access denied: Cannot execute commands outside current directory",
+                    };
+                }
+            }
+            catch {
+                return {
+                    success: false,
+                    code: -1,
+                    stdout: "",
+                    stderr: "",
+                    error: "Access denied: Cannot resolve directory path",
+                };
+            }
+            // Use /bin/bash -c to support full shell syntax (pipes, redirects, etc.)
+            return await new Promise((resolve) => {
+                execFile("/bin/bash", ["-c", command], {
+                    timeout: effectiveTimeout,
+                    cwd: resolvedCwd,
+                    maxBuffer: MAX_OUTPUT_BYTES,
+                }, (error, stdout, stderr) => {
+                    if (error) {
+                        const exitCode = typeof error.code === "number" ? error.code : 1;
+                        resolve({
+                            success: false,
+                            code: exitCode,
+                            stdout: truncateOutput(stdout || ""),
+                            stderr: truncateOutput(stderr || error.message),
+                            error: error.killed ? "Command timed out" : error.message,
+                        });
+                    }
+                    else {
+                        resolve({
+                            success: true,
+                            code: 0,
+                            stdout: truncateOutput(stdout),
+                            stderr: truncateOutput(stderr),
+                        });
+                    }
+                });
+            });
+        }
+        catch (error) {
+            return {
+                success: false,
+                code: -1,
+                stdout: "",
+                stderr: "",
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    },
+});
+// Conditionally inject executeBashCommand into directAgentTools when opted in.
+// This ensures the tool is only available to SDK consumers who explicitly enable it.
+if (shouldEnableBashTool()) {
+    directAgentTools.executeBashCommand = bashTool;
+}
 // eslint-disable-next-line no-redeclare
 export function getToolsForCategory(category = "all") {
     switch (category) {

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

@@ -10,8 +10,7 @@
  */
 import type { ChatMessage, ConversationMemoryConfig } from "../types/conversation.js";
 import type { CompactionResult, CompactionConfig } from "../types/contextTypes.js";
-export type { CompactionResult, CompactionConfig, } from "../types/contextTypes.js";
-export type CompactionStage = "prune" | "deduplicate" | "summarize" | "truncate";
+export type { CompactionConfig, CompactionResult, CompactionStage, } from "../types/contextTypes.js";
 export declare class ContextCompactor {
     private config;
     constructor(config?: CompactionConfig);

package/dist/lib/context/contextCompactor.js

@@ -15,8 +15,8 @@ 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 { summarizeMessages } from "./stages/structuredSummarizer.js";
 import { truncateWithSlidingWindow } from "./stages/slidingWindowTruncator.js";
+import { summarizeMessages } from "./stages/structuredSummarizer.js";
 const DEFAULT_CONFIG = {
     enablePrune: true,
     enableDeduplicate: true,
@@ -106,6 +106,7 @@ export class ContextCompactor {
                         model: this.config.summarizationModel,
                         keepRecentRatio: this.config.keepRecentRatio,
                         memoryConfig,
+                        targetTokens,
                     }), 120_000, "LLM summarization timed out after 120s");
                     if (summarizeResult.summarized) {
                         currentMessages = summarizeResult.messages;
@@ -146,6 +147,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/lib/context/prompts/summarizationPrompt.d.ts

@@ -1,12 +1,12 @@
 /**
  * Summarization Prompt Builder
  *
- * Builds prompts for summarizing conversation context into a 9-section structure.
+ * Builds prompts for summarizing conversation context into a 10-section structure.
  * Supports both initial summarization and incremental merging with existing summaries.
  */
 import type { SummarizationPromptOptions } from "../../types/contextTypes.js";
 export type { SummarizationPromptOptions } from "../../types/contextTypes.js";
-declare const NINE_SECTIONS: string[];
+declare const SUMMARY_SECTIONS: string[];
 /**
  * Builds a summarization prompt based on the provided options.
  *
@@ -14,4 +14,4 @@ declare const NINE_SECTIONS: string[];
  * @returns The constructed prompt string
  */
 export declare function buildSummarizationPrompt(options: SummarizationPromptOptions): string;
-export { NINE_SECTIONS };
+export { SUMMARY_SECTIONS };

package/dist/lib/context/prompts/summarizationPrompt.js

@@ -1,10 +1,10 @@
 /**
  * Summarization Prompt Builder
  *
- * Builds prompts for summarizing conversation context into a 9-section structure.
+ * Builds prompts for summarizing conversation context into a 10-section structure.
  * Supports both initial summarization and incremental merging with existing summaries.
  */
-const NINE_SECTIONS = [
+const SUMMARY_SECTIONS = [
     "Primary Request and Intent",
     "Key Technical Concepts",
     "Files and Code Sections",
@@ -14,6 +14,7 @@ const NINE_SECTIONS = [
     "Current Work",
     "Next Step",
     "Required Files",
+    "Constraints and Established Rules",
 ];
 function buildFileContextSection(filesRead, filesModified) {
     const hasFiles = (filesRead && filesRead.length > 0) ||
@@ -38,7 +39,7 @@ function buildFileContextSection(filesRead, filesModified) {
 }
 function buildInitialPrompt(options) {
     const fileContext = buildFileContextSection(options.filesRead, options.filesModified);
-    return `You are a context summarization assistant. Your task is to analyze the conversation and create a structured summary following a 9-section format.
+    return `You are a context summarization assistant. Your task is to analyze the conversation and create a structured summary following a 10-section format.
 
 Create a summary with the following sections:
 
@@ -67,7 +68,12 @@ What is being actively worked on right now?
 What is the immediate next action to take?
 
 ### 9. Required Files
-What files will need to be accessed or modified to continue?${fileContext}
+What files will need to be accessed or modified to continue?
+
+### 10. Constraints and Established Rules
+What user-imposed constraints, behavioral directives, coding standards, agreed-upon decisions, or established rules must persist across the conversation? Include any "always do X", "never do Y", naming conventions, architectural patterns, or preferences the user has stated.${fileContext}
+
+IMPORTANT: Section 10 (Constraints and Established Rules) must ALWAYS be preserved in full. User constraints and established agreements are never "no longer relevant" — they remain in effect for the entire session unless the user explicitly revokes them.
 
 Analyze the conversation thoroughly and fill in each section with relevant information. If a section is not applicable, write "N/A" for that section.`;
 }
@@ -80,18 +86,19 @@ Existing Summary:
 ${options.previousSummary}
 ---
 
-Update sections with new information while preserving important context from the existing summary. Maintain the same 9-section structure.
+Update sections with new information while preserving important context from the existing summary. Maintain the same 10-section structure.
 
 Instructions:
 1. Review the existing summary above
 2. Analyze the new conversation content
 3. MERGE the new information into the appropriate sections
 4. Update sections with relevant new information
-5. Remove information that is no longer relevant
+5. Remove information that is no longer relevant EXCEPT for Section 10 (Constraints and Established Rules) — user constraints and established agreements must ALWAYS be preserved unless the user explicitly revoked them
 6. Keep the summary concise but comprehensive
-7. Maintain the 9-section format${fileContext}
+7. Maintain the 10-section format
+8. Always carry forward ALL entries from Section 10 of the existing summary, adding any new constraints found in the new content${fileContext}
 
-Output the updated summary following the same 9-section structure.`;
+Output the updated summary following the same 10-section structure.`;
 }
 /**
  * Builds a summarization prompt based on the provided options.
@@ -107,5 +114,5 @@ export function buildSummarizationPrompt(options) {
     }
     return buildInitialPrompt(options);
 }
-export { NINE_SECTIONS };
+export { SUMMARY_SECTIONS };
 //# sourceMappingURL=summarizationPrompt.js.map

package/dist/lib/context/stages/structuredSummarizer.d.ts

@@ -1,10 +1,10 @@
 /**
  * Stage 3: Structured LLM Summarization
  *
- * Uses the structured 9-section prompt to summarize older messages
+ * Uses the structured 10-section prompt to summarize older messages
  * while preserving recent ones.
  */
-import type { ChatMessage } from "../../types/conversation.js";
 import type { SummarizeConfig, SummarizeResult } from "../../types/contextTypes.js";
+import type { ChatMessage } from "../../types/conversation.js";
 export type { SummarizeConfig, SummarizeResult, } from "../../types/contextTypes.js";
 export declare function summarizeMessages(messages: ChatMessage[], config?: SummarizeConfig): Promise<SummarizeResult>;

package/dist/lib/context/stages/structuredSummarizer.js

@@ -1,19 +1,59 @@
 /**
  * Stage 3: Structured LLM Summarization
  *
- * Uses the structured 9-section prompt to summarize older messages
+ * Uses the structured 10-section prompt to summarize older messages
  * while preserving recent ones.
  */
-import { generateSummary } from "../../utils/conversationMemory.js";
 import { randomUUID } from "crypto";
+import { generateSummary } from "../../utils/conversationMemory.js";
+import { estimateTokens } from "../../utils/tokenEstimation.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * Find the split index using token counting — walk backward from the end,
+ * accumulating token counts until we've reserved `targetRecentTokens` worth
+ * of recent content. Everything before the split index gets summarized.
+ */
+function findSplitIndexByTokens(messages, targetRecentTokens, provider) {
+    let recentTokens = 0;
+    let splitIndex = messages.length;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const content = typeof messages[i].content === "string"
+            ? messages[i].content
+            : JSON.stringify(messages[i].content);
+        const msgTokens = estimateTokens(content, provider);
+        if (recentTokens + msgTokens > targetRecentTokens) {
+            splitIndex = i + 1;
+            break;
+        }
+        recentTokens += msgTokens;
+    }
+    // Ensure at least one message is summarized
+    return Math.max(1, splitIndex);
+}
 export async function summarizeMessages(messages, config) {
     const keepRecentRatio = config?.keepRecentRatio ?? 0.3;
     if (messages.length <= 4) {
         return { summarized: false, messages };
     }
-    // Keep the most recent messages unsummarized
-    const keepCount = Math.max(4, Math.ceil(messages.length * keepRecentRatio));
-    const splitIndex = messages.length - keepCount;
+    // Determine split point: prefer token-based when a target budget is available,
+    // fall back to message-count-based split for backward compatibility.
+    let splitIndex;
+    if (config?.targetTokens && config.targetTokens > 0) {
+        // Keep `keepRecentRatio` fraction of the target budget as recent context
+        const targetRecentTokens = Math.floor(config.targetTokens * keepRecentRatio);
+        // NOTE: config.provider is the summarization provider, not the generation
+        // provider. Ideally we'd use the generation/budget provider for accurate
+        // token estimation, but SummarizeConfig doesn't carry a separate
+        // budgetProvider field. This is a known design limitation.
+        splitIndex = findSplitIndexByTokens(messages, targetRecentTokens, config.provider);
+    }
+    else {
+        // Legacy: message-count-based split
+        const keepCount = Math.max(4, Math.ceil(messages.length * keepRecentRatio));
+        splitIndex = messages.length - keepCount;
+    }
+    // Clamp so at least the last message is always preserved (never summarize everything)
+    splitIndex = Math.min(splitIndex, messages.length - 1);
     if (splitIndex <= 0) {
         return { summarized: false, messages };
     }
@@ -21,30 +61,40 @@ export async function summarizeMessages(messages, config) {
     const recentMessages = messages.slice(splitIndex);
     // Find previous summary if exists
     const previousSummary = messagesToSummarize.find((m) => m.metadata?.isSummary)?.content;
-    // Use memory config for summarization if available
-    if (config?.memoryConfig) {
-        const summaryText = await generateSummary(messagesToSummarize, config.memoryConfig, "[ContextCompactor]", previousSummary);
-        if (!summaryText) {
-            return { summarized: false, messages };
-        }
-        const summaryMessage = {
-            id: `summary-${randomUUID()}`,
-            role: "user",
-            content: `[Previous conversation summary]:\n\n${summaryText}`,
-            timestamp: new Date().toISOString(),
-            metadata: {
-                isSummary: true,
-                summarizesFrom: messagesToSummarize[0]?.id,
-                summarizesTo: messagesToSummarize[messagesToSummarize.length - 1]?.id,
-            },
-        };
-        return {
-            summarized: true,
-            messages: [summaryMessage, ...recentMessages],
-            summaryText,
-        };
-    }
-    // Without memory config, we can't call LLM
-    return { summarized: false, messages };
+    // Build effective memory config: use provided memoryConfig, or construct from provider/model
+    const effectiveMemoryConfig = config?.memoryConfig ? { ...config.memoryConfig } : {};
+    // Fill in summarization provider/model from compactor config if not already set
+    if (!effectiveMemoryConfig.summarizationProvider && config?.provider) {
+        effectiveMemoryConfig.summarizationProvider = config.provider;
+    }
+    if (!effectiveMemoryConfig.summarizationModel && config?.model) {
+        effectiveMemoryConfig.summarizationModel = config.model;
+    }
+    // Only skip if there's genuinely no provider available
+    if (!effectiveMemoryConfig.summarizationProvider &&
+        !effectiveMemoryConfig.summarizationModel) {
+        logger.debug("[ContextCompactor] Stage 3 skipped: no summarization provider or model available");
+        return { summarized: false, messages };
+    }
+    const summaryText = await generateSummary(messagesToSummarize, effectiveMemoryConfig, "[ContextCompactor]", previousSummary);
+    if (!summaryText) {
+        return { summarized: false, messages };
+    }
+    const summaryMessage = {
+        id: `summary-${randomUUID()}`,
+        role: "user",
+        content: `[Previous conversation summary]:\n\n${summaryText}`,
+        timestamp: new Date().toISOString(),
+        metadata: {
+            isSummary: true,
+            summarizesFrom: messagesToSummarize[0]?.id,
+            summarizesTo: messagesToSummarize[messagesToSummarize.length - 1]?.id,
+        },
+    };
+    return {
+        summarized: true,
+        messages: [summaryMessage, ...recentMessages],
+        summaryText,
+    };
 }
 //# sourceMappingURL=structuredSummarizer.js.map

package/dist/lib/mcp/servers/agent/directToolsServer.js

@@ -143,6 +143,8 @@ function getToolCategory(toolName) {
             return "filesystem";
         case "websearchGrounding":
             return "search";
+        case "executeBashCommand":
+            return "system";
         default:
             return "utility";
     }

package/dist/lib/mcp/toolRegistry.d.ts

@@ -103,6 +103,14 @@ export declare class MCPToolRegistry extends MCPRegistry {
      * Get tools by category
      */
     getToolsByCategory(category: string): ToolInfo[];
+    /**
+     * NL-001: Get available tools, filtering out those with OPEN circuit breakers.
+     * Returns both the filtered tools and the list of unavailable tool names.
+     */
+    getAvailableTools(circuitBreakers: Map<string, import("../utils/errorHandling.js").CircuitBreaker>): {
+        tools: ToolInfo[];
+        unavailableTools: string[];
+    };
     /**
      * Check if tool exists
      */

package/dist/lib/mcp/toolRegistry.js

@@ -565,6 +565,26 @@ export class MCPToolRegistry extends MCPRegistry {
         }
         return Array.from(uniqueTools.values());
     }
+    /**
+     * NL-001: Get available tools, filtering out those with OPEN circuit breakers.
+     * Returns both the filtered tools and the list of unavailable tool names.
+     */
+    getAvailableTools(circuitBreakers) {
+        const allTools = Array.from(this.tools.values());
+        const unavailableTools = [];
+        const tools = [];
+        for (const tool of allTools) {
+            const breakerKey = `${tool.serverId || "unknown"}.${tool.name}`;
+            const breaker = circuitBreakers.get(breakerKey);
+            if (breaker && breaker.getState() === "open") {
+                unavailableTools.push(tool.name);
+            }
+            else {
+                tools.push(tool);
+            }
+        }
+        return { tools, unavailableTools };
+    }
     /**
      * Check if tool exists
      */

package/dist/lib/neurolink.d.ts

@@ -32,6 +32,10 @@ export declare class NeuroLink {
     private externalServerManager;
     private toolCache;
     private readonly toolCacheDuration;
+    private modelAliasConfig?;
+    private lastCompactionMessageCount;
+    /** Extract sessionId from options context for compaction watermark keying */
+    private getCompactionSessionId;
     private toolCircuitBreakers;
     private toolExecutionMetrics;
     private currentStreamToolExecutions;
@@ -1140,6 +1144,12 @@ export declare class NeuroLink {
         averageExecutionTime: number;
         lastExecutionTime: number;
     }>;
+    /**
+     * NL-004: Set model alias/deprecation configuration.
+     * Models in the alias map will be warned, redirected, or blocked based on their action.
+     * @param config - Model alias configuration with aliases map
+     */
+    setModelAliasConfig(config: import("./types/generateTypes.js").ModelAliasConfig): void;
     /**
      * Get circuit breaker status for all tools
      * @returns Object with circuit breaker status for each tool