Repository navigation
Expand file tree
/
Copy pathmetadata.ts
More file actions
283 lines (260 loc) · 14.1 KB
/
Copy pathmetadata.ts
File metadata and controls
283 lines (260 loc) · 14.1 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
import { CLICK_BUTTONS } from '@agent-device/contracts/click-button';
import {
type DragGesturePayload,
type FlingGesturePayload,
GESTURE_KINDS,
type PanGesturePayload,
type PinchGesturePayload,
type RotateGesturePayload,
type SwipeGesturePayload,
type TransformGesturePayload,
readGesturePayload,
} from '@agent-device/contracts/gesture-input';
import { SCROLL_DURATION_MAX_MS } from '@agent-device/contracts/scroll-command';
import { IS_PREDICATES } from '@agent-device/contracts/is-predicate';
import {
SCROLL_DIRECTIONS,
SCROLL_INPUT_DIRECTIONS,
SWIPE_PATTERNS,
SWIPE_PAUSE_MAX_MS,
SWIPE_PRESETS,
SWIPE_REPETITION_MAX,
} from '@agent-device/contracts/scroll-gesture';
import { FIND_LOCATORS } from '@agent-device/selectors';
import {
booleanField,
elementTargetField,
enumField,
integerField,
interactionTargetField,
numberField,
operatorField,
pointField,
repeatedFields,
requiredField,
selectorSnapshotFields,
stringField,
type CommandFieldMap,
type InferCommandInput,
} from '../command-input.ts';
import { readCommonInput, type CommonCommandInput } from '../common-input-fields.ts';
import { readInputRecord } from '../input-readers.ts';
import { defineFieldCommandMetadata } from '../field-command-contract.ts';
import { postActionObservationFields } from '../post-action-observation-grammar.ts';
const FIND_ACTION_VALUES = [
'click',
'focus',
'exists',
'list',
'getText',
'getAttrs',
'wait',
'fill',
'type',
] as const;
const interactionCommandDescriptions = {
click:
"Activate a UI target by snapshot ref, selector, or coordinates. Prefer a ref or selector after a snapshot; use coordinates only when semantic targeting is unavailable. This can change app state. Success means the click was dispatched, not that it landed: use settle or verify to confirm the result without a follow-up snapshot, or wait for the expected screen. A ref or selector target is re-checked for motion before dispatch when the session's previous action just animated the screen, and is dispatched at its resting position; one that has not stopped refuses with target_still_moving rather than acting where it was.",
press:
"Short-press a UI target by snapshot ref, selector, or coordinates. Use longpress instead when the target requires a context-menu or hold gesture. Success means the press was dispatched, not that it landed: use settle or verify to confirm the result, or wait for the expected screen. A ref or selector target is re-checked for motion before dispatch when the session's previous action just animated the screen, and is dispatched at its resting position; one that has not stopped refuses with target_still_moving rather than acting where it was.",
fill: 'Replace text in a UI input selected by snapshot ref, selector, or coordinates. Pass an empty text to clear the field. Inspect unconfirmed evidence and assert the expected value or resulting screen before continuing. Prefer refs or selectors after snapshot; use recordAs to keep sensitive text out of a recorded replay while sending it to the live app.',
longpress:
'Hold a UI target by snapshot ref, selector, or coordinates to open a context menu or perform another hold gesture. Set durationMs when the default hold duration is unsuitable.',
hover:
'Move the pointer over a UI target by snapshot ref, selector, or coordinates without pressing, to reveal hover-gated UI such as row toolbars or menus. Web only; touch platforms have no hover state. Use settle to observe what the hover revealed without a follow-up snapshot.',
swipe: 'Quick coordinate fling with optional repeat pattern.',
focus:
'Move input focus to explicit screen coordinates without entering text. Prefer semantic interactions when a snapshot ref or selector is available; use type or fill after focus.',
type: 'Append text to the currently focused input. Use fill when the existing field value should be replaced, and focus first when no input is active.',
scroll:
'Scroll in a direction, or toward the top/bottom edge of scrollable content. Set until to a selector to reach an off-screen target in one command rather than a scroll-and-check loop. The optional amount is the finger-path fraction of the viewport axis, honored up to 0.8 of it; directional scrolls reduce release momentum, while app scroll physics determine the final content offset. A visible keyboard shortens the swiped band instead of being dismissed; when too little is left, the command refuses with scroll_keyboard_occludes_surface. A directional scroll also reports the movement it observed as movement: moved, at-edge, unchanged, or unobserved when the two reads could not back a claim either way; an unchanged surface inside a container that still hides content in that direction refuses with scroll_no_progress rather than repeating the requested distance. The movement field is absent where a tier verifies per pass (top/bottom, until), where the runtime cannot read a screen, or where a settle observation or a replay already owns that observation.',
get: 'Read text or accessibility attributes from a snapshot ref or selector without changing the app. Use format text for visible content or attrs for the element attribute map.',
is: 'Check whether a selector satisfies a UI predicate such as visible, hidden, exists, absent, editable, selected, focused, or text. `absent` passes only when one readable, complete, settled, unscoped, full-depth accessibility capture has zero matches. Use wait when the condition may appear asynchronously.',
find: 'Find by text/label/value/role/id and run action. The role locator matches snapshot kind vocabulary (button, text, text-field, switch, ...); pre-reconciliation leaf spellings (statictext, edittext, textview) stay accepted on the nodes that carried them during a deprecation window.',
gesture:
'Perform a structured pan, fling, swipe, pinch, rotate, transform, or drag gesture. Select the gesture kind, then provide only the inputs that apply to that kind.',
} as const;
type InteractionCommandName = keyof typeof interactionCommandDescriptions;
const clickFields = {
target: requiredField(interactionTargetField()),
button: enumField(CLICK_BUTTONS, 'Pointer button for platforms that support mouse buttons.'),
...selectorSnapshotFields(),
...repeatedFields(),
...postActionObservationFields('click'),
};
const pressFields = {
target: requiredField(interactionTargetField()),
...selectorSnapshotFields(),
...repeatedFields(),
...postActionObservationFields('press'),
};
const fillFields = {
target: requiredField(interactionTargetField()),
// "" is accepted and means "replace with nothing", i.e. clear the field (#2063). The key
// must still be present: omitting it is a missing argument, not a clear.
text: requiredField(
stringField('Text to enter into the target. Pass "" to clear it.', { allowEmpty: true }),
),
delayMs: integerField('Delay between typed characters.', { min: 0 }),
recordAs: stringField(
'When script recording is armed, send text to the live app but publish it as ${VAR}. Use an uppercase replay variable name such as PASSWORD.',
),
textStdin: operatorField(
booleanField(
"Operator-only: text was read from the CLI's stdin, so it is kept out of diagnostics and recorded actions.",
),
{
operatorPath:
'Pass --text-stdin on the CLI and pipe the text in; it is not exposed to model-facing tools.',
},
),
...selectorSnapshotFields(),
...postActionObservationFields('fill'),
};
const longPressFields = {
target: requiredField(interactionTargetField()),
durationMs: integerField('Long press duration in milliseconds.', { min: 0 }),
...selectorSnapshotFields(),
...postActionObservationFields('longpress'),
};
const hoverFields = {
target: requiredField(interactionTargetField()),
...selectorSnapshotFields(),
...postActionObservationFields('hover'),
};
const swipeFields = {
from: requiredField(pointField('Swipe start point.')),
to: requiredField(pointField('Swipe end point.')),
count: integerField('Number of swipe repetitions.', { min: 1, max: SWIPE_REPETITION_MAX }),
pauseMs: integerField('Pause between repeated swipes.', { min: 0, max: SWIPE_PAUSE_MAX_MS }),
pattern: enumField(SWIPE_PATTERNS),
};
const focusFields = {
x: requiredField(numberField('X coordinate.')),
y: requiredField(numberField('Y coordinate.')),
};
const typeFields = {
text: requiredField(stringField('Text to type.')),
delayMs: integerField('Delay between typed characters.', { min: 0 }),
};
const scrollFields = {
direction: requiredField(enumField(SCROLL_INPUT_DIRECTIONS)),
amount: numberField('Platform scroll amount.'),
pixels: integerField('Pixel scroll amount.', { min: 0 }),
until: stringField(
'Repeat scroll passes until this selector is visible on screen, then stop. Not valid with the top/bottom edge directions, which carry their own stop condition.',
),
durationMs: integerField('Scroll duration in milliseconds when the backend supports pacing.', {
min: 0,
max: SCROLL_DURATION_MAX_MS,
}),
...postActionObservationFields('scroll'),
};
// #1271 stage 2 (ADR 0012 amendment): `get`/`is`/`find` are observation-only,
// so a repair-armed heal excludes an OUT-OF-BAND one by default. Both flags
// are exposed here so the Node SDK's typed options and the MCP tool schema can
// set them, mirroring `--no-record`/`--record` on the CLI. On `find`, `record`
// is valid only for a read-only action — a mutating `find … click|fill|focus|
// type` is refused as INVALID_ARGS by the daemon (`handleFindCommands`), since
// the observe-vs-mutate split is a positional the schema cannot see.
const recordControlFields = () => ({
noRecord: booleanField('Do not record this action.'),
record: booleanField(
'Force-record this out-of-band observation into a repair-armed heal (mutually exclusive with noRecord). Authored replay steps are recorded automatically and never need this. On find, valid only for a read-only action.',
),
});
const getFields = {
format: requiredField(enumField(['text', 'attrs'] as const)),
target: requiredField(elementTargetField()),
...selectorSnapshotFields(),
...recordControlFields(),
};
const isFields = {
predicate: requiredField(enumField(IS_PREDICATES)),
selector: requiredField(stringField()),
value: stringField(),
...selectorSnapshotFields(),
...recordControlFields(),
};
const findFields = {
locator: enumField(FIND_LOCATORS),
query: requiredField(stringField()),
action: enumField(FIND_ACTION_VALUES),
// `find <q> fill ""` is the clear request (#2063); the daemon handler still refuses a MISSING
// value, and an empty `type` value.
value: stringField(undefined, { allowEmpty: true }),
timeoutMs: integerField(),
first: booleanField(),
last: booleanField(),
depth: integerField(),
raw: booleanField(),
...recordControlFields(),
};
const gestureFields = {
kind: requiredField(enumField(GESTURE_KINDS, 'Gesture variant.')),
direction: enumField(SCROLL_DIRECTIONS, 'Fling direction.'),
preset: enumField(SWIPE_PRESETS, 'Swipe preset.'),
origin: pointField('Gesture origin point.'),
delta: pointField('Movement delta for pan or transform gestures.'),
distance: integerField('Fling distance.', { min: 0 }),
scale: numberField('Pinch or transform scale.'),
degrees: numberField('Rotation in degrees.'),
durationMs: integerField('Pan/transform duration.', { min: 16, max: 10_000 }),
pointerCount: integerField('Pan touch pointer count (1 or 2).', { min: 1, max: 2 }),
source: stringField('Drag source @ref or selector.'),
destination: stringField('Drag destination @ref or selector.'),
sourceHoldMs: integerField('Drag activation hold duration.', { min: 1, max: 10_000 }),
moveMs: integerField('Drag movement duration.', { min: 16, max: 10_000 }),
destinationHoldMs: integerField('Hold before releasing at the destination.', {
min: 0,
max: 10_000,
}),
};
export type ClickInput = InferCommandInput<typeof clickFields>;
export type PressInput = InferCommandInput<typeof pressFields>;
export type FillInput = InferCommandInput<typeof fillFields>;
export type LongPressInput = InferCommandInput<typeof longPressFields>;
export type HoverInput = InferCommandInput<typeof hoverFields>;
export type GetInput = InferCommandInput<typeof getFields>;
export type PanInput = CommonCommandInput & PanGesturePayload;
export type FlingInput = CommonCommandInput & FlingGesturePayload;
export type SwipeGestureInput = CommonCommandInput & SwipeGesturePayload;
export type PinchInput = CommonCommandInput & PinchGesturePayload;
export type RotateInput = CommonCommandInput & RotateGesturePayload;
export type TransformInput = CommonCommandInput & TransformGesturePayload;
export type DragInput = CommonCommandInput & DragGesturePayload;
export type GestureInput =
| PanInput
| FlingInput
| SwipeGestureInput
| PinchInput
| RotateInput
| TransformInput
| DragInput;
export const interactionCommandMetadata = [
defineInteractionCommandMetadata('click', clickFields),
defineInteractionCommandMetadata('press', pressFields),
defineInteractionCommandMetadata('fill', fillFields),
defineInteractionCommandMetadata('longpress', longPressFields),
defineInteractionCommandMetadata('hover', hoverFields),
defineInteractionCommandMetadata('swipe', swipeFields),
defineInteractionCommandMetadata('focus', focusFields),
defineInteractionCommandMetadata('type', typeFields),
defineInteractionCommandMetadata('scroll', scrollFields),
defineInteractionCommandMetadata('get', getFields, { parseableOutput: true }),
defineInteractionCommandMetadata('is', isFields),
defineInteractionCommandMetadata('find', findFields, { parseableOutput: true }),
defineFieldCommandMetadata('gesture', interactionCommandDescriptions.gesture, gestureFields, {
readInput: readGestureInput,
}),
] as const;
export function readGestureInput(input: unknown): GestureInput {
const record = readInputRecord(input);
return { ...readCommonInput(record), ...readGesturePayload(record) } as GestureInput;
}
function defineInteractionCommandMetadata<
const TName extends InteractionCommandName,
const TFields extends CommandFieldMap,
>(name: TName, fields: TFields, options?: { parseableOutput?: true }) {
return defineFieldCommandMetadata(name, interactionCommandDescriptions[name], fields, options);
}