@iwsdk/cli 0.5.3 → 1.0.0-rc.1

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.
Files changed (39) hide show
  1. package/README.md +62 -1
  2. package/bin/iwsdk.js +1 -1
  3. package/dist/browser-lease.d.ts +14 -0
  4. package/dist/browser-lease.d.ts.map +1 -0
  5. package/dist/cli-types.d.ts +1 -1
  6. package/dist/cli-types.d.ts.map +1 -1
  7. package/dist/cli.js +2811 -485
  8. package/dist/cli.js.map +1 -1
  9. package/dist/commands/browser.d.ts +14 -0
  10. package/dist/commands/browser.d.ts.map +1 -0
  11. package/dist/commands/dev.d.ts +6 -2
  12. package/dist/commands/dev.d.ts.map +1 -1
  13. package/dist/commands/runtime.d.ts.map +1 -1
  14. package/dist/commands/status.d.ts.map +1 -1
  15. package/dist/contract.js +481 -30
  16. package/dist/contract.js.map +1 -1
  17. package/dist/help.d.ts +1 -0
  18. package/dist/help.d.ts.map +1 -1
  19. package/dist/index.d.ts.map +1 -1
  20. package/dist/index.js +2813 -487
  21. package/dist/index.js.map +1 -1
  22. package/dist/mcp-stdio.d.ts.map +1 -1
  23. package/dist/runtime-contract.d.ts +70 -1
  24. package/dist/runtime-contract.d.ts.map +1 -1
  25. package/dist/runtime-files.d.ts +19 -0
  26. package/dist/runtime-files.d.ts.map +1 -0
  27. package/dist/runtime-files.js +318 -0
  28. package/dist/runtime-files.js.map +1 -0
  29. package/dist/runtime-owner.d.ts +50 -0
  30. package/dist/runtime-owner.d.ts.map +1 -0
  31. package/dist/runtime-owner.js +539 -0
  32. package/dist/runtime-owner.js.map +1 -0
  33. package/dist/runtime-state.d.ts +20 -18
  34. package/dist/runtime-state.d.ts.map +1 -1
  35. package/dist/runtime-transport.d.ts.map +1 -1
  36. package/dist/screenshot-output.d.ts +13 -0
  37. package/dist/screenshot-output.d.ts.map +1 -0
  38. package/guidance/AGENTS.md +96 -37
  39. package/package.json +16 -2
package/dist/contract.js CHANGED
@@ -6,9 +6,25 @@
6
6
  */
7
7
  const DEFAULT_RUNTIME_COMMAND_TIMEOUT_MS = 30_000;
8
8
  const UI_RENDER_PREVIEW_TIMEOUT_MS = 60_000;
9
+ const ASSET_RENDER_PREVIEW_TIMEOUT_MS = 120_000;
10
+ const BROWSER_RUNTIME_COMMAND_TIMEOUT_MS = 60_000;
11
+ const BROWSER_RUNTIME_METHODS = new Set([
12
+ 'browser_interact',
13
+ 'browser_profile',
14
+ 'browser_snapshot',
15
+ 'get_console_logs',
16
+ 'reload_page',
17
+ 'screenshot',
18
+ ]);
9
19
  function getDefaultRuntimeCommandTimeoutMs(method) {
10
- return method === 'ui_render_preview'
11
- ? UI_RENDER_PREVIEW_TIMEOUT_MS
20
+ if (method === 'asset_render_preview') {
21
+ return ASSET_RENDER_PREVIEW_TIMEOUT_MS;
22
+ }
23
+ if (method === 'ui_render_preview') {
24
+ return UI_RENDER_PREVIEW_TIMEOUT_MS;
25
+ }
26
+ return BROWSER_RUNTIME_METHODS.has(method)
27
+ ? BROWSER_RUNTIME_COMMAND_TIMEOUT_MS
12
28
  : DEFAULT_RUNTIME_COMMAND_TIMEOUT_MS;
13
29
  }
14
30
  function describeValue(value) {
@@ -88,10 +104,13 @@ function assertSchemaValue(value, schema, path) {
88
104
  throw new Error(`${path} must be at most ${schema.maximum}`);
89
105
  }
90
106
  }
91
- if (typeof value === 'string' &&
92
- schema.pattern &&
93
- !new RegExp(schema.pattern).test(value)) {
94
- throw new Error(`${path} must match ${schema.pattern}`);
107
+ if (typeof value === 'string') {
108
+ if (schema.maxLength != null && value.length > schema.maxLength) {
109
+ throw new Error(`${path} allows at most ${schema.maxLength} characters`);
110
+ }
111
+ if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
112
+ throw new Error(`${path} must match ${schema.pattern}`);
113
+ }
95
114
  }
96
115
  if (Array.isArray(value)) {
97
116
  if (schema.minItems != null && value.length < schema.minItems) {
@@ -137,6 +156,8 @@ const IWSDK_RUNTIME_LAUNCH_PATH = '.iwsdk/runtime/launch.json';
137
156
  const IWSDK_RUNTIME_STATE_SCHEMA_VERSION = 2;
138
157
  const IWSDK_RUNTIME_BROWSER_READY_SCHEMA_VERSION = 2;
139
158
  const INTERNAL_BROWSER_PROBE_METHOD = '__iwsdk_browser_probe';
159
+ const INTERNAL_RUNTIME_SHUTDOWN_METHOD = '__iwsdk_runtime_shutdown';
160
+ const INTERNAL_RUNTIME_LAUNCH_CLAIM_ENV = 'IWSDK_DEV_LAUNCH_CLAIM_ID';
140
161
  function hasRuntimeBrowserCommandReadyContract(session) {
141
162
  if (!session?.browser) {
142
163
  return false;
@@ -859,14 +880,234 @@ const ALL_RUNTIME_MCP_TOOLS = [
859
880
  // =============================================================================
860
881
  {
861
882
  name: 'browser_screenshot',
862
- description: 'Capture the managed application runtime. If the workspace editor is visible, switches to the runtime before capturing.',
883
+ description: 'Capture the current application in the managed browser, persist the image locally, and return screenshotPath with capture metadata. The application surface is resolved automatically.',
863
884
  inputSchema: {
864
885
  type: 'object',
865
- properties: {},
886
+ properties: {
887
+ format: {
888
+ type: 'string',
889
+ enum: ['png', 'jpeg'],
890
+ description: 'Image format. Defaults to png.',
891
+ },
892
+ quality: {
893
+ type: 'number',
894
+ minimum: 20,
895
+ maximum: 100,
896
+ description: 'JPEG quality. Ignored for PNG.',
897
+ },
898
+ fullPage: {
899
+ type: 'boolean',
900
+ description: 'Capture the full application document when it fits the bounded 32-megapixel and 64-tile limits.',
901
+ },
902
+ ref: {
903
+ type: 'string',
904
+ description: 'Capture one fully visible element ref returned by browser_snapshot. Targets larger than the application viewport are rejected as non-retryable.',
905
+ },
906
+ },
866
907
  required: [],
867
908
  additionalProperties: false,
868
909
  },
869
910
  },
911
+ {
912
+ name: 'browser_snapshot',
913
+ description: 'Inspect the current application as a compact accessibility-first list of interactive elements and canvas regions. Use returned refs with browser_interact.',
914
+ inputSchema: {
915
+ type: 'object',
916
+ additionalProperties: false,
917
+ properties: {
918
+ maxNodes: {
919
+ type: 'integer',
920
+ minimum: 1,
921
+ maximum: 1000,
922
+ description: 'Maximum returned elements. Defaults to 200.',
923
+ },
924
+ maxTextLength: {
925
+ type: 'integer',
926
+ minimum: 16,
927
+ maximum: 1000,
928
+ description: 'Maximum text/name length per element. Defaults to 200.',
929
+ },
930
+ rootRef: {
931
+ type: 'string',
932
+ description: 'Optional existing ref used as the snapshot root.',
933
+ },
934
+ },
935
+ },
936
+ },
937
+ {
938
+ name: 'browser_interact',
939
+ description: 'Perform up to 10 trusted Playwright actions against the current application. Prefer refs from browser_snapshot; use coordinates for canvas input. Hold keys within one batch with keyDown, wait, and keyUp; keyDown and keyUp focus an optional ref or locator, and any held keys are released when the batch ends. This tool does not navigate to arbitrary URLs.',
940
+ inputSchema: {
941
+ type: 'object',
942
+ additionalProperties: false,
943
+ properties: {
944
+ timeoutMs: {
945
+ type: 'integer',
946
+ minimum: 100,
947
+ maximum: 12000,
948
+ description: 'Total timeout budget for the complete batch. Defaults to 10000 and is capped at 12000 so workspace restoration completes before the host command deadline.',
949
+ },
950
+ steps: {
951
+ type: 'array',
952
+ minItems: 1,
953
+ maxItems: 10,
954
+ items: {
955
+ type: 'object',
956
+ additionalProperties: false,
957
+ properties: {
958
+ action: {
959
+ type: 'string',
960
+ enum: [
961
+ 'click',
962
+ 'doubleClick',
963
+ 'hover',
964
+ 'pointerMove',
965
+ 'pointerDown',
966
+ 'pointerUp',
967
+ 'wheel',
968
+ 'fill',
969
+ 'type',
970
+ 'clear',
971
+ 'press',
972
+ 'keyDown',
973
+ 'keyUp',
974
+ 'check',
975
+ 'uncheck',
976
+ 'select',
977
+ 'scroll',
978
+ 'drag',
979
+ 'wait',
980
+ ],
981
+ },
982
+ ref: { type: 'string' },
983
+ targetRef: { type: 'string' },
984
+ locator: {
985
+ type: 'object',
986
+ additionalProperties: false,
987
+ properties: {
988
+ role: { type: 'string' },
989
+ name: { type: 'string' },
990
+ testId: { type: 'string' },
991
+ text: { type: 'string' },
992
+ },
993
+ },
994
+ targetLocator: {
995
+ type: 'object',
996
+ additionalProperties: false,
997
+ properties: {
998
+ role: { type: 'string' },
999
+ name: { type: 'string' },
1000
+ testId: { type: 'string' },
1001
+ text: { type: 'string' },
1002
+ },
1003
+ },
1004
+ point: {
1005
+ type: 'object',
1006
+ additionalProperties: false,
1007
+ properties: {
1008
+ x: { type: 'number' },
1009
+ y: { type: 'number' },
1010
+ canvasRef: { type: 'string' },
1011
+ },
1012
+ required: ['x', 'y'],
1013
+ },
1014
+ targetPoint: {
1015
+ type: 'object',
1016
+ additionalProperties: false,
1017
+ properties: {
1018
+ x: { type: 'number' },
1019
+ y: { type: 'number' },
1020
+ canvasRef: { type: 'string' },
1021
+ },
1022
+ required: ['x', 'y'],
1023
+ },
1024
+ button: {
1025
+ type: 'string',
1026
+ enum: ['left', 'middle', 'right'],
1027
+ },
1028
+ key: {
1029
+ type: 'string',
1030
+ maxLength: 100,
1031
+ description: 'Keyboard key for press, keyDown, or keyUp. Keys held by keyDown are scoped to this batch and released automatically at the end.',
1032
+ },
1033
+ durationMs: {
1034
+ type: 'integer',
1035
+ minimum: 0,
1036
+ maximum: 12000,
1037
+ description: 'For wait, pause for this duration within the batch timeout.',
1038
+ },
1039
+ value: { type: 'string' },
1040
+ values: { type: 'array', items: { type: 'string' } },
1041
+ text: { type: 'string' },
1042
+ path: {
1043
+ type: 'string',
1044
+ description: 'For wait, the expected application pathname, search, and hash.',
1045
+ },
1046
+ loadState: {
1047
+ type: 'string',
1048
+ enum: ['domcontentloaded', 'load', 'networkidle'],
1049
+ description: 'For wait, the application load state to await.',
1050
+ },
1051
+ state: {
1052
+ type: 'string',
1053
+ enum: [
1054
+ 'attached',
1055
+ 'checked',
1056
+ 'detached',
1057
+ 'disabled',
1058
+ 'editable',
1059
+ 'enabled',
1060
+ 'focused',
1061
+ 'hidden',
1062
+ 'unchecked',
1063
+ 'visible',
1064
+ ],
1065
+ },
1066
+ deltaX: { type: 'number' },
1067
+ deltaY: { type: 'number' },
1068
+ timeoutMs: {
1069
+ type: 'integer',
1070
+ minimum: 100,
1071
+ maximum: 12000,
1072
+ },
1073
+ },
1074
+ required: ['action'],
1075
+ },
1076
+ },
1077
+ },
1078
+ required: ['steps'],
1079
+ },
1080
+ },
1081
+ {
1082
+ name: 'browser_profile',
1083
+ description: 'Start, stop, or inspect a bounded uncalibrated desktop-browser performance profile for the current application.',
1084
+ inputSchema: {
1085
+ type: 'object',
1086
+ additionalProperties: false,
1087
+ properties: {
1088
+ action: {
1089
+ type: 'string',
1090
+ enum: ['start', 'status', 'stop'],
1091
+ },
1092
+ mode: {
1093
+ type: 'string',
1094
+ enum: ['interaction', 'rendering', 'trace'],
1095
+ description: 'Profile mode used when action is start.',
1096
+ },
1097
+ maxDurationMs: {
1098
+ type: 'integer',
1099
+ minimum: 1000,
1100
+ maximum: 60000,
1101
+ description: 'Safety auto-stop duration. Defaults to 30000.',
1102
+ },
1103
+ profileId: {
1104
+ type: 'string',
1105
+ description: 'Optional profile ID precondition for stop.',
1106
+ },
1107
+ },
1108
+ required: ['action'],
1109
+ },
1110
+ },
870
1111
  // =============================================================================
871
1112
  // Device State
872
1113
  // =============================================================================
@@ -985,19 +1226,21 @@ const ALL_RUNTIME_MCP_TOOLS = [
985
1226
  properties: {
986
1227
  count: {
987
1228
  type: 'number',
988
- description: 'Maximum number of logs to return (most recent N)',
1229
+ minimum: 1,
1230
+ maximum: 200,
1231
+ description: 'Maximum number of logs to return (most recent N). Defaults to 100 and is capped at 200.',
989
1232
  },
990
1233
  level: {
991
1234
  oneOf: [
992
1235
  {
993
1236
  type: 'string',
994
- enum: ['log', 'info', 'warn', 'error', 'debug'],
1237
+ enum: ['log', 'info', 'warn', 'error', 'debug', 'trace'],
995
1238
  },
996
1239
  {
997
1240
  type: 'array',
998
1241
  items: {
999
1242
  type: 'string',
1000
- enum: ['log', 'info', 'warn', 'error', 'debug'],
1243
+ enum: ['log', 'info', 'warn', 'error', 'debug', 'trace'],
1001
1244
  },
1002
1245
  },
1003
1246
  ],
@@ -1094,7 +1337,7 @@ const ALL_RUNTIME_MCP_TOOLS = [
1094
1337
  },
1095
1338
  {
1096
1339
  name: 'scene_render_file',
1097
- description: 'Validate, compose, and render an IWSDK scene JSON file without opening it in the live editor. Invalid files return structured diagnostics and no PNG; valid files return hashes, render metadata, and PNG image data.',
1340
+ description: 'Validate, compose, and render an IWSDK scene JSON file without opening it in the live editor. Invalid files return structured diagnostics and no PNG; valid files persist the PNG locally and return screenshotPath with hashes and render metadata.',
1098
1341
  inputSchema: {
1099
1342
  type: 'object',
1100
1343
  additionalProperties: false,
@@ -1110,8 +1353,16 @@ const ALL_RUNTIME_MCP_TOOLS = [
1110
1353
  type: 'string',
1111
1354
  description: 'Stable id of an exact camera declared in document.authoring.views. Use this, not view, for names such as "hero".',
1112
1355
  },
1113
- width: { type: 'number', minimum: 1 },
1114
- height: { type: 'number', minimum: 1 },
1356
+ width: {
1357
+ type: 'number',
1358
+ minimum: 1,
1359
+ description: 'Render width in pixels. For agent-loop review use 512 or smaller; use 384 or smaller when verifying a correction.',
1360
+ },
1361
+ height: {
1362
+ type: 'number',
1363
+ minimum: 1,
1364
+ description: 'Render height in pixels. For agent-loop review use 512 or smaller; use 384 or smaller when verifying a correction.',
1365
+ },
1115
1366
  },
1116
1367
  required: ['path'],
1117
1368
  },
@@ -1593,7 +1844,7 @@ const ALL_RUNTIME_MCP_TOOLS = [
1593
1844
  },
1594
1845
  {
1595
1846
  name: 'scene_screenshot',
1596
- description: 'Capture a native scene editor screenshot. Supports exact saved authoring viewId cameras, current/top/front/back/left/right/quarter/orbit views, and explicit perspective/orthographic poses.',
1847
+ description: 'Capture a native scene editor screenshot, persist the PNG locally, and return screenshotPath. Supports exact saved authoring viewId cameras, current/top/front/back/left/right/quarter/orbit views, and explicit perspective/orthographic poses.',
1597
1848
  inputSchema: {
1598
1849
  type: 'object',
1599
1850
  properties: {
@@ -1618,6 +1869,57 @@ const ALL_RUNTIME_MCP_TOOLS = [
1618
1869
  },
1619
1870
  },
1620
1871
  },
1872
+ {
1873
+ name: 'asset_render_preview',
1874
+ description: 'Render an isolated manifest model as one labelled multi-view contact sheet without changing the open scene. Supports authored materials or a neutral clay pass, optional framing around one named subtree, persists the PNG locally, and returns screenshotPath with deterministic geometry diagnostics. UIKitML assets must use ui_render_preview.',
1875
+ inputSchema: {
1876
+ type: 'object',
1877
+ additionalProperties: false,
1878
+ properties: {
1879
+ assetId: {
1880
+ type: 'string',
1881
+ description: 'Renderable glTF or Object3D manifest asset id. UIKitML assets are rejected with guidance to use ui_render_preview.',
1882
+ },
1883
+ views: {
1884
+ type: 'array',
1885
+ minItems: 1,
1886
+ maxItems: 6,
1887
+ items: {
1888
+ type: 'string',
1889
+ enum: ['front', 'back', 'left', 'right', 'top', 'quarter'],
1890
+ },
1891
+ description: 'Ordered contact-sheet views. Defaults to front, back, right, top, and quarter.',
1892
+ },
1893
+ mode: {
1894
+ type: 'string',
1895
+ enum: ['material', 'clay'],
1896
+ description: 'Use authored materials or a fixed neutral clay material. Defaults to material.',
1897
+ },
1898
+ focus: {
1899
+ type: 'string',
1900
+ maxLength: 512,
1901
+ description: 'Optional exact object name or slash-separated named hierarchy path to frame. The full asset remains visible for attachment context.',
1902
+ },
1903
+ width: {
1904
+ type: 'number',
1905
+ minimum: 320,
1906
+ maximum: 2048,
1907
+ description: 'Composite contact-sheet width in pixels. Defaults to 640. Keep agent-loop previews at 640 or smaller; use focus rather than more pixels for detail review.',
1908
+ },
1909
+ height: {
1910
+ type: 'number',
1911
+ minimum: 240,
1912
+ maximum: 2048,
1913
+ description: 'Composite contact-sheet height in pixels. Defaults to 480. Keep agent-loop previews at 480 or smaller; use focus rather than more pixels for detail review.',
1914
+ },
1915
+ background: {
1916
+ type: 'string',
1917
+ description: 'Three.js-compatible background color. Defaults to #202226.',
1918
+ },
1919
+ },
1920
+ required: ['assetId'],
1921
+ },
1922
+ },
1621
1923
  {
1622
1924
  name: 'ui_list_assets',
1623
1925
  description: 'List UIKitML assets available in the project asset manifest. Use a returned asset id with ui_render_preview or a PanelUI component config.',
@@ -1634,7 +1936,7 @@ const ALL_RUNTIME_MCP_TOOLS = [
1634
1936
  },
1635
1937
  {
1636
1938
  name: 'ui_render_preview',
1637
- description: 'Render one UIKitML asset from the project asset manifest in isolation against a plain background. Use this to inspect panel layout without the surrounding scene.',
1939
+ description: 'Render one UIKitML asset from the project asset manifest in isolation against a plain background, persist the PNG locally, and return screenshotPath. Use this to inspect panel layout without the surrounding scene.',
1638
1940
  inputSchema: {
1639
1941
  type: 'object',
1640
1942
  additionalProperties: false,
@@ -1663,6 +1965,45 @@ const ALL_RUNTIME_MCP_TOOLS = [
1663
1965
  required: ['assetId'],
1664
1966
  },
1665
1967
  },
1968
+ {
1969
+ name: 'ui_inspect',
1970
+ description: 'Inspect live UIKitML elements owned by one ECS panel entity. Omit selector to list stable-ID elements, or use #id, .class, and descendant selectors for focused inspection. Returns bounded current text, state, layout, and selected computed properties without interacting with the UI; documents over 10,000 objects fail explicitly. Requires FRAMEWORK_MCP_RUNTIME.',
1971
+ inputSchema: {
1972
+ type: 'object',
1973
+ additionalProperties: false,
1974
+ properties: {
1975
+ entityIndex: {
1976
+ type: 'integer',
1977
+ minimum: 0,
1978
+ description: 'Panel entity index from ecs_find_entities or scene_get_runtime_hierarchy.',
1979
+ },
1980
+ selector: {
1981
+ type: 'string',
1982
+ maxLength: 512,
1983
+ description: 'Optional #id, .class, or descendant selector with at most 16 parts. Omit to list every stable-ID element in document order.',
1984
+ },
1985
+ properties: {
1986
+ type: 'array',
1987
+ minItems: 1,
1988
+ maxItems: 20,
1989
+ items: {
1990
+ type: 'string',
1991
+ maxLength: 64,
1992
+ pattern: '^[A-Za-z][A-Za-z0-9]*$',
1993
+ description: 'Camel-case UIKit property name.',
1994
+ },
1995
+ description: 'Optional computed UIKit property names to return. Defaults to common text, value, state, display, and pointer-event properties.',
1996
+ },
1997
+ limit: {
1998
+ type: 'integer',
1999
+ minimum: 1,
2000
+ maximum: 50,
2001
+ description: 'Maximum returned elements. Defaults to 50.',
2002
+ },
2003
+ },
2004
+ required: ['entityIndex'],
2005
+ },
2006
+ },
1666
2007
  {
1667
2008
  name: 'scene_compare_screenshots',
1668
2009
  description: 'Capture two native scene editor screenshots and report byte identity. This is not a perceptual image comparison.',
@@ -2331,7 +2672,7 @@ const ALL_RUNTIME_MCP_TOOLS = [
2331
2672
  },
2332
2673
  {
2333
2674
  name: 'ecs_snapshot',
2334
- 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.',
2675
+ description: 'Capture a snapshot of all ECS entity/component state. Retains 2 snapshots by default; set capacity (2-20) to keep a larger rolling window. Use with ecs_diff to compare. Requires FRAMEWORK_MCP_RUNTIME.',
2335
2676
  inputSchema: {
2336
2677
  type: 'object',
2337
2678
  properties: {
@@ -2339,6 +2680,10 @@ const ALL_RUNTIME_MCP_TOOLS = [
2339
2680
  type: 'string',
2340
2681
  description: 'Label for this snapshot (default: auto-generated). Use to reference in ecs_diff.',
2341
2682
  },
2683
+ capacity: {
2684
+ type: 'number',
2685
+ description: 'Rolling snapshot capacity for this runtime (integer 2-20). Omit to keep the current capacity; defaults to 2.',
2686
+ },
2342
2687
  },
2343
2688
  },
2344
2689
  },
@@ -2401,20 +2746,79 @@ const EXPECTED_TAB_SCHEMA = {
2401
2746
  },
2402
2747
  required: ['id', 'generation'],
2403
2748
  };
2749
+ const RUNTIME_TARGET_SCHEMA = {
2750
+ type: 'object',
2751
+ additionalProperties: false,
2752
+ description: 'Execution destination. Omit for the managed browser. Physical devices require headsetId, pageId and tabGeneration from runtime_list_targets.',
2753
+ properties: {
2754
+ deviceClass: { type: 'string', enum: ['managed', 'physical'] },
2755
+ headsetId: { type: 'string' },
2756
+ pageId: { type: 'string' },
2757
+ tabGeneration: { type: 'integer', minimum: 1 },
2758
+ browserEpoch: { type: 'integer', minimum: 1 },
2759
+ sessionId: { type: 'string' },
2760
+ },
2761
+ required: ['deviceClass'],
2762
+ };
2763
+ const CONTROL_TOOLS = [
2764
+ {
2765
+ name: 'runtime_pair_headset',
2766
+ description: 'Associate an exact headset identifier (adb serial) with this dev session. Open the returned bootstrap URL on that device, then discover its page using runtime_list_targets.',
2767
+ inputSchema: {
2768
+ type: 'object',
2769
+ properties: { headsetId: { type: 'string' } },
2770
+ required: ['headsetId'],
2771
+ },
2772
+ },
2773
+ {
2774
+ name: 'runtime_get_status',
2775
+ description: 'Read live runtime ownership and managed browser lifecycle. Does not launch or recover a browser.',
2776
+ inputSchema: { type: 'object', properties: {} },
2777
+ },
2778
+ {
2779
+ name: 'runtime_list_targets',
2780
+ description: 'Discover connected targets, exact identities, readiness and supported methods. Physical targets must be explicitly selected.',
2781
+ inputSchema: { type: 'object', properties: {} },
2782
+ },
2783
+ {
2784
+ name: 'runtime_wait',
2785
+ description: 'Wait for a lifecycle revision change, without causing recovery. Returns a current snapshot on timeout.',
2786
+ inputSchema: {
2787
+ type: 'object',
2788
+ properties: {
2789
+ afterRevision: { type: 'integer', minimum: 0 },
2790
+ timeoutMs: { type: 'integer', minimum: 0, maximum: 25000 },
2791
+ },
2792
+ },
2793
+ },
2794
+ {
2795
+ name: 'runtime_recover',
2796
+ description: 'Explicitly retry launching the managed browser after failures. Does not replay previous commands or reset live page state.',
2797
+ inputSchema: { type: 'object', properties: {} },
2798
+ },
2799
+ ];
2404
2800
  function withExpectedTabPrecondition(schema) {
2405
2801
  return {
2406
2802
  ...schema,
2407
2803
  properties: {
2408
2804
  ...(schema.properties ?? {}),
2409
2805
  expectedTab: EXPECTED_TAB_SCHEMA,
2806
+ runtimeTarget: RUNTIME_TARGET_SCHEMA,
2410
2807
  },
2411
2808
  };
2412
2809
  }
2413
- const RUNTIME_MCP_TOOLS = ALL_RUNTIME_MCP_TOOLS.filter((tool) => (!tool.name.startsWith('scene_') ||
2810
+ const RUNTIME_MCP_TOOLS = [
2811
+ ...ALL_RUNTIME_MCP_TOOLS,
2812
+ ...CONTROL_TOOLS,
2813
+ ]
2814
+ .filter((tool) => (!tool.name.startsWith('scene_') ||
2414
2815
  PUBLIC_SCENE_MCP_TOOL_NAME_SET.has(tool.name)) &&
2415
- !REMOVED_WORKSPACE_MCP_TOOL_NAME_SET.has(tool.name)).map((tool) => ({
2816
+ !REMOVED_WORKSPACE_MCP_TOOL_NAME_SET.has(tool.name))
2817
+ .map((tool) => ({
2416
2818
  ...tool,
2417
- inputSchema: withExpectedTabPrecondition(tool.inputSchema),
2819
+ inputSchema: CONTROL_TOOLS.some((control) => control.name === tool.name)
2820
+ ? tool.inputSchema
2821
+ : withExpectedTabPrecondition(tool.inputSchema),
2418
2822
  }));
2419
2823
  const RUNTIME_TOOL_TO_METHOD = {
2420
2824
  xr_get_session_status: 'get_session_status',
@@ -2434,6 +2838,9 @@ const RUNTIME_TOOL_TO_METHOD = {
2434
2838
  xr_get_device_state: 'get_device_state',
2435
2839
  xr_set_device_state: 'set_device_state',
2436
2840
  browser_screenshot: 'screenshot',
2841
+ browser_snapshot: 'browser_snapshot',
2842
+ browser_interact: 'browser_interact',
2843
+ browser_profile: 'browser_profile',
2437
2844
  browser_get_console_logs: 'get_console_logs',
2438
2845
  browser_reload_page: 'reload_page',
2439
2846
  scene_get_render_stats: 'get_render_stats',
@@ -2456,6 +2863,9 @@ const ALL_RUNTIME_CLI_PATHS = {
2456
2863
  xr_get_gamepad_state: ['xr', 'get-gamepad-state'],
2457
2864
  xr_set_gamepad_state: ['xr', 'set-gamepad-state'],
2458
2865
  browser_screenshot: ['browser', 'screenshot'],
2866
+ browser_snapshot: ['browser', 'snapshot'],
2867
+ browser_interact: ['browser', 'interact'],
2868
+ browser_profile: ['browser', 'profile'],
2459
2869
  xr_get_device_state: ['xr', 'get-device-state'],
2460
2870
  xr_set_device_state: ['xr', 'set-device-state'],
2461
2871
  browser_get_console_logs: ['browser', 'logs'],
@@ -2495,8 +2905,10 @@ const ALL_RUNTIME_CLI_PATHS = {
2495
2905
  scene_get_logs: ['scene', 'logs'],
2496
2906
  scene_set_camera: ['scene', 'set-camera'],
2497
2907
  scene_screenshot: ['scene', 'screenshot'],
2908
+ asset_render_preview: ['asset', 'render-preview'],
2498
2909
  ui_list_assets: ['ui', 'assets'],
2499
2910
  ui_render_preview: ['ui', 'render-preview'],
2911
+ ui_inspect: ['ui', 'inspect'],
2500
2912
  scene_compare_screenshots: ['scene', 'compare-screenshots'],
2501
2913
  scene_begin_review: ['scene', 'begin-review'],
2502
2914
  scene_set_review_lens: ['scene', 'set-review-lens'],
@@ -2536,6 +2948,7 @@ const SCENE_EDITOR_MCP_TOOL_NAMES = [
2536
2948
  'scene_screenshot',
2537
2949
  'scene_set_preview_visibility',
2538
2950
  'scene_measure_image_regions',
2951
+ 'asset_render_preview',
2539
2952
  'ui_list_assets',
2540
2953
  'ui_render_preview',
2541
2954
  ];
@@ -2554,9 +2967,27 @@ const EDITOR_TARGET_MCP_TOOL_NAME_SET = new Set([
2554
2967
  ...REVIEW_EVIDENCE_MCP_TOOL_NAMES,
2555
2968
  ...WORKSPACE_MCP_TOOL_NAMES,
2556
2969
  ]);
2557
- const APP_TARGET_MCP_TOOL_NAME_SET = new Set(['browser_screenshot']);
2970
+ const HOST_BROWSER_MCP_TOOL_NAME_SET = new Set([
2971
+ 'browser_screenshot',
2972
+ 'browser_snapshot',
2973
+ 'browser_interact',
2974
+ 'browser_profile',
2975
+ 'browser_get_console_logs',
2976
+ 'browser_reload_page',
2977
+ ]);
2978
+ const APP_TARGET_MCP_TOOL_NAME_SET = new Set([
2979
+ ...HOST_BROWSER_MCP_TOOL_NAME_SET,
2980
+ 'ui_inspect',
2981
+ ]);
2558
2982
  const RUNTIME_OPERATIONS = RUNTIME_MCP_TOOLS.map((tool) => {
2559
- const cliPath = RUNTIME_CLI_PATHS[tool.name];
2983
+ const cliPath = RUNTIME_CLI_PATHS[tool.name] ??
2984
+ {
2985
+ runtime_get_status: ['runtime', 'status'],
2986
+ runtime_list_targets: ['runtime', 'targets'],
2987
+ runtime_wait: ['runtime', 'wait'],
2988
+ runtime_recover: ['runtime', 'recover'],
2989
+ runtime_pair_headset: ['runtime', 'pair-headset'],
2990
+ }[tool.name];
2560
2991
  const target = EDITOR_TARGET_MCP_TOOL_NAME_SET.has(tool.name)
2561
2992
  ? { role: 'editor' }
2562
2993
  : APP_TARGET_MCP_TOOL_NAME_SET.has(tool.name)
@@ -2570,6 +3001,14 @@ const RUNTIME_OPERATIONS = RUNTIME_MCP_TOOLS.map((tool) => {
2570
3001
  mcpName: tool.name,
2571
3002
  wsMethod: RUNTIME_TOOL_TO_METHOD[tool.name] ?? tool.name,
2572
3003
  ...(target ? { target } : {}),
3004
+ execution: tool.name.startsWith('runtime_')
3005
+ ? 'server'
3006
+ : HOST_BROWSER_MCP_TOOL_NAME_SET.has(tool.name)
3007
+ ? 'host'
3008
+ : 'runtime',
3009
+ physical: !EDITOR_TARGET_MCP_TOOL_NAME_SET.has(tool.name) &&
3010
+ (!HOST_BROWSER_MCP_TOOL_NAME_SET.has(tool.name) ||
3011
+ tool.name === 'browser_reload_page'),
2573
3012
  description: tool.description,
2574
3013
  inputSchema: tool.inputSchema,
2575
3014
  };
@@ -2600,29 +3039,41 @@ function resolveRuntimeOperationRequest(operation, params) {
2600
3039
  expectedTab.generation < 1)) {
2601
3040
  throw new Error(`${operation.mcpName}.expectedTab requires the { id, generation } object returned as result._tab`);
2602
3041
  }
2603
- if (operation.mcpName === 'browser_screenshot' &&
2604
- paramsRecord != null &&
2605
- Object.keys(paramsRecord).some((key) => key !== 'expectedTab')) {
2606
- throw new Error('browser_screenshot does not accept parameters; it always captures the application runtime');
2607
- }
2608
3042
  assertSchemaValue(params, operation.inputSchema, operation.mcpName);
2609
3043
  const commandParams = paramsRecord == null
2610
3044
  ? params
2611
- : Object.fromEntries(Object.entries(paramsRecord).filter(([key]) => key !== 'expectedTab'));
3045
+ : Object.fromEntries(Object.entries(paramsRecord).filter(([key]) => key !== 'expectedTab' && key !== 'runtimeTarget'));
3046
+ const selection = paramsRecord?.runtimeTarget;
3047
+ if (selection?.deviceClass === 'physical' &&
3048
+ (!selection.headsetId ||
3049
+ !selection.pageId ||
3050
+ !Number.isInteger(selection.tabGeneration))) {
3051
+ throw new Error('Physical runtimeTarget requires headsetId, pageId and tabGeneration from runtime_list_targets.');
3052
+ }
3053
+ if (selection &&
3054
+ isRecord(expectedTab) &&
3055
+ ((selection.pageId != null && selection.pageId !== expectedTab.id) ||
3056
+ (selection.tabGeneration != null &&
3057
+ selection.tabGeneration !== expectedTab.generation))) {
3058
+ throw new Error('runtimeTarget and expectedTab must identify the same page generation.');
3059
+ }
2612
3060
  const target = isRecord(expectedTab) &&
2613
3061
  typeof expectedTab.id === 'string' &&
2614
3062
  typeof expectedTab.generation === 'number'
2615
3063
  ? {
2616
3064
  ...(operation.target ?? {}),
3065
+ ...selection,
2617
3066
  pageId: expectedTab.id,
2618
3067
  tabGeneration: expectedTab.generation,
2619
3068
  }
2620
- : operation.target;
3069
+ : selection
3070
+ ? { ...operation.target, ...selection }
3071
+ : operation.target;
2621
3072
  return { params: commandParams, target };
2622
3073
  }
2623
3074
  function isRecord(value) {
2624
3075
  return typeof value === 'object' && value !== null && !Array.isArray(value);
2625
3076
  }
2626
3077
 
2627
- export { APP_RUNTIME_SCENE_MCP_TOOL_NAMES, DEFAULT_RUNTIME_COMMAND_TIMEOUT_MS, INTERNAL_BROWSER_PROBE_METHOD, IWSDK_PROJECT_STATE_DIR, IWSDK_RUNTIME_BROWSER_READY_SCHEMA_VERSION, IWSDK_RUNTIME_LAUNCH_PATH, IWSDK_RUNTIME_LOGS_DIR, IWSDK_RUNTIME_SESSION_PATH, IWSDK_RUNTIME_STATE_DIR, IWSDK_RUNTIME_STATE_SCHEMA_VERSION, MCP_CONFIG_TARGETS, PROJECT_ASSET_MCP_TOOL_NAMES, REVIEW_EVIDENCE_MCP_TOOL_NAMES, RUNTIME_CLI_PATHS, RUNTIME_MCP_TOOLS, RUNTIME_OPERATIONS, RUNTIME_TOOL_TO_METHOD, SCENE_EDITOR_MCP_TOOL_NAMES, SCENE_FILE_MCP_TOOL_NAMES, SCENE_MCP_TOOL_NAMES, SUPPORTED_AI_TOOLS, UI_RENDER_PREVIEW_TIMEOUT_MS, WORKSPACE_MCP_TOOL_NAMES, getDefaultRuntimeCommandTimeoutMs, getRuntimeOperationByCliPath, getRuntimeOperationByToolName, hasRuntimeBrowserCommandReadyContract, isRuntimeBrowserCommandReady, resolveRuntimeOperationRequest };
3078
+ export { APP_RUNTIME_SCENE_MCP_TOOL_NAMES, ASSET_RENDER_PREVIEW_TIMEOUT_MS, BROWSER_RUNTIME_COMMAND_TIMEOUT_MS, DEFAULT_RUNTIME_COMMAND_TIMEOUT_MS, INTERNAL_BROWSER_PROBE_METHOD, INTERNAL_RUNTIME_LAUNCH_CLAIM_ENV, INTERNAL_RUNTIME_SHUTDOWN_METHOD, IWSDK_PROJECT_STATE_DIR, IWSDK_RUNTIME_BROWSER_READY_SCHEMA_VERSION, IWSDK_RUNTIME_LAUNCH_PATH, IWSDK_RUNTIME_LOGS_DIR, IWSDK_RUNTIME_SESSION_PATH, IWSDK_RUNTIME_STATE_DIR, IWSDK_RUNTIME_STATE_SCHEMA_VERSION, MCP_CONFIG_TARGETS, PROJECT_ASSET_MCP_TOOL_NAMES, REVIEW_EVIDENCE_MCP_TOOL_NAMES, RUNTIME_CLI_PATHS, RUNTIME_MCP_TOOLS, RUNTIME_OPERATIONS, RUNTIME_TOOL_TO_METHOD, SCENE_EDITOR_MCP_TOOL_NAMES, SCENE_FILE_MCP_TOOL_NAMES, SCENE_MCP_TOOL_NAMES, SUPPORTED_AI_TOOLS, UI_RENDER_PREVIEW_TIMEOUT_MS, WORKSPACE_MCP_TOOL_NAMES, getDefaultRuntimeCommandTimeoutMs, getRuntimeOperationByCliPath, getRuntimeOperationByToolName, hasRuntimeBrowserCommandReadyContract, isRuntimeBrowserCommandReady, resolveRuntimeOperationRequest };
2628
3079
  //# sourceMappingURL=contract.js.map