@juspay/neurolink 4.0.0 → 4.1.0

package/dist/lib/mcp/semaphore-manager.d.ts

@@ -0,0 +1,137 @@
+/**
+ * NeuroLink MCP Semaphore Manager
+ * Prevents race conditions in concurrent tool executions using a robust semaphore pattern
+ * Based on proven patterns from 1MCP reference implementation
+ */
+import type { NeuroLinkExecutionContext } from "./factory.js";
+/**
+ * Semaphore operation result
+ */
+export interface SemaphoreResult<T> {
+    success: boolean;
+    result?: T;
+    error?: Error;
+    waitTime: number;
+    executionTime: number;
+    queueDepth: number;
+}
+/**
+ * Semaphore statistics
+ */
+export interface SemaphoreStats {
+    activeOperations: number;
+    queuedOperations: number;
+    totalOperations: number;
+    totalWaitTime: number;
+    averageWaitTime: number;
+    peakQueueDepth: number;
+    lastActivity: number;
+}
+/**
+ * Semaphore Manager for concurrent operation control
+ * Implements the proven semaphore pattern from 1MCP to prevent race conditions
+ */
+export declare class SemaphoreManager {
+    private locks;
+    private queues;
+    private stats;
+    private globalStats;
+    /**
+     * Acquire a semaphore and execute an operation
+     * Ensures exclusive access to resources identified by the key
+     *
+     * @param key Unique identifier for the resource
+     * @param operation Async operation to execute with exclusive access
+     * @param context Optional execution context for enhanced tracking
+     * @returns Result of the operation with timing metrics
+     */
+    acquire<T>(key: string, operation: () => Promise<T>, context?: NeuroLinkExecutionContext): Promise<SemaphoreResult<T>>;
+    /**
+     * Try to acquire a semaphore without waiting
+     * Returns immediately if the resource is locked
+     *
+     * @param key Unique identifier for the resource
+     * @param operation Async operation to execute if lock is available
+     * @param context Optional execution context
+     * @returns Result of the operation or null if resource is locked
+     */
+    tryAcquire<T>(key: string, operation: () => Promise<T>, context?: NeuroLinkExecutionContext): Promise<SemaphoreResult<T> | null>;
+    /**
+     * Check if a resource is currently locked
+     *
+     * @param key Resource identifier
+     * @returns True if the resource is locked
+     */
+    isLocked(key: string): boolean;
+    /**
+     * Get the current queue depth for a resource
+     *
+     * @param key Resource identifier
+     * @returns Number of operations waiting for this resource
+     */
+    getQueueDepth(key: string): number;
+    /**
+     * Get statistics for a specific resource or global stats
+     *
+     * @param key Optional resource identifier
+     * @returns Semaphore statistics
+     */
+    getStats(key?: string): SemaphoreStats;
+    /**
+     * Clear all semaphores (use with caution)
+     * This will reject all pending operations
+     */
+    clearAll(): void;
+    /**
+     * Update queue depth statistics
+     *
+     * @private
+     */
+    private updateQueueDepth;
+    /**
+     * Increment active operations counter
+     *
+     * @private
+     */
+    private incrementActiveOperations;
+    /**
+     * Decrement active operations counter
+     *
+     * @private
+     */
+    private decrementActiveOperations;
+    /**
+     * Update timing statistics
+     *
+     * @private
+     */
+    private updateStats;
+    /**
+     * Create empty statistics object
+     *
+     * @private
+     */
+    private createEmptyStats;
+}
+/**
+ * Default semaphore manager instance
+ */
+export declare const defaultSemaphoreManager: SemaphoreManager;
+/**
+ * Utility function to acquire semaphore with default manager
+ *
+ * @param key Resource identifier
+ * @param operation Operation to execute
+ * @param context Optional execution context
+ * @returns Operation result with metrics
+ */
+export declare function acquireSemaphore<T>(key: string, operation: () => Promise<T>, context?: NeuroLinkExecutionContext): Promise<SemaphoreResult<T>>;
+/**
+ * Utility function to try acquiring semaphore without waiting
+ *
+ * @param key Resource identifier
+ * @param operation Operation to execute
+ * @param context Optional execution context
+ * @returns Operation result or null if locked
+ */
+export declare function tryAcquireSemaphore<T>(key: string, operation: () => Promise<T>, context?: NeuroLinkExecutionContext): Promise<SemaphoreResult<T> | null>;

package/dist/lib/mcp/semaphore-manager.js

@@ -0,0 +1,329 @@
+/**
+ * NeuroLink MCP Semaphore Manager
+ * Prevents race conditions in concurrent tool executions using a robust semaphore pattern
+ * Based on proven patterns from 1MCP reference implementation
+ */
+/**
+ * Semaphore Manager for concurrent operation control
+ * Implements the proven semaphore pattern from 1MCP to prevent race conditions
+ */
+export class SemaphoreManager {
+    locks = new Map();
+    queues = new Map();
+    stats = new Map();
+    globalStats = {
+        activeOperations: 0,
+        queuedOperations: 0,
+        totalOperations: 0,
+        totalWaitTime: 0,
+        averageWaitTime: 0,
+        peakQueueDepth: 0,
+        lastActivity: Date.now(),
+    };
+    /**
+     * Acquire a semaphore and execute an operation
+     * Ensures exclusive access to resources identified by the key
+     *
+     * @param key Unique identifier for the resource
+     * @param operation Async operation to execute with exclusive access
+     * @param context Optional execution context for enhanced tracking
+     * @returns Result of the operation with timing metrics
+     */
+    async acquire(key, operation, context) {
+        const startTime = Date.now();
+        let waitTime = 0;
+        let executionTime = 0;
+        let queueDepth = 0;
+        // Get or create queue for this key
+        const queue = this.queues.get(key) || [];
+        queueDepth = queue.length;
+        // Check if there's an active lock
+        const existingLock = this.locks.get(key);
+        if (existingLock) {
+            // Add to queue and wait
+            queueDepth++;
+            this.updateQueueDepth(key, queueDepth);
+            const waitPromise = new Promise((resolve, reject) => {
+                queue.push({ resolve, reject });
+                this.queues.set(key, queue);
+            });
+            if (process.env.NEUROLINK_DEBUG === "true") {
+                console.log(`[Semaphore] Operation waiting in queue for key: ${key} (depth: ${queueDepth})`);
+            }
+            // Wait for existing lock and our turn in queue
+            await existingLock;
+            await waitPromise;
+            waitTime = Date.now() - startTime;
+        }
+        // Create new lock for this operation
+        let lockResolve;
+        const lockPromise = new Promise((resolve) => {
+            lockResolve = resolve;
+        });
+        this.locks.set(key, lockPromise);
+        // Update statistics
+        this.incrementActiveOperations(key);
+        // Execute the operation
+        const executionStartTime = Date.now();
+        if (process.env.NEUROLINK_DEBUG === "true") {
+            console.log(`[Semaphore] Executing operation for key: ${key}`);
+        }
+        try {
+            const result = await operation();
+            executionTime = Math.max(1, Date.now() - executionStartTime); // Ensure at least 1ms
+            // Update statistics
+            this.updateStats(key, waitTime, executionTime);
+            if (process.env.NEUROLINK_DEBUG === "true") {
+                console.log(`[Semaphore] Operation completed successfully for key: ${key}`);
+            }
+            return {
+                success: true,
+                result,
+                waitTime,
+                executionTime,
+                queueDepth,
+            };
+        }
+        catch (error) {
+            executionTime = Math.max(1, Date.now() - executionStartTime); // Ensure at least 1ms
+            const errorObj = error instanceof Error ? error : new Error(String(error));
+            // Update statistics even for errors
+            this.updateStats(key, waitTime, executionTime);
+            if (process.env.NEUROLINK_DEBUG === "true") {
+                console.error(`[Semaphore] Operation failed for key: ${key}`, errorObj.message);
+            }
+            return {
+                success: false,
+                error: errorObj,
+                waitTime,
+                executionTime,
+                queueDepth,
+            };
+        }
+        finally {
+            // Release the lock
+            this.locks.delete(key);
+            if (lockResolve) {
+                lockResolve();
+            }
+            // Process queue
+            const queue = this.queues.get(key) || [];
+            if (queue.length > 0) {
+                const next = queue.shift();
+                if (queue.length === 0) {
+                    this.queues.delete(key);
+                }
+                else {
+                    this.queues.set(key, queue);
+                }
+                // Allow next operation to proceed
+                next.resolve();
+            }
+            // Update statistics
+            this.decrementActiveOperations(key);
+            if (process.env.NEUROLINK_DEBUG === "true") {
+                console.log(`[Semaphore] Released lock for key: ${key}`);
+            }
+        }
+    }
+    /**
+     * Try to acquire a semaphore without waiting
+     * Returns immediately if the resource is locked
+     *
+     * @param key Unique identifier for the resource
+     * @param operation Async operation to execute if lock is available
+     * @param context Optional execution context
+     * @returns Result of the operation or null if resource is locked
+     */
+    async tryAcquire(key, operation, context) {
+        // Check if there's an active lock or queue
+        if (this.locks.has(key) || (this.queues.get(key) || []).length > 0) {
+            if (process.env.NEUROLINK_DEBUG === "true") {
+                console.log(`[Semaphore] tryAcquire failed - resource locked: ${key}`);
+            }
+            return null;
+        }
+        // No lock, proceed with normal acquire
+        return this.acquire(key, operation, context);
+    }
+    /**
+     * Check if a resource is currently locked
+     *
+     * @param key Resource identifier
+     * @returns True if the resource is locked
+     */
+    isLocked(key) {
+        return this.locks.has(key);
+    }
+    /**
+     * Get the current queue depth for a resource
+     *
+     * @param key Resource identifier
+     * @returns Number of operations waiting for this resource
+     */
+    getQueueDepth(key) {
+        const queue = this.queues.get(key) || [];
+        const hasLock = this.locks.has(key);
+        return queue.length + (hasLock ? 1 : 0);
+    }
+    /**
+     * Get statistics for a specific resource or global stats
+     *
+     * @param key Optional resource identifier
+     * @returns Semaphore statistics
+     */
+    getStats(key) {
+        if (key) {
+            return (this.stats.get(key) || {
+                activeOperations: 0,
+                queuedOperations: 0,
+                totalOperations: 0,
+                totalWaitTime: 0,
+                averageWaitTime: 0,
+                peakQueueDepth: 0,
+                lastActivity: 0,
+            });
+        }
+        return { ...this.globalStats };
+    }
+    /**
+     * Clear all semaphores (use with caution)
+     * This will reject all pending operations
+     */
+    clearAll() {
+        console.warn("[Semaphore] Clearing all semaphores - pending operations will be rejected");
+        // Reject all queued operations
+        for (const [key, queue] of this.queues) {
+            for (const op of queue) {
+                op.reject(new Error("Semaphore cleared"));
+            }
+        }
+        // Clear all data structures
+        this.locks.clear();
+        this.queues.clear();
+        this.stats.clear();
+        // Reset global stats
+        this.globalStats = {
+            activeOperations: 0,
+            queuedOperations: 0,
+            totalOperations: this.globalStats.totalOperations,
+            totalWaitTime: this.globalStats.totalWaitTime,
+            averageWaitTime: this.globalStats.averageWaitTime,
+            peakQueueDepth: this.globalStats.peakQueueDepth,
+            lastActivity: Date.now(),
+        };
+    }
+    /**
+     * Update queue depth statistics
+     *
+     * @private
+     */
+    updateQueueDepth(key, depth) {
+        const keyStats = this.stats.get(key) || this.createEmptyStats();
+        if (depth > keyStats.peakQueueDepth) {
+            keyStats.peakQueueDepth = depth;
+        }
+        keyStats.queuedOperations = depth;
+        this.stats.set(key, keyStats);
+        // Update global stats
+        this.globalStats.queuedOperations = Array.from(this.stats.values()).reduce((total, stats) => total + stats.queuedOperations, 0);
+        // Update global peak
+        if (depth > this.globalStats.peakQueueDepth) {
+            this.globalStats.peakQueueDepth = depth;
+        }
+    }
+    /**
+     * Increment active operations counter
+     *
+     * @private
+     */
+    incrementActiveOperations(key) {
+        const keyStats = this.stats.get(key) || this.createEmptyStats();
+        keyStats.activeOperations++;
+        keyStats.totalOperations++;
+        keyStats.lastActivity = Date.now();
+        this.stats.set(key, keyStats);
+        this.globalStats.activeOperations++;
+        this.globalStats.totalOperations++;
+        this.globalStats.lastActivity = Date.now();
+    }
+    /**
+     * Decrement active operations counter
+     *
+     * @private
+     */
+    decrementActiveOperations(key) {
+        const keyStats = this.stats.get(key);
+        if (keyStats && keyStats.activeOperations > 0) {
+            keyStats.activeOperations--;
+            keyStats.lastActivity = Date.now();
+        }
+        if (this.globalStats.activeOperations > 0) {
+            this.globalStats.activeOperations--;
+        }
+        this.globalStats.lastActivity = Date.now();
+    }
+    /**
+     * Update timing statistics
+     *
+     * @private
+     */
+    updateStats(key, waitTime, executionTime) {
+        const keyStats = this.stats.get(key) || this.createEmptyStats();
+        keyStats.totalWaitTime += waitTime;
+        keyStats.averageWaitTime =
+            keyStats.totalOperations > 0
+                ? keyStats.totalWaitTime / keyStats.totalOperations
+                : 0;
+        keyStats.lastActivity = Date.now();
+        this.stats.set(key, keyStats);
+        // Update global stats
+        this.globalStats.totalWaitTime += waitTime;
+        this.globalStats.averageWaitTime =
+            this.globalStats.totalOperations > 0
+                ? this.globalStats.totalWaitTime / this.globalStats.totalOperations
+                : 0;
+    }
+    /**
+     * Create empty statistics object
+     *
+     * @private
+     */
+    createEmptyStats() {
+        return {
+            activeOperations: 0,
+            queuedOperations: 0,
+            totalOperations: 0,
+            totalWaitTime: 0,
+            averageWaitTime: 0,
+            peakQueueDepth: 0,
+            lastActivity: Date.now(),
+        };
+    }
+}
+/**
+ * Default semaphore manager instance
+ */
+export const defaultSemaphoreManager = new SemaphoreManager();
+/**
+ * Utility function to acquire semaphore with default manager
+ *
+ * @param key Resource identifier
+ * @param operation Operation to execute
+ * @param context Optional execution context
+ * @returns Operation result with metrics
+ */
+export async function acquireSemaphore(key, operation, context) {
+    return defaultSemaphoreManager.acquire(key, operation, context);
+}
+/**
+ * Utility function to try acquiring semaphore without waiting
+ *
+ * @param key Resource identifier
+ * @param operation Operation to execute
+ * @param context Optional execution context
+ * @returns Operation result or null if locked
+ */
+export async function tryAcquireSemaphore(key, operation, context) {
+    return defaultSemaphoreManager.tryAcquire(key, operation, context);
+}

package/dist/lib/mcp/servers/ai-providers/ai-workflow-tools.d.ts

@@ -30,13 +30,13 @@ export declare const workflowToolSchemas: {
         includeAsyncTests: z.ZodDefault<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         codeFunction: string;
-        testTypes: ("integration" | "unit" | "edge-cases" | "performance" | "security")[];
+        testTypes: ("integration" | "unit" | "performance" | "edge-cases" | "security")[];
         framework: "jest" | "mocha" | "vitest" | "pytest" | "unittest" | "rspec";
         coverageTarget: number;
         includeAsyncTests: boolean;
     }, {
         codeFunction: string;
-        testTypes?: ("integration" | "unit" | "edge-cases" | "performance" | "security")[] | undefined;
+        testTypes?: ("integration" | "unit" | "performance" | "edge-cases" | "security")[] | undefined;
         framework?: "jest" | "mocha" | "vitest" | "pytest" | "unittest" | "rspec" | undefined;
         coverageTarget?: number | undefined;
         includeAsyncTests?: boolean | undefined;

package/dist/lib/mcp/session-manager.d.ts

@@ -0,0 +1,186 @@
+/**
+ * NeuroLink MCP Session Management System
+ * Enables continuous tool calling with persistent state across executions
+ * Based on patterns from Cline's session management implementation
+ */
+import type { NeuroLinkExecutionContext, ToolResult } from "./factory.js";
+import { type PersistenceOptions } from "./session-persistence.js";
+/**
+ * Session state for orchestrator operations
+ */
+export interface OrchestratorSession {
+    id: string;
+    context: NeuroLinkExecutionContext;
+    toolHistory: ToolResult[];
+    state: Map<string, any>;
+    metadata: {
+        userAgent?: string;
+        origin?: string;
+        tags?: string[];
+    };
+    createdAt: number;
+    lastActivity: number;
+    expiresAt: number;
+}
+/**
+ * Session creation options
+ */
+export interface SessionOptions {
+    ttl?: number;
+    metadata?: {
+        userAgent?: string;
+        origin?: string;
+        tags?: string[];
+    };
+}
+/**
+ * Session statistics
+ */
+export interface SessionStats {
+    activeSessions: number;
+    totalSessionsCreated: number;
+    totalSessionsExpired: number;
+    averageSessionDuration: number;
+    averageToolsPerSession: number;
+    peakConcurrentSessions: number;
+    lastCleanup: number;
+}
+/**
+ * Session Manager for maintaining state across tool executions
+ * Implements session lifecycle management with automatic cleanup
+ */
+export declare class SessionManager {
+    private sessions;
+    private sessionCounter;
+    private stats;
+    private cleanupInterval;
+    private defaultTTL;
+    private cleanupIntervalMs;
+    private persistence;
+    private persistenceEnabled;
+    constructor(defaultTTL?: number, cleanupIntervalMs?: number, autoCleanup?: boolean, enablePersistence?: boolean);
+    /**
+     * Initialize session manager with persistence
+     */
+    initialize(persistenceOptions?: PersistenceOptions): Promise<void>;
+    /**
+     * Create a new session
+     *
+     * @param context Execution context for the session
+     * @param options Session configuration options
+     * @returns Created session
+     */
+    createSession(context: NeuroLinkExecutionContext, options?: SessionOptions): OrchestratorSession;
+    /**
+     * Get an existing session
+     *
+     * @param sessionId Session identifier
+     * @param extend Whether to extend the session's expiration
+     * @returns Session if found and not expired
+     */
+    getSession(sessionId: string, extend?: boolean): OrchestratorSession | null;
+    /**
+     * Update session with new tool result
+     *
+     * @param sessionId Session identifier
+     * @param toolResult Result from tool execution
+     * @returns Updated session or null if not found
+     */
+    updateSession(sessionId: string, toolResult: ToolResult): OrchestratorSession | null;
+    /**
+     * Set session state value
+     *
+     * @param sessionId Session identifier
+     * @param key State key
+     * @param value State value
+     * @returns Updated session or null if not found
+     */
+    setSessionState(sessionId: string, key: string, value: any): OrchestratorSession | null;
+    /**
+     * Get session state value
+     *
+     * @param sessionId Session identifier
+     * @param key State key
+     * @returns State value or undefined
+     */
+    getSessionState(sessionId: string, key: string): any;
+    /**
+     * Remove a session
+     *
+     * @param sessionId Session identifier
+     * @returns True if session was removed
+     */
+    removeSession(sessionId: string): boolean;
+    /**
+     * Clean up expired sessions
+     *
+     * @returns Number of sessions cleaned up
+     */
+    cleanup(): Promise<number>;
+    /**
+     * Get an existing session with async persistence loading
+     *
+     * @param sessionId Session identifier
+     * @param extend Whether to extend the session's expiration
+     * @returns Session if found and not expired, or null
+     */
+    getSessionAsync(sessionId: string, extend?: boolean): Promise<OrchestratorSession | null>;
+    /**
+     * Get all active sessions
+     *
+     * @returns Array of active sessions
+     */
+    getActiveSessions(): Promise<OrchestratorSession[]>;
+    /**
+     * Get session statistics
+     *
+     * @returns Session statistics
+     */
+    getStats(): SessionStats;
+    /**
+     * Clear all sessions
+     */
+    clearAll(): void;
+    /**
+     * Start automatic cleanup interval
+     *
+     * @private
+     */
+    private startAutoCleanup;
+    /**
+     * Stop automatic cleanup interval
+     */
+    stopAutoCleanup(): void;
+    /**
+     * Generate unique session ID
+     *
+     * @private
+     */
+    private generateSessionId;
+    /**
+     * Update statistics
+     *
+     * @private
+     */
+    private updateStats;
+}
+/**
+ * Default session manager instance
+ */
+export declare const defaultSessionManager: SessionManager;
+/**
+ * Utility function to create session with default manager
+ *
+ * @param context Execution context
+ * @param options Session options
+ * @returns Created session
+ */
+export declare function createSession(context: NeuroLinkExecutionContext, options?: SessionOptions): Promise<OrchestratorSession>;
+/**
+ * Utility function to get session with default manager
+ *
+ * @param sessionId Session identifier
+ * @param extend Whether to extend expiration
+ * @returns Session or null
+ */
+export declare function getSession(sessionId: string, extend?: boolean): Promise<OrchestratorSession | null>;