Repository navigation
Expand file tree
/
Copy pathcommand-output-schemas.ts
More file actions
350 lines (335 loc) · 14.3 KB
/
Copy pathcommand-output-schemas.ts
File metadata and controls
350 lines (335 loc) · 14.3 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
import type { JsonSchema } from '../commands/command-contract.ts';
import type { CommandResultMap } from '@agent-device/command-registry/command-result';
import { commandSupportsSettleObservation } from '@agent-device/command-registry/registry';
import {
booleanSchema,
enumSchema,
looseObjectSchema,
numberSchema,
objectSchema,
stringArraySchema,
stringSchema,
} from '../commands/command-input.ts';
import { DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/device.ts';
import { PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS } from '../commands/management/push.ts';
import { INTERACTION_COMMAND_OUTPUT_SCHEMAS } from '../commands/interaction/index.ts';
import { RECORDING_COMMAND_OUTPUT_SCHEMAS } from '../commands/recording/index.ts';
import { REPLAY_COMMAND_OUTPUT_SCHEMAS } from '../commands/replay/index.ts';
import { SYSTEM_COMMAND_OUTPUT_SCHEMAS } from '../commands/system/index.ts';
import { DEVICE_TARGETS, PUBLIC_PLATFORMS } from '@agent-device/kernel/device';
/**
* Registry of per-command MCP `outputSchema`s, keyed by the daemon command
* NAME. It is type-tied to the typed-result spine `CommandResultMap`
* (@agent-device/command-registry/command-result) via
* `satisfies Record<keyof CommandResultMap, JsonSchema>`, so the one-for-one
* invariant is compiler-enforced: a new `CommandResultMap` entry without a schema
* here is a missing-key error, and a typo'd/extra key is an excess-property error.
* The genuinely-dynamic commands (snapshot overlays, gestures, perf, logs, …) are
* absent from BOTH maps — their tools stay byte-identical to today (no
* `outputSchema` key), exactly as `CommandResultMap` omits them rather than
* inventing a shape.
*
* There is no type→JSON-Schema generator in this repo. Schemas are hand-authored from
* matching contract types, using the shared JSON-Schema primitives in
* `src/commands/command-input.ts`. Where a command family is owned by one module (the
* descriptors' `ownerFiles`), that module authors its entries and projects them into this
* map instead of being hand-listed here. Two invariants:
* - NEVER strict: no `additionalProperties: false` anywhere, so the additive
* `cost` object (opted in via `--cost` / `includeCost`) and any other additive
* fields ride into `structuredContent` and still validate.
* - Accurate, never invented: required-vs-optional, enums, `const` discriminants
* and discriminated-union branches mirror the source contract types.
*
* The opt-in `--settle` observation (#1101) is not hand-listed per entry: the
* base map carries none and `deriveSettleObservationSchemas` grafts it onto
* exactly the entries whose descriptor declares the post-action observation
* trait (#1652).
*/
export const DEVICE_KINDS = ['simulator', 'emulator', 'device'] as const;
function constSchema(value: string): JsonSchema {
return { type: 'string', const: value };
}
// PostActionSurfaceChange (packages/contracts/src/interaction.ts) — the post-action capture
// describes a different surface than the pre-action baseline (#2438), so no same-surface
// comparison is presented across it. Also mirrored in the interaction family module
// (src/commands/interaction/index.ts), which needs it for its own InteractionEvidence
// projection without importing back into this file.
const postActionSurfaceChangeSchema: JsonSchema = objectSchema(
{
from: stringSchema('Surface the pre-action baseline described: a host bundle id, or app.'),
to: stringSchema('Surface the post-action capture describes: a host bundle id, or app.'),
disclosure: stringSchema('Agent-facing sentence explaining the surface transition.'),
},
['from', 'to', 'disclosure'],
'Present when an in-place system surface (web sign-in or Apple Pay sheet) was presented over the app, or left it.',
);
// SettleObservation (packages/contracts/src/interaction.ts) — opt-in `--settle` settled
// diff observation (#1101).
const settleObservationSchema: JsonSchema = objectSchema(
{
settled: booleanSchema(
'Whether the UI held the quiet window before the deadline. false is advisory, not failure.',
),
waitedMs: numberSchema(),
captures: numberSchema(),
quietMs: numberSchema(),
timeoutMs: numberSchema(),
refsGeneration: numberSchema(
'Snapshot generation of the stored settled tree; refs on added diff lines were minted from it.',
),
refs: {
type: 'array',
items: objectSchema(
{
ref: stringSchema('Plain ref body (e12) minted from the stored settled tree.'),
},
['ref'],
),
},
surfaceChange: postActionSurfaceChangeSchema,
diff: objectSchema(
{
summary: objectSchema(
{
additions: numberSchema(),
removals: numberSchema(),
unchanged: numberSchema(),
},
['additions', 'removals', 'unchanged'],
),
lines: {
type: 'array',
items: objectSchema(
{
kind: enumSchema(['added', 'removed']),
text: stringSchema(),
ref: stringSchema('Plain ref body (e12) for added lines.'),
},
['kind', 'text'],
),
},
truncated: booleanSchema('Lines were capped to the response bound.'),
},
['summary', 'lines'],
'Settled diff vs the pre-action tree (changed lines only).',
),
tail: {
type: 'array',
description:
'Unchanged interactive refs tail: still-present, actionable elements from the settled tree, attached only when diff carries zero added-line refs (a modal-dismiss/toast-only diff).',
items: objectSchema(
{
ref: stringSchema('Plain ref body (e12) minted from the stored settled tree.'),
role: stringSchema(),
label: stringSchema(),
},
['ref', 'role'],
),
},
tailTruncated: booleanSchema('Present (true) when tail candidates exceeded the response cap.'),
hint: stringSchema(),
},
['settled', 'waitedMs', 'captures', 'quietMs', 'timeoutMs'],
);
/** Grafts the opt-in `--settle` observation onto a closed schema or union branch. */
function withSettleObservation(schema: JsonSchema): JsonSchema {
// Union-shaped results (fill) carry the observation in EACH branch, never
// next to the oneOf.
if (schema.oneOf) {
return { ...schema, oneOf: schema.oneOf.map(withSettleObservation) };
}
return {
...schema,
properties: { ...(schema.properties ?? {}), settle: settleObservationSchema },
};
}
/**
* #1652: whether a command's output schema advertises `settle` derives from
* its descriptor post-action observation trait instead of hand-listed
* properties per schema. The base map below carries no settle property
* anywhere; this pass grafts it onto exactly the trait-capable entries.
* Copies only — press and click share one base schema object, so an in-place
* graft would leak across them.
*/
function deriveSettleObservationSchemas(
schemas: Record<keyof CommandResultMap, JsonSchema>,
): Record<keyof CommandResultMap, JsonSchema> {
const derived: Record<keyof CommandResultMap, JsonSchema> = { ...schemas };
for (const command of Object.keys(derived) as Array<keyof CommandResultMap>) {
if (!commandSupportsSettleObservation(command)) continue;
derived[command] = withSettleObservation(derived[command]);
}
return derived;
}
const BASE_COMMAND_OUTPUT_SCHEMAS = {
// packages/contracts/src/viewport.ts
viewport: objectSchema(
{ width: numberSchema(), height: numberSchema(), message: stringSchema() },
['width', 'height', 'message'],
),
// packages/contracts/src/wait.ts — compact public daemon projection.
wait: objectSchema(
{
waitedMs: numberSchema(),
kind: constSchema('selector'),
text: stringSchema(),
selector: stringSchema(),
captures: numberSchema(),
nodeCount: numberSchema(),
hint: stringSchema(),
warning: stringSchema(),
},
['waitedMs'],
),
// packages/contracts/src/scroll-command.ts — ScrollCommandResult. The
// settle-capable generic-route pair must both be typed so the trait
// derivation grafts the observation onto each (#1652); platform leaves add
// gesture-plan coordinates on top, which the non-strict schema admits.
scroll: objectSchema(
{
direction: enumSchema(['up', 'down', 'left', 'right']),
edge: enumSchema(['top', 'bottom']),
until: stringSchema('Until scrolls only: the selector the passes stopped on.'),
passes: numberSchema('Edge and until scrolls only: how many scroll-and-check passes ran.'),
amount: numberSchema(),
pixels: numberSchema(),
durationMs: numberSchema(),
message: stringSchema(),
keyboardAvoided: booleanSchema(
'Present only when an on-screen keyboard forced the swipe into the band above it; the reported pixels were planned against the shorter referenceHeight.',
),
keyboardMinY: numberSchema(
'Where the keyboard began, in the same unit as the gesture coordinates. Clipped scrolls only.',
),
movement: enumSchema(
['moved', 'at-edge', 'unchanged', 'unobserved'],
'Directional scrolls only: what the owner observed after its gesture. `moved` means the content inside the scroller the swipe ran in differs from the tree the session stored immediately before the gesture; `at-edge` and `unchanged` mean it did not change, with no hidden content left to reveal and with no end-of-content signal to read, respectively; `unobserved` means the pair could not back a claim in either direction — nothing comparable was available (no stored tree, a capture from another lineage, a surface that never came to rest), or every difference sits outside the scroller that was swiped, which a changing status bar does on Android — so the reported distance rests on the gesture plan alone. The field is absent — which is never a claim that nothing moved — on the tiers that verify per pass (`scroll top`/`bottom`, `--until`), on a runtime bound without a capture, on a platform whose scroll dispatches no swipe (the Linux wheel), and where the caller already owns that observation (`--settle`, or a replay with `postGestureStabilization: false`).',
),
},
['direction'],
),
// packages/contracts/src/prepare.ts — prepare is not MCP-exposed, but the schema stays
// map-complete with CommandResultMap.
prepare: objectSchema(
{
action: constSchema('ios-runner'),
// PublicPlatform leaf, mirroring PrepareCommandResult (packages/contracts/src/prepare.ts).
platform: enumSchema(PUBLIC_PLATFORMS),
deviceId: stringSchema(),
deviceName: stringSchema(),
kind: enumSchema(DEVICE_KINDS),
durationMs: numberSchema(),
runner: objectSchema({}, []),
cache: enumSchema(['exact', 'miss', 'external']),
artifact: enumSchema(['valid', 'rebuilt']),
buildMs: numberSchema(),
connectMs: numberSchema(),
healthCheckMs: numberSchema(),
xctestrunPath: stringSchema(),
recoveryReason: stringSchema(),
failureReason: stringSchema(),
timing: objectSchema(
{
totalMs: numberSchema(),
additiveParts: objectSchema(
{
buildMs: numberSchema(),
connectAfterBuildMs: numberSchema(),
healthCheckMs: numberSchema(),
},
['connectAfterBuildMs', 'healthCheckMs'],
),
containment: objectSchema(
{
connectMs: { type: 'array', items: constSchema('buildMs') },
healthCheckMs: { type: 'array', items: stringSchema() },
},
['healthCheckMs'],
),
note: stringSchema(),
},
['totalMs', 'additiveParts', 'containment', 'note'],
),
message: stringSchema(),
},
[
'action',
'platform',
'deviceId',
'deviceName',
'kind',
'durationMs',
'runner',
'connectMs',
'healthCheckMs',
'timing',
'message',
],
),
// packages/contracts/src/doctor.ts
doctor: objectSchema(
{
status: enumSchema(['pass', 'warn', 'fail', 'info']),
summary: stringSchema(),
kind: enumSchema(['auto', 'react-native', 'expo', 'repack']),
platform: stringSchema(),
target: enumSchema(DEVICE_TARGETS),
targetApp: stringSchema(),
metro: objectSchema({ host: stringSchema(), port: numberSchema() }, ['host', 'port']),
checks: {
type: 'array',
items: objectSchema(
{
id: stringSchema(),
status: enumSchema(['pass', 'warn', 'fail', 'info']),
summary: stringSchema(),
hint: stringSchema(),
command: stringSchema(),
evidence: looseObjectSchema(),
},
['id', 'status', 'summary'],
),
},
},
['status', 'summary', 'kind', 'checks'],
),
// packages/contracts/src/diff.ts — the public Node command accepts snapshot diffs.
diff: objectSchema(
{
mode: constSchema('snapshot'),
baselineInitialized: booleanSchema(),
summary: objectSchema(
{
additions: numberSchema(),
removals: numberSchema(),
unchanged: numberSchema(),
},
['additions', 'removals', 'unchanged'],
),
lines: {
type: 'array',
items: objectSchema(
{
kind: enumSchema(['added', 'removed']),
text: stringSchema(),
ref: stringSchema(),
},
['kind', 'text'],
),
},
warnings: stringArraySchema(),
},
['mode', 'baselineInitialized', 'summary', 'lines'],
),
// A family that owns its commands authors their advertised response shape beside the
// command surface and projects it here. This spread stays last: a hand-written entry for
// a projected command then fails as TS2783 instead of quietly overriding the family's,
// and this map's `satisfies` still refuses a missing `CommandResultMap` key.
...DEVICE_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
...PUSH_MANAGEMENT_COMMAND_OUTPUT_SCHEMAS,
...INTERACTION_COMMAND_OUTPUT_SCHEMAS,
...RECORDING_COMMAND_OUTPUT_SCHEMAS,
...REPLAY_COMMAND_OUTPUT_SCHEMAS,
...SYSTEM_COMMAND_OUTPUT_SCHEMAS,
} satisfies Record<keyof CommandResultMap, JsonSchema>;
export const COMMAND_OUTPUT_SCHEMAS = deriveSettleObservationSchemas(BASE_COMMAND_OUTPUT_SCHEMAS);