Skip to content

Commit 2d0163a

Browse files
committed
feat: add wait stable settle primitive
Add `agent-device wait stable [quietMs] [timeoutMs]` (defaults 500/10000) as a new target kind on the existing wait command/plumbing: it polls the interactive-only tree via the existing selector-snapshot backend at the existing wait poll cadence, and resolves once two or more consecutive captures are unchanged for quietMs, comparing a small local per-node digest (type, label, identifier, rounded rect). Timeout throws the standard wait COMMAND_FAILED shape with capture stats (captures, nodeCount) attached, and the wait-current-surface enrichment now also recognizes the stable timeout message. Successful results add settledAfterMs/captures/nodeCount alongside waitedMs. This rides the same CLI grammar -> command catalog -> daemon handler -> runtime poll loop as `wait text`/`wait selector`; no new runner protocol. Polling snapshots intentionally do not update the session cache, since the interactive-only tree is a settle signal and would otherwise degrade subsequent ref/get/find lookups in the same session. Documents wait stable in `help workflow` as the replacement for guessed sleeps between actions and snapshots in the core loop. Closes #1049
1 parent e3566b6 commit 2d0163a

13 files changed

Lines changed: 350 additions & 11 deletions

File tree

‎src/cli/parser/cli-help.ts‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -218,8 +218,11 @@ Read-only and waits:
218218
agent-device is visible 'label="Online"'
219219
agent-device wait text "Refreshing metrics..." 3000
220220
agent-device wait 'label="Ready"' 3000
221+
agent-device wait stable
222+
agent-device wait stable 500 10000
221223
agent-device find "Increment" press --json
222224
For async/list text presence, prefer wait text over is visible when no interaction is needed.
225+
wait stable [quietMs] [timeoutMs] (defaults 500/10000) replaces guessed sleeps between actions and snapshots in the core loop: it polls the interactive-only tree and resolves once two or more consecutive captures are unchanged for quietMs, or fails with the standard wait-timeout shape plus the last capture stats (captures, nodeCount) on timeout; use it after relaunch/navigation instead of a fixed wait <ms> before the next snapshot or action.
223226
Use snapshot -i only when refs are needed for an action or targeted query.
224227
Ambiguous find: add --first or --last. If info is not visible/exposed, report that gap instead of typing/searching/navigating to reveal it.
225228

‎src/client/client-types.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -440,27 +440,44 @@ type WaitCommandTarget =
440440
text?: never;
441441
ref?: never;
442442
selector?: never;
443+
stable?: never;
444+
quietMs?: never;
443445
timeoutMs?: never;
444446
}
445447
| (SelectorSnapshotCommandOptions & {
446448
text: string;
447449
durationMs?: never;
448450
ref?: never;
449451
selector?: never;
452+
stable?: never;
453+
quietMs?: never;
450454
timeoutMs?: number;
451455
})
452456
| (SelectorSnapshotCommandOptions & {
453457
ref: string;
454458
durationMs?: never;
455459
text?: never;
456460
selector?: never;
461+
stable?: never;
462+
quietMs?: never;
457463
timeoutMs?: number;
458464
})
459465
| (SelectorSnapshotCommandOptions & {
460466
selector: string;
461467
durationMs?: never;
462468
text?: never;
463469
ref?: never;
470+
stable?: never;
471+
quietMs?: never;
472+
timeoutMs?: number;
473+
})
474+
| (SelectorSnapshotCommandOptions & {
475+
stable: true;
476+
durationMs?: never;
477+
text?: never;
478+
ref?: never;
479+
selector?: never;
480+
quietMs?: number;
464481
timeoutMs?: number;
465482
});
466483

‎src/commands/capture/index.test.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,37 @@ describe('capture command interface', () => {
134134
expectInvalidArgs(() => waitDaemonWriter({ text: 'Ready', ref: '@e1' }), 'exactly one');
135135
});
136136

137+
test('reads and writes wait stable with defaults', () => {
138+
expect(waitCliReader(['stable'], flags())).toMatchObject({ stable: true });
139+
expect(waitDaemonWriter({ stable: true })).toMatchObject({
140+
command: 'wait',
141+
positionals: ['stable'],
142+
});
143+
});
144+
145+
test('reads and writes wait stable with quietMs and timeoutMs', () => {
146+
expect(waitCliReader(['stable', '500', '10000'], flags())).toMatchObject({
147+
stable: true,
148+
quietMs: 500,
149+
timeoutMs: 10_000,
150+
});
151+
expect(waitDaemonWriter({ stable: true, quietMs: 500, timeoutMs: 10_000 })).toMatchObject({
152+
command: 'wait',
153+
positionals: ['stable', '500', '10000'],
154+
});
155+
});
156+
157+
test('rejects wait stable combined with another target', () => {
158+
expectInvalidArgs(() => waitDaemonWriter({ stable: true, text: 'Ready' }), 'exactly one');
159+
});
160+
161+
test('rejects wait stable timeoutMs without quietMs', () => {
162+
expectInvalidArgs(
163+
() => waitDaemonWriter({ stable: true, timeoutMs: 10_000 }),
164+
'quietMs before timeoutMs',
165+
);
166+
});
167+
137168
test('reads and writes alert action and timeout', () => {
138169
expect(alertCliReader(['wait', '3000'], flags())).toMatchObject({
139170
action: 'wait',
Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
export const WAIT_KIND_VALUES = ['duration', 'text', 'ref', 'selector'] as const;
1+
export const WAIT_KIND_VALUES = ['duration', 'text', 'ref', 'selector', 'stable'] as const;

‎src/commands/capture/wait.ts‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -26,14 +26,16 @@ import { WAIT_KIND_VALUES } from './wait-command-contract.ts';
2626

2727
const WAIT_COMMAND_NAME = 'wait';
2828

29-
const waitCommandDescription = 'Wait for duration, text, ref, or selector.';
29+
const waitCommandDescription = 'Wait for duration, text, ref, selector, or stable UI.';
3030

3131
const waitCommandMetadata = defineFieldCommandMetadata(WAIT_COMMAND_NAME, waitCommandDescription, {
3232
kind: enumField(WAIT_KIND_VALUES),
3333
durationMs: integerField(),
3434
text: stringField(),
3535
ref: stringField(),
3636
selector: stringField(),
37+
stable: booleanField(),
38+
quietMs: integerField(),
3739
timeoutMs: integerField(),
3840
depth: integerField(),
3941
scope: stringField(),
@@ -45,7 +47,7 @@ const waitCommandDefinition = defineExecutableCommand(waitCommandMetadata, (clie
4547
);
4648

4749
const waitCliSchema = {
48-
usageOverride: 'wait <ms>|text <text>|@ref|<selector> [timeoutMs]',
50+
usageOverride: 'wait <ms>|text <text>|@ref|<selector>|stable [quietMs] [timeoutMs]',
4951
positionalArgs: ['durationOrSelector', 'timeoutMs?'],
5052
allowsExtraPositionals: true,
5153
allowedFlags: [...SELECTOR_SNAPSHOT_FLAGS],
@@ -83,7 +85,7 @@ function readWaitOptionsFromPositionals(
8385
if (!parsed) {
8486
throw new AppError(
8587
'INVALID_ARGS',
86-
'wait requires <ms>, text <text>, @ref, or <selector> [timeoutMs].',
88+
'wait requires <ms>, text <text>, @ref, <selector> [timeoutMs], or stable [quietMs] [timeoutMs].',
8789
);
8890
}
8991
const base = {
@@ -98,6 +100,14 @@ function readWaitOptionsFromPositionals(
98100
if (parsed.kind === 'ref') {
99101
return { ...base, ref: parsed.rawRef, ...readTimeoutOption(parsed.timeoutMs) };
100102
}
103+
if (parsed.kind === 'stable') {
104+
return {
105+
...base,
106+
stable: true,
107+
...readQuietOption(parsed.quietMs),
108+
...readTimeoutOption(parsed.timeoutMs),
109+
};
110+
}
101111
return {
102112
...base,
103113
selector: parsed.selectorExpression,
@@ -112,17 +122,25 @@ function waitPositionals(options: WaitCommandOptions): string[] {
112122
options.text !== undefined ? 'text' : undefined,
113123
options.ref !== undefined ? 'ref' : undefined,
114124
options.selector !== undefined ? 'selector' : undefined,
125+
options.stable !== undefined ? 'stable' : undefined,
115126
].filter(Boolean);
116127
if (targets.length !== 1) {
117128
throw new AppError(
118129
'INVALID_ARGS',
119-
'wait command requires exactly one of durationMs, text, ref, or selector.',
130+
'wait command requires exactly one of durationMs, text, ref, selector, or stable.',
120131
);
121132
}
122133
if (options.durationMs !== undefined) return [String(options.durationMs)];
123134
const timeout = optionalNumber(options.timeoutMs);
124135
if (options.text !== undefined) return ['text', options.text, ...timeout];
125136
if (options.ref !== undefined) return [options.ref, ...timeout];
137+
if (options.stable !== undefined) {
138+
const quiet = optionalNumber(options.quietMs);
139+
if (quiet.length === 0 && timeout.length > 0) {
140+
throw new AppError('INVALID_ARGS', 'wait stable requires quietMs before timeoutMs.');
141+
}
142+
return ['stable', ...quiet, ...timeout];
143+
}
126144
const selector = options.selector!;
127145
if (!tryParseSelectorChain(selector)) {
128146
throw new AppError('INVALID_ARGS', `Invalid wait selector: ${selector}`);
@@ -133,3 +151,7 @@ function waitPositionals(options: WaitCommandOptions): string[] {
133151
function readTimeoutOption(timeoutMs: number | null): { timeoutMs?: number } {
134152
return timeoutMs === null ? {} : { timeoutMs };
135153
}
154+
155+
function readQuietOption(quietMs: number | null): { quietMs?: number } {
156+
return quietMs === null ? {} : { quietMs };
157+
}

‎src/commands/interaction/runtime/selector-read-shared.ts‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,12 @@ export async function requireSnapshotSession(
3636
export async function captureSelectorSnapshot(
3737
runtime: AgentDeviceRuntime,
3838
options: CommandContext & SelectorSnapshotOptions,
39-
captureOptions: { updateSession: boolean; scope?: string; includeRects?: boolean } = {
39+
captureOptions: {
40+
updateSession: boolean;
41+
scope?: string;
42+
includeRects?: boolean;
43+
interactiveOnly?: boolean;
44+
} = {
4045
updateSession: true,
4146
},
4247
): Promise<CapturedSnapshot> {
@@ -47,7 +52,7 @@ export async function captureSelectorSnapshot(
4752
const sessionName = options.session ?? 'default';
4853
const session = await runtime.sessions.get(sessionName);
4954
const result = await captureSnapshot(toBackendContext(runtime, options), {
50-
interactiveOnly: false,
55+
interactiveOnly: captureOptions.interactiveOnly ?? false,
5156
depth: options.depth,
5257
scope: captureOptions.scope ?? options.scope,
5358
raw: options.raw,

‎src/commands/interaction/runtime/selector-read.test.ts‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -338,6 +338,163 @@ test('runtime selector convenience methods use explicit target helpers', async (
338338
assert.deepEqual(waited, { kind: 'text', text: 'Ready', waitedMs: 0 });
339339
});
340340

341+
test('runtime wait stable settles after two unchanged captures', async () => {
342+
const snapshot = selectorSnapshot();
343+
const clock = createFakeClock();
344+
let captures = 0;
345+
const device = createAgentDevice({
346+
backend: {
347+
platform: 'ios',
348+
captureSnapshot: async () => {
349+
captures += 1;
350+
return { snapshot };
351+
},
352+
} satisfies AgentDeviceBackend,
353+
artifacts: createLocalArtifactAdapter(),
354+
sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
355+
policy: localCommandPolicy(),
356+
clock,
357+
});
358+
359+
const result = await device.selectors.wait({
360+
session: 'default',
361+
target: { kind: 'stable', quietMs: 500, timeoutMs: 10_000 },
362+
});
363+
364+
// Poll cadence is 300ms; a 500ms quiet window needs a 3rd identical capture to
365+
// accumulate enough elapsed time since the first (baseline) capture.
366+
assert.equal(result.kind, 'stable');
367+
if (result.kind === 'stable') {
368+
assert.equal(result.captures, 3);
369+
assert.equal(result.nodeCount, snapshot.nodes.length);
370+
assert.equal(result.settledAfterMs, result.waitedMs);
371+
}
372+
assert.equal(captures, 3);
373+
});
374+
375+
test('runtime wait stable requires quiet captures after instability before settling', async () => {
376+
const snapshot = selectorSnapshot();
377+
const changedSnapshot = makeSnapshotState([
378+
{
379+
index: 0,
380+
depth: 0,
381+
type: 'Button',
382+
label: 'Loading',
383+
rect: { x: 0, y: 0, width: 1, height: 1 },
384+
},
385+
]);
386+
const clock = createFakeClock();
387+
let captures = 0;
388+
const device = createAgentDevice({
389+
backend: {
390+
platform: 'ios',
391+
captureSnapshot: async () => {
392+
captures += 1;
393+
// First capture unstable/changed relative to the initial nothing-seen-yet state,
394+
// second capture changes again (still unstable), then two identical captures settle.
395+
if (captures <= 2) return { snapshot: captures === 1 ? snapshot : changedSnapshot };
396+
return { snapshot: changedSnapshot };
397+
},
398+
} satisfies AgentDeviceBackend,
399+
artifacts: createLocalArtifactAdapter(),
400+
sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
401+
policy: localCommandPolicy(),
402+
clock,
403+
});
404+
405+
const result = await device.selectors.wait({
406+
session: 'default',
407+
target: { kind: 'stable', quietMs: 500, timeoutMs: 10_000 },
408+
});
409+
410+
assert.equal(result.kind, 'stable');
411+
// capture 1: baseline; capture 2: changed (reset quiet window); capture 3+4: unchanged -> settle.
412+
assert.equal(captures, 4);
413+
});
414+
415+
test('runtime wait stable times out with capture stats when never settling', async () => {
416+
const clock = createFakeClock();
417+
let captures = 0;
418+
const device = createAgentDevice({
419+
backend: {
420+
platform: 'ios',
421+
captureSnapshot: async () => {
422+
captures += 1;
423+
return {
424+
snapshot: makeSnapshotState([
425+
{
426+
index: 0,
427+
depth: 0,
428+
type: 'Button',
429+
label: `Item ${captures}`,
430+
rect: { x: 0, y: 0, width: 1, height: 1 },
431+
},
432+
]),
433+
};
434+
},
435+
} satisfies AgentDeviceBackend,
436+
artifacts: createLocalArtifactAdapter(),
437+
sessions: createMemorySessionStore([{ name: 'default' }]),
438+
policy: localCommandPolicy(),
439+
clock,
440+
});
441+
442+
await assert.rejects(
443+
() =>
444+
device.selectors.wait({
445+
session: 'default',
446+
target: { kind: 'stable', quietMs: 500, timeoutMs: 1_000 },
447+
}),
448+
(error: unknown) =>
449+
error instanceof Error &&
450+
error.message === 'wait timed out waiting for a stable UI' &&
451+
(error as { details?: { reason?: string; captures?: number } }).details?.reason ===
452+
'wait_stable_timeout' &&
453+
typeof (error as { details?: { captures?: number } }).details?.captures === 'number',
454+
);
455+
assert.ok(captures > 1);
456+
});
457+
458+
test('runtime wait stable uses provided defaults when quietMs/timeoutMs are omitted', async () => {
459+
const snapshot = selectorSnapshot();
460+
const clock = createFakeClock();
461+
let captures = 0;
462+
const device = createAgentDevice({
463+
backend: {
464+
platform: 'ios',
465+
captureSnapshot: async () => {
466+
captures += 1;
467+
return { snapshot };
468+
},
469+
} satisfies AgentDeviceBackend,
470+
artifacts: createLocalArtifactAdapter(),
471+
sessions: createMemorySessionStore([{ name: 'default', snapshot }]),
472+
policy: localCommandPolicy(),
473+
clock,
474+
});
475+
476+
const result = await device.selectors.wait({
477+
session: 'default',
478+
target: { kind: 'stable' },
479+
});
480+
481+
assert.equal(result.kind, 'stable');
482+
assert.equal(captures, 3);
483+
});
484+
485+
function createFakeClock(stepMs = 300): {
486+
now: () => number;
487+
sleep: (ms: number) => Promise<void>;
488+
} {
489+
let elapsed = 0;
490+
return {
491+
now: () => elapsed,
492+
sleep: async (ms: number) => {
493+
elapsed += ms > 0 ? ms : stepMs;
494+
},
495+
};
496+
}
497+
341498
function selectorSnapshot(): SnapshotState {
342499
return makeSnapshotState([
343500
{

0 commit comments

Comments
 (0)