@iwsdk/vite-plugin-dev 0.3.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.js CHANGED
@@ -1,15 +1,887 @@
1
- import { spawn, execFile } from 'child_process';
2
1
  import { randomUUID } from 'crypto';
3
2
  import * as fs from 'fs';
4
- import { existsSync, readFileSync } from 'fs';
5
- import { readFile, mkdir, writeFile, unlink } from 'fs/promises';
3
+ import { realpathSync, existsSync, readFileSync } from 'fs';
6
4
  import * as path from 'path';
7
- import { WebSocketServer } from 'ws';
5
+ import path__default from 'path';
6
+ import { WebSocketServer, WebSocket } from 'ws';
7
+ import { spawn } from 'child_process';
8
8
  import * as os from 'os';
9
9
  import { chromium } from 'playwright';
10
10
  import sharp from 'sharp';
11
+ import { readFile, rm, mkdir, writeFile, rename } from 'fs/promises';
11
12
  import { fileURLToPath } from 'url';
12
13
 
14
+ /**
15
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
16
+ *
17
+ * This source code is licensed under the MIT license found in the
18
+ * LICENSE file in the root directory of this source tree.
19
+ */
20
+ const IWSDK_RUNTIME_SESSION_PATH = '.iwsdk/runtime/session.json';
21
+ const IWSDK_RUNTIME_STATE_SCHEMA_VERSION = 2;
22
+ const INTERNAL_BROWSER_PROBE_METHOD = '__iwsdk_browser_probe';
23
+ const RUNTIME_MCP_TOOLS = [
24
+ // =============================================================================
25
+ // Session Management
26
+ // =============================================================================
27
+ {
28
+ name: 'xr_get_session_status',
29
+ description: 'Get XR session and device status',
30
+ inputSchema: {
31
+ type: 'object',
32
+ properties: {},
33
+ required: [],
34
+ },
35
+ },
36
+ {
37
+ name: 'xr_accept_session',
38
+ description: 'Accept an offered XR session (equivalent to clicking "Enter XR" button)',
39
+ inputSchema: {
40
+ type: 'object',
41
+ properties: {},
42
+ required: [],
43
+ },
44
+ },
45
+ {
46
+ name: 'xr_end_session',
47
+ description: 'End the current active XR session',
48
+ inputSchema: {
49
+ type: 'object',
50
+ properties: {},
51
+ required: [],
52
+ },
53
+ },
54
+ // =============================================================================
55
+ // Transform Control
56
+ // =============================================================================
57
+ {
58
+ name: 'xr_get_transform',
59
+ description: 'Get position and orientation of a tracked device',
60
+ inputSchema: {
61
+ type: 'object',
62
+ properties: {
63
+ device: {
64
+ type: 'string',
65
+ enum: [
66
+ 'headset',
67
+ 'controller-left',
68
+ 'controller-right',
69
+ 'hand-left',
70
+ 'hand-right',
71
+ ],
72
+ description: 'The device to query',
73
+ },
74
+ },
75
+ required: ['device'],
76
+ },
77
+ },
78
+ {
79
+ name: 'xr_set_transform',
80
+ description: 'Set position and/or orientation of a tracked device. Position is in meters, orientation can be quaternion or euler angles (degrees).',
81
+ inputSchema: {
82
+ type: 'object',
83
+ properties: {
84
+ device: {
85
+ type: 'string',
86
+ enum: [
87
+ 'headset',
88
+ 'controller-left',
89
+ 'controller-right',
90
+ 'hand-left',
91
+ 'hand-right',
92
+ ],
93
+ description: 'The device to move',
94
+ },
95
+ position: {
96
+ type: 'object',
97
+ description: 'World position in meters',
98
+ properties: {
99
+ x: { type: 'number', description: 'X position (left/right)' },
100
+ y: {
101
+ type: 'number',
102
+ description: 'Y position (up/down, 1.6 is standing height)',
103
+ },
104
+ z: {
105
+ type: 'number',
106
+ description: 'Z position (forward/back, negative is forward)',
107
+ },
108
+ },
109
+ },
110
+ orientation: {
111
+ type: 'object',
112
+ description: 'Rotation as quaternion {x,y,z,w} or euler angles {pitch,yaw,roll} in degrees',
113
+ properties: {
114
+ x: { type: 'number', description: 'Quaternion X component' },
115
+ y: { type: 'number', description: 'Quaternion Y component' },
116
+ z: { type: 'number', description: 'Quaternion Z component' },
117
+ w: { type: 'number', description: 'Quaternion W component' },
118
+ pitch: {
119
+ type: 'number',
120
+ description: 'Pitch in degrees (X rotation)',
121
+ },
122
+ yaw: { type: 'number', description: 'Yaw in degrees (Y rotation)' },
123
+ roll: {
124
+ type: 'number',
125
+ description: 'Roll in degrees (Z rotation)',
126
+ },
127
+ },
128
+ },
129
+ },
130
+ required: ['device'],
131
+ },
132
+ },
133
+ {
134
+ name: 'xr_look_at',
135
+ description: 'Orient a device to look at a specific world position',
136
+ inputSchema: {
137
+ type: 'object',
138
+ properties: {
139
+ device: {
140
+ type: 'string',
141
+ enum: [
142
+ 'headset',
143
+ 'controller-left',
144
+ 'controller-right',
145
+ 'hand-left',
146
+ 'hand-right',
147
+ ],
148
+ description: 'The device to orient',
149
+ },
150
+ target: {
151
+ type: 'object',
152
+ description: 'World position to look at',
153
+ properties: {
154
+ x: { type: 'number' },
155
+ y: { type: 'number' },
156
+ z: { type: 'number' },
157
+ },
158
+ required: ['x', 'y', 'z'],
159
+ },
160
+ moveToDistance: {
161
+ type: 'number',
162
+ description: 'Optional: move device to this distance from target',
163
+ },
164
+ },
165
+ required: ['device', 'target'],
166
+ },
167
+ },
168
+ {
169
+ name: 'xr_animate_to',
170
+ description: 'Smoothly animate a device to a new position/orientation over time',
171
+ inputSchema: {
172
+ type: 'object',
173
+ properties: {
174
+ device: {
175
+ type: 'string',
176
+ enum: [
177
+ 'headset',
178
+ 'controller-left',
179
+ 'controller-right',
180
+ 'hand-left',
181
+ 'hand-right',
182
+ ],
183
+ description: 'The device to animate',
184
+ },
185
+ position: {
186
+ type: 'object',
187
+ description: 'Target world position in meters',
188
+ properties: {
189
+ x: { type: 'number' },
190
+ y: { type: 'number' },
191
+ z: { type: 'number' },
192
+ },
193
+ },
194
+ orientation: {
195
+ type: 'object',
196
+ description: 'Target rotation as quaternion {x,y,z,w} or euler angles {pitch,yaw,roll} in degrees',
197
+ properties: {
198
+ x: { type: 'number', description: 'Quaternion X component' },
199
+ y: { type: 'number', description: 'Quaternion Y component' },
200
+ z: { type: 'number', description: 'Quaternion Z component' },
201
+ w: { type: 'number', description: 'Quaternion W component' },
202
+ pitch: {
203
+ type: 'number',
204
+ description: 'Pitch in degrees (X rotation)',
205
+ },
206
+ yaw: { type: 'number', description: 'Yaw in degrees (Y rotation)' },
207
+ roll: {
208
+ type: 'number',
209
+ description: 'Roll in degrees (Z rotation)',
210
+ },
211
+ },
212
+ },
213
+ duration: {
214
+ type: 'number',
215
+ description: 'Animation duration in seconds (default: 0.5)',
216
+ },
217
+ },
218
+ required: ['device'],
219
+ },
220
+ },
221
+ // =============================================================================
222
+ // Input Mode
223
+ // =============================================================================
224
+ {
225
+ name: 'xr_set_input_mode',
226
+ description: 'Switch between controller and hand tracking input modes',
227
+ inputSchema: {
228
+ type: 'object',
229
+ properties: {
230
+ mode: {
231
+ type: 'string',
232
+ enum: ['controller', 'hand'],
233
+ description: 'Input mode to switch to',
234
+ },
235
+ },
236
+ required: ['mode'],
237
+ },
238
+ },
239
+ {
240
+ name: 'xr_set_connected',
241
+ description: 'Connect or disconnect an input device',
242
+ inputSchema: {
243
+ type: 'object',
244
+ properties: {
245
+ device: {
246
+ type: 'string',
247
+ enum: [
248
+ 'controller-left',
249
+ 'controller-right',
250
+ 'hand-left',
251
+ 'hand-right',
252
+ ],
253
+ description: 'The input device',
254
+ },
255
+ connected: {
256
+ type: 'boolean',
257
+ description: 'Whether the device should be connected',
258
+ },
259
+ },
260
+ required: ['device', 'connected'],
261
+ },
262
+ },
263
+ // =============================================================================
264
+ // Select/Trigger Input
265
+ // =============================================================================
266
+ {
267
+ name: 'xr_get_select_value',
268
+ description: 'Get the current select (trigger/pinch) value for an input device',
269
+ inputSchema: {
270
+ type: 'object',
271
+ properties: {
272
+ device: {
273
+ type: 'string',
274
+ enum: [
275
+ 'controller-left',
276
+ 'controller-right',
277
+ 'hand-left',
278
+ 'hand-right',
279
+ ],
280
+ description: 'The input device',
281
+ },
282
+ },
283
+ required: ['device'],
284
+ },
285
+ },
286
+ {
287
+ name: 'xr_set_select_value',
288
+ description: 'Set the select (trigger/pinch) value for an input device. Use for grab-move-release patterns.',
289
+ inputSchema: {
290
+ type: 'object',
291
+ properties: {
292
+ device: {
293
+ type: 'string',
294
+ enum: [
295
+ 'controller-left',
296
+ 'controller-right',
297
+ 'hand-left',
298
+ 'hand-right',
299
+ ],
300
+ description: 'The input device',
301
+ },
302
+ value: {
303
+ type: 'number',
304
+ minimum: 0,
305
+ maximum: 1,
306
+ description: 'Select value (0=released, 1=fully pressed/pinched)',
307
+ },
308
+ },
309
+ required: ['device', 'value'],
310
+ },
311
+ },
312
+ {
313
+ name: 'xr_select',
314
+ description: 'Perform a complete select action (press and release). Dispatches selectstart, select, selectend events.',
315
+ inputSchema: {
316
+ type: 'object',
317
+ properties: {
318
+ device: {
319
+ type: 'string',
320
+ enum: [
321
+ 'controller-left',
322
+ 'controller-right',
323
+ 'hand-left',
324
+ 'hand-right',
325
+ ],
326
+ description: 'The input device',
327
+ },
328
+ duration: {
329
+ type: 'number',
330
+ description: 'How long to hold in seconds (default: 0.15)',
331
+ },
332
+ },
333
+ required: ['device'],
334
+ },
335
+ },
336
+ // =============================================================================
337
+ // Gamepad State (Controllers only)
338
+ // =============================================================================
339
+ {
340
+ name: 'xr_get_gamepad_state',
341
+ description: 'Get full gamepad state including all buttons and axes. Button indices in the result: 0=trigger, 1=squeeze, 2=thumbstick, 3=A/X, 4=B/Y, 5=thumbrest.',
342
+ inputSchema: {
343
+ type: 'object',
344
+ properties: {
345
+ device: {
346
+ type: 'string',
347
+ enum: ['controller-left', 'controller-right'],
348
+ description: 'The controller',
349
+ },
350
+ },
351
+ required: ['device'],
352
+ },
353
+ },
354
+ {
355
+ name: 'xr_set_gamepad_state',
356
+ description: 'Set gamepad button and axis values by index',
357
+ inputSchema: {
358
+ type: 'object',
359
+ properties: {
360
+ device: {
361
+ type: 'string',
362
+ enum: ['controller-left', 'controller-right'],
363
+ description: 'The controller',
364
+ },
365
+ buttons: {
366
+ type: 'array',
367
+ description: 'Button states to set',
368
+ items: {
369
+ type: 'object',
370
+ properties: {
371
+ index: {
372
+ type: 'number',
373
+ description: 'Button index (0=trigger, 1=squeeze, 2=thumbstick, 3=A/X, 4=B/Y, 5=thumbrest)',
374
+ },
375
+ value: { type: 'number', description: 'Button value 0-1' },
376
+ touched: {
377
+ type: 'boolean',
378
+ description: 'Whether button is touched',
379
+ },
380
+ },
381
+ required: ['index', 'value'],
382
+ },
383
+ },
384
+ axes: {
385
+ type: 'array',
386
+ description: 'Axis values to set',
387
+ items: {
388
+ type: 'object',
389
+ properties: {
390
+ index: {
391
+ type: 'number',
392
+ description: 'Axis index (0=thumbstick X, 1=thumbstick Y)',
393
+ },
394
+ value: { type: 'number', description: 'Axis value -1 to 1' },
395
+ },
396
+ required: ['index', 'value'],
397
+ },
398
+ },
399
+ },
400
+ required: ['device'],
401
+ },
402
+ },
403
+ // =============================================================================
404
+ // Screenshot
405
+ // =============================================================================
406
+ {
407
+ name: 'browser_screenshot',
408
+ description: 'Capture a screenshot of the browser. Returns the image directly.',
409
+ inputSchema: {
410
+ type: 'object',
411
+ properties: {},
412
+ },
413
+ },
414
+ // =============================================================================
415
+ // Device State
416
+ // =============================================================================
417
+ {
418
+ name: 'xr_get_device_state',
419
+ description: 'Get comprehensive state of the XR device including headset, controllers, and hands',
420
+ inputSchema: {
421
+ type: 'object',
422
+ properties: {},
423
+ required: [],
424
+ },
425
+ },
426
+ {
427
+ name: 'xr_set_device_state',
428
+ description: 'Set device state. When called with no state, resets everything to defaults.',
429
+ inputSchema: {
430
+ type: 'object',
431
+ properties: {
432
+ state: {
433
+ type: 'object',
434
+ description: 'Partial device state to apply. Omit to reset to defaults.',
435
+ properties: {
436
+ headset: {
437
+ type: 'object',
438
+ description: 'Headset transform',
439
+ properties: {
440
+ position: {
441
+ type: 'object',
442
+ properties: {
443
+ x: { type: 'number' },
444
+ y: { type: 'number' },
445
+ z: { type: 'number' },
446
+ },
447
+ },
448
+ orientation: {
449
+ type: 'object',
450
+ properties: {
451
+ x: { type: 'number' },
452
+ y: { type: 'number' },
453
+ z: { type: 'number' },
454
+ w: { type: 'number' },
455
+ },
456
+ },
457
+ },
458
+ },
459
+ inputMode: {
460
+ type: 'string',
461
+ enum: ['controller', 'hand'],
462
+ description: 'Input mode',
463
+ },
464
+ stereoEnabled: {
465
+ type: 'boolean',
466
+ description: 'Whether stereo rendering is enabled',
467
+ },
468
+ fov: {
469
+ type: 'number',
470
+ description: 'Field of view in degrees',
471
+ },
472
+ controllers: {
473
+ type: 'object',
474
+ description: 'Controller states',
475
+ properties: {
476
+ left: {
477
+ type: 'object',
478
+ properties: {
479
+ position: { type: 'object' },
480
+ orientation: { type: 'object' },
481
+ connected: { type: 'boolean' },
482
+ },
483
+ },
484
+ right: {
485
+ type: 'object',
486
+ properties: {
487
+ position: { type: 'object' },
488
+ orientation: { type: 'object' },
489
+ connected: { type: 'boolean' },
490
+ },
491
+ },
492
+ },
493
+ },
494
+ hands: {
495
+ type: 'object',
496
+ description: 'Hand states',
497
+ properties: {
498
+ left: {
499
+ type: 'object',
500
+ properties: {
501
+ position: { type: 'object' },
502
+ orientation: { type: 'object' },
503
+ connected: { type: 'boolean' },
504
+ },
505
+ },
506
+ right: {
507
+ type: 'object',
508
+ properties: {
509
+ position: { type: 'object' },
510
+ orientation: { type: 'object' },
511
+ connected: { type: 'boolean' },
512
+ },
513
+ },
514
+ },
515
+ },
516
+ },
517
+ },
518
+ },
519
+ },
520
+ },
521
+ // =============================================================================
522
+ // Console Logs (Plugin-specific, not in IWER)
523
+ // =============================================================================
524
+ {
525
+ name: 'browser_get_console_logs',
526
+ description: 'Get console logs from the browser with optional filtering. By default excludes debug level logs.',
527
+ inputSchema: {
528
+ type: 'object',
529
+ properties: {
530
+ count: {
531
+ type: 'number',
532
+ description: 'Maximum number of logs to return (most recent N)',
533
+ },
534
+ level: {
535
+ oneOf: [
536
+ {
537
+ type: 'string',
538
+ enum: ['log', 'info', 'warn', 'error', 'debug'],
539
+ },
540
+ {
541
+ type: 'array',
542
+ items: {
543
+ type: 'string',
544
+ enum: ['log', 'info', 'warn', 'error', 'debug'],
545
+ },
546
+ },
547
+ ],
548
+ description: 'Filter by log level(s). Default: ["log", "info", "warn", "error"] (excludes debug)',
549
+ },
550
+ pattern: {
551
+ type: 'string',
552
+ description: 'Regex pattern to filter log messages',
553
+ },
554
+ since: {
555
+ type: 'number',
556
+ description: 'Return logs since this timestamp (ms since epoch)',
557
+ },
558
+ },
559
+ },
560
+ },
561
+ {
562
+ name: 'browser_reload_page',
563
+ description: 'Reload the browser page to reset application state. Use when the app enters an unrecoverable state or to apply code changes.',
564
+ inputSchema: {
565
+ type: 'object',
566
+ properties: {},
567
+ },
568
+ },
569
+ // =============================================================================
570
+ // Framework-Specific Tools (IWSDK or any framework with FRAMEWORK_MCP_RUNTIME)
571
+ // =============================================================================
572
+ {
573
+ name: 'scene_get_hierarchy',
574
+ description: 'Get the Three.js scene hierarchy as a JSON tree. Returns object names, UUIDs, and entity indices where available. Requires IWSDK or a framework that provides FRAMEWORK_MCP_RUNTIME.',
575
+ inputSchema: {
576
+ type: 'object',
577
+ properties: {
578
+ parentId: {
579
+ type: 'string',
580
+ description: 'UUID of parent Object3D to start from. Defaults to scene root if omitted.',
581
+ },
582
+ maxDepth: {
583
+ type: 'number',
584
+ description: 'Maximum depth to traverse (default: 5). Use to limit context size.',
585
+ },
586
+ },
587
+ },
588
+ },
589
+ {
590
+ name: 'scene_get_object_transform',
591
+ description: 'Get local and global transforms of an Object3D. Includes positionRelativeToXROrigin which can be used directly with xr_look_at tool. Requires IWSDK or a framework that provides FRAMEWORK_MCP_RUNTIME.',
592
+ inputSchema: {
593
+ type: 'object',
594
+ properties: {
595
+ uuid: {
596
+ type: 'string',
597
+ description: 'UUID of the Object3D (get this from scene_get_hierarchy)',
598
+ },
599
+ },
600
+ required: ['uuid'],
601
+ },
602
+ },
603
+ // =============================================================================
604
+ // ECS Debugging (IWSDK — requires FRAMEWORK_MCP_RUNTIME)
605
+ // =============================================================================
606
+ {
607
+ name: 'ecs_pause',
608
+ description: 'Pause ECS system updates. The render loop continues (XR session stays alive, screenshots still work) but no systems tick. Use ecs_step to advance individual frames while paused. Requires FRAMEWORK_MCP_RUNTIME.',
609
+ inputSchema: {
610
+ type: 'object',
611
+ properties: {},
612
+ },
613
+ },
614
+ {
615
+ name: 'ecs_resume',
616
+ description: 'Resume ECS system updates after pausing. The first frame after resume uses a capped delta to avoid physics explosions. Requires FRAMEWORK_MCP_RUNTIME.',
617
+ inputSchema: {
618
+ type: 'object',
619
+ properties: {},
620
+ },
621
+ },
622
+ {
623
+ name: 'ecs_step',
624
+ description: 'Advance N ECS frames with a fixed timestep while paused. Must call ecs_pause first. Useful for frame-by-frame debugging. Requires FRAMEWORK_MCP_RUNTIME.',
625
+ inputSchema: {
626
+ type: 'object',
627
+ properties: {
628
+ count: {
629
+ type: 'number',
630
+ description: 'Number of frames to advance (1-120, default: 1)',
631
+ },
632
+ delta: {
633
+ type: 'number',
634
+ description: 'Fixed timestep in seconds for each frame (default: 1/72 ≈ 0.0139, matching Quest refresh rate)',
635
+ },
636
+ },
637
+ },
638
+ },
639
+ {
640
+ name: 'ecs_query_entity',
641
+ description: 'Get all component data for an entity. Use entityIndex from scene_get_hierarchy or ecs_find_entities. Returns serialized component values including vectors, entity refs, and Object3D references. Requires FRAMEWORK_MCP_RUNTIME.',
642
+ inputSchema: {
643
+ type: 'object',
644
+ properties: {
645
+ entityIndex: {
646
+ type: 'number',
647
+ description: 'Entity index (get this from scene_get_hierarchy or ecs_find_entities)',
648
+ },
649
+ components: {
650
+ type: 'array',
651
+ items: { type: 'string' },
652
+ description: 'Optional list of component IDs to include. If omitted, returns all components on the entity.',
653
+ },
654
+ },
655
+ required: ['entityIndex'],
656
+ },
657
+ },
658
+ {
659
+ name: 'ecs_find_entities',
660
+ description: 'Find entities by component composition and/or name. Returns entity indices and component lists. Use the returned entityIndex values with ecs_query_entity for detailed inspection. Requires FRAMEWORK_MCP_RUNTIME.',
661
+ inputSchema: {
662
+ type: 'object',
663
+ properties: {
664
+ withComponents: {
665
+ type: 'array',
666
+ items: { type: 'string' },
667
+ description: 'Component IDs that entities must have (AND logic)',
668
+ },
669
+ withoutComponents: {
670
+ type: 'array',
671
+ items: { type: 'string' },
672
+ description: 'Component IDs that entities must NOT have',
673
+ },
674
+ namePattern: {
675
+ type: 'string',
676
+ description: 'Regex pattern to match against entity Object3D name (case-insensitive)',
677
+ },
678
+ limit: {
679
+ type: 'number',
680
+ description: 'Maximum number of results (1-50, default: 50)',
681
+ },
682
+ },
683
+ },
684
+ },
685
+ {
686
+ name: 'ecs_list_systems',
687
+ description: 'List all registered ECS systems with name, priority, pause state, config keys, and query entity counts. Requires FRAMEWORK_MCP_RUNTIME.',
688
+ inputSchema: {
689
+ type: 'object',
690
+ properties: {},
691
+ },
692
+ },
693
+ {
694
+ name: 'ecs_list_components',
695
+ description: 'List all registered ECS components with their field schemas (type, default). Requires FRAMEWORK_MCP_RUNTIME.',
696
+ inputSchema: {
697
+ type: 'object',
698
+ properties: {},
699
+ },
700
+ },
701
+ {
702
+ name: 'ecs_toggle_system',
703
+ description: 'Pause or resume a specific ECS system by name. Use ecs_list_systems to discover system names. Requires FRAMEWORK_MCP_RUNTIME.',
704
+ inputSchema: {
705
+ type: 'object',
706
+ properties: {
707
+ name: {
708
+ type: 'string',
709
+ description: "System class name (e.g. 'OrbSystem', 'RobotSystem')",
710
+ },
711
+ paused: {
712
+ type: 'boolean',
713
+ description: 'Set to true to pause, false to resume. If omitted, toggles current state.',
714
+ },
715
+ },
716
+ required: ['name'],
717
+ },
718
+ },
719
+ {
720
+ name: 'ecs_set_component',
721
+ description: 'Set a component field value on an entity. Scalars use setValue (with validation), vectors accept arrays. Use ecs_query_entity to inspect current values first. Requires FRAMEWORK_MCP_RUNTIME.',
722
+ inputSchema: {
723
+ type: 'object',
724
+ properties: {
725
+ entityIndex: {
726
+ type: 'number',
727
+ description: 'Entity index (from ecs_find_entities or scene_get_hierarchy)',
728
+ },
729
+ componentId: {
730
+ type: 'string',
731
+ description: "Component ID (e.g. 'Orb', 'RobotMood', 'Transform')",
732
+ },
733
+ field: {
734
+ type: 'string',
735
+ description: "Field name within the component (e.g. 'orbitSpeed', 'mood')",
736
+ },
737
+ value: {
738
+ description: 'New value. Scalars: number/string/boolean. Vectors: array of numbers (e.g. [1,2,3] for Vec3).',
739
+ },
740
+ },
741
+ required: ['entityIndex', 'componentId', 'field', 'value'],
742
+ },
743
+ },
744
+ {
745
+ name: 'ecs_snapshot',
746
+ description: 'Capture a snapshot of all ECS entity/component state. Stores up to 2 snapshots. Use with ecs_diff to compare. Requires FRAMEWORK_MCP_RUNTIME.',
747
+ inputSchema: {
748
+ type: 'object',
749
+ properties: {
750
+ label: {
751
+ type: 'string',
752
+ description: 'Label for this snapshot (default: auto-generated). Use to reference in ecs_diff.',
753
+ },
754
+ },
755
+ },
756
+ },
757
+ {
758
+ name: 'ecs_diff',
759
+ description: 'Compare two ECS snapshots. Shows added/removed/changed entities and field-level diffs. Requires FRAMEWORK_MCP_RUNTIME.',
760
+ inputSchema: {
761
+ type: 'object',
762
+ properties: {
763
+ from: {
764
+ type: 'string',
765
+ description: "Label of the 'before' snapshot",
766
+ },
767
+ to: {
768
+ type: 'string',
769
+ description: "Label of the 'after' snapshot",
770
+ },
771
+ },
772
+ required: ['from', 'to'],
773
+ },
774
+ },
775
+ ];
776
+ const RUNTIME_TOOL_TO_METHOD = {
777
+ xr_get_session_status: 'get_session_status',
778
+ xr_accept_session: 'accept_session',
779
+ xr_end_session: 'end_session',
780
+ xr_get_transform: 'get_transform',
781
+ xr_set_transform: 'set_transform',
782
+ xr_look_at: 'look_at',
783
+ xr_animate_to: 'animate_to',
784
+ xr_set_input_mode: 'set_input_mode',
785
+ xr_set_connected: 'set_connected',
786
+ xr_get_select_value: 'get_select_value',
787
+ xr_set_select_value: 'set_select_value',
788
+ xr_select: 'select',
789
+ xr_get_gamepad_state: 'get_gamepad_state',
790
+ xr_set_gamepad_state: 'set_gamepad_state',
791
+ xr_get_device_state: 'get_device_state',
792
+ xr_set_device_state: 'set_device_state',
793
+ browser_screenshot: 'screenshot',
794
+ browser_get_console_logs: 'get_console_logs',
795
+ browser_reload_page: 'reload_page',
796
+ scene_get_hierarchy: 'get_scene_hierarchy',
797
+ scene_get_object_transform: 'get_object_transform',
798
+ };
799
+ const RUNTIME_CLI_PATHS = {
800
+ xr_get_session_status: ['xr', 'status'],
801
+ xr_accept_session: ['xr', 'enter'],
802
+ xr_end_session: ['xr', 'exit'],
803
+ xr_get_transform: ['xr', 'get-transform'],
804
+ xr_set_transform: ['xr', 'set-transform'],
805
+ xr_look_at: ['xr', 'look-at'],
806
+ xr_animate_to: ['xr', 'animate-to'],
807
+ xr_set_input_mode: ['xr', 'set-input-mode'],
808
+ xr_set_connected: ['xr', 'set-connected'],
809
+ xr_get_select_value: ['xr', 'get-select-value'],
810
+ xr_set_select_value: ['xr', 'set-select-value'],
811
+ xr_select: ['xr', 'select'],
812
+ xr_get_gamepad_state: ['xr', 'get-gamepad-state'],
813
+ xr_set_gamepad_state: ['xr', 'set-gamepad-state'],
814
+ browser_screenshot: ['browser', 'screenshot'],
815
+ xr_get_device_state: ['xr', 'get-device-state'],
816
+ xr_set_device_state: ['xr', 'set-device-state'],
817
+ browser_get_console_logs: ['browser', 'logs'],
818
+ browser_reload_page: ['browser', 'reload'],
819
+ scene_get_hierarchy: ['scene', 'hierarchy'],
820
+ scene_get_object_transform: ['scene', 'transform'],
821
+ ecs_pause: ['ecs', 'pause'],
822
+ ecs_resume: ['ecs', 'resume'],
823
+ ecs_step: ['ecs', 'step'],
824
+ ecs_query_entity: ['ecs', 'query'],
825
+ ecs_find_entities: ['ecs', 'find'],
826
+ ecs_list_systems: ['ecs', 'systems'],
827
+ ecs_list_components: ['ecs', 'components'],
828
+ ecs_toggle_system: ['ecs', 'toggle-system'],
829
+ ecs_set_component: ['ecs', 'set-component'],
830
+ ecs_snapshot: ['ecs', 'snapshot'],
831
+ ecs_diff: ['ecs', 'diff'],
832
+ };
833
+ RUNTIME_MCP_TOOLS.map((tool) => {
834
+ const cliPath = RUNTIME_CLI_PATHS[tool.name];
835
+ return {
836
+ id: cliPath ? cliPath.join('.') : tool.name,
837
+ domain: cliPath?.[0] ?? 'misc',
838
+ action: cliPath?.[1] ?? tool.name,
839
+ cliPath: cliPath ?? ['misc', tool.name],
840
+ mcpName: tool.name,
841
+ wsMethod: RUNTIME_TOOL_TO_METHOD[tool.name] ?? tool.name,
842
+ description: tool.description,
843
+ inputSchema: tool.inputSchema,
844
+ };
845
+ });
846
+
847
+ /**
848
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
849
+ *
850
+ * This source code is licensed under the MIT license found in the
851
+ * LICENSE file in the root directory of this source tree.
852
+ */
853
+ const RUNTIME_RPC_ERROR_CODE = -32e3;
854
+ function createUnavailableBrowserRpcError(browser) {
855
+ if (browser?.status === 'launch_failed') {
856
+ return {
857
+ code: RUNTIME_RPC_ERROR_CODE,
858
+ message: browser.lastError?.message ?? 'Managed browser launch failed.',
859
+ cause: browser.lastError?.cause ?? 'browser_launch_failed',
860
+ };
861
+ }
862
+ if (browser?.status === 'disconnected') {
863
+ return {
864
+ code: RUNTIME_RPC_ERROR_CODE,
865
+ message: browser.lastError?.message ??
866
+ 'Managed browser runtime disconnected from the MCP bridge.',
867
+ cause: browser.lastError?.cause ?? 'connection_lost',
868
+ };
869
+ }
870
+ if (browser?.connected && browser.commandReady === false) {
871
+ return {
872
+ code: RUNTIME_RPC_ERROR_CODE,
873
+ message: browser.lastError?.message ??
874
+ 'Managed browser command path is still warming up.',
875
+ cause: browser.lastError?.cause ?? 'browser_not_ready',
876
+ };
877
+ }
878
+ return {
879
+ code: RUNTIME_RPC_ERROR_CODE,
880
+ message: 'Browser not ready',
881
+ cause: browser?.lastError?.cause ?? 'browser_not_ready',
882
+ };
883
+ }
884
+
13
885
  /**
14
886
  * Copyright (c) Meta Platforms, Inc. and affiliates.
15
887
  *
@@ -17,6 +889,7 @@ import { fileURLToPath } from 'url';
17
889
  * LICENSE file in the root directory of this source tree.
18
890
  */
19
891
  const MAX_LOGS = 1000;
892
+ const TRACE_PREFIX = '[IWSDK-MCP-TRACE]';
20
893
  /** Map Playwright console message types to our LogLevel. */
21
894
  const PLAYWRIGHT_TYPE_MAP = {
22
895
  log: 'log',
@@ -87,10 +960,12 @@ let installPromise = null;
87
960
  * On install failure the flag stays unset so the next retry can try again.
88
961
  */
89
962
  async function ensureChromiumInstalled() {
90
- if (chromiumInstalled)
963
+ if (chromiumInstalled) {
91
964
  return;
92
- if (installPromise)
965
+ }
966
+ if (installPromise) {
93
967
  return installPromise;
968
+ }
94
969
  const execPath = chromium.executablePath();
95
970
  if (fs.existsSync(execPath)) {
96
971
  chromiumInstalled = true;
@@ -125,24 +1000,102 @@ async function doChromiumInstall() {
125
1000
  });
126
1001
  });
127
1002
  }
1003
+ /**
1004
+ * Check whether a GPU device is available. On macOS/Windows this always
1005
+ * returns true (Metal/D3D11 require a GPU by definition). On Linux it
1006
+ * probes /dev/dri/ for render nodes, which works in Docker, VMs, and
1007
+ * bare-metal environments without requiring external tools.
1008
+ */
1009
+ function hasGpuDevice() {
1010
+ if (os.platform() !== 'linux') {
1011
+ return true;
1012
+ }
1013
+ try {
1014
+ const entries = fs.readdirSync('/dev/dri');
1015
+ return entries.some((e) => e.startsWith('renderD') || e.startsWith('card'));
1016
+ }
1017
+ catch {
1018
+ return false;
1019
+ }
1020
+ }
1021
+ const VALID_GPU_VALUES = ['auto', 'gpu', 'swiftshader'];
1022
+ /**
1023
+ * Resolve the GPU / ANGLE backend for Chromium.
1024
+ *
1025
+ * Override with IWSDK_GPU env var:
1026
+ * - "auto" (default) auto-detect; hardware GL when a GPU is present,
1027
+ * SwiftShader otherwise
1028
+ * - "gpu" force hardware GL (fails if no GPU)
1029
+ * - "swiftshader" force CPU-based SwiftShader rendering
1030
+ */
1031
+ function resolveGpuBackend() {
1032
+ const envOverride = process.env.IWSDK_GPU?.toLowerCase();
1033
+ if (envOverride !== undefined && !VALID_GPU_VALUES.includes(envOverride)) {
1034
+ console.warn(`⚠️ IWSDK: Unknown IWSDK_GPU value "${process.env.IWSDK_GPU}". ` +
1035
+ 'Valid values: auto, gpu, swiftshader. Falling back to auto-detect.');
1036
+ }
1037
+ if (envOverride === 'swiftshader') {
1038
+ return {
1039
+ kind: 'swiftshader',
1040
+ useGl: 'angle',
1041
+ useAngle: 'swiftshader',
1042
+ reason: 'env-override',
1043
+ };
1044
+ }
1045
+ const platform = os.platform();
1046
+ if (platform === 'darwin') {
1047
+ return {
1048
+ kind: 'hardware',
1049
+ useGl: 'angle',
1050
+ useAngle: 'metal',
1051
+ reason: 'auto',
1052
+ };
1053
+ }
1054
+ if (platform === 'win32') {
1055
+ return {
1056
+ kind: 'hardware',
1057
+ useGl: 'angle',
1058
+ useAngle: 'd3d11',
1059
+ reason: 'auto',
1060
+ };
1061
+ }
1062
+ // Linux: honour explicit "gpu" override, otherwise auto-detect
1063
+ if (envOverride === 'gpu') {
1064
+ return {
1065
+ kind: 'hardware',
1066
+ useGl: 'angle',
1067
+ useAngle: 'gl',
1068
+ reason: 'env-override',
1069
+ };
1070
+ }
1071
+ if (hasGpuDevice()) {
1072
+ return { kind: 'hardware', useGl: 'angle', useAngle: 'gl', reason: 'auto' };
1073
+ }
1074
+ return {
1075
+ kind: 'swiftshader',
1076
+ useGl: 'angle',
1077
+ useAngle: 'swiftshader',
1078
+ reason: 'auto',
1079
+ };
1080
+ }
128
1081
  async function launchManagedBrowser(url, headless, verbose, viewport = null, screenshotSize = {
129
1082
  width: 800,
130
1083
  height: 800,
131
- }) {
1084
+ }, traceMcp = false) {
132
1085
  await ensureChromiumInstalled();
133
- // Select GPU backend based on platform
134
- const angleBackend = os.platform() === 'darwin'
135
- ? 'metal'
136
- : os.platform() === 'win32'
137
- ? 'd3d11'
138
- : 'gl';
1086
+ const backend = resolveGpuBackend();
1087
+ console.log(backend.kind === 'swiftshader'
1088
+ ? backend.reason === 'env-override'
1089
+ ? '🖥️ IWSDK: Using SwiftShader (software rendering) — IWSDK_GPU=swiftshader'
1090
+ : '🖥️ IWSDK: Using SwiftShader (software rendering) — no GPU detected'
1091
+ : `🖥️ IWSDK: Using hardware GPU (${backend.useAngle})`);
139
1092
  const browser = await chromium.launch({
140
1093
  headless,
141
1094
  args: [
142
- '--enable-webgl', // Ensure WebGL is available
143
- '--use-gl=angle', // Use ANGLE for WebGL
144
- `--use-angle=${angleBackend}`, // Platform-specific GPU backend
145
- '--disable-background-timer-throttling', // No rAF throttling
1095
+ '--enable-webgl',
1096
+ `--use-gl=${backend.useGl}`,
1097
+ `--use-angle=${backend.useAngle}`,
1098
+ '--disable-background-timer-throttling',
146
1099
  '--disable-renderer-backgrounding',
147
1100
  ],
148
1101
  });
@@ -165,7 +1118,7 @@ async function launchManagedBrowser(url, headless, verbose, viewport = null, scr
165
1118
  if (type === 'error') {
166
1119
  console.error('[browser]', text);
167
1120
  }
168
- else if (verbose) {
1121
+ else if (verbose || text.startsWith(TRACE_PREFIX)) {
169
1122
  console.log(`[browser:${type}]`, text);
170
1123
  }
171
1124
  });
@@ -191,9 +1144,10 @@ async function launchManagedBrowser(url, headless, verbose, viewport = null, scr
191
1144
  // Mark this tab as the Playwright-managed tab. The injection template
192
1145
  // checks this flag and only initializes the MCP WebSocket client when
193
1146
  // present, so manually-opened browser tabs are not remote-controlled.
194
- await page.addInitScript(() => {
1147
+ await page.addInitScript((traceEnabled) => {
195
1148
  window.__IWER_MCP_MANAGED = true;
196
- });
1149
+ window.__IWSDK_MCP_TRACE = traceEnabled;
1150
+ }, traceMcp);
197
1151
  await page.goto(url, { waitUntil: 'networkidle' });
198
1152
  // Wait for IWER to inject and XR device to be available
199
1153
  await page.waitForFunction(() => window.IWER_DEVICE !== undefined, {
@@ -228,6 +1182,21 @@ async function launchManagedBrowser(url, headless, verbose, viewport = null, scr
228
1182
  },
229
1183
  page,
230
1184
  queryLogs: (options) => consoleCapture.query(options),
1185
+ getTabMetadata: async () => page.evaluate(() => {
1186
+ const id = typeof sessionStorage !== 'undefined'
1187
+ ? sessionStorage.getItem('iwer-mcp-tab-id')
1188
+ : null;
1189
+ const rawGeneration = typeof sessionStorage !== 'undefined'
1190
+ ? sessionStorage.getItem('iwer-mcp-gen')
1191
+ : null;
1192
+ const generation = rawGeneration != null && rawGeneration !== ''
1193
+ ? Number(rawGeneration)
1194
+ : null;
1195
+ return {
1196
+ id,
1197
+ generation: Number.isFinite(generation) ? generation : null,
1198
+ };
1199
+ }),
231
1200
  screenshot: async () => {
232
1201
  const raw = await page.screenshot({ type: 'png' });
233
1202
  // In non-agent modes (viewport is null / freely resizable), downscale
@@ -271,11 +1240,11 @@ function hzdbTelemetry(args, clientVersion) {
271
1240
  if (clientVersion) {
272
1241
  globalArgs.push('--client-version', clientVersion);
273
1242
  }
274
- const child = execFile('npx', [...globalArgs, ...args], {
275
- timeout: 5000,
276
- shell: true,
1243
+ const child = spawn('npx', [...globalArgs, ...args], {
1244
+ stdio: 'ignore',
277
1245
  });
278
1246
  child.on('error', () => { });
1247
+ child.unref();
279
1248
  }
280
1249
  function reportSessionStart(sessionId, opts) {
281
1250
  const args = ['session-start', '--session-id', sessionId];
@@ -441,216 +1410,132 @@ function createRelayHandler(options) {
441
1410
  * This source code is licensed under the MIT license found in the
442
1411
  * LICENSE file in the root directory of this source tree.
443
1412
  */
444
- const MCP_CONFIG_TARGETS = {
445
- claude: { file: '.mcp.json', jsonKey: 'mcpServers', format: 'json' },
446
- cursor: { file: '.cursor/mcp.json', jsonKey: 'mcpServers', format: 'json' },
447
- copilot: { file: '.vscode/mcp.json', jsonKey: 'servers', format: 'json' },
448
- codex: { file: '.codex/config.toml', jsonKey: null, format: 'toml' },
449
- };
450
- const TOML_BLOCK_START = '# --- IWER managed (do not edit) ---';
451
- const TOML_BLOCK_END = '# --- end IWER managed ---';
452
- /**
453
- * Merge our server entries into an existing (or new) JSON config file.
454
- * When `managedKeys` is provided, any key in that list that is NOT in
455
- * `serverEntries` is removed — this prevents stale entries from surviving
456
- * across config changes (e.g. uninstalling an optional MCP server).
457
- * Returns true if the file was newly created.
458
- */
459
- async function mergeJsonConfig(filePath, serverEntries, jsonKey, managedKeys) {
460
- let existing = {};
461
- let created = false;
462
- try {
463
- const raw = await readFile(filePath, 'utf-8');
464
- existing = JSON.parse(raw);
465
- }
466
- catch {
467
- created = true;
468
- }
469
- const section = existing[jsonKey] ?? {};
470
- if (managedKeys) {
471
- for (const key of managedKeys) {
472
- if (!(key in serverEntries)) {
473
- delete section[key];
474
- }
475
- }
1413
+ function isTraceEnabled() {
1414
+ return process.env.IWSDK_RUNTIME_TRACE === '1';
1415
+ }
1416
+ function traceRuntimeSession(event, details = {}) {
1417
+ if (!isTraceEnabled()) {
1418
+ return;
476
1419
  }
477
- Object.assign(section, serverEntries);
478
- existing[jsonKey] = section;
479
- await mkdir(path.dirname(filePath), { recursive: true });
480
- await writeFile(filePath, JSON.stringify(existing, null, 2) + '\n');
481
- return created;
1420
+ console.error(`[IWSDK-RUNTIME-TRACE][session] ${event} ${JSON.stringify(details)}`);
482
1421
  }
483
- /**
484
- * Remove our managed server keys from a JSON config file.
485
- * If we originally created the file and the servers section is now empty
486
- * with no other top-level keys, delete the file entirely.
487
- *
488
- * @internal Not called by the plugin at runtime (MCP configs are left in
489
- * place on shutdown). Kept as a tested utility for potential external use.
490
- */
491
- async function unmergeJsonConfig(filePath, serverKeys, jsonKey, weCreatedFile) {
492
- let raw;
1422
+ function normalizeWorkspaceRoot(workspaceRoot) {
1423
+ const resolved = path__default.resolve(workspaceRoot);
493
1424
  try {
494
- raw = await readFile(filePath, 'utf-8');
1425
+ return existsSync(resolved) ? realpathSync.native(resolved) : resolved;
495
1426
  }
496
1427
  catch {
497
- return; // file doesn't exist — no-op
1428
+ return resolved;
498
1429
  }
499
- let existing;
1430
+ }
1431
+ function getRuntimeSessionFilePath(workspaceRoot) {
1432
+ return path__default.join(normalizeWorkspaceRoot(workspaceRoot), IWSDK_RUNTIME_SESSION_PATH);
1433
+ }
1434
+ const sessionMutationQueues = new Map();
1435
+ async function enqueueSessionMutation(workspaceRoot, mutate) {
1436
+ const normalizedWorkspaceRoot = normalizeWorkspaceRoot(workspaceRoot);
1437
+ const previous = sessionMutationQueues.get(normalizedWorkspaceRoot) ?? Promise.resolve();
1438
+ const next = previous
1439
+ .catch(() => { })
1440
+ .then(() => mutate(normalizedWorkspaceRoot));
1441
+ sessionMutationQueues.set(normalizedWorkspaceRoot, next);
500
1442
  try {
501
- existing = JSON.parse(raw);
502
- }
503
- catch {
504
- return; // invalid JSON — leave it alone
1443
+ return await next;
505
1444
  }
506
- const section = existing[jsonKey];
507
- if (section) {
508
- for (const key of serverKeys) {
509
- delete section[key];
1445
+ finally {
1446
+ if (sessionMutationQueues.get(normalizedWorkspaceRoot) === next) {
1447
+ sessionMutationQueues.delete(normalizedWorkspaceRoot);
510
1448
  }
511
- if (Object.keys(section).length === 0) {
512
- delete existing[jsonKey];
513
- }
514
- }
515
- if (weCreatedFile && Object.keys(existing).length === 0) {
516
- try {
517
- await unlink(filePath);
518
- }
519
- catch { }
520
- }
521
- else {
522
- await writeFile(filePath, JSON.stringify(existing, null, 2) + '\n');
523
1449
  }
524
1450
  }
525
- /**
526
- * Merge our managed TOML block into an existing (or new) config file.
527
- * Returns true if the file was newly created.
528
- */
529
- async function mergeTomlConfig(filePath, serverEntries) {
530
- let existing = '';
531
- let created = false;
1451
+ async function readRuntimeSession(filePath) {
532
1452
  try {
533
- existing = await readFile(filePath, 'utf-8');
1453
+ const raw = await readFile(filePath, 'utf8');
1454
+ return JSON.parse(raw);
534
1455
  }
535
1456
  catch {
536
- created = true;
537
- }
538
- // Remove any old managed block
539
- const startIdx = existing.indexOf(TOML_BLOCK_START);
540
- const endIdx = existing.indexOf(TOML_BLOCK_END);
541
- if (startIdx !== -1 && endIdx !== -1 && startIdx < endIdx) {
542
- existing =
543
- existing.slice(0, startIdx).trimEnd() +
544
- '\n' +
545
- existing.slice(endIdx + TOML_BLOCK_END.length).trimStart();
546
- existing = existing.trim();
1457
+ return null;
547
1458
  }
548
- // Build new managed block
549
- const tomlLines = [TOML_BLOCK_START];
550
- for (const [name, entry] of Object.entries(serverEntries)) {
551
- tomlLines.push(`[mcp_servers.${name}]`);
552
- tomlLines.push(`command = ${JSON.stringify(entry.command)}`);
553
- tomlLines.push(`args = [${entry.args.map((a) => JSON.stringify(a)).join(', ')}]`);
554
- tomlLines.push('');
555
- }
556
- tomlLines.push(TOML_BLOCK_END);
557
- const newContent = existing
558
- ? existing.trimEnd() + '\n\n' + tomlLines.join('\n') + '\n'
559
- : tomlLines.join('\n') + '\n';
560
- await mkdir(path.dirname(filePath), { recursive: true });
561
- await writeFile(filePath, newContent);
562
- return created;
563
1459
  }
564
- /**
565
- * Remove our managed TOML block from a config file.
566
- * If we originally created the file and it's now effectively empty, delete it.
567
- *
568
- * @internal Not called by the plugin at runtime (MCP configs are left in
569
- * place on shutdown). Kept as a tested utility for potential external use.
570
- */
571
- async function unmergeTomlConfig(filePath, weCreatedFile) {
572
- let existing;
1460
+ async function writeRuntimeSession(workspaceRoot, session) {
1461
+ const filePath = getRuntimeSessionFilePath(workspaceRoot);
1462
+ await mkdir(path__default.dirname(filePath), { recursive: true });
1463
+ const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
573
1464
  try {
574
- existing = await readFile(filePath, 'utf-8');
1465
+ await writeFile(tempPath, `${JSON.stringify(session, null, 2)}\n`, 'utf8');
1466
+ await rename(tempPath, filePath);
575
1467
  }
576
- catch {
577
- return; // file doesn't exist — no-op
578
- }
579
- const startIdx = existing.indexOf(TOML_BLOCK_START);
580
- const endIdx = existing.indexOf(TOML_BLOCK_END);
581
- if (startIdx === -1 || endIdx === -1 || startIdx >= endIdx) {
582
- // No managed block found — nothing to remove
583
- if (weCreatedFile && existing.trim() === '') {
584
- try {
585
- await unlink(filePath);
586
- }
587
- catch { }
588
- }
589
- return;
590
- }
591
- const cleaned = existing.slice(0, startIdx).trimEnd() +
592
- '\n' +
593
- existing.slice(endIdx + TOML_BLOCK_END.length).trimStart();
594
- const result = cleaned.trim();
595
- if (weCreatedFile && result === '') {
596
- try {
597
- await unlink(filePath);
598
- }
599
- catch { }
600
- }
601
- else {
602
- await writeFile(filePath, result + '\n');
1468
+ finally {
1469
+ await rm(tempPath, { force: true }).catch(() => { });
603
1470
  }
1471
+ return session;
604
1472
  }
605
- /**
606
- * Warm up the RAG MCP server by spawning it and waiting for initialization.
607
- * This downloads the HuggingFace embedding model if not already cached.
608
- * The process is killed after initialization completes.
609
- */
610
- function warmupRagMcp(ragMcpServerPath, verbose) {
611
- if (!existsSync(ragMcpServerPath)) {
612
- if (verbose) {
613
- console.log('[RAG-MCP] Server not found, skipping warmup');
614
- }
615
- return;
616
- }
617
- console.log('📚 RAG-MCP: Warming up (downloading model if needed)...');
618
- const warmupProcess = spawn('node', [ragMcpServerPath], {
619
- stdio: ['pipe', 'pipe', 'pipe'],
620
- });
621
- let initialized = false;
622
- warmupProcess.stderr?.on('data', (data) => {
623
- const output = data.toString();
624
- if (verbose) {
625
- // Print warmup progress
626
- process.stderr.write(`[RAG-MCP Warmup] ${output}`);
627
- }
628
- // Check if initialization is complete
629
- if (output.includes('IWSDK RAG MCP Server is ready')) {
630
- initialized = true;
631
- clearTimeout(warmupTimeout);
632
- console.log('📚 RAG-MCP: Model cached successfully');
633
- warmupProcess.kill('SIGTERM');
634
- }
1473
+ async function registerRuntimeSession(input) {
1474
+ return enqueueSessionMutation(input.workspaceRoot, async (workspaceRoot) => {
1475
+ const existing = await readRuntimeSession(getRuntimeSessionFilePath(workspaceRoot));
1476
+ const now = new Date().toISOString();
1477
+ const session = {
1478
+ schemaVersion: IWSDK_RUNTIME_STATE_SCHEMA_VERSION,
1479
+ sessionId: input.sessionId,
1480
+ workspaceRoot,
1481
+ pid: input.pid,
1482
+ port: input.port,
1483
+ localUrl: input.localUrl,
1484
+ networkUrls: input.networkUrls ?? [],
1485
+ aiMode: input.aiMode,
1486
+ browser: input.browser ?? existing?.browser,
1487
+ registeredAt: existing?.registeredAt ?? now,
1488
+ updatedAt: now,
1489
+ };
1490
+ traceRuntimeSession('register', {
1491
+ workspaceRoot,
1492
+ port: input.port,
1493
+ browserStatus: session.browser?.status ?? null,
1494
+ bridgeConnected: session.browser?.connected ?? false,
1495
+ commandReady: session.browser?.commandReady ?? false,
1496
+ });
1497
+ return writeRuntimeSession(workspaceRoot, session);
635
1498
  });
636
- warmupProcess.on('error', (error) => {
637
- if (verbose) {
638
- console.error('[RAG-MCP] Warmup error:', error.message);
1499
+ }
1500
+ async function setRuntimeSessionBrowserState(workspaceRoot, browser) {
1501
+ return enqueueSessionMutation(workspaceRoot, async (normalizedWorkspaceRoot) => {
1502
+ const existing = await readRuntimeSession(getRuntimeSessionFilePath(normalizedWorkspaceRoot));
1503
+ if (!existing) {
1504
+ return null;
639
1505
  }
1506
+ const session = {
1507
+ ...existing,
1508
+ browser,
1509
+ updatedAt: new Date().toISOString(),
1510
+ };
1511
+ traceRuntimeSession('set_browser_state', {
1512
+ workspaceRoot: normalizedWorkspaceRoot,
1513
+ browserStatus: browser.status,
1514
+ bridgeConnected: browser.connected,
1515
+ commandReady: browser.commandReady,
1516
+ connectedClientCount: browser.connectedClientCount,
1517
+ lastError: browser.lastError ?? null,
1518
+ });
1519
+ return writeRuntimeSession(normalizedWorkspaceRoot, session);
640
1520
  });
641
- warmupProcess.on('exit', (code) => {
642
- if (!initialized && code !== 0 && verbose) {
643
- console.warn(`[RAG-MCP] Warmup process exited with code ${code}`);
644
- }
1521
+ }
1522
+ async function unregisterRuntimeSession(workspaceRoot) {
1523
+ await enqueueSessionMutation(workspaceRoot, async (normalizedWorkspaceRoot) => {
1524
+ traceRuntimeSession('unregister', {
1525
+ workspaceRoot: normalizedWorkspaceRoot,
1526
+ });
1527
+ await rm(getRuntimeSessionFilePath(normalizedWorkspaceRoot), {
1528
+ force: true,
1529
+ }).catch(() => { });
645
1530
  });
646
- // Safety timeout - kill after 5 minutes if still running
647
- const warmupTimeout = setTimeout(() => {
648
- if (!initialized && !warmupProcess.killed) {
649
- console.warn('[RAG-MCP] Warmup timeout, killing process');
650
- warmupProcess.kill('SIGTERM');
651
- }
652
- }, 5 * 60 * 1000);
653
1531
  }
1532
+
1533
+ /**
1534
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
1535
+ *
1536
+ * This source code is licensed under the MIT license found in the
1537
+ * LICENSE file in the root directory of this source tree.
1538
+ */
654
1539
  /**
655
1540
  * Derive internal headless / devUI / viewport settings from the AI mode.
656
1541
  */
@@ -694,7 +1579,6 @@ function processOptions(options = {}) {
694
1579
  };
695
1580
  processed.ai = {
696
1581
  mode,
697
- tools: options.ai.tools ?? ['claude'],
698
1582
  headless: settings.headless,
699
1583
  devUI: settings.devUI,
700
1584
  viewport: settings.fixedViewport ? screenshotSize : null,
@@ -749,10 +1633,74 @@ function iwsdkDev(options = {}) {
749
1633
  }
750
1634
  // Closure-scoped state for browser auto-recovery
751
1635
  let browserLaunchPromise = null;
1636
+ let browserCommandReadyPromise = null;
1637
+ let browserRuntimeClients = null;
752
1638
  let serverShuttingDown = false;
753
1639
  let browserUrl = '';
754
1640
  let consecutiveFailures = 0;
1641
+ let currentBrowserState = null;
755
1642
  const MAX_LAUNCH_FAILURES = 3;
1643
+ const BRIDGE_READY_TIMEOUT_MS = 5000;
1644
+ const traceEnabled = process.env.IWSDK_RUNTIME_TRACE === '1';
1645
+ const wsConnectionIds = new WeakMap();
1646
+ const wsConnectionKinds = new WeakMap();
1647
+ const traceRuntime = (event, details = {}) => {
1648
+ if (!traceEnabled) {
1649
+ return;
1650
+ }
1651
+ console.error(`[IWSDK-RUNTIME-TRACE][vite] ${event} ${JSON.stringify(details)}`);
1652
+ };
1653
+ const getConnectionId = (ws) => wsConnectionIds.get(ws) ?? 'unknown';
1654
+ const getConnectionKind = (ws) => wsConnectionKinds.get(ws) ?? 'command';
1655
+ const markConnectionKind = (ws, kind) => {
1656
+ wsConnectionKinds.set(ws, kind);
1657
+ };
1658
+ const createBrowserIssue = (cause, message) => ({
1659
+ cause,
1660
+ message,
1661
+ at: new Date().toISOString(),
1662
+ });
1663
+ const classifyBrowserLaunchFailure = (message) => /permission|not permitted|denied|sandbox|eacces|eperm/i.test(message)
1664
+ ? 'permission_denied'
1665
+ : 'browser_launch_failed';
1666
+ const createBrowserState = (status, options = {}, previous = currentBrowserState) => {
1667
+ const connectedClientCount = options.connectedClientCount ?? browserRuntimeClients?.size ?? 0;
1668
+ const connected = options.connected ?? status === 'connected';
1669
+ const commandReady = options.commandReady ?? false;
1670
+ return {
1671
+ status,
1672
+ connected,
1673
+ commandReady,
1674
+ connectedClientCount,
1675
+ lastTransitionAt: new Date().toISOString(),
1676
+ ...((options.lastBridgeConnectedAt ?? previous?.lastBridgeConnectedAt)
1677
+ ? {
1678
+ lastBridgeConnectedAt: options.lastBridgeConnectedAt ??
1679
+ previous?.lastBridgeConnectedAt,
1680
+ }
1681
+ : {}),
1682
+ ...((options.lastCommandReadyAt ?? previous?.lastCommandReadyAt)
1683
+ ? {
1684
+ lastCommandReadyAt: options.lastCommandReadyAt ?? previous?.lastCommandReadyAt,
1685
+ }
1686
+ : {}),
1687
+ ...(options.lastError ? { lastError: options.lastError } : {}),
1688
+ };
1689
+ };
1690
+ currentBrowserState = createBrowserState('launching', { connected: false }, null);
1691
+ const publishBrowserState = (browser) => {
1692
+ currentBrowserState = browser;
1693
+ traceRuntime('browser_state', {
1694
+ status: browser.status,
1695
+ bridgeConnected: browser.connected,
1696
+ commandReady: browser.commandReady,
1697
+ connectedClientCount: browser.connectedClientCount,
1698
+ lastError: browser.lastError ?? null,
1699
+ });
1700
+ void setRuntimeSessionBrowserState(config.root, browser).catch((error) => {
1701
+ console.error('[IWSDK Dev] Failed to update browser state:', error);
1702
+ });
1703
+ };
756
1704
  /**
757
1705
  * Launch (or re-launch) the Playwright-managed browser.
758
1706
  * Guards against concurrent launches via `browserLaunchPromise`.
@@ -763,14 +1711,40 @@ function iwsdkDev(options = {}) {
763
1711
  return browserLaunchPromise;
764
1712
  }
765
1713
  browserLaunchPromise = (async () => {
1714
+ publishBrowserState(createBrowserState('launching'));
1715
+ traceRuntime('browser_launch_start', {
1716
+ browserUrl,
1717
+ headless: pluginOptions.ai.headless,
1718
+ });
766
1719
  try {
767
- const browser = await launchManagedBrowser(browserUrl, pluginOptions.ai.headless, pluginOptions.verbose, pluginOptions.ai.viewport, pluginOptions.ai.screenshotSize);
1720
+ const browser = await launchManagedBrowser(browserUrl, pluginOptions.ai.headless, pluginOptions.verbose, pluginOptions.ai.viewport, pluginOptions.ai.screenshotSize, traceEnabled);
768
1721
  managedBrowser = browser;
769
1722
  consecutiveFailures = 0;
1723
+ traceRuntime('browser_launch_success', {
1724
+ browserRuntimeClients: browserRuntimeClients?.size ?? 0,
1725
+ });
1726
+ publishBrowserState(createBrowserState((browserRuntimeClients?.size ?? 0) > 0
1727
+ ? 'connected'
1728
+ : 'waiting_for_connection', {
1729
+ connected: (browserRuntimeClients?.size ?? 0) > 0,
1730
+ commandReady: false,
1731
+ lastBridgeConnectedAt: (browserRuntimeClients?.size ?? 0) > 0
1732
+ ? new Date().toISOString()
1733
+ : undefined,
1734
+ }));
770
1735
  // On unexpected close, mark as null. The browser will be
771
1736
  // relaunched lazily on the next MCP request via ensureBrowser().
772
1737
  browser.onClose(() => {
773
1738
  managedBrowser = null;
1739
+ browserCommandReadyPromise = null;
1740
+ traceRuntime('browser_closed', {
1741
+ serverShuttingDown,
1742
+ });
1743
+ publishBrowserState(createBrowserState('disconnected', {
1744
+ connected: false,
1745
+ commandReady: false,
1746
+ lastError: createBrowserIssue('connection_lost', 'Managed browser closed unexpectedly. It will relaunch on the next MCP request.'),
1747
+ }));
774
1748
  if (!serverShuttingDown) {
775
1749
  console.log('🔄 IWSDK: Browser closed. Will relaunch on next MCP request.');
776
1750
  }
@@ -778,6 +1752,16 @@ function iwsdkDev(options = {}) {
778
1752
  }
779
1753
  catch (error) {
780
1754
  consecutiveFailures++;
1755
+ const message = error instanceof Error ? error.message : String(error);
1756
+ traceRuntime('browser_launch_failed', {
1757
+ consecutiveFailures,
1758
+ message,
1759
+ });
1760
+ publishBrowserState(createBrowserState('launch_failed', {
1761
+ connected: false,
1762
+ commandReady: false,
1763
+ lastError: createBrowserIssue(classifyBrowserLaunchFailure(message), message),
1764
+ }));
781
1765
  console.error('❌ IWSDK: Failed to launch browser:', error);
782
1766
  if (consecutiveFailures >= MAX_LAUNCH_FAILURES) {
783
1767
  console.error(`❌ IWSDK: ${MAX_LAUNCH_FAILURES} consecutive launch failures, giving up. ` +
@@ -798,17 +1782,111 @@ function iwsdkDev(options = {}) {
798
1782
  const ensureBrowser = async () => {
799
1783
  const current = managedBrowser;
800
1784
  if (current && !current.isClosed()) {
1785
+ traceRuntime('ensure_browser_reuse', {
1786
+ browserRuntimeClients: browserRuntimeClients?.size ?? 0,
1787
+ });
801
1788
  return { browser: current, relaunched: false };
802
1789
  }
803
1790
  managedBrowser = null;
804
1791
  if (consecutiveFailures >= MAX_LAUNCH_FAILURES) {
1792
+ traceRuntime('ensure_browser_aborted', {
1793
+ consecutiveFailures,
1794
+ });
805
1795
  return { browser: null, relaunched: false };
806
1796
  }
807
1797
  await launchBrowser();
1798
+ traceRuntime('ensure_browser_relaunch_result', {
1799
+ relaunched: managedBrowser !== null,
1800
+ browserRuntimeClients: browserRuntimeClients?.size ?? 0,
1801
+ });
808
1802
  return { browser: managedBrowser, relaunched: managedBrowser !== null };
809
1803
  };
1804
+ const waitForBridgeConnection = async (timeoutMs, reason) => {
1805
+ const startedAt = Date.now();
1806
+ traceRuntime('bridge_wait_start', {
1807
+ reason,
1808
+ timeoutMs,
1809
+ browserRuntimeClients: browserRuntimeClients?.size ?? 0,
1810
+ });
1811
+ while (Date.now() - startedAt < timeoutMs) {
1812
+ if ((browserRuntimeClients?.size ?? 0) > 0) {
1813
+ const waitedForBridgeMs = Date.now() - startedAt;
1814
+ traceRuntime('bridge_wait_ready', {
1815
+ reason,
1816
+ waitedForBridgeMs,
1817
+ });
1818
+ return waitedForBridgeMs;
1819
+ }
1820
+ await new Promise((resolve) => setTimeout(resolve, 100));
1821
+ }
1822
+ const waitedForBridgeMs = Date.now() - startedAt;
1823
+ traceRuntime('bridge_wait_timeout', {
1824
+ reason,
1825
+ waitedForBridgeMs,
1826
+ });
1827
+ return waitedForBridgeMs;
1828
+ };
1829
+ const ensureBrowserCommandReady = async (reason) => {
1830
+ if (browserCommandReadyPromise) {
1831
+ return browserCommandReadyPromise;
1832
+ }
1833
+ browserCommandReadyPromise = (async () => {
1834
+ const { browser, relaunched } = await ensureBrowser();
1835
+ if (!browser) {
1836
+ return {
1837
+ browser: null,
1838
+ relaunched: false,
1839
+ bridgeConnected: false,
1840
+ waitedForBridgeMs: 0,
1841
+ };
1842
+ }
1843
+ const needsBridgeWait = relaunched ||
1844
+ !currentBrowserState?.connected ||
1845
+ currentBrowserState?.commandReady === false;
1846
+ const waitedForBridgeMs = needsBridgeWait
1847
+ ? await waitForBridgeConnection(BRIDGE_READY_TIMEOUT_MS, reason)
1848
+ : 0;
1849
+ const bridgeConnected = (browserRuntimeClients?.size ?? 0) > 0;
1850
+ if (bridgeConnected) {
1851
+ publishBrowserState(createBrowserState('connected', {
1852
+ connected: true,
1853
+ commandReady: true,
1854
+ connectedClientCount: browserRuntimeClients.size,
1855
+ lastBridgeConnectedAt: currentBrowserState?.lastBridgeConnectedAt ??
1856
+ new Date().toISOString(),
1857
+ lastCommandReadyAt: new Date().toISOString(),
1858
+ }));
1859
+ }
1860
+ else {
1861
+ publishBrowserState(createBrowserState('waiting_for_connection', {
1862
+ connected: false,
1863
+ commandReady: false,
1864
+ connectedClientCount: 0,
1865
+ lastError: createBrowserIssue(relaunched ? 'browser_relaunched' : 'browser_not_ready', relaunched
1866
+ ? 'Browser relaunched and is waiting for the runtime bridge to reconnect.'
1867
+ : 'Managed browser bridge has not connected yet.'),
1868
+ }));
1869
+ }
1870
+ traceRuntime('browser_command_ready_result', {
1871
+ reason,
1872
+ relaunched,
1873
+ bridgeConnected,
1874
+ waitedForBridgeMs,
1875
+ });
1876
+ return {
1877
+ browser,
1878
+ relaunched,
1879
+ bridgeConnected,
1880
+ waitedForBridgeMs,
1881
+ };
1882
+ })().finally(() => {
1883
+ browserCommandReadyPromise = null;
1884
+ });
1885
+ return browserCommandReadyPromise;
1886
+ };
810
1887
  // Initialize WebSocket server and client tracking
811
1888
  mcpClients = new Set();
1889
+ browserRuntimeClients = new Set();
812
1890
  mcpWss = new WebSocketServer({ noServer: true });
813
1891
  // First-response-wins relay handler (extracted for testability)
814
1892
  const relay = createRelayHandler({
@@ -819,96 +1897,243 @@ function iwsdkDev(options = {}) {
819
1897
  relay.cleanStale(60000);
820
1898
  }, 60000);
821
1899
  relayCleanupInterval.unref();
1900
+ const BROWSER_RELAUNCHED_RESULT = {
1901
+ status: 'browser_relaunched',
1902
+ message: 'Browser was closed and has been relaunched. ' +
1903
+ 'The page state has been reset — please retry your request.',
1904
+ };
1905
+ const sendWsJson = (ws, payload, context) => {
1906
+ if (ws.readyState !== WebSocket.OPEN) {
1907
+ traceRuntime('ws_send_skipped', {
1908
+ connectionId: getConnectionId(ws),
1909
+ kind: getConnectionKind(ws),
1910
+ context,
1911
+ readyState: ws.readyState,
1912
+ });
1913
+ return;
1914
+ }
1915
+ traceRuntime('ws_send', {
1916
+ connectionId: getConnectionId(ws),
1917
+ kind: getConnectionKind(ws),
1918
+ context,
1919
+ id: payload.id ?? null,
1920
+ });
1921
+ ws.send(JSON.stringify(payload));
1922
+ };
1923
+ const sendUnavailableBrowser = (ws, requestId, context) => {
1924
+ sendWsJson(ws, {
1925
+ id: requestId,
1926
+ error: createUnavailableBrowserRpcError(currentBrowserState),
1927
+ }, context);
1928
+ };
1929
+ const sendInternalError = (ws, requestId, error, context) => {
1930
+ sendWsJson(ws, {
1931
+ id: requestId,
1932
+ error: {
1933
+ code: -32e3,
1934
+ message: error instanceof Error ? error.message : String(error),
1935
+ },
1936
+ }, context);
1937
+ };
1938
+ const createBrowserProbeResult = (waitedForBridgeMs) => ({
1939
+ bridgeConnected: Boolean(currentBrowserState?.connected),
1940
+ commandReady: Boolean(currentBrowserState?.commandReady),
1941
+ waitedForBridgeMs,
1942
+ browser: currentBrowserState ??
1943
+ createBrowserState('launching', {
1944
+ connected: false,
1945
+ commandReady: false,
1946
+ }),
1947
+ });
822
1948
  mcpWss.on('connection', (ws) => {
1949
+ const connectionId = randomUUID();
1950
+ wsConnectionIds.set(ws, connectionId);
1951
+ markConnectionKind(ws, 'command');
823
1952
  mcpClients.add(ws);
1953
+ traceRuntime('ws_connected', {
1954
+ connectionId,
1955
+ kind: getConnectionKind(ws),
1956
+ });
824
1957
  if (pluginOptions.verbose) {
825
1958
  console.log('[IWSDK-MCP] Client connected');
826
1959
  }
827
1960
  ws.on('message', async (data) => {
828
1961
  const message = data.toString();
1962
+ traceRuntime('ws_message', {
1963
+ connectionId,
1964
+ kind: getConnectionKind(ws),
1965
+ bytes: data.length,
1966
+ });
829
1967
  if (pluginOptions.verbose) {
830
1968
  console.log('[IWSDK-MCP] Message received:', message.substring(0, 100));
831
1969
  }
832
- // Intercept server-side tools that use Playwright directly.
833
- // These respond from the Node process without a browser round-trip.
834
1970
  let intercepted = false;
835
1971
  try {
836
1972
  const parsed = JSON.parse(message);
837
- const BROWSER_RELAUNCHED_RESULT = {
838
- status: 'browser_relaunched',
839
- message: 'Browser was closed and has been relaunched. ' +
840
- 'The page state has been reset — please retry your request.',
841
- };
842
- // Console logs: Playwright captures via CDP
843
- if (parsed.method === 'get_console_logs' && parsed.id) {
1973
+ if (parsed?.type === 'iwsdk_browser_hello') {
844
1974
  intercepted = true;
845
- const { browser, relaunched } = await ensureBrowser();
846
- if (relaunched) {
847
- ws.send(JSON.stringify({
848
- id: parsed.id,
849
- result: BROWSER_RELAUNCHED_RESULT,
1975
+ markConnectionKind(ws, 'bridge');
1976
+ if (!browserRuntimeClients.has(ws)) {
1977
+ browserRuntimeClients.add(ws);
1978
+ publishBrowserState(createBrowserState('connected', {
1979
+ connected: true,
1980
+ commandReady: false,
1981
+ connectedClientCount: browserRuntimeClients.size,
1982
+ lastBridgeConnectedAt: new Date().toISOString(),
850
1983
  }));
851
1984
  }
852
- else {
853
- const params = parsed.params ?? {};
854
- if (!params.level) {
855
- params.level = ['log', 'info', 'warn', 'error'];
1985
+ traceRuntime('bridge_hello', {
1986
+ connectionId,
1987
+ tabId: parsed.tabId ?? null,
1988
+ tabGeneration: parsed.tabGeneration ?? null,
1989
+ connectedClientCount: browserRuntimeClients.size,
1990
+ });
1991
+ return;
1992
+ }
1993
+ if (parsed.method === INTERNAL_BROWSER_PROBE_METHOD &&
1994
+ typeof parsed.id === 'string') {
1995
+ intercepted = true;
1996
+ traceRuntime('probe_request', {
1997
+ connectionId,
1998
+ requestId: parsed.id,
1999
+ });
2000
+ try {
2001
+ const readiness = await ensureBrowserCommandReady('internal_browser_probe');
2002
+ if (!readiness.browser || !readiness.bridgeConnected) {
2003
+ sendUnavailableBrowser(ws, parsed.id, 'probe_unavailable');
2004
+ }
2005
+ else {
2006
+ sendWsJson(ws, {
2007
+ id: parsed.id,
2008
+ result: createBrowserProbeResult(readiness.waitedForBridgeMs),
2009
+ }, 'probe_ready');
856
2010
  }
857
- const result = browser ? browser.queryLogs(params) : [];
858
- ws.send(JSON.stringify({ id: parsed.id, result }));
859
2011
  }
2012
+ catch (error) {
2013
+ sendInternalError(ws, parsed.id, error, 'probe_error');
2014
+ }
2015
+ return;
860
2016
  }
861
- // Screenshot: Playwright captures via CDP compositor
862
- if (!intercepted && parsed.method === 'screenshot' && parsed.id) {
2017
+ if (parsed.method === 'get_console_logs' &&
2018
+ typeof parsed.id === 'string') {
863
2019
  intercepted = true;
864
2020
  try {
865
- const { browser, relaunched } = await ensureBrowser();
866
- if (relaunched) {
867
- ws.send(JSON.stringify({
2021
+ const readiness = await ensureBrowserCommandReady('get_console_logs');
2022
+ if (!readiness.browser || !readiness.bridgeConnected) {
2023
+ sendUnavailableBrowser(ws, parsed.id, 'console_logs_unavailable');
2024
+ return;
2025
+ }
2026
+ if (readiness.relaunched) {
2027
+ const tab = await readiness.browser.getTabMetadata();
2028
+ sendWsJson(ws, {
868
2029
  id: parsed.id,
869
2030
  result: BROWSER_RELAUNCHED_RESULT,
870
- }));
2031
+ ...(tab.id
2032
+ ? {
2033
+ _tabId: tab.id,
2034
+ _tabGeneration: tab.generation ?? undefined,
2035
+ }
2036
+ : {}),
2037
+ }, 'console_logs_relaunched');
2038
+ return;
871
2039
  }
872
- else if (browser) {
873
- const buffer = await browser.screenshot();
874
- const base64 = buffer.toString('base64');
875
- ws.send(JSON.stringify({
876
- id: parsed.id,
877
- result: { imageData: base64, mimeType: 'image/png' },
878
- }));
2040
+ const params = parsed.params ?? {};
2041
+ if (!params.level) {
2042
+ params.level = ['log', 'info', 'warn', 'error'];
879
2043
  }
880
- else {
881
- ws.send(JSON.stringify({
2044
+ const tab = await readiness.browser.getTabMetadata();
2045
+ sendWsJson(ws, {
2046
+ id: parsed.id,
2047
+ result: readiness.browser.queryLogs(params),
2048
+ ...(tab.id
2049
+ ? {
2050
+ _tabId: tab.id,
2051
+ _tabGeneration: tab.generation ?? undefined,
2052
+ }
2053
+ : {}),
2054
+ }, 'console_logs_result');
2055
+ }
2056
+ catch (error) {
2057
+ sendInternalError(ws, parsed.id, error, 'console_logs_error');
2058
+ }
2059
+ return;
2060
+ }
2061
+ if (parsed.method === 'screenshot' &&
2062
+ typeof parsed.id === 'string') {
2063
+ intercepted = true;
2064
+ try {
2065
+ const readiness = await ensureBrowserCommandReady('screenshot');
2066
+ if (!readiness.browser || !readiness.bridgeConnected) {
2067
+ sendUnavailableBrowser(ws, parsed.id, 'screenshot_unavailable');
2068
+ return;
2069
+ }
2070
+ if (readiness.relaunched) {
2071
+ sendWsJson(ws, {
882
2072
  id: parsed.id,
883
- error: { code: -32000, message: 'Browser not ready' },
884
- }));
2073
+ result: BROWSER_RELAUNCHED_RESULT,
2074
+ }, 'screenshot_relaunched');
2075
+ return;
885
2076
  }
886
- }
887
- catch (err) {
888
- ws.send(JSON.stringify({
2077
+ const buffer = await readiness.browser.screenshot();
2078
+ const base64 = buffer.toString('base64');
2079
+ sendWsJson(ws, {
889
2080
  id: parsed.id,
890
- error: {
891
- code: -32000,
892
- message: err instanceof Error ? err.message : String(err),
893
- },
894
- }));
2081
+ result: { imageData: base64, mimeType: 'image/png' },
2082
+ }, 'screenshot_result');
2083
+ }
2084
+ catch (error) {
2085
+ sendInternalError(ws, parsed.id, error, 'screenshot_error');
895
2086
  }
2087
+ return;
896
2088
  }
897
2089
  }
898
- catch {
899
- // Not JSON — fall through to relay
2090
+ catch (error) {
2091
+ traceRuntime('ws_message_parse_fallthrough', {
2092
+ connectionId,
2093
+ kind: getConnectionKind(ws),
2094
+ message: error instanceof Error ? error.message : 'non_json_message',
2095
+ });
900
2096
  }
901
2097
  if (!intercepted) {
902
2098
  relay.onMessage(ws, message, mcpClients);
903
2099
  }
904
2100
  });
905
- ws.on('close', () => {
2101
+ ws.on('close', (code, reasonBuffer) => {
2102
+ const kind = getConnectionKind(ws);
2103
+ const reason = typeof reasonBuffer === 'string'
2104
+ ? reasonBuffer
2105
+ : reasonBuffer.toString('utf8');
906
2106
  mcpClients.delete(ws);
2107
+ const removedBridge = browserRuntimeClients.delete(ws);
2108
+ if (removedBridge) {
2109
+ browserCommandReadyPromise = null;
2110
+ publishBrowserState(createBrowserState(browserRuntimeClients.size > 0 ? 'connected' : 'disconnected', {
2111
+ connected: browserRuntimeClients.size > 0,
2112
+ commandReady: false,
2113
+ connectedClientCount: browserRuntimeClients.size,
2114
+ lastError: browserRuntimeClients.size > 0
2115
+ ? undefined
2116
+ : createBrowserIssue('connection_lost', 'Managed browser runtime disconnected from the MCP bridge.'),
2117
+ }));
2118
+ }
2119
+ traceRuntime('ws_closed', {
2120
+ connectionId,
2121
+ kind,
2122
+ code,
2123
+ reason,
2124
+ removedBridge,
2125
+ browserRuntimeClients: browserRuntimeClients.size,
2126
+ });
907
2127
  if (pluginOptions.verbose) {
908
2128
  console.log('[IWSDK-MCP] Client disconnected');
909
2129
  }
910
2130
  });
911
2131
  ws.on('error', (error) => {
2132
+ traceRuntime('ws_error', {
2133
+ connectionId,
2134
+ kind: getConnectionKind(ws),
2135
+ message: error instanceof Error ? error.message : String(error),
2136
+ });
912
2137
  if (pluginOptions.verbose) {
913
2138
  console.error('[IWSDK-MCP] WebSocket error:', error);
914
2139
  }
@@ -919,6 +2144,10 @@ function iwsdkDev(options = {}) {
919
2144
  if (request.url !== '/__iwer_mcp') {
920
2145
  return;
921
2146
  }
2147
+ traceRuntime('ws_upgrade', {
2148
+ url: request.url,
2149
+ remoteAddress: request.socket.remoteAddress ?? null,
2150
+ });
922
2151
  if (pluginOptions.verbose) {
923
2152
  console.log('[IWSDK-MCP] WebSocket upgrade request received');
924
2153
  }
@@ -929,15 +2158,8 @@ function iwsdkDev(options = {}) {
929
2158
  if (pluginOptions.verbose) {
930
2159
  console.log('🔌 IWSDK-MCP: WebSocket endpoint registered at /__iwer_mcp');
931
2160
  }
932
- // Generate MCP config files for selected AI tools after server starts
933
- // We wait for the 'listening' event to get the actual port (in case configured port was busy)
934
- // Find the path to the MCP server script
935
- // It's installed in node_modules/@iwsdk/vite-plugin-dev/dist/mcp-server.js
936
- const mcpServerPath = path.join(config.root, 'node_modules', '@iwsdk', 'vite-plugin-dev', 'dist', 'mcp-server.js');
937
- // Find the path to the RAG MCP server
938
- const ragMcpServerPath = path.join(config.root, 'node_modules', '@felixtz', 'iwsdk-rag-mcp', 'dist', 'index.js');
939
- // Check if hzdb is installed (for MCP config — telemetry uses npx and fails silently)
940
- const hzdbInstalled = existsSync(path.join(config.root, 'node_modules', '@meta-quest', 'hzdb'));
2161
+ // Register the project-local runtime session after server start.
2162
+ // Waiting for 'listening' lets us record Vite's actual chosen port.
941
2163
  // Resolve IWSDK version for telemetry attribution
942
2164
  let iwsdkVersion;
943
2165
  try {
@@ -951,85 +2173,42 @@ function iwsdkDev(options = {}) {
951
2173
  // Session tracking for telemetry
952
2174
  const sessionId = randomUUID();
953
2175
  const sessionStartTime = Date.now();
954
- const writeMcpConfigs = async (actualPort) => {
955
- const mcpServerArgs = [mcpServerPath, '--port', String(actualPort)];
956
- if (iwsdkVersion) {
957
- mcpServerArgs.push('--client-version', iwsdkVersion);
958
- }
959
- // Build the full set of all possible managed entries, then remove
960
- // those whose packages aren't installed. The full key list is passed
961
- // as managedKeys so mergeJsonConfig can clean up stale entries from
962
- // previous runs where a package was present but has since been removed.
963
- const serverEntries = {
964
- 'iwsdk-dev-mcp': {
965
- command: 'node',
966
- args: mcpServerArgs,
967
- },
968
- 'iwsdk-rag-local': existsSync(ragMcpServerPath)
969
- ? { command: 'node', args: [ragMcpServerPath] }
970
- : undefined,
971
- hzdb: hzdbInstalled
972
- ? { command: 'npx', args: ['@meta-quest/hzdb', 'mcp', 'server'] }
973
- : undefined,
974
- };
975
- const managedKeys = Object.keys(serverEntries);
976
- const activeEntries = {};
977
- for (const [key, value] of Object.entries(serverEntries)) {
978
- if (value) {
979
- activeEntries[key] = value;
980
- }
981
- }
982
- const tools = pluginOptions.ai.tools;
983
- const writes = [];
984
- for (const tool of tools) {
985
- const target = MCP_CONFIG_TARGETS[tool];
986
- const filePath = path.join(config.root, target.file);
987
- if (target.format === 'json') {
988
- writes.push(mergeJsonConfig(filePath, activeEntries, target.jsonKey, managedKeys));
989
- }
990
- else {
991
- writes.push(mergeTomlConfig(filePath, activeEntries));
992
- }
993
- }
994
- const results = await Promise.allSettled(writes);
995
- const failures = results.filter((r) => r.status === 'rejected');
996
- if (failures.length > 0) {
997
- for (const f of failures) {
998
- console.error('[MCP] Config write failed:', f.reason);
999
- }
1000
- }
1001
- else if (pluginOptions.verbose) {
1002
- const toolNames = tools.join(', ');
1003
- console.log(`📝 MCP: Generated config files for [${toolNames}] (port: ${actualPort})`);
1004
- }
1005
- };
1006
2176
  // Wait for server to start listening to get the actual port
1007
- server.httpServer?.on('listening', () => {
2177
+ server.httpServer?.on('listening', async () => {
1008
2178
  const address = server.httpServer?.address();
1009
2179
  const actualPort = typeof address === 'object' && address
1010
2180
  ? address.port
1011
2181
  : server.config.server.port || 5173;
1012
- writeMcpConfigs(actualPort);
2182
+ const protocol = server.config.server.https ? 'https' : 'http';
2183
+ browserUrl = `${protocol}://localhost:${actualPort}`;
2184
+ try {
2185
+ await registerRuntimeSession({
2186
+ sessionId,
2187
+ workspaceRoot: config.root,
2188
+ pid: process.pid,
2189
+ port: actualPort,
2190
+ localUrl: server.resolvedUrls?.local?.[0] ?? browserUrl,
2191
+ networkUrls: server.resolvedUrls?.network ?? [],
2192
+ aiMode: pluginOptions.ai?.mode,
2193
+ browser: currentBrowserState ?? undefined,
2194
+ });
2195
+ }
2196
+ catch (error) {
2197
+ console.error('[IWSDK Dev] Failed to register runtime session:', error);
2198
+ }
1013
2199
  // Report session start to hzdb telemetry (fire-and-forget via npx)
1014
2200
  reportSessionStart(sessionId, {
1015
2201
  iwsdkVersion,
1016
2202
  clientVersion: iwsdkVersion,
1017
2203
  port: actualPort,
1018
2204
  });
1019
- // Warm up RAG MCP server (downloads embedding model if needed)
1020
- // This ensures the model is cached before Claude Code tries to use it
1021
- warmupRagMcp(ragMcpServerPath, pluginOptions.verbose);
1022
2205
  // Launch Playwright-managed browser
1023
- const protocol = server.config.server.https ? 'https' : 'http';
1024
- browserUrl = `${protocol}://localhost:${actualPort}`;
1025
2206
  launchBrowser();
1026
2207
  });
1027
2208
  // Clean up WebSocket server and browser when Vite server closes.
1028
- // MCP config files (.mcp.json, .cursor/mcp.json, etc.) are intentionally
1029
- // left in place — they are harmless when the dev server isn't running and
1030
- // will be overwritten with fresh values on the next `npm run dev`.
1031
2209
  server.httpServer?.on('close', () => {
1032
2210
  serverShuttingDown = true;
2211
+ void unregisterRuntimeSession(config.root);
1033
2212
  reportSessionEnd(sessionId, {
1034
2213
  durationMs: Date.now() - sessionStartTime,
1035
2214
  reason: 'user_closed',
@@ -1141,5 +2320,5 @@ function iwsdkDev(options = {}) {
1141
2320
  /** @deprecated Use `iwsdkDev` instead */
1142
2321
  const injectIWER = iwsdkDev;
1143
2322
 
1144
- export { injectIWER, iwsdkDev, mergeJsonConfig, mergeTomlConfig, unmergeJsonConfig, unmergeTomlConfig };
2323
+ export { injectIWER, iwsdkDev };
1145
2324
  //# sourceMappingURL=index.js.map