@iwsdk/cli 0.5.2 → 1.0.0-rc.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/README.md +62 -1
- package/bin/iwsdk.js +1 -1
- package/dist/browser-lease.d.ts +14 -0
- package/dist/browser-lease.d.ts.map +1 -0
- package/dist/cli-types.d.ts +1 -1
- package/dist/cli-types.d.ts.map +1 -1
- package/dist/cli.js +2811 -485
- package/dist/cli.js.map +1 -1
- package/dist/commands/browser.d.ts +14 -0
- package/dist/commands/browser.d.ts.map +1 -0
- package/dist/commands/dev.d.ts +6 -2
- package/dist/commands/dev.d.ts.map +1 -1
- package/dist/commands/runtime.d.ts.map +1 -1
- package/dist/commands/status.d.ts.map +1 -1
- package/dist/contract.js +481 -30
- package/dist/contract.js.map +1 -1
- package/dist/help.d.ts +1 -0
- package/dist/help.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2813 -487
- package/dist/index.js.map +1 -1
- package/dist/mcp-stdio.d.ts.map +1 -1
- package/dist/runtime-contract.d.ts +70 -1
- package/dist/runtime-contract.d.ts.map +1 -1
- package/dist/runtime-files.d.ts +19 -0
- package/dist/runtime-files.d.ts.map +1 -0
- package/dist/runtime-files.js +318 -0
- package/dist/runtime-files.js.map +1 -0
- package/dist/runtime-owner.d.ts +50 -0
- package/dist/runtime-owner.d.ts.map +1 -0
- package/dist/runtime-owner.js +539 -0
- package/dist/runtime-owner.js.map +1 -0
- package/dist/runtime-state.d.ts +20 -18
- package/dist/runtime-state.d.ts.map +1 -1
- package/dist/runtime-transport.d.ts.map +1 -1
- package/dist/screenshot-output.d.ts +13 -0
- package/dist/screenshot-output.d.ts.map +1 -0
- package/guidance/AGENTS.md +96 -37
- 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
|
-
|
|
11
|
-
|
|
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.
|
|
93
|
-
|
|
94
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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: {
|
|
1114
|
-
|
|
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.
|
|
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 =
|
|
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))
|
|
2816
|
+
!REMOVED_WORKSPACE_MCP_TOOL_NAME_SET.has(tool.name))
|
|
2817
|
+
.map((tool) => ({
|
|
2416
2818
|
...tool,
|
|
2417
|
-
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
|
|
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
|
-
:
|
|
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
|