@midscene/ios 1.8.4-beta-20260521065716.0 → 1.8.4

package/dist/es/bin.mjs

@@ -635,6 +635,10 @@ class IOSWebDriverClient extends WebDriverClient {
             debugIOS(`Failed to apply iOS session configuration: ${error}`);
         }
     }
+    async setupExistingSession() {
+        this.ensureSession();
+        await this.setupIOSSession();
+    }
     async executeRequest(method, endpoint, data) {
         return this.makeRequest(method, this.buildSessionEndpoint(endpoint), data);
     }
@@ -732,7 +736,10 @@ class IOSDevice {
         debugDevice(`Connecting to iOS device: ${this.deviceId}`);
         try {
             await this.wdaManager.start();
-            await this.wdaBackend.createSession();
+            if (this.options?.sessionId) {
+                debugDevice(`Using existing WDA session: ${this.options.sessionId}`);
+                await this.wdaBackend.setupExistingSession();
+            } else await this.wdaBackend.createSession();
             const deviceInfo = await this.wdaBackend.getDeviceInfo();
             if (deviceInfo?.udid) {
                 this.deviceId = deviceInfo.udid;
@@ -1207,7 +1214,10 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         const mjpegPort = options?.wdaMjpegPort ?? DEFAULT_WDA_MJPEG_PORT;
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
-            host: wdaHost
+            host: wdaHost,
+            ...options?.sessionId ? {
+                sessionId: options.sessionId
+            } : {}
         });
         this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
@@ -1334,6 +1344,22 @@ async function agentFromWebDriverAgent(opts) {
     await device.connect();
     return new IOSAgent(device, opts);
 }
+async function probeWdaReady(host, port, timeoutMs = 800) {
+    const controller = new AbortController();
+    const timer = setTimeout(()=>controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`http://${host}:${port}/status`, {
+            signal: controller.signal
+        });
+        if (!res.ok) return false;
+        const body = await res.json().catch(()=>null);
+        return body?.value?.ready === true;
+    } catch  {
+        return false;
+    } finally{
+        clearTimeout(timer);
+    }
+}
 const iosPlaygroundPlatform = definePlaygroundPlatform({
     id: 'ios',
     title: 'Midscene iOS Playground',
@@ -1344,10 +1370,12 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
         if (availablePlaygroundPort !== PLAYGROUND_SERVER_PORT) console.log(`⚠️  Port ${PLAYGROUND_SERVER_PORT} is busy, using port ${availablePlaygroundPort} instead`);
         const sessionManager = {
             async getSetupSchema () {
+                const wdaReady = await probeWdaReady('localhost', DEFAULT_WDA_PORT);
                 return {
                     title: 'Connect WebDriverAgent',
                     description: 'Provide the WebDriverAgent host and port that are already running for your selected iPhone or simulator.',
                     primaryActionLabel: 'Create Agent',
+                    autoSubmitWhenReady: wdaReady,
                     fields: [
                         {
                             key: 'host',
@@ -1364,6 +1392,13 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                             required: true,
                             defaultValue: DEFAULT_WDA_PORT,
                             placeholder: DEFAULT_WDA_PORT.toString()
+                        },
+                        {
+                            key: 'sessionId',
+                            label: 'WebDriverAgent session ID',
+                            type: 'text',
+                            required: false,
+                            placeholder: 'Existing session ID'
                         }
                     ]
                 };
@@ -1372,9 +1407,13 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
                 const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
+                const sessionId = 'string' == typeof input?.sessionId && input.sessionId.trim() ? input.sessionId.trim() : void 0;
                 const connectAgent = async ()=>agentFromWebDriverAgent({
                         wdaHost: host,
-                        wdaPort: port
+                        wdaPort: port,
+                        ...sessionId ? {
+                            sessionId
+                        } : {}
                     });
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
@@ -1389,6 +1428,9 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                     metadata: {
                         wdaHost: host,
                         wdaPort: port,
+                        ...sessionId ? {
+                            sessionId
+                        } : {},
                         ...deviceInfo ? {
                             deviceInfo
                         } : {}

package/dist/es/cli.mjs

@@ -634,6 +634,10 @@ class IOSWebDriverClient extends WebDriverClient {
             debugIOS(`Failed to apply iOS session configuration: ${error}`);
         }
     }
+    async setupExistingSession() {
+        this.ensureSession();
+        await this.setupIOSSession();
+    }
     async executeRequest(method, endpoint, data) {
         return this.makeRequest(method, this.buildSessionEndpoint(endpoint), data);
     }
@@ -731,7 +735,10 @@ class IOSDevice {
         debugDevice(`Connecting to iOS device: ${this.deviceId}`);
         try {
             await this.wdaManager.start();
-            await this.wdaBackend.createSession();
+            if (this.options?.sessionId) {
+                debugDevice(`Using existing WDA session: ${this.options.sessionId}`);
+                await this.wdaBackend.setupExistingSession();
+            } else await this.wdaBackend.createSession();
             const deviceInfo = await this.wdaBackend.getDeviceInfo();
             if (deviceInfo?.udid) {
                 this.deviceId = deviceInfo.udid;
@@ -1206,7 +1213,10 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         const mjpegPort = options?.wdaMjpegPort ?? DEFAULT_WDA_MJPEG_PORT;
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
-            host: wdaHost
+            host: wdaHost,
+            ...options?.sessionId ? {
+                sessionId: options.sessionId
+            } : {}
         });
         this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
@@ -1348,9 +1358,20 @@ const iosInitArgShape = {
     deviceId: z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
     wdaHost: z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
     wdaPort: z.number().optional().describe('WebDriverAgent port'),
+    sessionId: z.string().optional().describe('Existing WebDriverAgent session ID to reuse'),
     useWDA: z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
     wdaMjpegPort: z.number().optional().describe('WebDriverAgent MJPEG streaming port')
 };
+function getTargetIdentity(initArgs) {
+    if (initArgs?.deviceId) return initArgs.sessionId ? `${initArgs.deviceId}-session-${initArgs.sessionId}` : initArgs.deviceId;
+    if (initArgs?.wdaHost || initArgs?.wdaPort || initArgs?.sessionId) {
+        const wdaHost = initArgs.wdaHost ?? 'localhost';
+        const wdaPort = initArgs.wdaPort ?? 'default';
+        const sessionSegment = initArgs.sessionId ? `-session-${initArgs.sessionId}` : '';
+        return `wda-${wdaHost}-${wdaPort}${sessionSegment}`;
+    }
+    return 'auto';
+}
 class IOSMidsceneTools extends BaseMidsceneTools {
     getCliReportSessionName() {
         return 'midscene-ios';
@@ -1389,7 +1410,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
                 cli: this.getAgentInitArgCliMetadata(),
                 handler: async (args)=>{
                     const initArgs = this.extractAgentInitParam(args);
-                    const identity = initArgs?.deviceId ?? (initArgs?.wdaHost || initArgs?.wdaPort ? `wda-${initArgs.wdaHost ?? 'localhost'}-${initArgs.wdaPort ?? 'default'}` : 'auto');
+                    const identity = getTargetIdentity(initArgs);
                     const reportSession = this.createNewCliReportSession(identity);
                     this.commitCliReportSession(reportSession);
                     if (this.agent) {
@@ -1436,7 +1457,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
 const tools = new IOSMidsceneTools();
 runToolsCLI(tools, 'midscene-ios', {
     stripPrefix: 'ios_',
-    version: "1.8.4-beta-20260521065716.0",
+    version: "1.8.4",
     extraCommands: createReportCliCommands()
 }).catch((e)=>{
     process.exit(reportCLIError(e));

package/dist/es/index.mjs

@@ -455,6 +455,10 @@ class IOSWebDriverClient extends WebDriverClient {
             debugIOS(`Failed to apply iOS session configuration: ${error}`);
         }
     }
+    async setupExistingSession() {
+        this.ensureSession();
+        await this.setupIOSSession();
+    }
     async executeRequest(method, endpoint, data) {
         return this.makeRequest(method, this.buildSessionEndpoint(endpoint), data);
     }
@@ -552,7 +556,10 @@ class IOSDevice {
         debugDevice(`Connecting to iOS device: ${this.deviceId}`);
         try {
             await this.wdaManager.start();
-            await this.wdaBackend.createSession();
+            if (this.options?.sessionId) {
+                debugDevice(`Using existing WDA session: ${this.options.sessionId}`);
+                await this.wdaBackend.setupExistingSession();
+            } else await this.wdaBackend.createSession();
             const deviceInfo = await this.wdaBackend.getDeviceInfo();
             if (deviceInfo?.udid) {
                 this.deviceId = deviceInfo.udid;
@@ -1027,7 +1034,10 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         const mjpegPort = options?.wdaMjpegPort ?? DEFAULT_WDA_MJPEG_PORT;
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
-            host: wdaHost
+            host: wdaHost,
+            ...options?.sessionId ? {
+                sessionId: options.sessionId
+            } : {}
         });
         this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
@@ -1353,9 +1363,20 @@ const iosInitArgShape = {
     deviceId: z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
     wdaHost: z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
     wdaPort: z.number().optional().describe('WebDriverAgent port'),
+    sessionId: z.string().optional().describe('Existing WebDriverAgent session ID to reuse'),
     useWDA: z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
     wdaMjpegPort: z.number().optional().describe('WebDriverAgent MJPEG streaming port')
 };
+function getTargetIdentity(initArgs) {
+    if (initArgs?.deviceId) return initArgs.sessionId ? `${initArgs.deviceId}-session-${initArgs.sessionId}` : initArgs.deviceId;
+    if (initArgs?.wdaHost || initArgs?.wdaPort || initArgs?.sessionId) {
+        const wdaHost = initArgs.wdaHost ?? 'localhost';
+        const wdaPort = initArgs.wdaPort ?? 'default';
+        const sessionSegment = initArgs.sessionId ? `-session-${initArgs.sessionId}` : '';
+        return `wda-${wdaHost}-${wdaPort}${sessionSegment}`;
+    }
+    return 'auto';
+}
 class IOSMidsceneTools extends BaseMidsceneTools {
     getCliReportSessionName() {
         return 'midscene-ios';
@@ -1394,7 +1415,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
                 cli: this.getAgentInitArgCliMetadata(),
                 handler: async (args)=>{
                     const initArgs = this.extractAgentInitParam(args);
-                    const identity = initArgs?.deviceId ?? (initArgs?.wdaHost || initArgs?.wdaPort ? `wda-${initArgs.wdaHost ?? 'localhost'}-${initArgs.wdaPort ?? 'default'}` : 'auto');
+                    const identity = getTargetIdentity(initArgs);
                     const reportSession = this.createNewCliReportSession(identity);
                     this.commitCliReportSession(reportSession);
                     if (this.agent) {
@@ -1484,6 +1505,22 @@ async function checkIOSEnvironment() {
         };
     }
 }
+async function probeWdaReady(host, port, timeoutMs = 800) {
+    const controller = new AbortController();
+    const timer = setTimeout(()=>controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`http://${host}:${port}/status`, {
+            signal: controller.signal
+        });
+        if (!res.ok) return false;
+        const body = await res.json().catch(()=>null);
+        return body?.value?.ready === true;
+    } catch  {
+        return false;
+    } finally{
+        clearTimeout(timer);
+    }
+}
 const iosPlaygroundPlatform = definePlaygroundPlatform({
     id: 'ios',
     title: 'Midscene iOS Playground',
@@ -1494,10 +1531,12 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
         if (availablePlaygroundPort !== PLAYGROUND_SERVER_PORT) console.log(`⚠️  Port ${PLAYGROUND_SERVER_PORT} is busy, using port ${availablePlaygroundPort} instead`);
         const sessionManager = {
             async getSetupSchema () {
+                const wdaReady = await probeWdaReady('localhost', DEFAULT_WDA_PORT);
                 return {
                     title: 'Connect WebDriverAgent',
                     description: 'Provide the WebDriverAgent host and port that are already running for your selected iPhone or simulator.',
                     primaryActionLabel: 'Create Agent',
+                    autoSubmitWhenReady: wdaReady,
                     fields: [
                         {
                             key: 'host',
@@ -1514,6 +1553,13 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                             required: true,
                             defaultValue: DEFAULT_WDA_PORT,
                             placeholder: DEFAULT_WDA_PORT.toString()
+                        },
+                        {
+                            key: 'sessionId',
+                            label: 'WebDriverAgent session ID',
+                            type: 'text',
+                            required: false,
+                            placeholder: 'Existing session ID'
                         }
                     ]
                 };
@@ -1522,9 +1568,13 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
                 const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
+                const sessionId = 'string' == typeof input?.sessionId && input.sessionId.trim() ? input.sessionId.trim() : void 0;
                 const connectAgent = async ()=>agentFromWebDriverAgent({
                         wdaHost: host,
-                        wdaPort: port
+                        wdaPort: port,
+                        ...sessionId ? {
+                            sessionId
+                        } : {}
                     });
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
@@ -1539,6 +1589,9 @@ const iosPlaygroundPlatform = definePlaygroundPlatform({
                     metadata: {
                         wdaHost: host,
                         wdaPort: port,
+                        ...sessionId ? {
+                            sessionId
+                        } : {},
                         ...deviceInfo ? {
                             deviceInfo
                         } : {}

package/dist/es/mcp-server.mjs

@@ -634,6 +634,10 @@ class IOSWebDriverClient extends WebDriverClient {
             debugIOS(`Failed to apply iOS session configuration: ${error}`);
         }
     }
+    async setupExistingSession() {
+        this.ensureSession();
+        await this.setupIOSSession();
+    }
     async executeRequest(method, endpoint, data) {
         return this.makeRequest(method, this.buildSessionEndpoint(endpoint), data);
     }
@@ -731,7 +735,10 @@ class IOSDevice {
         debugDevice(`Connecting to iOS device: ${this.deviceId}`);
         try {
             await this.wdaManager.start();
-            await this.wdaBackend.createSession();
+            if (this.options?.sessionId) {
+                debugDevice(`Using existing WDA session: ${this.options.sessionId}`);
+                await this.wdaBackend.setupExistingSession();
+            } else await this.wdaBackend.createSession();
             const deviceInfo = await this.wdaBackend.getDeviceInfo();
             if (deviceInfo?.udid) {
                 this.deviceId = deviceInfo.udid;
@@ -1206,7 +1213,10 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         const mjpegPort = options?.wdaMjpegPort ?? DEFAULT_WDA_MJPEG_PORT;
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
-            host: wdaHost
+            host: wdaHost,
+            ...options?.sessionId ? {
+                sessionId: options.sessionId
+            } : {}
         });
         this.wdaManager = WDAManager.getInstance(wdaPort, wdaHost);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
@@ -1348,9 +1358,20 @@ const iosInitArgShape = {
     deviceId: z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
     wdaHost: z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
     wdaPort: z.number().optional().describe('WebDriverAgent port'),
+    sessionId: z.string().optional().describe('Existing WebDriverAgent session ID to reuse'),
     useWDA: z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
     wdaMjpegPort: z.number().optional().describe('WebDriverAgent MJPEG streaming port')
 };
+function getTargetIdentity(initArgs) {
+    if (initArgs?.deviceId) return initArgs.sessionId ? `${initArgs.deviceId}-session-${initArgs.sessionId}` : initArgs.deviceId;
+    if (initArgs?.wdaHost || initArgs?.wdaPort || initArgs?.sessionId) {
+        const wdaHost = initArgs.wdaHost ?? 'localhost';
+        const wdaPort = initArgs.wdaPort ?? 'default';
+        const sessionSegment = initArgs.sessionId ? `-session-${initArgs.sessionId}` : '';
+        return `wda-${wdaHost}-${wdaPort}${sessionSegment}`;
+    }
+    return 'auto';
+}
 class IOSMidsceneTools extends BaseMidsceneTools {
     getCliReportSessionName() {
         return 'midscene-ios';
@@ -1389,7 +1410,7 @@ class IOSMidsceneTools extends BaseMidsceneTools {
                 cli: this.getAgentInitArgCliMetadata(),
                 handler: async (args)=>{
                     const initArgs = this.extractAgentInitParam(args);
-                    const identity = initArgs?.deviceId ?? (initArgs?.wdaHost || initArgs?.wdaPort ? `wda-${initArgs.wdaHost ?? 'localhost'}-${initArgs.wdaPort ?? 'default'}` : 'auto');
+                    const identity = getTargetIdentity(initArgs);
                     const reportSession = this.createNewCliReportSession(identity);
                     this.commitCliReportSession(reportSession);
                     if (this.agent) {
@@ -1440,7 +1461,7 @@ class IOSMCPServer extends BaseMCPServer {
     constructor(toolsManager){
         super({
             name: '@midscene/ios-mcp',
-            version: "1.8.4-beta-20260521065716.0",
+            version: "1.8.4",
             description: 'Control the iOS device using natural language commands'
         }, toolsManager);
     }

package/dist/lib/bin.js

@@ -660,6 +660,10 @@ class IOSWebDriverClient extends webdriver_namespaceObject.WebDriverClient {
             debugIOS(`Failed to apply iOS session configuration: ${error}`);
         }
     }
+    async setupExistingSession() {
+        this.ensureSession();
+        await this.setupIOSSession();
+    }
     async executeRequest(method, endpoint, data) {
         return this.makeRequest(method, this.buildSessionEndpoint(endpoint), data);
     }
@@ -757,7 +761,10 @@ class IOSDevice {
         debugDevice(`Connecting to iOS device: ${this.deviceId}`);
         try {
             await this.wdaManager.start();
-            await this.wdaBackend.createSession();
+            if (this.options?.sessionId) {
+                debugDevice(`Using existing WDA session: ${this.options.sessionId}`);
+                await this.wdaBackend.setupExistingSession();
+            } else await this.wdaBackend.createSession();
             const deviceInfo = await this.wdaBackend.getDeviceInfo();
             if (deviceInfo?.udid) {
                 this.deviceId = deviceInfo.udid;
@@ -1232,7 +1239,10 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         const mjpegPort = options?.wdaMjpegPort ?? DEFAULT_WDA_MJPEG_PORT;
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
-            host: wdaHost
+            host: wdaHost,
+            ...options?.sessionId ? {
+                sessionId: options.sessionId
+            } : {}
         });
         this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
@@ -1359,6 +1369,22 @@ async function agentFromWebDriverAgent(opts) {
     await device.connect();
     return new IOSAgent(device, opts);
 }
+async function probeWdaReady(host, port, timeoutMs = 800) {
+    const controller = new AbortController();
+    const timer = setTimeout(()=>controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`http://${host}:${port}/status`, {
+            signal: controller.signal
+        });
+        if (!res.ok) return false;
+        const body = await res.json().catch(()=>null);
+        return body?.value?.ready === true;
+    } catch  {
+        return false;
+    } finally{
+        clearTimeout(timer);
+    }
+}
 const iosPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroundPlatform)({
     id: 'ios',
     title: 'Midscene iOS Playground',
@@ -1369,10 +1395,12 @@ const iosPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroundPla
         if (availablePlaygroundPort !== constants_namespaceObject.PLAYGROUND_SERVER_PORT) console.log(`⚠️  Port ${constants_namespaceObject.PLAYGROUND_SERVER_PORT} is busy, using port ${availablePlaygroundPort} instead`);
         const sessionManager = {
             async getSetupSchema () {
+                const wdaReady = await probeWdaReady('localhost', constants_namespaceObject.DEFAULT_WDA_PORT);
                 return {
                     title: 'Connect WebDriverAgent',
                     description: 'Provide the WebDriverAgent host and port that are already running for your selected iPhone or simulator.',
                     primaryActionLabel: 'Create Agent',
+                    autoSubmitWhenReady: wdaReady,
                     fields: [
                         {
                             key: 'host',
@@ -1389,6 +1417,13 @@ const iosPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroundPla
                             required: true,
                             defaultValue: constants_namespaceObject.DEFAULT_WDA_PORT,
                             placeholder: constants_namespaceObject.DEFAULT_WDA_PORT.toString()
+                        },
+                        {
+                            key: 'sessionId',
+                            label: 'WebDriverAgent session ID',
+                            type: 'text',
+                            required: false,
+                            placeholder: 'Existing session ID'
                         }
                     ]
                 };
@@ -1397,9 +1432,13 @@ const iosPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroundPla
                 const host = 'string' == typeof input?.host && input.host.trim() ? input.host.trim().replace(/^https?:\/\//, '') : 'localhost';
                 const port = 'number' == typeof input?.port ? input.port : Number.parseInt(String(input?.port ?? constants_namespaceObject.DEFAULT_WDA_PORT), 10);
                 if (Number.isNaN(port) || port < 1 || port > 65535) throw new Error(`Invalid WebDriverAgent port: ${String(input?.port)}`);
+                const sessionId = 'string' == typeof input?.sessionId && input.sessionId.trim() ? input.sessionId.trim() : void 0;
                 const connectAgent = async ()=>agentFromWebDriverAgent({
                         wdaHost: host,
-                        wdaPort: port
+                        wdaPort: port,
+                        ...sessionId ? {
+                            sessionId
+                        } : {}
                     });
                 const agent = await connectAgent();
                 const deviceInfo = await agent.interface.getConnectedDeviceInfo?.();
@@ -1414,6 +1453,9 @@ const iosPlaygroundPlatform = (0, playground_namespaceObject.definePlaygroundPla
                     metadata: {
                         wdaHost: host,
                         wdaPort: port,
+                        ...sessionId ? {
+                            sessionId
+                        } : {},
                         ...deviceInfo ? {
                             deviceInfo
                         } : {}

package/dist/lib/cli.js

@@ -658,6 +658,10 @@ class IOSWebDriverClient extends webdriver_namespaceObject.WebDriverClient {
             debugIOS(`Failed to apply iOS session configuration: ${error}`);
         }
     }
+    async setupExistingSession() {
+        this.ensureSession();
+        await this.setupIOSSession();
+    }
     async executeRequest(method, endpoint, data) {
         return this.makeRequest(method, this.buildSessionEndpoint(endpoint), data);
     }
@@ -755,7 +759,10 @@ class IOSDevice {
         debugDevice(`Connecting to iOS device: ${this.deviceId}`);
         try {
             await this.wdaManager.start();
-            await this.wdaBackend.createSession();
+            if (this.options?.sessionId) {
+                debugDevice(`Using existing WDA session: ${this.options.sessionId}`);
+                await this.wdaBackend.setupExistingSession();
+            } else await this.wdaBackend.createSession();
             const deviceInfo = await this.wdaBackend.getDeviceInfo();
             if (deviceInfo?.udid) {
                 this.deviceId = deviceInfo.udid;
@@ -1230,7 +1237,10 @@ ScreenSize: ${size.width}x${size.height} (DPR: ${size.scale})
         const mjpegPort = options?.wdaMjpegPort ?? DEFAULT_WDA_MJPEG_PORT;
         this.wdaBackend = new IOSWebDriverClient({
             port: wdaPort,
-            host: wdaHost
+            host: wdaHost,
+            ...options?.sessionId ? {
+                sessionId: options.sessionId
+            } : {}
         });
         this.wdaManager = webdriver_namespaceObject.WDAManager.getInstance(wdaPort, wdaHost);
         this.mjpegStreamUrl = `http://${wdaHost}:${mjpegPort}`;
@@ -1372,9 +1382,20 @@ const iosInitArgShape = {
     deviceId: core_namespaceObject.z.string().optional().describe('iOS device UDID (optional when WDA auto-detect is sufficient)'),
     wdaHost: core_namespaceObject.z.string().optional().describe('WebDriverAgent host, defaults to localhost'),
     wdaPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent port'),
+    sessionId: core_namespaceObject.z.string().optional().describe('Existing WebDriverAgent session ID to reuse'),
     useWDA: core_namespaceObject.z.boolean().optional().describe('Whether to reuse an existing WebDriverAgent session'),
     wdaMjpegPort: core_namespaceObject.z.number().optional().describe('WebDriverAgent MJPEG streaming port')
 };
+function getTargetIdentity(initArgs) {
+    if (initArgs?.deviceId) return initArgs.sessionId ? `${initArgs.deviceId}-session-${initArgs.sessionId}` : initArgs.deviceId;
+    if (initArgs?.wdaHost || initArgs?.wdaPort || initArgs?.sessionId) {
+        const wdaHost = initArgs.wdaHost ?? 'localhost';
+        const wdaPort = initArgs.wdaPort ?? 'default';
+        const sessionSegment = initArgs.sessionId ? `-session-${initArgs.sessionId}` : '';
+        return `wda-${wdaHost}-${wdaPort}${sessionSegment}`;
+    }
+    return 'auto';
+}
 class IOSMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools {
     getCliReportSessionName() {
         return 'midscene-ios';
@@ -1413,7 +1434,7 @@ class IOSMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools {
                 cli: this.getAgentInitArgCliMetadata(),
                 handler: async (args)=>{
                     const initArgs = this.extractAgentInitParam(args);
-                    const identity = initArgs?.deviceId ?? (initArgs?.wdaHost || initArgs?.wdaPort ? `wda-${initArgs.wdaHost ?? 'localhost'}-${initArgs.wdaPort ?? 'default'}` : 'auto');
+                    const identity = getTargetIdentity(initArgs);
                     const reportSession = this.createNewCliReportSession(identity);
                     this.commitCliReportSession(reportSession);
                     if (this.agent) {
@@ -1460,7 +1481,7 @@ class IOSMidsceneTools extends base_tools_namespaceObject.BaseMidsceneTools {
 const tools = new IOSMidsceneTools();
 (0, cli_namespaceObject.runToolsCLI)(tools, 'midscene-ios', {
     stripPrefix: 'ios_',
-    version: "1.8.4-beta-20260521065716.0",
+    version: "1.8.4",
     extraCommands: (0, core_namespaceObject.createReportCliCommands)()
 }).catch((e)=>{
     process.exit((0, cli_namespaceObject.reportCLIError)(e));