fix(core): handle null data in WaitFor and support array keyName in KeyboardPress (#1354)

* fix(core): handle null data in WaitFor and support array keyName in KeyboardPress

This commit fixes two critical bugs:

1. **Fix null data handling in task execution**
   - Fixed TypeError when AI extract() returns null for WaitFor operations
   - Added null/undefined check before accessing data properties
   - WaitFor operations now return false when data is null (condition not met)
   - Other operations (Assert, Query, String, Number) return null when data is null
   - Location: src/agent/tasks.ts:936-938

2. **Add array support for keyName in KeyboardPress**
   - Updated actionKeyboardPressParamSchema to accept string | string[]
   - Allows key combinations like ['Control', 'A'] for keyboard shortcuts
   - Maintains backward compatibility with string format
   - Updated type definitions in aiKeyboardPress method
   - Locations:
     - src/device/index.ts:197-199
     - src/agent/agent.ts:575-622

**Test Coverage:**
- Added comprehensive unit tests for null data handling (8 test cases)
- Added unit tests for keyName array validation (7 test cases)
- All tests verify edge cases and expected behavior

Fixes issue where executor crashed with:
"TypeError: Cannot read properties of null (reading 'StatementIsTruthy')"

And fixes parameter validation error:
"Invalid parameters for action KeyboardPress: Expected string, received array"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(ios,android): handle array keyName in KeyboardPress action

- Updated iOS and Android device implementations to handle keyName as string | string[]
- For mobile devices, array keys are joined with '+' (e.g., ['Control', 'A'] becomes 'Control+A')
- This fixes TypeScript compilation errors in iOS and Android packages
- Maintains backward compatibility with string format

Related to the KeyboardPress array support added in the previous commit.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor(ios,android): improve KeyboardPress array handling

- Remove incorrect join('+') approach that doesn't work on mobile devices
- Use last key from array instead (e.g., ['Control', 'A'] → 'A')
- Add clear warning messages when array input is used on mobile platforms
- Mobile devices don't support keyboard combinations, this is a graceful degradation

This makes the behavior more predictable and provides better feedback to developers.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* test(core): fix TaskExecutor constructor arguments in null data tests

- Fixed TaskExecutor constructor call to match actual signature
- Constructor requires (interface, insight, options) instead of (insight, interface)
- All 8 tests now passing

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(ios,android): improve logging for unsupported key combinations in device input

* fix(core): handle null data in WaitFor and improve keyName parameter description

This commit fixes the null data handling bug and improves the KeyboardPress parameter description.

## Changes:

### 1. Fix null data handling in task execution
- Fixed TypeError when AI extract() returns null for WaitFor operations
- Added null/undefined check before accessing data properties (tasks.ts:936-938)
- WaitFor operations now return false when data is null (condition not met)
- Other operations (Assert, Query, String, Number) return null when data is null

### 2. Improve KeyboardPress parameter description
- Reverted keyName to only accept string type (not array)
- Added clear description: "Use '+' for key combinations, e.g., 'Control+A', 'Shift+Enter'"
- This provides better guidance to AI for generating key combinations
- Simplified iOS/Android implementations (no special array handling needed)

### 3. Test coverage
- Added 8 unit tests for null data handling
- Updated KeyboardPress tests to validate string-only format
- Added test for key combination strings (e.g., 'Control+A')
- Added test to verify arrays are rejected
- Fixed unused variable warning in test file

## Fixed Issues:

**Issue 1:** Executor crashes with null data
```
TypeError: Cannot read properties of null (reading 'StatementIsTruthy')
```

**Issue 2:** Unclear how to specify key combinations
- Now clearly documented in parameter description with examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* docs(core): align KeyboardPress action description with parameter schema

Updated the KeyboardPress action description to explicitly mention
support for key combinations (e.g., "Control+A", "Shift+Enter"),
making it consistent with the keyName parameter description that
already documented this functionality.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix(core): handle null and undefined data in WaitFor output processing

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: quanru

packages/android/src/device.ts

@@ -212,8 +212,7 @@ export class AndroidDevice implements AbstractInterface {
         );
       }),
       defineActionKeyboardPress(async (param) => {
-        const key = param.keyName;
-        await this.keyboardPress(key);
+        await this.keyboardPress(param.keyName);
       }),
       defineAction({
         name: 'AndroidBackButton',

packages/core/src/agent/tasks.ts

@@ -933,9 +933,17 @@ export class TaskExecutor {
           // If AI returned a plain string instead of structured format, use it directly
           if (typeof data === 'string') {
             outputResult = data;
+          } else if (type === 'WaitFor') {
+            if (data === null || data === undefined) {
+              outputResult = false;
+            } else {
+              outputResult = (data as any)[keyOfResult];
+            }
+          } else if (data === null || data === undefined) {
+            outputResult = null;
           } else {
             assert(
-              type !== 'WaitFor' ? data?.[keyOfResult] !== undefined : true,
+              data?.[keyOfResult] !== undefined,
               'No result in query data',
             );
             outputResult = (data as any)[keyOfResult];

packages/core/src/device/index.ts

@@ -194,7 +194,11 @@ export const actionKeyboardPressParamSchema = z.object({
   locate: getMidsceneLocationSchema()
     .describe('The element to be clicked before pressing the key')
     .optional(),
-  keyName: z.string().describe('The key to be pressed'),
+  keyName: z
+    .string()
+    .describe(
+      "The key to be pressed. Use '+' for key combinations, e.g., 'Control+A', 'Shift+Enter'",
+    ),
 });
 export type ActionKeyboardPressParam = {
   locate?: LocateResultElement;
@@ -210,7 +214,7 @@ export const defineActionKeyboardPress = (
   >({
     name: 'KeyboardPress',
     description:
-      'Press a function key, like "Enter", "Tab", "Escape". Do not use this to type text.',
+      'Press a key or key combination, like "Enter", "Tab", "Escape", or "Control+A", "Shift+Enter". Do not use this to type text.',
     interfaceAlias: 'aiKeyboardPress',
     paramSchema: actionKeyboardPressParamSchema,
     call,

packages/core/tests/unit-test/action-param-validation.test.ts

@@ -1,5 +1,5 @@
 import { getMidsceneLocationSchema, parseActionParam } from '@/ai-model';
-import { defineAction } from '@/device';
+import { actionKeyboardPressParamSchema, defineAction } from '@/device';
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod';
 
@@ -255,7 +255,7 @@ describe('Action Parameter Validation', () => {
             .default(false)
             .describe('Append instead of replace'),
         }),
-        call: async (param) => {
+        call: async () => {
           // Mock implementation
         },
       });
@@ -321,4 +321,68 @@ describe('Action Parameter Validation', () => {
       expect(parsed.value).toBe('test');
     });
   });
+
+  describe('KeyboardPress Action', () => {
+    it('should accept keyName as a string', () => {
+      const rawParam = {
+        keyName: 'Enter',
+      };
+
+      const parsed = parseActionParam(rawParam, actionKeyboardPressParamSchema);
+
+      expect(parsed).toEqual({
+        keyName: 'Enter',
+      });
+    });
+
+    it('should accept keyName as key combination string', () => {
+      const rawParam = {
+        keyName: 'Control+A',
+      };
+
+      const parsed = parseActionParam(rawParam, actionKeyboardPressParamSchema);
+
+      expect(parsed).toEqual({
+        keyName: 'Control+A',
+      });
+    });
+
+    it('should accept keyName with optional locate parameter', () => {
+      const rawParam = {
+        keyName: 'Control+V',
+        locate: {
+          prompt: 'text input field',
+          deepThink: false,
+        },
+      };
+
+      const parsed = parseActionParam(rawParam, actionKeyboardPressParamSchema);
+
+      expect(parsed.keyName).toEqual('Control+V');
+      expect(parsed.locate).toEqual({
+        prompt: 'text input field',
+        deepThink: false,
+      });
+    });
+
+    it('should reject keyName with invalid type', () => {
+      const rawParam = {
+        keyName: 123, // Invalid type
+      };
+
+      expect(() =>
+        parseActionParam(rawParam, actionKeyboardPressParamSchema),
+      ).toThrow();
+    });
+
+    it('should reject keyName as array', () => {
+      const rawParam = {
+        keyName: ['Control', 'A'], // Arrays not supported
+      };
+
+      expect(() =>
+        parseActionParam(rawParam, actionKeyboardPressParamSchema),
+      ).toThrow();
+    });
+  });
 });