@jshookmcp/jshook 0.2.0 → 0.2.2

package/dist/src/server/domains/process/handlers.base.js

@@ -0,0 +1,1022 @@
+import { UnifiedProcessManager, MemoryManager } from '../../domains/shared/modules.js';
+import { MemoryAuditTrail } from '../../../modules/process/memory/AuditTrail.js';
+import { logger } from '../../../utils/logger.js';
+import { argNumber, argStringArray } from '../../domains/shared/parse-args.js';
+const MEMORY_PATTERN_TYPES = new Set([
+    'hex',
+    'int32',
+    'int64',
+    'float',
+    'double',
+    'string',
+]);
+export function validatePid(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`Invalid PID: ${JSON.stringify(value)}`);
+    return n;
+}
+export function requireString(value, name) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new Error(`${name} must be a non-empty string`);
+    }
+    return value;
+}
+export function requirePositiveNumber(value, name) {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`${name} must be a positive number`);
+    return n;
+}
+function normalizePatternType(value) {
+    if (typeof value === 'string' && MEMORY_PATTERN_TYPES.has(value)) {
+        return value;
+    }
+    return 'hex';
+}
+function getOptionalPid(value) {
+    const pid = Number(value);
+    return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+}
+function getOptionalString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function getOptionalPositiveNumber(value) {
+    const size = Number(value);
+    return Number.isFinite(size) && size > 0 ? size : undefined;
+}
+function getWriteSize(data, encoding) {
+    if (encoding === 'hex') {
+        const normalized = data.replace(/\s+/g, '');
+        return Math.ceil(normalized.length / 2);
+    }
+    return Buffer.from(data, 'base64').length;
+}
+export class ProcessHandlersBase {
+    processManager;
+    memoryManager;
+    platform;
+    auditTrail = new MemoryAuditTrail();
+    constructor() {
+        this.processManager = new UnifiedProcessManager();
+        this.memoryManager = new MemoryManager();
+        this.platform = this.processManager.getPlatform();
+        logger.info(`ProcessToolHandlers initialized for platform: ${this.platform}`);
+    }
+    async buildMemoryDiagnostics(input) {
+        const recommendedActions = new Set();
+        const permission = await this.memoryManager.checkAvailability();
+        if (!permission.available) {
+            recommendedActions.add('Run as administrator');
+        }
+        let processInfo = null;
+        if (input.pid != null) {
+            try {
+                const resolvedProcess = await this.processManager.getProcessByPid(input.pid);
+                processInfo = resolvedProcess
+                    ? {
+                        pid: resolvedProcess.pid,
+                        name: resolvedProcess.name,
+                        executablePath: resolvedProcess.executablePath,
+                        windowTitle: resolvedProcess.windowTitle,
+                        windowHandle: resolvedProcess.windowHandle,
+                        memoryUsage: resolvedProcess.memoryUsage,
+                    }
+                    : null;
+            }
+            catch {
+                processInfo = null;
+            }
+            if (!processInfo) {
+                recommendedActions.add('Check if process is still running');
+            }
+        }
+        let protectionInfo = null;
+        let protectionQueryFailed = false;
+        if (input.pid != null && input.address) {
+            try {
+                protectionInfo = await this.memoryManager.checkMemoryProtection(input.pid, input.address);
+            }
+            catch {
+                protectionQueryFailed = true;
+            }
+            if (protectionQueryFailed || protectionInfo?.success === false) {
+                recommendedActions.add('Verify address is within valid memory region');
+            }
+        }
+        if (input.size != null &&
+            protectionInfo?.regionSize != null &&
+            input.size > protectionInfo.regionSize) {
+            recommendedActions.add('Reduce the requested size to fit the target memory region');
+        }
+        if (input.operation === 'memory_read' &&
+            protectionInfo?.success &&
+            protectionInfo.isReadable === false) {
+            recommendedActions.add('Ensure target memory region is readable');
+        }
+        if (input.operation === 'memory_write' &&
+            protectionInfo?.success &&
+            protectionInfo.isWritable === false) {
+            recommendedActions.add('Ensure target memory region is writable');
+        }
+        let modulesEnumerated = false;
+        let moduleCount = null;
+        if (input.pid != null) {
+            try {
+                const modulesResult = await this.memoryManager.enumerateModules(input.pid);
+                modulesEnumerated = modulesResult.success;
+                moduleCount = modulesResult.modules?.length ?? null;
+            }
+            catch {
+                modulesEnumerated = false;
+            }
+        }
+        if (input.pid != null && input.address) {
+            recommendedActions.add('Re-resolve the address after the process restarts because ASLR can shift module addresses');
+        }
+        const normalizedError = input.error?.toLowerCase() ?? '';
+        if (normalizedError.includes('access denied') ||
+            normalizedError.includes('permission') ||
+            normalizedError.includes('privilege') ||
+            normalizedError.includes('administrator')) {
+            recommendedActions.add('Run as administrator');
+        }
+        const aslrNote = modulesEnumerated
+            ? moduleCount && moduleCount > 0
+                ? `Enumerated ${moduleCount} module(s). Treat absolute addresses as session-specific because ASLR can shift module bases between launches.`
+                : 'Module enumeration succeeded but returned no modules. Absolute addresses may still change across process launches because of ASLR.'
+            : 'Module enumeration was unavailable. Assume ASLR may shift absolute addresses between launches and re-resolve addresses after restarts.';
+        return {
+            permission: {
+                available: permission.available,
+                reason: permission.reason,
+                platform: this.platform,
+            },
+            process: {
+                exists: input.pid != null ? Boolean(processInfo) : null,
+                pid: input.pid ?? null,
+                name: processInfo?.name ?? null,
+            },
+            address: {
+                queried: input.pid != null && Boolean(input.address),
+                valid: input.pid != null && input.address ? (protectionInfo?.success ?? null) : null,
+                protection: protectionInfo?.protection ?? null,
+                regionStart: protectionInfo?.regionStart ?? null,
+                regionSize: protectionInfo?.regionSize ?? null,
+            },
+            aslr: {
+                heuristic: true,
+                note: aslrNote,
+            },
+            recommendedActions: Array.from(recommendedActions),
+        };
+    }
+    async safeBuildMemoryDiagnostics(input) {
+        try {
+            return await this.buildMemoryDiagnostics(input);
+        }
+        catch (diagnosticError) {
+            logger.warn('Memory diagnostics generation failed:', diagnosticError);
+            return undefined;
+        }
+    }
+    recordMemoryAudit(entry) {
+        try {
+            this.auditTrail.record(entry);
+        }
+        catch (auditError) {
+            logger.warn('Memory audit trail recording failed:', auditError);
+        }
+    }
+    async handleProcessFind(args) {
+        try {
+            const pattern = requireString(args.pattern, 'pattern');
+            const processes = await this.processManager.findProcesses(pattern);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            pattern,
+                            count: processes.length,
+                            processes: processes.map((p) => ({
+                                pid: p.pid,
+                                name: p.name,
+                                path: p.executablePath,
+                                windowTitle: p.windowTitle,
+                                windowHandle: p.windowHandle,
+                                memoryMB: p.memoryUsage ? Math.round(p.memoryUsage / 1024 / 1024) : undefined,
+                            })),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Process find failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessGet(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const process = await this.processManager.getProcessByPid(pid);
+            if (!process) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: `Process with PID ${pid} not found`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const cmdLine = await this.processManager.getProcessCommandLine(pid);
+            const debugPort = await this.processManager.checkDebugPort(pid, {
+                commandLine: cmdLine.commandLine,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            process: {
+                                ...process,
+                                commandLine: cmdLine.commandLine,
+                                parentPid: cmdLine.parentPid,
+                                debugPort,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Process get failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessWindows(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const windows = await this.processManager.getProcessWindows(pid);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            pid,
+                            windowCount: windows.length,
+                            windows: windows.map((w) => ({
+                                handle: w.handle,
+                                title: w.title,
+                                className: w.className,
+                                processId: w.processId,
+                            })),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Process windows failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessFindChromium(_args) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        success: false,
+                        disabled: true,
+                        message: 'process_find_chromium is disabled to avoid scanning user-installed browser processes.',
+                        guidance: [
+                            'Use browser_launch(driver="chrome"|"camoufox") to start a managed browser session.',
+                            'Use browser_attach/browser_launch(mode="connect") with an explicit browserURL/wsEndpoint.',
+                            'Use process_launch_debug for explicitly targeted Electron/Chromium executables.',
+                        ],
+                        platform: this.platform,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    async handleProcessCheckDebugPort(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const debugPort = await this.processManager.checkDebugPort(pid);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            pid,
+                            debugPort,
+                            canAttach: debugPort !== null,
+                            attachUrl: debugPort ? `http://localhost:${debugPort}` : null,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Check debug port failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessLaunchDebug(args) {
+        try {
+            const executablePath = requireString(args.executablePath, 'executablePath');
+            const debugPort = argNumber(args, 'debugPort', 9222);
+            const argsList = argStringArray(args, 'args');
+            const process = await this.processManager.launchWithDebug(executablePath, debugPort, argsList);
+            if (!process) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Failed to launch process',
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            process: {
+                                pid: process.pid,
+                                name: process.name,
+                                path: process.executablePath,
+                            },
+                            debugPort,
+                            attachUrl: `http://localhost:${debugPort}`,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Launch debug failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleProcessKill(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const killed = await this.processManager.killProcess(pid);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: killed,
+                            pid,
+                            message: killed
+                                ? `Process ${pid} killed successfully`
+                                : `Failed to kill process ${pid}`,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Process kill failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error instanceof Error ? error.message : String(error),
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryRead(args) {
+        const startedAt = Date.now();
+        try {
+            const pid = validatePid(args.pid);
+            const address = requireString(args.address, 'address');
+            const size = requirePositiveNumber(args.size, 'size');
+            const availability = await this.memoryManager.checkAvailability();
+            if (!availability.available) {
+                const errorMessage = availability.reason ?? 'Memory operations not available';
+                const diagnostics = await this.safeBuildMemoryDiagnostics({
+                    pid,
+                    address,
+                    size,
+                    operation: 'memory_read',
+                    error: errorMessage,
+                });
+                this.recordMemoryAudit({
+                    operation: 'memory_read',
+                    pid,
+                    address,
+                    size,
+                    result: 'failure',
+                    error: errorMessage,
+                    durationMs: Date.now() - startedAt,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Memory operations not available',
+                                reason: availability.reason,
+                                platform: this.platform,
+                                requestedAddress: address,
+                                requestedSize: size,
+                                pid,
+                                diagnostics,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const result = await this.memoryManager.readMemory(pid, address, size);
+            const diagnostics = !result.success
+                ? await this.safeBuildMemoryDiagnostics({
+                    pid,
+                    address,
+                    size,
+                    operation: 'memory_read',
+                    error: result.error,
+                })
+                : undefined;
+            this.recordMemoryAudit({
+                operation: 'memory_read',
+                pid,
+                address,
+                size,
+                result: result.success ? 'success' : 'failure',
+                error: result.error,
+                durationMs: Date.now() - startedAt,
+            });
+            const payload = {
+                success: result.success,
+                data: result.data,
+                error: result.error,
+                pid,
+                address,
+                size,
+                platform: this.platform,
+            };
+            if (!result.success) {
+                payload.diagnostics = diagnostics;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(payload, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory read failed:', error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const pid = getOptionalPid(args.pid);
+            const address = getOptionalString(args.address);
+            const size = getOptionalPositiveNumber(args.size);
+            const diagnostics = await this.safeBuildMemoryDiagnostics({
+                pid,
+                address,
+                size,
+                operation: 'memory_read',
+                error: errorMessage,
+            });
+            this.recordMemoryAudit({
+                operation: 'memory_read',
+                pid: pid ?? null,
+                address: address ?? null,
+                size: size ?? null,
+                result: 'failure',
+                error: errorMessage,
+                durationMs: Date.now() - startedAt,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: errorMessage,
+                            diagnostics,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryWrite(args) {
+        const startedAt = Date.now();
+        try {
+            const pid = validatePid(args.pid);
+            const address = requireString(args.address, 'address');
+            const data = requireString(args.data, 'data');
+            const encoding = args.encoding || 'hex';
+            const size = getWriteSize(data, encoding);
+            const availability = await this.memoryManager.checkAvailability();
+            if (!availability.available) {
+                const errorMessage = availability.reason ?? 'Memory operations not available';
+                const diagnostics = await this.safeBuildMemoryDiagnostics({
+                    pid,
+                    address,
+                    size,
+                    operation: 'memory_write',
+                    error: errorMessage,
+                });
+                this.recordMemoryAudit({
+                    operation: 'memory_write',
+                    pid,
+                    address,
+                    size,
+                    result: 'failure',
+                    error: errorMessage,
+                    durationMs: Date.now() - startedAt,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Memory operations not available',
+                                reason: availability.reason,
+                                platform: this.platform,
+                                requestedAddress: address,
+                                dataLength: data != null ? data.length : 0,
+                                encoding,
+                                pid,
+                                diagnostics,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const result = await this.memoryManager.writeMemory(pid, address, data, encoding);
+            const diagnostics = !result.success
+                ? await this.safeBuildMemoryDiagnostics({
+                    pid,
+                    address,
+                    size,
+                    operation: 'memory_write',
+                    error: result.error,
+                })
+                : undefined;
+            this.recordMemoryAudit({
+                operation: 'memory_write',
+                pid,
+                address,
+                size,
+                result: result.success ? 'success' : 'failure',
+                error: result.error,
+                durationMs: Date.now() - startedAt,
+            });
+            const payload = {
+                success: result.success,
+                bytesWritten: result.bytesWritten,
+                error: result.error,
+                pid,
+                address,
+                dataLength: data.length,
+                encoding,
+                platform: this.platform,
+            };
+            if (!result.success) {
+                payload.diagnostics = diagnostics;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(payload, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory write failed:', error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const pid = getOptionalPid(args.pid);
+            const address = getOptionalString(args.address);
+            const data = getOptionalString(args.data);
+            const encoding = args.encoding || 'hex';
+            const size = data ? getWriteSize(data, encoding) : undefined;
+            const diagnostics = await this.safeBuildMemoryDiagnostics({
+                pid,
+                address,
+                size,
+                operation: 'memory_write',
+                error: errorMessage,
+            });
+            this.recordMemoryAudit({
+                operation: 'memory_write',
+                pid: pid ?? null,
+                address: address ?? null,
+                size: size ?? null,
+                result: 'failure',
+                error: errorMessage,
+                durationMs: Date.now() - startedAt,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: errorMessage,
+                            diagnostics,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryScan(args) {
+        const startedAt = Date.now();
+        try {
+            const pid = validatePid(args.pid);
+            const pattern = requireString(args.pattern, 'pattern');
+            const patternType = normalizePatternType(args.patternType);
+            const availability = await this.memoryManager.checkAvailability();
+            if (!availability.available) {
+                const errorMessage = availability.reason ?? 'Memory operations not available';
+                const diagnostics = await this.safeBuildMemoryDiagnostics({
+                    pid,
+                    operation: 'memory_scan',
+                    error: errorMessage,
+                });
+                this.recordMemoryAudit({
+                    operation: 'memory_scan',
+                    pid,
+                    address: null,
+                    size: null,
+                    result: 'failure',
+                    error: errorMessage,
+                    durationMs: Date.now() - startedAt,
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Memory operations not available',
+                                reason: availability.reason,
+                                platform: this.platform,
+                                requestedPattern: pattern,
+                                patternType,
+                                pid,
+                                diagnostics,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const result = await this.memoryManager.scanMemory(pid, pattern, patternType);
+            const diagnostics = !result.success
+                ? await this.safeBuildMemoryDiagnostics({
+                    pid,
+                    operation: 'memory_scan',
+                    error: result.error,
+                })
+                : undefined;
+            this.recordMemoryAudit({
+                operation: 'memory_scan',
+                pid,
+                address: null,
+                size: null,
+                result: result.success ? 'success' : 'failure',
+                error: result.error,
+                durationMs: Date.now() - startedAt,
+            });
+            const payload = {
+                success: result.success,
+                addresses: result.addresses,
+                error: result.error,
+                pid,
+                pattern,
+                patternType,
+                platform: this.platform,
+            };
+            if (!result.success) {
+                payload.diagnostics = diagnostics;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(payload, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory scan failed:', error);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const pid = getOptionalPid(args.pid);
+            const diagnostics = await this.safeBuildMemoryDiagnostics({
+                pid,
+                operation: 'memory_scan',
+                error: errorMessage,
+            });
+            this.recordMemoryAudit({
+                operation: 'memory_scan',
+                pid: pid ?? null,
+                address: null,
+                size: null,
+                result: 'failure',
+                error: errorMessage,
+                durationMs: Date.now() - startedAt,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: errorMessage,
+                            diagnostics,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryAuditExport(args) {
+        try {
+            const exportedJson = this.auditTrail.exportJson();
+            const entries = JSON.parse(exportedJson);
+            const clear = args.clear === true;
+            const count = this.auditTrail.size();
+            if (clear) {
+                this.auditTrail.clear();
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            count,
+                            cleared: clear,
+                            entries,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory audit export failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryCheckProtection(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const address = requireString(args.address, 'address');
+            const result = await this.memoryManager.checkMemoryProtection(pid, address);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory check protection failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryScanFiltered(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const pattern = requireString(args.pattern, 'pattern');
+            const addresses = args.addresses;
+            const patternType = normalizePatternType(args.patternType);
+            const availability = await this.memoryManager.checkAvailability();
+            if (!availability.available) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Memory operations not available',
+                                reason: availability.reason,
+                                platform: this.platform,
+                                pid,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const result = await this.memoryManager.scanMemoryFiltered(pid, pattern, addresses, patternType);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory scan filtered failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryBatchWrite(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const patches = args.patches;
+            const availability = await this.memoryManager.checkAvailability();
+            if (!availability.available) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                success: false,
+                                message: 'Memory operations not available',
+                                reason: availability.reason,
+                                platform: this.platform,
+                                pid,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            const result = await this.memoryManager.batchMemoryWrite(pid, patches);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory batch write failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryDumpRegion(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const address = requireString(args.address, 'address');
+            const size = requirePositiveNumber(args.size, 'size');
+            const outputPath = requireString(args.outputPath, 'outputPath');
+            if (/^[/\\]/.test(outputPath) || /\.\./.test(outputPath) || /^[A-Za-z]:/.test(outputPath)) {
+                throw new Error('outputPath must be a relative path without parent directory traversal or drive letters');
+            }
+            const result = await this.memoryManager.dumpMemoryRegion(pid, address, size, outputPath);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory dump region failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+    async handleMemoryListRegions(args) {
+        try {
+            const pid = validatePid(args.pid);
+            const result = await this.memoryManager.enumerateRegions(pid);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error('Memory list regions failed:', error);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: error instanceof Error ? error.message : String(error) }, null, 2),
+                    },
+                ],
+            };
+        }
+    }
+}