fix: expose push notification simulation across iOS and Android

Author: thymikee

README.md

@@ -14,7 +14,7 @@ The project is in early development and considered experimental. Pull requests a
 
 ## Features
 - Platforms: iOS (simulator + physical device core automation) and Android (emulator + device).
-- Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `long-press`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `wait`, `alert`, `screenshot`, `close`, `reinstall`.
+- Core commands: `open`, `back`, `home`, `app-switcher`, `press`, `long-press`, `focus`, `type`, `fill`, `scroll`, `scrollintoview`, `wait`, `alert`, `screenshot`, `close`, `reinstall`, `push`.
 - Inspection commands: `snapshot` (accessibility tree), `diff snapshot` (structural baseline diff), `appstate`, `apps`, `devices`.
 - Device tooling: `adb` (Android), `simctl`/`devicectl` (iOS via Xcode).
 - Minimal dependencies; TypeScript executed directly on Node 22+ (no build step).
@@ -137,6 +137,7 @@ agent-device scrollintoview @e42
 
 ## Command Index
 - `boot`, `open`, `close`, `reinstall`, `home`, `back`, `app-switcher`
+- `push`
 - `batch`
 - `snapshot`, `diff snapshot`, `find`, `get`
 - `press` (alias: `click`), `focus`, `type`, `fill`, `long-press`, `swipe`, `scroll`, `scrollintoview`, `pinch`, `is`
@@ -146,6 +147,26 @@ agent-device scrollintoview @e42
 - `settings faceid match|nonmatch|enroll|unenroll` (iOS simulator only)
 - `appstate`, `apps`, `devices`, `session list`
 
+Push notification simulation:
+
+```bash
+# iOS simulator: app bundle + payload file
+agent-device push com.example.app ./payload.apns --platform ios --device "iPhone 16"
+
+# iOS simulator: inline JSON payload
+agent-device push com.example.app '{"aps":{"alert":"Welcome","badge":1}}' --platform ios
+
+# Android: package + payload (action/extras map)
+agent-device push com.example.app '{"action":"com.example.app.PUSH","extras":{"title":"Welcome","unread":3,"promo":true}}' --platform android
+```
+
+Payload notes:
+- iOS uses `xcrun simctl push <device> <bundle> <payload>` and requires APNs-style JSON object (for example `{"aps":{"alert":"..."}}`).
+- Android uses `adb shell am broadcast` with payload JSON shape:
+  `{"action":"<intent-action>","receiver":"<optional component>","extras":{"key":"value","flag":true,"count":3}}`.
+- Android extras support string/boolean/number values.
+- `push` works with session context (uses session device) or explicit device selectors.
+
 ## iOS Snapshots
 
 Notes:

skills/agent-device/SKILL.md

@@ -50,12 +50,19 @@ agent-device open "https://example.com" --platform ios       # iOS deep link (op
 agent-device open MyApp "myapp://screen/to" --platform ios   # iOS deep link in app context
 agent-device close [app]          # Close app or just end session
 agent-device reinstall <app> <path> # Uninstall + install app in one command
+agent-device push <bundle|package> <payload.json|inline-json> # Simulate push notification delivery
 agent-device session list         # List active sessions
 ```
 
 `boot` requires either an active session or an explicit selector (`--platform`, `--device`, `--udid`, or `--serial`).
 `boot` is a fallback, not a regular step: use it when starting a new session only if `open` cannot find/connect to an available target.
 
+Push payloads:
+- iOS simulator (`simctl push`) expects APNs-style JSON, e.g. `{"aps":{"alert":"Welcome","badge":1}}`.
+- Android (`adb shell am broadcast`) expects:
+  `{"action":"com.example.app.PUSH","receiver":"com.example.app/.PushReceiver","extras":{"title":"Welcome","unread":3,"promo":true}}`.
+- Android extras support string/boolean/number values.
+
 ### Snapshot (page analysis)
 
 ```bash

src/core/__tests__/capabilities.test.ts

@@ -33,7 +33,7 @@ test('iOS simulator-only commands reject iOS devices and Android', () => {
 });
 
 test('simulator-only iOS commands with Android support reject iOS devices', () => {
-  for (const cmd of ['settings']) {
+  for (const cmd of ['settings', 'push']) {
     assert.equal(isCommandSupportedOnDevice(cmd, iosSimulator), true, `${cmd} on iOS sim`);
     assert.equal(isCommandSupportedOnDevice(cmd, iosDevice), false, `${cmd} on iOS device`);
     assert.equal(isCommandSupportedOnDevice(cmd, androidDevice), true, `${cmd} on Android`);

src/core/__tests__/dispatch-push.test.ts

@@ -0,0 +1,91 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { promises as fs } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { dispatchCommand } from '../dispatch.ts';
+import { AppError } from '../../utils/errors.ts';
+import type { DeviceInfo } from '../../utils/device.ts';
+
+const ANDROID_DEVICE: DeviceInfo = {
+  platform: 'android',
+  id: 'emulator-5554',
+  name: 'Pixel',
+  kind: 'emulator',
+  booted: true,
+};
+
+test('dispatch push reports missing payload file as INVALID_ARGS', async () => {
+  await assert.rejects(
+    () => dispatchCommand(ANDROID_DEVICE, 'push', ['com.example.app', './missing-payload.json']),
+    (error: unknown) => {
+      assert.equal(error instanceof AppError, true);
+      assert.equal((error as AppError).code, 'INVALID_ARGS');
+      assert.match((error as AppError).message, /payload file not found/i);
+      return true;
+    },
+  );
+});
+
+test('dispatch push reports directory payload path as INVALID_ARGS', async () => {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-dispatch-push-dir-'));
+  try {
+    await assert.rejects(
+      () => dispatchCommand(ANDROID_DEVICE, 'push', ['com.example.app', tempDir]),
+      (error: unknown) => {
+        assert.equal(error instanceof AppError, true);
+        assert.equal((error as AppError).code, 'INVALID_ARGS');
+        assert.match((error as AppError).message, /not a file/i);
+        return true;
+      },
+    );
+  } finally {
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+});
+
+test('dispatch push prefers existing brace-prefixed payload file over inline parsing', async () => {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'agent-device-dispatch-push-brace-'));
+  const adbPath = path.join(tempDir, 'adb');
+  const argsLogPath = path.join(tempDir, 'args.log');
+  const payloadPath = path.join(tempDir, '{payload}.json');
+  await fs.writeFile(
+    adbPath,
+    '#!/bin/sh\nprintf "%s\\n" "$@" > "$AGENT_DEVICE_TEST_ARGS_FILE"\nexit 0\n',
+    'utf8',
+  );
+  await fs.chmod(adbPath, 0o755);
+  await fs.writeFile(payloadPath, '{"action":"com.example.app.PUSH","extras":{"title":"Hello"}}\n', 'utf8');
+
+  const previousPath = process.env.PATH;
+  const previousArgsFile = process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+  process.env.PATH = `${tempDir}${path.delimiter}${previousPath ?? ''}`;
+  process.env.AGENT_DEVICE_TEST_ARGS_FILE = argsLogPath;
+
+  try {
+    const result = await dispatchCommand(ANDROID_DEVICE, 'push', ['com.example.app', payloadPath]);
+    assert.deepEqual(result, {
+      platform: 'android',
+      package: 'com.example.app',
+      action: 'com.example.app.PUSH',
+      extrasCount: 1,
+    });
+    const args = (await fs.readFile(argsLogPath, 'utf8'))
+      .trim()
+      .split('\n')
+      .filter(Boolean);
+    assert.equal(args.includes('-a'), true);
+    assert.equal(args.includes('com.example.app.PUSH'), true);
+    assert.equal(args.includes('--es'), true);
+    assert.equal(args.includes('title'), true);
+  } finally {
+    process.env.PATH = previousPath;
+    if (previousArgsFile === undefined) {
+      delete process.env.AGENT_DEVICE_TEST_ARGS_FILE;
+    } else {
+      process.env.AGENT_DEVICE_TEST_ARGS_FILE = previousArgsFile;
+    }
+    await fs.rm(tempDir, { recursive: true, force: true });
+  }
+});
+

src/core/capabilities.ts

@@ -33,6 +33,7 @@ const COMMAND_CAPABILITY_MATRIX: Record<string, CommandCapability> = {
   open: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   reinstall: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   press: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
+  push: { ios: { simulator: true }, android: { emulator: true, device: true, unknown: true } },
   record: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   screenshot: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },
   scroll: { ios: { simulator: true, device: true }, android: { emulator: true, device: true, unknown: true } },

src/core/dispatch.ts

@@ -8,13 +8,14 @@ import {
   backAndroid,
   ensureAdb,
   homeAndroid,
+  pushAndroidNotification,
   setAndroidSetting,
   snapshotAndroid,
 } from '../platforms/android/index.ts';
 import { listIosDevices } from '../platforms/ios/devices.ts';
 import { getInteractor, type RunnerContext } from '../utils/interactors.ts';
 import { runIosRunnerCommand } from '../platforms/ios/runner-client.ts';
-import { setIosSetting } from '../platforms/ios/index.ts';
+import { pushIosNotification, setIosSetting } from '../platforms/ios/index.ts';
 import { isDeepLinkTarget } from './open-target.ts';
 import type { RawSnapshotNode } from '../utils/snapshot.ts';
 import type { CliFlags } from '../utils/command-schema.ts';
@@ -429,6 +430,28 @@ export async function dispatchCommand(
       await setAndroidSetting(device, setting, state);
       return { setting, state };
     }
+    case 'push': {
+      const target = positionals[0]?.trim();
+      const payloadArg = positionals[1]?.trim();
+      if (!target || !payloadArg) {
+        throw new AppError(
+          'INVALID_ARGS',
+          'push requires <bundle|package> <payload.json|inline-json>',
+        );
+      }
+      const payload = await readNotificationPayload(payloadArg);
+      if (device.platform === 'ios') {
+        await pushIosNotification(device, target, payload);
+        return { platform: 'ios', bundleId: target };
+      }
+      const androidResult = await pushAndroidNotification(device, target, payload);
+      return {
+        platform: 'android',
+        package: target,
+        action: androidResult.action,
+        extrasCount: androidResult.extrasCount,
+      };
+    }
     case 'snapshot': {
       if (device.platform === 'ios') {
         const result = (await withDiagnosticTimer(
@@ -516,6 +539,51 @@ function clampIosSwipeDuration(durationMs: number): number {
   return Math.min(60, Math.max(16, Math.round(durationMs)));
 }
 
+async function readNotificationPayload(payloadArg: string): Promise<Record<string, unknown>> {
+  const trimmed = payloadArg.trim();
+  if (!trimmed) {
+    throw new AppError('INVALID_ARGS', 'push payload cannot be empty');
+  }
+  const payloadText = await resolvePushPayloadText(payloadArg, trimmed);
+  try {
+    const parsed = JSON.parse(payloadText) as unknown;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw new AppError('INVALID_ARGS', 'push payload must be a JSON object');
+    }
+    return parsed as Record<string, unknown>;
+  } catch (error) {
+    if (error instanceof AppError) throw error;
+    throw new AppError('INVALID_ARGS', `Invalid push payload JSON: ${payloadArg}`);
+  }
+}
+
+function looksLikeInlineJson(value: string): boolean {
+  return (value.startsWith('{') && value.endsWith('}')) || (value.startsWith('[') && value.endsWith(']'));
+}
+
+async function resolvePushPayloadText(payloadArg: string, trimmedArg: string): Promise<string> {
+  const filePayload = await tryReadPushPayloadFile(payloadArg);
+  if (filePayload !== null) return filePayload;
+  if (looksLikeInlineJson(trimmedArg)) return trimmedArg;
+  throw new AppError('INVALID_ARGS', `Push payload file not found: ${payloadArg}`);
+}
+
+async function tryReadPushPayloadFile(payloadArg: string): Promise<string | null> {
+  try {
+    return await fs.readFile(payloadArg, 'utf8');
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === 'ENOENT') return null;
+    if (code === 'EISDIR') {
+      throw new AppError('INVALID_ARGS', `Push payload path is not a file: ${payloadArg}`);
+    }
+    if (code === 'EACCES' || code === 'EPERM') {
+      throw new AppError('INVALID_ARGS', `Push payload file is not readable: ${payloadArg}`);
+    }
+    throw new AppError('COMMAND_FAILED', `Unable to read push payload file: ${payloadArg}`, { cause: String(error) });
+  }
+}
+
 export function shouldUseIosTapSeries(
   device: DeviceInfo,
   count: number,