@juspay/neurolink 9.25.1 → 9.26.0

package/dist/providers/googleAiStudio.js

@@ -1,17 +1,17 @@
 import { createGoogleGenerativeAI } from "@ai-sdk/google";
 import { embed, embedMany, streamText, } from "ai";
 import { ErrorCategory, ErrorSeverity, GoogleAIModels, } from "../constants/enums.js";
-import { estimateTokens } from "../utils/tokenEstimation.js";
 import { BaseProvider } from "../core/baseProvider.js";
 import { DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
+import { ATTR, tracers, withClientSpan } from "../telemetry/index.js";
 import { AuthenticationError, NetworkError, ProviderError, RateLimitError, } from "../types/errors.js";
 import { ERROR_CODES, NeuroLinkError } from "../utils/errorHandling.js";
 import { logger } from "../utils/logger.js";
 import { isGemini3Model } from "../utils/modelDetection.js";
-import { tracers, ATTR, withClientSpan } from "../telemetry/index.js";
 import { composeAbortSignals, createTimeoutController, TimeoutError, } from "../utils/timeout.js";
-import { buildNativeToolDeclarations, buildNativeConfig, computeMaxSteps, collectStreamChunks, extractTextFromParts, executeNativeToolCalls, handleMaxStepsTermination, pushModelResponseToHistory, sanitizeToolsForGemini, } from "./googleNativeGemini3.js";
+import { estimateTokens } from "../utils/tokenEstimation.js";
+import { buildNativeConfig, buildNativeToolDeclarations, collectStreamChunks, computeMaxSteps, executeNativeToolCalls, extractTextFromParts, handleMaxStepsTermination, pushModelResponseToHistory, sanitizeToolsForGemini, } from "./googleNativeGemini3.js";
 // Google AI Live API types now imported from ../types/providerSpecific.js
 // Import proper types for multimodal message handling
 // Create Google GenAI client
@@ -626,9 +626,12 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         // Add model response with ALL parts (including thoughtSignature) to history
                         pushModelResponseToHistory(currentContents, chunkResult.rawResponseParts, chunkResult.stepFunctionCalls);
                         const functionResponses = await executeNativeToolCalls("[GoogleAIStudio]", chunkResult.stepFunctionCalls, executeMap, failedTools, allToolCalls, { abortSignal: composedSignal });
-                        // Add function responses to history
+                        // Add function responses to history — the @google/genai SDK
+                        // only accepts "user" and "model" as valid roles in contents.
+                        // Function/tool responses must use role: "user" (matching the
+                        // SDK's own automaticFunctionCalling implementation).
                         currentContents.push({
-                            role: "function",
+                            role: "user",
                             parts: functionResponses,
                         });
                     }
@@ -776,9 +779,12 @@ export class GoogleAIStudioProvider extends BaseProvider {
                         // This is critical for Gemini 3 - it requires thought signatures in subsequent turns
                         pushModelResponseToHistory(currentContents, chunkResult.rawResponseParts, chunkResult.stepFunctionCalls);
                         const functionResponses = await executeNativeToolCalls("[GoogleAIStudio]", chunkResult.stepFunctionCalls, executeMap, failedTools, allToolCalls, { toolExecutions, abortSignal: composedSignal });
-                        // Add function responses to history
+                        // Add function responses to history — the @google/genai SDK
+                        // only accepts "user" and "model" as valid roles in contents.
+                        // Function/tool responses must use role: "user" (matching the
+                        // SDK's own automaticFunctionCalling implementation).
                         currentContents.push({
-                            role: "function",
+                            role: "user",
                             parts: functionResponses,
                         });
                     }

package/dist/server/utils/validation.d.ts

@@ -40,9 +40,9 @@ export declare const AgentExecuteRequestSchema: z.ZodObject<{
     userId?: string | undefined;
     stream?: boolean | undefined;
     sessionId?: string | undefined;
-    temperature?: number | undefined;
     maxTokens?: number | undefined;
     systemPrompt?: string | undefined;
+    temperature?: number | undefined;
     tools?: string[] | undefined;
 }, {
     input: string | {
@@ -55,9 +55,9 @@ export declare const AgentExecuteRequestSchema: z.ZodObject<{
     userId?: string | undefined;
     stream?: boolean | undefined;
     sessionId?: string | undefined;
-    temperature?: number | undefined;
     maxTokens?: number | undefined;
     systemPrompt?: string | undefined;
+    temperature?: number | undefined;
     tools?: string[] | undefined;
 }>;
 /**

package/dist/types/configTypes.d.ts

@@ -27,6 +27,7 @@ export type NeurolinkConstructorConfig = {
     hitl?: HITLConfig;
     toolRegistry?: MCPToolRegistry;
     observability?: ObservabilityConfig;
+    modelAliasConfig?: import("./generateTypes.js").ModelAliasConfig;
 };
 /**
  * Provider-specific configuration
@@ -117,6 +118,8 @@ export type ToolConfig = {
     maxToolsPerProvider?: number;
     /** Whether MCP tools should be enabled */
     enableMCPTools?: boolean;
+    /** Whether the bash command execution tool should be enabled (opt-in, defaults to false) */
+    enableBashTool?: boolean;
 };
 /**
  * Backup metadata information

package/dist/types/contextTypes.d.ts

@@ -2,10 +2,9 @@
  * Context Types for NeuroLink - Factory Pattern Implementation
  * Provides type-safe context integration for AI generation
  */
-import type { JsonObject } from "./common.js";
 import type { ExecutionContext } from "../types/tools.js";
+import type { JsonObject } from "./common.js";
 import type { ChatMessage, ConversationMemoryConfig } from "./conversation.js";
-import type { CompactionStage } from "../context/contextCompactor.js";
 /**
  * Base context type for all AI operations
  */
@@ -173,6 +172,8 @@ export declare class ContextConverter {
     private static inferProvider;
     private static extractCustomData;
 }
+/** Stages available in the compaction pipeline. */
+export type CompactionStage = "prune" | "deduplicate" | "summarize" | "truncate";
 /** Result of multi-stage context compaction. */
 export type CompactionResult = {
     compacted: boolean;
@@ -447,6 +448,8 @@ export type SummarizeConfig = {
     model?: string;
     keepRecentRatio?: number;
     memoryConfig?: Partial<ConversationMemoryConfig>;
+    /** Target token budget — when set, split uses token counting instead of message count */
+    targetTokens?: number;
 };
 /** Result of structured LLM summarization (Stage 3). */
 export type SummarizeResult = {

package/dist/types/contextTypes.js

@@ -155,12 +155,12 @@ export class ContextFactory {
      */
     static processContext(context, config = {}) {
         const startTime = Date.now();
-        const finalConfig = { ...this.DEFAULT_CONFIG, ...config };
+        const finalConfig = { ...ContextFactory.DEFAULT_CONFIG, ...config };
         let processedContext = null;
         const template = "default";
         let truncated = false;
         if (finalConfig.includeInPrompt && finalConfig.mode !== "metadata_only") {
-            processedContext = this.formatContextForPrompt(context, finalConfig);
+            processedContext = ContextFactory.formatContextForPrompt(context, finalConfig);
             // Truncate if necessary
             if (finalConfig.maxLength &&
                 processedContext.length > finalConfig.maxLength) {
@@ -188,13 +188,13 @@ export class ContextFactory {
     static formatContextForPrompt(context, config) {
         switch (config.mode) {
             case "prompt_prefix":
-                return this.formatAsPrefix(context);
+                return ContextFactory.formatAsPrefix(context);
             case "prompt_suffix":
-                return this.formatAsSuffix(context);
+                return ContextFactory.formatAsSuffix(context);
             case "system_prompt":
-                return this.formatForSystemPrompt(context);
+                return ContextFactory.formatForSystemPrompt(context);
             case "structured_prompt":
-                return this.formatStructured(context);
+                return ContextFactory.formatStructured(context);
             case "metadata_only":
             case "none":
             default:
@@ -304,7 +304,7 @@ export class ContextConverter {
                         legacyContext.authToken ||
                         legacyContext.accessToken,
                     endpoint: legacyContext.apiEndpoint || legacyContext.serviceUrl,
-                    provider: this.inferProvider(legacyContext),
+                    provider: ContextConverter.inferProvider(legacyContext),
                 },
                 platformConfig: {
                     type: legacyContext.platformType || "generic",
@@ -328,7 +328,7 @@ export class ContextConverter {
                         }
                         : {}),
                     // Include all additional custom data
-                    ...this.extractCustomData(legacyContext),
+                    ...ContextConverter.extractCustomData(legacyContext),
                 },
             },
             metadata: includeMetadata

package/dist/types/generateTypes.d.ts

@@ -548,6 +548,13 @@ export type GenerateResult = {
         workflowId: string;
         workflowName: string;
     };
+    retries?: {
+        count: number;
+        errors: Array<{
+            code: string;
+            message: string;
+        }>;
+    };
 };
 /**
  * Unified options for both generation and streaming
@@ -899,6 +906,13 @@ export type TextGenerationResult = {
     imageOutput?: {
         base64: string;
     } | null;
+    retries?: {
+        count: number;
+        errors: Array<{
+            code: string;
+            message: string;
+        }>;
+    };
 };
 /**
  * Enhanced result type with optional analytics/evaluation
@@ -907,3 +921,14 @@ export type EnhancedGenerateResult = GenerateResult & {
     analytics?: AnalyticsData;
     evaluation?: EvaluationData;
 };
+/**
+ * NL-004: Model alias/deprecation configuration.
+ * Allows mapping deprecated model names to their replacements.
+ */
+export type ModelAliasConfig = {
+    aliases: Record<string, {
+        target: string;
+        action: "warn" | "redirect" | "block";
+        reason?: string;
+    }>;
+};

package/dist/utils/messageBuilder.js

@@ -1182,6 +1182,8 @@ async function downloadImageFromUrl(url) {
  * - Supports alt text for accessibility (included as context in text parts)
  */
 async function convertSimpleImagesToProviderFormat(text, images, provider, _model) {
+    // Validate image count against provider-specific limits before processing
+    ProviderImageAdapter.validateImageCount(images.length, provider, _model);
     // For Vercel AI SDK, we need to return the content in the standard format
     // The Vercel AI SDK will handle provider-specific formatting internally
     // IMPORTANT: Generate alt text descriptions BEFORE URL downloading to maintain correct image numbering

package/dist/utils/modelAliasResolver.d.ts

@@ -0,0 +1,17 @@
+/**
+ * NL-004: Model alias/deprecation resolver.
+ *
+ * Resolves model names against an alias configuration map and applies the
+ * configured action (warn, redirect, or block).
+ */
+import type { ModelAliasConfig } from "../types/generateTypes.js";
+/**
+ * Resolve model aliases/deprecations.
+ * Checks the model name against the alias map and applies the configured action.
+ *
+ * @param model - The requested model name (may be undefined).
+ * @param config - The alias configuration containing model mappings.
+ * @returns The resolved model name (original or redirected).
+ * @throws {NeuroLinkError} When the alias action is "block".
+ */
+export declare function resolveModel(model: string | undefined, config: ModelAliasConfig | undefined): string | undefined;

package/dist/utils/modelAliasResolver.js

@@ -0,0 +1,54 @@
+/**
+ * NL-004: Model alias/deprecation resolver.
+ *
+ * Resolves model names against an alias configuration map and applies the
+ * configured action (warn, redirect, or block).
+ */
+import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
+import { NeuroLinkError } from "./errorHandling.js";
+import { logger } from "./logger.js";
+/**
+ * Resolve model aliases/deprecations.
+ * Checks the model name against the alias map and applies the configured action.
+ *
+ * @param model - The requested model name (may be undefined).
+ * @param config - The alias configuration containing model mappings.
+ * @returns The resolved model name (original or redirected).
+ * @throws {NeuroLinkError} When the alias action is "block".
+ */
+export function resolveModel(model, config) {
+    if (!model || !config?.aliases) {
+        return model;
+    }
+    const alias = config.aliases[model];
+    if (!alias) {
+        return model;
+    }
+    switch (alias.action) {
+        case "block":
+            throw new NeuroLinkError({
+                code: "MODEL_DEPRECATED",
+                message: `Model '${model}' is blocked. ${alias.reason || `Use '${alias.target}' instead.`}`,
+                category: ErrorCategory.VALIDATION,
+                severity: ErrorSeverity.HIGH,
+                retriable: false,
+                context: {
+                    requestedModel: model,
+                    suggestedModel: alias.target,
+                    reason: alias.reason,
+                },
+            });
+        case "warn":
+            logger.warn(`[ModelAlias] Model '${model}' is deprecated. ${alias.reason || `Redirecting to '${alias.target}'.`}`, {
+                requestedModel: model,
+                targetModel: alias.target,
+                reason: alias.reason,
+            });
+            return alias.target;
+        case "redirect":
+            logger.debug(`[ModelAlias] Redirecting model '${model}' to '${alias.target}'`);
+            return alias.target;
+        default:
+            return model;
+    }
+}

package/dist/utils/pdfProcessor.d.ts

@@ -7,7 +7,7 @@
  *
  * The conversion uses pdf-to-img package (MuPDF-based) for high-quality conversion.
  */
-import type { FileProcessingResult, PDFProviderConfig, PDFProcessorOptions } from "../types/fileTypes.js";
+import type { FileProcessingResult, PDFProcessorOptions, PDFProviderConfig } from "../types/fileTypes.js";
 /**
  * Options for PDF to image conversion
  */

package/dist/utils/pdfProcessor.js

@@ -8,8 +8,8 @@
  * The conversion uses pdf-to-img package (MuPDF-based) for high-quality conversion.
  */
 import { PDF_LIMITS } from "../core/constants.js";
-import { logger } from "./logger.js";
 import { ErrorFactory } from "./errorHandling.js";
+import { logger } from "./logger.js";
 /**
  * Provider configurations for PDF handling
  *
@@ -98,7 +98,7 @@ const PDF_PROVIDER_CONFIGS = {
     "openai-compatible": {
         maxSizeMB: 10,
         maxPages: 100,
-        supportsNative: true,
+        supportsNative: false, // LiteLLM is a proxy — underlying model may not support native PDF; default to safe text extraction
         requiresCitations: false,
         apiType: "files-api",
     },
@@ -133,7 +133,7 @@ export class PDFProcessor {
     static async process(content, options) {
         const provider = (options?.provider || "unknown").toLowerCase();
         const config = PDF_PROVIDER_CONFIGS[provider];
-        if (!this.isValidPDF(content)) {
+        if (!PDFProcessor.isValidPDF(content)) {
             throw new Error("Invalid PDF file format. File must start with %PDF- header.");
         }
         if (!config) {
@@ -149,7 +149,7 @@ export class PDFProcessor {
         if (sizeMB > config.maxSizeMB) {
             throw new Error(`PDF size ${sizeMB.toFixed(2)}MB exceeds ${config.maxSizeMB}MB limit for ${provider}`);
         }
-        const metadata = this.extractBasicMetadata(content);
+        const metadata = PDFProcessor.extractBasicMetadata(content);
         if (metadata.estimatedPages && metadata.estimatedPages > config.maxPages) {
             const enforceLimits = options?.enforceLimits !== false;
             if (enforceLimits) {
@@ -205,7 +205,7 @@ export class PDFProcessor {
         if (buffer.length < 5) {
             return false;
         }
-        return buffer.subarray(0, 5).equals(this.PDF_SIGNATURE);
+        return buffer.subarray(0, 5).equals(PDFProcessor.PDF_SIGNATURE);
     }
     static extractBasicMetadata(buffer) {
         const headerSize = Math.min(10000, buffer.length);
@@ -274,7 +274,7 @@ export class PDFProcessor {
                 "A valid PDF must be at least 5 bytes (PDF header).");
         }
         // 2. Validate PDF magic bytes (%PDF-)
-        if (!this.isValidPDF(pdfBuffer)) {
+        if (!PDFProcessor.isValidPDF(pdfBuffer)) {
             throw new Error("Invalid PDF: File must start with %PDF- header. " +
                 "The provided buffer does not appear to be a valid PDF file.");
         }
@@ -354,7 +354,7 @@ export class PDFProcessor {
     static async convertFromPath(pdfPath, options) {
         const fs = await import("fs/promises");
         const pdfBuffer = await fs.readFile(pdfPath);
-        return this.convertToImages(pdfBuffer, options);
+        return PDFProcessor.convertToImages(pdfBuffer, options);
     }
     /**
      * Check if PDF to image conversion is available

package/dist/utils/toolUtils.d.ts

@@ -24,6 +24,14 @@ export declare function shouldAllowCustomTools(toolConfig?: ToolConfig): boolean
  * @returns true if MCP tools should be enabled
  */
 export declare function shouldEnableMCPTools(toolConfig?: ToolConfig): boolean;
+/**
+ * Check if the bash command execution tool should be enabled.
+ * This is opt-in only (defaults to false) for security reasons.
+ *
+ * @param toolConfig - Optional tool configuration (if available from config)
+ * @returns true if the bash tool should be enabled
+ */
+export declare function shouldEnableBashTool(toolConfig?: ToolConfig): boolean;
 /**
  * Get maximum tools per provider
  * @param toolConfig - Optional tool configuration

package/dist/utils/toolUtils.js

@@ -40,6 +40,21 @@ export function shouldEnableMCPTools(toolConfig) {
     }
     return process.env.NEUROLINK_DISABLE_MCP_TOOLS !== "true";
 }
+/**
+ * Check if the bash command execution tool should be enabled.
+ * This is opt-in only (defaults to false) for security reasons.
+ *
+ * @param toolConfig - Optional tool configuration (if available from config)
+ * @returns true if the bash tool should be enabled
+ */
+export function shouldEnableBashTool(toolConfig) {
+    // Priority: explicit config > environment variable > default (false)
+    if (toolConfig?.enableBashTool !== undefined) {
+        return toolConfig.enableBashTool;
+    }
+    // Single source of truth for environment variable access
+    return process.env.NEUROLINK_ENABLE_BASH_TOOL === "true";
+}
 /**
  * Get maximum tools per provider
  * @param toolConfig - Optional tool configuration