chore(agentic): improve mobile recipe validation and perps testability (#28974)

## **Description**

This PR is limited to mobile app and mobile agentic validation
improvements discovered while validating perps review flows on `mm-4`.

Scope of this PR:
- stabilize Perps modify-action selectors so live validation no longer
depends on the accidental `undefined-*` selector path
- tighten the mobile agentic recipe contract so invalid
`wait_for.timeout` usage fails fast
- make `validate-recipe.js` schema-validate before execution
- copy screenshots into the passed artifact directory so validation
proof stays with the run artifacts
- document the canonical mobile agentic timing fields in
`scripts/perps/agentic/README.md`

Compatibility note:
- default recipe artifact behavior is unchanged
- only explicit `--artifacts-dir` runs now treat the provided path as
the artifact root, so screenshots and run artifacts stay together under
the requested directory

Out of scope for this PR:
- `.agents/skills/fs-cook`
- `TRACKER.md`
- `docs/readme/fs-cook*.md`
- worker-template integration
- wrapper skill work (`fs-review`, `fs-fixbug`)
- Codex-vs-Claude recipe delegation work

## **Changelog**

CHANGELOG entry: null

## **Related issues**

Fixes:
- none

## **Manual testing steps**

```gherkin
Feature: perps modify-action testability and mobile agentic validation contract

  Scenario: stable modify action selectors are available on the live BTC market details screen
    Given mm-4 is running MetaMask Mobile on PerpsMarketDetails for BTC
    When the user presses the modify button for the open position
    Then the modify action sheet selector appears
    And the stable flip option selector appears
    And the old undefined-derived selector is no longer needed

  Scenario: mobile agentic validation rejects invalid wait timing fields
    Given a recipe uses wait_for with timeout instead of timeout_ms
    When validate-flow-schema.js runs
    Then the recipe fails with an explicit schema error

  Scenario: screenshots are copied into the requested artifact directory
    Given validate-recipe.js runs a recipe with a screenshot step
    When the recipe passes
    Then the screenshot file is copied into the passed artifacts directory
```

## **Screenshots/Recordings**

### **Before**

- Live validation had to rely on `undefined-flip_position`
- Successful screenshots lived outside the requested artifact root

### **After**

- Live selector probe on `mm-4` confirms:
  - `perps-market-details-modify-button`
  - `perps-market-details-modify-action-sheet`
  - `perps-market-details-modify-action-sheet-flip_position`
- Successful screenshots copy into the requested artifacts directory

## **Pre-merge author checklist**

- [x] I've followed [MetaMask Contributor
Docs](https://github.com/MetaMask/contributor-docs) and [MetaMask Mobile
Coding
Standards](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/CODING_GUIDELINES.md).
- [x] I've completed the PR template to the best of my ability
- [x] I've included tests if applicable
- [ ] I've documented my code using [JSDoc](https://jsdoc.app/) format
if applicable
- [ ] I've applied the right labels on the PR (see [labeling
guidelines](https://github.com/MetaMask/metamask-mobile/blob/main/.github/guidelines/LABELING_GUIDELINES.md)).
Not required for external contributors.

#### Performance checks (if applicable)

- [ ] I've tested on Android
  - Ideally on a mid-range device; emulator is acceptable
- [ ] I've tested with a power user scenario
- Use these [power-user
SRPs](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/edit-v2/401401446401?draftShareId=9d77e1e1-4bdc-4be1-9ebb-ccd916988d93)
to import wallets with many accounts and tokens
- [ ] I've instrumented key operations with Sentry traces for production
performance metrics
- See [`trace()`](/app/util/trace.ts) for usage and
[`addToken`](/app/components/Views/AddAsset/components/AddCustomToken/AddCustomToken.tsx#L274)
for an example

For performance guidelines and tooling, see the [Performance
Guide](https://consensyssoftware.atlassian.net/wiki/spaces/TL1/pages/400085549067/Performance+Guide+for+Engineers).

## **Pre-merge reviewer checklist**

- [ ] I've manually tested the PR (e.g. pull and build branch, run the
app, test code being changed).
- [ ] I confirm that this PR addresses all acceptance criteria described
in the ticket it closes and includes the necessary testing evidence such
as recordings and or screenshots.

Author: abretonc7s

app/components/UI/Perps/Perps.testIds.ts

@@ -700,6 +700,7 @@ export const PerpsOrderBookViewSelectorsIDs = {
   LONG_BUTTON: 'perps-order-book-long-button',
   SHORT_BUTTON: 'perps-order-book-short-button',
   MODIFY_BUTTON: 'perps-order-book-modify-button',
+  MODIFY_ACTION_SHEET: 'perps-order-book-modify-action-sheet',
   CLOSE_BUTTON: 'perps-order-book-close-button',
   DEPTH_BAND_BUTTON: 'perps-order-book-depth-band-button',
   DEPTH_BAND_OPTION: 'perps-order-book-depth-band-option',
@@ -762,6 +763,17 @@ export const PerpsTransactionsViewSelectorsIDs = {
   FUNDING_LOAD_MORE_SPINNER: 'perps-transactions-funding-load-more-spinner',
 } as const;
 
+// ========================================
+// PERPS MODIFY ACTION SHEET SELECTORS
+// ========================================
+
+export const PerpsModifyActionSheetSelectorsIDs = {
+  SHEET: 'perps-modify-action-sheet',
+  ADD_TO_POSITION: 'perps-modify-action-sheet-add_to_position',
+  REDUCE_POSITION: 'perps-modify-action-sheet-reduce_position',
+  FLIP_POSITION: 'perps-modify-action-sheet-flip_position',
+} as const;
+
 // ========================================
 // PERPS FLIP POSITION CONFIRM SHEET SELECTORS
 // ========================================

app/components/UI/Perps/Views/PerpsMarketDetailsView/PerpsMarketDetailsView.tsx

@@ -1640,6 +1640,7 @@ const PerpsMarketDetailsView: React.FC<PerpsMarketDetailsViewProps> = () => {
           position={existingPosition ?? undefined}
           onClose={closeModifySheet}
           onReversePosition={handleReversePosition}
+          testID={PerpsMarketDetailsViewSelectorsIDs.MODIFY_ACTION_SHEET}
         />
       )}
 

app/components/UI/Perps/Views/PerpsOrderBookView/PerpsOrderBookView.tsx

@@ -818,6 +818,7 @@ const PerpsOrderBookView: React.FC<PerpsOrderBookViewProps> = ({
           position={existingPosition ?? undefined}
           onClose={closeModifySheet}
           onReversePosition={handleReversePosition}
+          testID={PerpsOrderBookViewSelectorsIDs.MODIFY_ACTION_SHEET}
         />
       )}
 

app/components/UI/Perps/Views/PerpsSelectModifyActionView/PerpsSelectModifyActionView.test.tsx

@@ -38,17 +38,19 @@ jest.mock(
       onClose,
       onActionSelect,
       position,
+      testID,
     }: {
       onClose: () => void;
       onActionSelect: (action: string) => void;
       position?: Position;
+      testID?: string;
     }) {
       const ReactModule = jest.requireActual('react');
       const { View, Text, TouchableOpacity } =
         jest.requireActual('react-native');
       return ReactModule.createElement(
         View,
-        { testID: 'modify-action-sheet' },
+        { testID: testID || 'modify-action-sheet' },
         ReactModule.createElement(Text, null, 'Modify Position'),
         position &&
           ReactModule.createElement(
@@ -126,6 +128,12 @@ describe('PerpsSelectModifyActionView', () => {
     expect(screen.getByTestId('modify-action-sheet')).toBeOnTheScreen();
   });
 
+  it('passes testID through to the modify action sheet', () => {
+    render(<PerpsSelectModifyActionView testID="custom-modify-sheet" />);
+
+    expect(screen.getByTestId('custom-modify-sheet')).toBeOnTheScreen();
+  });
+
   it('renders add to position option', () => {
     render(<PerpsSelectModifyActionView />);
 

app/components/UI/Perps/Views/PerpsSelectModifyActionView/PerpsSelectModifyActionView.tsx

@@ -23,6 +23,7 @@ interface PerpsSelectModifyActionViewProps {
   position?: Position;
   onClose?: () => void;
   onReversePosition?: (position: Position) => void;
+  testID?: string;
 }
 
 const PerpsSelectModifyActionView: React.FC<
@@ -32,6 +33,7 @@ const PerpsSelectModifyActionView: React.FC<
   position: positionProp,
   onClose: onExternalClose,
   onReversePosition,
+  testID,
 }) => {
   const navigation = useNavigation();
   const route =
@@ -159,6 +161,7 @@ const PerpsSelectModifyActionView: React.FC<
       position={position}
       onActionSelect={handleActionSelect}
       sheetRef={sheetRef}
+      testID={testID}
     />
   );
 };

app/components/UI/Perps/components/PerpsModifyActionSheet/PerpsModifyActionSheet.test.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { render, screen, fireEvent } from '@testing-library/react-native';
 import PerpsModifyActionSheet from './PerpsModifyActionSheet';
 import { type Position } from '@metamask/perps-controller';
+import { PerpsModifyActionSheetSelectorsIDs } from '../../Perps.testIds';
 const { mockTheme } = jest.requireActual('../../../../../util/theme');
 
 // Mock dependencies
@@ -268,6 +269,23 @@ describe('PerpsModifyActionSheet', () => {
     expect(screen.getByTestId('test-modify-sheet')).toBeOnTheScreen();
   });
 
+  it('uses stable default testIDs when none are provided', () => {
+    render(
+      <PerpsModifyActionSheet
+        onClose={mockOnClose}
+        onActionSelect={mockOnActionSelect}
+        position={mockPosition}
+      />,
+    );
+
+    expect(
+      screen.getByTestId(PerpsModifyActionSheetSelectorsIDs.SHEET),
+    ).toBeOnTheScreen();
+    expect(
+      screen.getByTestId(PerpsModifyActionSheetSelectorsIDs.FLIP_POSITION),
+    ).toBeOnTheScreen();
+  });
+
   it('renders action items with correct testIDs', () => {
     render(
       <PerpsModifyActionSheet

app/components/UI/Perps/components/PerpsModifyActionSheet/PerpsModifyActionSheet.tsx

@@ -18,6 +18,7 @@ import { strings } from '../../../../../../locales/i18n';
 import styleSheet from './PerpsModifyActionSheet.styles';
 import type { ModifyAction } from './PerpsModifyActionSheet.types';
 import { type Position } from '@metamask/perps-controller';
+import { PerpsModifyActionSheetSelectorsIDs } from '../../Perps.testIds';
 
 interface ActionOption {
   action: ModifyAction;
@@ -41,7 +42,7 @@ const PerpsModifyActionSheet: React.FC<PerpsModifyActionSheetProps> = ({
   position,
   onActionSelect,
   sheetRef: externalSheetRef,
-  testID,
+  testID = PerpsModifyActionSheetSelectorsIDs.SHEET,
 }) => {
   const { styles } = useStyles(styleSheet, {});
   const internalSheetRef = useRef<BottomSheetRef>(null);

scripts/perps/agentic/README.md

@@ -231,7 +231,7 @@ Executable gate checks that must pass before a flow runs. Defined in `teams/<tea
 | `eval_ref` | `ref`, `assert` | Run a named eval ref |
 | `call` | `ref` | Call another flow (workflow nodes only) |
 | `wait` | | Pause N ms |
-| `wait_for` | condition | Poll until condition met (route/test_id/expression) |
+| `wait_for` | condition | Poll until condition met (route/test_id/expression). Canonical timing fields are `timeout_ms` and `poll_ms`. |
 | `log_watch` | `watch_for` or `must_not_appear` | Scan Metro logs |
 | `screenshot` | | Capture screen |
 | `manual` | | Human intervention point |

scripts/perps/agentic/validate-flow-schema.js

@@ -83,6 +83,11 @@ function validateActionShape(node, issues) {
       if (!node.route && !node.not_route && !node.test_id && !node.expression) {
         issues.push(`  [${node.id || '?'}] action="wait_for" requires a condition`);
       }
+      if ('timeout' in node && !('timeout_ms' in node)) {
+        issues.push(
+          `  [${node.id || '?'}] action="wait_for" uses unsupported field "timeout"; use "timeout_ms" instead`
+        );
+      }
       break;
     case 'switch':
       if (!Array.isArray(node.cases) || node.cases.length === 0) {

scripts/perps/agentic/validate-recipe.js

@@ -30,6 +30,23 @@ const {
 
 const DEFAULT_LOG_LINES = 400;
 
+function validateSchemaOrThrow(appRoot, recipePath) {
+  const validatorPath = path.join(__dirname, 'validate-flow-schema.js');
+  const result = spawnSync('node', [validatorPath, recipePath], {
+    cwd: appRoot,
+    encoding: 'utf8',
+  });
+
+  if (result.status === 0) {
+    return;
+  }
+
+  const output = [result.stdout || '', result.stderr || '']
+    .join('\n')
+    .trim();
+  throw new Error(`Schema validation failed for ${recipePath}\n${output}`);
+}
+
 function timestampSlug() {
   return new Date()
     .toISOString()
@@ -537,11 +554,14 @@ function ensureRunArtifacts(runOptions, recipePath) {
     return state.artifacts;
   }
 
+  const explicitArtifactsDir = runOptions.artifactsDir
+    ? path.resolve(runOptions.artifactsDir)
+    : '';
   const baseDir =
-    runOptions.artifactsDir ||
+    explicitArtifactsDir ||
     path.join(runOptions.appRoot, '.agent', 'recipe-runs');
   const recipeLabel = sanitizeFileSegment(path.basename(recipePath, path.extname(recipePath)));
-  const rootDir = path.resolve(path.join(baseDir, `${timestampSlug()}_${recipeLabel}`));
+  const rootDir = explicitArtifactsDir || path.resolve(path.join(baseDir, `${timestampSlug()}_${recipeLabel}`));
 
   const artifacts = {
     rootDir,
@@ -1644,6 +1664,8 @@ async function main() {
       throw new Error(`No recipe teams directory found: ${teamsDir}`);
     }
 
+    validateSchemaOrThrow(appRoot, recipeInput.recipePath);
+
     const runOptions = {
       appRoot,
       artifactsDir: options.artifactsDir,