feat(maestro): numeric option fields accept ${VAR} lookup interpolation (#1293)

Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: thymikee

scripts/maestro-conformance/expected-divergence.ts

@@ -73,22 +73,17 @@ export const FLOW_DIVERGENCES: Record<string, FlowDivergence> = {
   // --- Unsupported options on supported commands (parity gaps) ---
   'upstream/032_element_index': {
     classification: 'we-reject',
-    reason: 'A literal tapOn.index is supported; the flow also uses a ${0 + 1} JS-expression index.',
-    unsupported: ['tapOn.index (expression)'],
-    tracking: COMPAT_TRACKER,
+    reason:
+      'tapOn.index supports ${VAR} lookup; the flow uses a ${0 + 1} JS expression, which is not supported.',
+    unsupported: ['tapOn.index (JS expression)'],
+    tracking: 'https://github.com/callstack/agent-device/issues/1292',
   },
   'upstream/034_press_key': {
     classification: 'we-reject',
     reason: 'pressKey supports back/enter/home/return; the flow exercises ~30 Android/TV keycodes.',
     unsupported: ['pressKey (extended keycodes)'],
     tracking: COMPAT_TRACKER,
   },
-  'upstream/042_extended_wait': {
-    classification: 'we-reject',
-    reason: 'A literal extendedWaitUntil.timeout is supported; the flow interpolates ${TIMEOUT} from a flow env block (unresolved ${} is fail-loud).',
-    unsupported: ['extendedWaitUntil.timeout (interpolation)'],
-    tracking: COMPAT_TRACKER,
-  },
   'upstream/076_optional_assertion': {
     classification: 'we-reject',
     reason: 'assertTrue is outside the supported subset; optional is now supported on scrollUntilVisible and extendedWaitUntil.',

scripts/maestro-conformance/normalize.ts

@@ -358,7 +358,7 @@ function canonicalizeAgentCommand(
       return dropUndefined({
         kind: 'assert',
         mode: command.notVisible ? 'notVisible' : 'visible',
-        timed: true,
+        timed: command.timeout != null,
         selector: agentSelector(command.notVisible ?? command.visible),
       });
     case 'swipe':

src/compat/maestro/__tests__/program-ir-parser.test.ts

@@ -463,6 +463,71 @@ describe('parseMaestroProgram', () => {
       /Invalid Maestro YAML flow[\s\S]*\/flows\/includes\/child\.yaml:line 4/i,
     );
   });
+
+  test('parses numeric option fields as literals or variable references', () => {
+    const program = parseMaestroProgram(
+      [
+        '---',
+        '- extendedWaitUntil:',
+        '    visible: Ready',
+        '    timeout: ${TIMEOUT}',
+        '- scrollUntilVisible:',
+        '    element: Item',
+        '    timeout: 1200',
+        '- waitForAnimationToEnd: ${ANIM_TIMEOUT}',
+        '- tapOn:',
+        '    id: button',
+        '    index: ${INDEX}',
+        '    repeat: ${REPEAT}',
+        '    delay: 50',
+        '- doubleTapOn:',
+        '    id: button',
+        '    delay: ${DELAY}',
+        '- swipe:',
+        '    start: 90%, 50%',
+        '    end: 10%, 50%',
+        '    duration: ${DURATION}',
+        '- eraseText: ${CHARS}',
+        '- eraseText:',
+        '    charactersToErase: ${CHARS}',
+      ].join('\n'),
+    );
+
+    const extendedWaitUntil = commandOfKind(program.commands[0], 'extendedWaitUntil');
+    assert.equal(extendedWaitUntil.timeout, '${TIMEOUT}');
+
+    const scrollUntilVisible = commandOfKind(program.commands[1], 'scrollUntilVisible');
+    assert.equal(scrollUntilVisible.timeout, 1200);
+
+    const waitForAnimationToEnd = commandOfKind(program.commands[2], 'waitForAnimationToEnd');
+    assert.equal(waitForAnimationToEnd.timeout, '${ANIM_TIMEOUT}');
+
+    const tapOn = commandOfKind(program.commands[3], 'tapOn');
+    assert.equal(tapOn.index, '${INDEX}');
+    assert.equal(tapOn.repeat, '${REPEAT}');
+    assert.equal(tapOn.delay, 50);
+
+    const doubleTapOn = commandOfKind(program.commands[4], 'doubleTapOn');
+    assert.equal(doubleTapOn.delay, '${DELAY}');
+
+    const swipe = commandOfKind(program.commands[5], 'swipe');
+    assert.equal(swipe.gesture.kind, 'coordinates');
+    assert.equal(swipe.gesture.duration, '${DURATION}');
+
+    const eraseTextScalar = commandOfKind(program.commands[6], 'eraseText');
+    assert.equal(eraseTextScalar.charactersToErase, '${CHARS}');
+    const eraseTextMap = commandOfKind(program.commands[7], 'eraseText');
+    assert.equal(eraseTextMap.charactersToErase, '${CHARS}');
+
+    assert.throws(
+      () => parseMaestroProgram('---\n- tapOn:\n    id: button\n    index: ${0 + 1}\n'),
+      /tapOn\.index.*non-negative integer.*line 4/i,
+    );
+    assert.throws(
+      () => parseMaestroProgram('---\n- eraseText: 0\n'),
+      /eraseText.*positive integer.*line 2/i,
+    );
+  });
 });
 
 function commandOfKind<K extends MaestroCommand['kind']>(

src/compat/maestro/__tests__/runtime-port.test.ts

@@ -344,4 +344,81 @@ describe('MaestroRuntimePort', () => {
       }),
     ).rejects.toBe(failure);
   });
+
+  test('resolves ${VAR} numeric option fields to numbers at runtime', async () => {
+    const calls: RecordedCall[] = [];
+    const operations = makeOperations({
+      tapOn: vi.fn(async (input, context) => record(calls, 'tapOn', input, context)),
+      doubleTapOn: vi.fn(async (input, context) => record(calls, 'doubleTapOn', input, context)),
+      eraseText: vi.fn(async (input, context) => record(calls, 'eraseText', input, context)),
+      scrollUntilVisible: vi.fn(async (input, context) =>
+        record(calls, 'scrollUntilVisible', input, context),
+      ),
+      waitForAnimationToEnd: vi.fn(async (input, context) =>
+        record(calls, 'waitForAnimationToEnd', input, context),
+      ),
+      gesture: vi.fn(async (input, context) => record(calls, 'gesture', input, context)),
+    });
+    const program = parseMaestroProgram(
+      [
+        '---',
+        '- tapOn:',
+        '    id: button',
+        '    index: ${INDEX}',
+        '    repeat: ${REPEAT}',
+        '    delay: ${DELAY}',
+        '- doubleTapOn:',
+        '    id: button',
+        '    delay: ${DELAY}',
+        '- eraseText:',
+        '    charactersToErase: ${CHARS}',
+        '- scrollUntilVisible:',
+        '    element: Item',
+        '    timeout: ${SCROLL_TIMEOUT}',
+        '- waitForAnimationToEnd: ${ANIM_TIMEOUT}',
+        '- swipe:',
+        '    start: 90%, 50%',
+        '    end: 10%, 50%',
+        '    duration: ${DURATION}',
+      ].join('\n'),
+    );
+
+    await executeMaestroProgram(program, createMaestroRuntimePort(operations), {
+      env: {
+        INDEX: '2',
+        REPEAT: '3',
+        DELAY: '100',
+        CHARS: '4',
+        SCROLL_TIMEOUT: '5000',
+        ANIM_TIMEOUT: '2000',
+        DURATION: '250',
+      },
+    });
+
+    expect(calls).toHaveLength(6);
+    expect(calls[0]).toMatchObject({
+      kind: 'tapOn',
+      input: { target: expect.anything(), repeat: 3, delay: 100 },
+    });
+    expect(calls[1]).toMatchObject({
+      kind: 'doubleTapOn',
+      input: { target: expect.anything(), delay: 100 },
+    });
+    expect(calls[2]).toMatchObject({
+      kind: 'eraseText',
+      input: { charactersToErase: 4 },
+    });
+    expect(calls[3]).toMatchObject({
+      kind: 'scrollUntilVisible',
+      input: { timeoutMs: 5000 },
+    });
+    expect(calls[4]).toMatchObject({
+      kind: 'waitForAnimationToEnd',
+      input: { timeoutMs: 2000 },
+    });
+    expect(calls[5]).toMatchObject({
+      kind: 'gesture',
+      input: { durationMs: 250 },
+    });
+  });
 });

src/compat/maestro/engine-flow.ts

@@ -21,17 +21,50 @@ export function resolveCommand<T extends { readonly source: MaestroCommand['sour
   };
 }
 
+export type ResolveNumericConstraints = {
+  integer?: boolean;
+  nonNegative?: boolean;
+  positive?: boolean;
+};
+
+function resolveNumericDescription(constraints: ResolveNumericConstraints): string {
+  if (constraints.positive) return 'a positive integer';
+  if (constraints.nonNegative) return 'a non-negative integer';
+  if (constraints.integer) return 'an integer';
+  return 'a finite number';
+}
+
+export function resolveNumeric(
+  value: number | string | undefined,
+  name: string,
+  constraints: ResolveNumericConstraints = {},
+): number | undefined {
+  if (value === undefined) return undefined;
+  const num = typeof value === 'number' ? value : Number(value);
+  const description = resolveNumericDescription(constraints);
+  if (!Number.isFinite(num)) {
+    throw new AppError('INVALID_ARGS', `Maestro ${name} must be ${description}.`);
+  }
+  if (constraints.integer && !Number.isInteger(num)) {
+    throw new AppError('INVALID_ARGS', `Maestro ${name} must be ${description}.`);
+  }
+  if (constraints.nonNegative && num < 0) {
+    throw new AppError('INVALID_ARGS', `Maestro ${name} must be ${description}.`);
+  }
+  if (constraints.positive && num <= 0) {
+    throw new AppError('INVALID_ARGS', `Maestro ${name} must be ${description}.`);
+  }
+  return num;
+}
+
 export function readIterationCount(
   value: number | string | undefined,
   fallback: number,
   context: MaestroExecutionContext,
   name: string,
 ): number {
   const resolved = value === undefined ? fallback : Number(context.resolve(String(value)));
-  if (!Number.isInteger(resolved) || resolved < 0) {
-    throw new AppError('INVALID_ARGS', `Maestro ${name} must resolve to a non-negative integer.`);
-  }
-  return resolved;
+  return resolveNumeric(resolved, name, { integer: true, nonNegative: true }) ?? fallback;
 }
 
 export function checkpointMaestroCancellation(signal: AbortSignal | undefined): void {

src/compat/maestro/program-ir-command-parser.ts

@@ -46,8 +46,8 @@ import {
   readOptionalBoolean,
   readOptionalCommandOption,
   readOptionalEntry,
-  readOptionalNonNegativeInteger,
   readOptionalNumber,
+  readOptionalPositiveInteger,
   readOptionalString,
   readRequiredPositiveInteger,
   readRequiredString,
@@ -515,14 +515,3 @@ function parseLaunchArguments(
   if (value === null) invalidAt(`${name} expects a scalar, list, or map.`, node, context);
   return { kind: 'scalar', value };
 }
-
-function readOptionalPositiveInteger(
-  node: Node | null | undefined,
-  name: string,
-  context: MaestroProgramParseContext,
-): number | undefined {
-  const value = readOptionalNonNegativeInteger(node, name, context);
-  if (value !== undefined && value === 0)
-    invalidAt(`Maestro ${name} expects a positive integer.`, node, context);
-  return value;
-}

src/compat/maestro/program-ir-gesture-parser.ts

@@ -296,7 +296,7 @@ export function parseMaestroSwipeCommand(
 function parseCoordinateSwipe(
   entries: readonly MaestroMapEntry[],
   source: MaestroSourceLocation,
-  duration: number | undefined,
+  duration: number | string | undefined,
   commandNode: Node,
   context: MaestroProgramParseContext,
 ): MaestroSwipeCommand {
@@ -331,7 +331,7 @@ function parseTargetSwipe(
   entries: readonly MaestroMapEntry[],
   source: MaestroSourceLocation,
   direction: MaestroDirection | undefined,
-  duration: number | undefined,
+  duration: number | string | undefined,
   commandNode: Node,
   context: MaestroProgramParseContext,
 ): MaestroSwipeCommand {
@@ -360,7 +360,7 @@ function parseTargetSwipe(
 function parseScreenSwipe(
   source: MaestroSourceLocation,
   direction: MaestroDirection | undefined,
-  duration: number | undefined,
+  duration: number | string | undefined,
   commandNode: Node,
   context: MaestroProgramParseContext,
 ): MaestroSwipeCommand {