fix: make in-app back the default

Author: thymikee

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+CommandExecution.swift

@@ -510,12 +510,10 @@ extension RunnerTests {
       // Return path relative to app container root (tmp/ maps to NSTemporaryDirectory)
       return Response(ok: true, data: DataPayload(message: "tmp/\(fileName)"))
 #endif
-    case .back:
-      performDefaultBackAction(app: activeApp)
-      return Response(ok: true, data: DataPayload(message: "back"))
-    case .backInApp:
+    case .back, .backInApp:
       if tapInAppBackControl(app: activeApp) {
-        return Response(ok: true, data: DataPayload(message: "backInApp"))
+        let message = command.command == .back ? "back" : "backInApp"
+        return Response(ok: true, data: DataPayload(message: message))
       }
       return Response(ok: false, error: ErrorPayload(message: "in-app back control is not available"))
     case .backSystem:

ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+Interaction.swift

@@ -51,13 +51,6 @@ extension RunnerTests {
     start.press(forDuration: 0.05, thenDragTo: end)
   }
 
-  func performDefaultBackAction(app: XCUIApplication) {
-    if tapInAppBackControl(app: app) {
-      return
-    }
-    performBackGesture(app: app)
-  }
-
   func performSystemBackAction(app: XCUIApplication) -> Bool {
 #if os(macOS)
     return false

skills/agent-device/SKILL.md

@@ -48,7 +48,7 @@ Use this skill as a router with mandatory defaults. Read this file first. For no
 - Use `get`, `is`, or `find` when they can answer the question without changing UI state.
 - Use `fill` to replace text.
 - Use `type` to append text.
-- When a task asks to "go back", prefer `back --in-app` for predictable app-owned navigation and reserve plain `back` or `back --system` for platform back gestures or button semantics.
+- When a task asks to "go back", use plain `back` for predictable app-owned navigation and reserve `back --system` for platform back gestures or button semantics.
 - If there is no simulator, no app install, or no open app session yet, switch to `bootstrap-install.md` instead of improvising setup steps.
 - Use the smallest unblock action first when transient UI blocks inspection, but do not navigate, search, or enter new text just to make the UI reveal data unless the user asked for that interaction.
 - Do not use external lookups to compensate for missing on-screen data unless the user asked for them.

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

@@ -43,15 +43,15 @@ async function withMockedAdb(
   }
 }
 
-test('dispatch back maps explicit Android back modes to keyevent 4', async () => {
+test('dispatch back defaults to in-app mode and keeps Android back on keyevent 4', async () => {
   await withMockedAdb('agent-device-dispatch-back-modes-', async (argsLogPath) => {
-    for (const backMode of ['in-app', 'system'] as const) {
+    for (const backMode of [undefined, 'in-app', 'system'] as const) {
       const result = await dispatchCommand(ANDROID_DEVICE, 'back', [], undefined, {
         backMode,
       });
 
       assert.equal(result?.action, 'back');
-      assert.equal(result?.mode, backMode);
+      assert.equal(result?.mode, backMode ?? 'in-app');
     }
 
     const args = (await fs.readFile(argsLogPath, 'utf8')).trim().split('\n').filter(Boolean);
@@ -68,6 +68,12 @@ test('dispatch back maps explicit Android back modes to keyevent 4', async () =>
       'input',
       'keyevent',
       '4',
+      '-s',
+      'emulator-5554',
+      'shell',
+      'input',
+      'keyevent',
+      '4',
     ]);
   });
 });

src/core/dispatch.ts

@@ -408,7 +408,7 @@ export async function dispatchCommand(
         }
         case 'back': {
           await interactor.back(context?.backMode);
-          return { action: 'back', mode: context?.backMode ?? 'default' };
+          return { action: 'back', mode: context?.backMode ?? 'in-app' };
         }
         case 'home': {
           await interactor.home();

src/utils/__tests__/interactors.test.ts

@@ -2,8 +2,8 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { resolveAppleBackRunnerCommand } from '../interactors.ts';
 
-test('resolveAppleBackRunnerCommand keeps default back behavior when no mode is provided', () => {
-  assert.equal(resolveAppleBackRunnerCommand(), 'back');
+test('resolveAppleBackRunnerCommand defaults plain back to in-app navigation', () => {
+  assert.equal(resolveAppleBackRunnerCommand(), 'backInApp');
 });
 
 test('resolveAppleBackRunnerCommand maps explicit back modes to runner commands', () => {

src/utils/interactors.ts

@@ -42,7 +42,7 @@ export type RunnerContext = {
 };
 
 export type BackMode = 'in-app' | 'system';
-export type AppleBackRunnerCommand = 'back' | 'backInApp' | 'backSystem';
+export type AppleBackRunnerCommand = 'backInApp' | 'backSystem';
 
 type Interactor = {
   open(
@@ -154,9 +154,8 @@ export function getInteractor(device: DeviceInfo, runnerContext: RunnerContext):
 }
 
 export function resolveAppleBackRunnerCommand(mode?: BackMode): AppleBackRunnerCommand {
-  if (mode === 'in-app') return 'backInApp';
   if (mode === 'system') return 'backSystem';
-  return 'back';
+  return 'backInApp';
 }
 
 type RunnerOpts = {

website/docs/docs/commands.md

@@ -37,8 +37,8 @@ agent-device app-switcher
 - `open <url>` deep links are supported on Android and iOS.
 - `open <app> <url>` opens a deep link on iOS.
 - `open --platform macos --surface app|frontmost-app|desktop|menubar` selects the macOS session surface explicitly. `app` is the default when an app argument is provided.
-- `back` without flags preserves the legacy default: on Apple targets it prefers an in-app back control first, then falls back to the platform back gesture or remote action; on Android it sends the system back event.
-- `back --in-app` asks for app-owned back navigation explicitly. On Apple targets that means visible in-app back UI only. On Android this currently falls back to the same system back event because Android routes in-app back through that platform event.
+- `back` now defaults to app-owned back navigation. On Apple targets that means visible in-app back UI only. On Android this currently maps to the same back keyevent because Android routes in-app back through that platform event.
+- `back --in-app` is an explicit alias for the default app-owned behavior.
 - `back --system` asks for system back input explicitly. On Android this is the normal back keyevent. On iOS and tvOS it uses the platform back gesture or Siri Remote menu action. On macOS, where there is no generic system back input, `back --system` reports unavailable instead of falling back to app-owned navigation.
 - On iOS devices, `http(s)://` URLs open in Safari when no app is active. Custom scheme URLs require an active app in the session.
 - `AGENT_DEVICE_SESSION` and `AGENT_DEVICE_PLATFORM` can pre-bind a default session/platform for CLI automation runs, so normal commands (`open`, `snapshot`, `press`, `fill`, `screenshot`, `devices`, and `batch`) do not need those flags repeated on every call.
@@ -58,7 +58,7 @@ agent-device app-switcher
 ```bash
 agent-device open "https://example.com" --platform ios           # open link in web browser
 agent-device open MyApp "myapp://screen/to" --platform ios       # open deep link to MyApp
-agent-device back --in-app --platform ios                        # tap visible app back UI only
+agent-device back --platform ios                                 # tap visible app back UI only
 agent-device back --system --platform ios                        # use edge-swipe or remote back action
 agent-device open com.example.myapp --remote-config ./agent-device.remote.json --relaunch
 agent-device reinstall MyApp /path/to/app-debug.apk --platform android --serial emulator-5554