@mobileaidev/ai-app-bridge 0.2.5 → 0.2.7

package/bin/ai-app-bridge.js

@@ -31,6 +31,8 @@ Commands:
   network                Read generic in-app network records.
   state                  Read generic in-app state records.
   events                 Read generic in-app event records.
+  freeze-app             Stop the target app processes with SIGSTOP.
+  thaw-app               Resume the target app processes with SIGCONT.
 
 H5/WebView commands:
   h5-dom                 Read native Android WebView DOM.
@@ -48,7 +50,7 @@ Flutter commands:
   flutter-nodes          Read Flutter operable nodes.
   flutter-action         Dispatch a raw Flutter action payload.
   tap-flutter-text       Tap a Flutter node by text.
-  input-flutter-text     Set Flutter text through the Flutter action bridge.
+  input-flutter-text     Set Flutter text through the Flutter action bridge.
   scroll-flutter         Scroll Flutter content.
   flutter-h5-dom         Read DOM through a Flutter H5 adapter.
   flutter-h5-eval        Execute JavaScript through a Flutter H5 adapter.
@@ -62,18 +64,19 @@ Device/action commands:
   tap-text               Tap a visible node by exact text or content description.
   tap-uia-text           Tap a UIAutomator node by text.
   wait-text              Wait until text appears in bridge or UIAutomator output.
-  input-text             Set native Android text through the in-app bridge; ASCII can fall back to ADB.
+  input-text             Set native Android text through the in-app bridge; ASCII can fall back to ADB.
   swipe                  Swipe device coordinates through ADB.
   keyevent               Send an Android keyevent through ADB.
   keyboard-state         Read Android soft keyboard visibility from dumpsys.
   hide-keyboard          Hide the Android soft keyboard when it is visible.
 
-App/permission commands:
-  install-apk            Install an APK and assist device-side installer screens.
-  launch-app             Launch the target package LAUNCHER Activity.
-  launch-activity        Launch an explicit Android Activity component.
-  launch-native-test     Launch the debug native Android bridge test Activity.
-  launch-flutter         Launch the Flutter Activity.
+App/permission commands:
+  install-apk            Install an APK and assist device-side installer screens.
+  clear-app-data         Clear target app local data through the bridge runtime.
+  launch-app             Launch the target package LAUNCHER Activity.
+  launch-activity        Launch an explicit Android Activity component.
+  launch-native-test     Launch the debug native Android bridge test Activity.
+  launch-flutter         Launch the Flutter Activity.
   permission-state       Read Android runtime permission state.
   permission-grant       Grant an Android runtime permission.
   permission-revoke      Revoke an Android runtime permission.
@@ -94,14 +97,14 @@ Options:
   --adb-timeout-ms <ms>  Timeout for ADB subprocesses.
   --out-file <path>      Screenshot output path.
   --artifact-dir <path>  Directory for generated screenshot/artifact defaults.
-  --apk-path <path>      APK path used by install-apk.
-  --activity <name>      Activity class for launch-activity or launch-app override.
-  --component <pkg/act>  Explicit Android component for launch-activity.
-  --action <name>        Intent action for launch-activity.
-  --category <name>      Intent category for launch-activity; may be repeated.
-  --data <uri>           Intent data URI for launch-activity.
-  --extra <key=value>    String intent extra for launch-activity; may be repeated.
-  --text <text>          Text used by Unicode-safe bridge input commands.
+  --apk-path <path>      APK path used by install-apk.
+  --activity <name>      Activity class for launch-activity or launch-app override.
+  --component <pkg/act>  Explicit Android component for launch-activity.
+  --action <name>        Intent action for launch-activity.
+  --category <name>      Intent category for launch-activity; may be repeated.
+  --data <uri>           Intent data URI for launch-activity.
+  --extra <key=value>    String intent extra for launch-activity; may be repeated.
+  --text <text>          Text used by Unicode-safe bridge input commands.
   --value <text>         Text value used by h5-input or flutter-h5-input.
   --selector <css>       CSS selector used by H5 commands.
   --target-text <text>   Text used by tap-text or wait-text.
@@ -155,7 +158,7 @@ Options:
   --permission <name>    Android permission for permission-* commands.
   --op <name>            App-op name for appops-set.
   --mode <mode>          App-op mode for appops-set.
-  --pid <pid|current>    PID filter for logcat.
+  --pid <pid|current>    PID filter for logcat, or explicit process for freeze/thaw.
   --app-pid              Filter logcat by current app pid.
   --tag <tag[,tag]>      Logcat tag filter.
   --level <level>        Minimum logcat level.
@@ -229,19 +232,19 @@ async function runCommand(command, options, ctx) {
     }
     case 'flutter-nodes':
       return flutterNodes(ctx);
-    case 'tap-flutter-text':
-      return flutterAction(ctx, { action: 'tapText', text: requiredString(options.targetText, 'targetText') });
-    case 'input-flutter-text': {
-      const result = await flutterAction(ctx, {
-        action: 'inputText',
-        text: requiredString(options.text, 'text'),
-        ...(options.tapX !== undefined && options.tapY !== undefined ? { x: Number(options.tapX), y: Number(options.tapY) } : {}),
-      });
-      if (booleanOption(options.hideKeyboard)) {
-        result.keyboard = await hideKeyboard(ctx, options);
-      }
-      return result;
-    }
+    case 'tap-flutter-text':
+      return flutterAction(ctx, { action: 'tapText', text: requiredString(options.targetText, 'targetText') });
+    case 'input-flutter-text': {
+      const result = await flutterAction(ctx, {
+        action: 'inputText',
+        text: requiredString(options.text, 'text'),
+        ...(options.tapX !== undefined && options.tapY !== undefined ? { x: Number(options.tapX), y: Number(options.tapY) } : {}),
+      });
+      if (booleanOption(options.hideKeyboard)) {
+        result.keyboard = await hideKeyboard(ctx, options);
+      }
+      return result;
+    }
     case 'scroll-flutter':
       return options.targetText
         ? flutterAction(ctx, { action: 'scrollUntilText', text: options.targetText, maxSwipes: Number(options.maxSwipes || 12) })
@@ -256,6 +259,10 @@ async function runCommand(command, options, ctx) {
       return bridgeGet(ctx, withQuery('/v1/state', captureQuery(options)));
     case 'events':
       return bridgeGet(ctx, withQuery('/v1/events', captureQuery(options)));
+    case 'freeze-app':
+      return freezeApp(ctx, options);
+    case 'thaw-app':
+      return thawApp(ctx, options);
     case 'h5-dom':
       return bridgeGet(ctx, '/v1/h5/dom');
     case 'h5-eval':
@@ -298,6 +305,8 @@ async function runCommand(command, options, ctx) {
       return hideKeyboard(ctx, options);
     case 'install-apk':
       return installApk(ctx, options);
+    case 'clear-app-data':
+      return clearAppData(ctx);
     case 'webview-pages':
       return webviewPages(ctx, options);
     case 'webview-network':
@@ -327,15 +336,15 @@ async function runCommand(command, options, ctx) {
       return appopsSet(ctx, requiredString(options.op, 'op'), requiredString(options.mode, 'mode'));
     case 'tap-uia-text':
       return tapUiaText(ctx, requiredString(options.targetText, 'targetText'), options);
-    case 'permission-dialog':
-      return permissionDialog(ctx, options);
-    case 'launch-app':
-      return launchApp(ctx, options);
-    case 'launch-activity':
-      return launchActivity(ctx, options);
-    case 'launch-native-test':
-      return launchNativeTest(ctx);
-    case 'launch-flutter':
+    case 'permission-dialog':
+      return permissionDialog(ctx, options);
+    case 'launch-app':
+      return launchApp(ctx, options);
+    case 'launch-activity':
+      return launchActivity(ctx, options);
+    case 'launch-native-test':
+      return launchNativeTest(ctx);
+    case 'launch-flutter':
       return launchFlutter(ctx, options.initialRoute || '');
     case 'smoke':
       return smoke(ctx, options);
@@ -359,25 +368,25 @@ function parseArgs(argv) {
     const rawName = arg.slice(2);
     const name = rawName.replace(/-([a-z])/g, (_, value) => value.toUpperCase());
     const next = argv[index + 1];
-    if (next === undefined || next.startsWith('--')) {
-      appendOption(options, name, true);
-      continue;
-    }
-    appendOption(options, name, next);
-    index += 1;
-  }
-  return { command, options };
-}
-
-function appendOption(options, name, value) {
-  if (name === 'extra' || name === 'category') {
-    if (!Array.isArray(options[name])) options[name] = [];
-    options[name].push(value);
-    return;
-  }
-  options[name] = value;
-}
-
+    if (next === undefined || next.startsWith('--')) {
+      appendOption(options, name, true);
+      continue;
+    }
+    appendOption(options, name, next);
+    index += 1;
+  }
+  return { command, options };
+}
+
+function appendOption(options, name, value) {
+  if (name === 'extra' || name === 'category') {
+    if (!Array.isArray(options[name])) options[name] = [];
+    options[name].push(value);
+    return;
+  }
+  options[name] = value;
+}
+
 async function adb(ctx, args, { binary = false } = {}) {
   const allArgs = adbArgs(ctx, args);
   return new Promise((resolve, reject) => {
@@ -782,41 +791,41 @@ async function ensureForward(ctx) {
   };
 }
 
-async function resolveDevicePort(ctx) {
-  if (ctx.explicitPort) return { port: ctx.port, source: 'explicit-port' };
-  try {
-    const result = await adb(ctx, ['shell', 'run-as', ctx.packageName, 'cat', 'files/ai_app_bridge_port.json']);
-    const state = JSON.parse(result.stdout.trim());
-    const discoveredPort = Number(state.port);
-    if (state.ok === true && Number.isInteger(discoveredPort) && discoveredPort > 0) {
-      return { port: discoveredPort, source: 'package-port-file', state };
-    }
-  } catch (error) {
-    if (!shouldUseDefaultPortFallback(ctx)) {
-      ctx.devicePortSource = 'package-port-file';
-      ctx.devicePortError = firstErrorLine(error);
-      error.aiAppBridgePortDiscovery = true;
-      throw error;
-    }
-    return {
-      port: ctx.port,
-      source: 'default-port',
-      error: firstErrorLine(error),
-    };
-  }
-  if (!shouldUseDefaultPortFallback(ctx)) {
-    const error = new Error(`bridge port discovery failed for explicit package: ${ctx.packageName}`);
-    error.aiAppBridgePortDiscovery = true;
-    ctx.devicePortSource = 'package-port-file';
-    ctx.devicePortError = firstErrorLine(error);
-    throw error;
-  }
-  return { port: ctx.port, source: 'default-port' };
-}
-
-function shouldUseDefaultPortFallback(ctx) {
-  return !ctx.explicitPackageName;
-}
+async function resolveDevicePort(ctx) {
+  if (ctx.explicitPort) return { port: ctx.port, source: 'explicit-port' };
+  try {
+    const result = await adb(ctx, ['shell', 'run-as', ctx.packageName, 'cat', 'files/ai_app_bridge_port.json']);
+    const state = JSON.parse(result.stdout.trim());
+    const discoveredPort = Number(state.port);
+    if (state.ok === true && Number.isInteger(discoveredPort) && discoveredPort > 0) {
+      return { port: discoveredPort, source: 'package-port-file', state };
+    }
+  } catch (error) {
+    if (!shouldUseDefaultPortFallback(ctx)) {
+      ctx.devicePortSource = 'package-port-file';
+      ctx.devicePortError = firstErrorLine(error);
+      error.aiAppBridgePortDiscovery = true;
+      throw error;
+    }
+    return {
+      port: ctx.port,
+      source: 'default-port',
+      error: firstErrorLine(error),
+    };
+  }
+  if (!shouldUseDefaultPortFallback(ctx)) {
+    const error = new Error(`bridge port discovery failed for explicit package: ${ctx.packageName}`);
+    error.aiAppBridgePortDiscovery = true;
+    ctx.devicePortSource = 'package-port-file';
+    ctx.devicePortError = firstErrorLine(error);
+    throw error;
+  }
+  return { port: ctx.port, source: 'default-port' };
+}
+
+function shouldUseDefaultPortFallback(ctx) {
+  return !ctx.explicitPackageName;
+}
 
 async function bridgeStatus(ctx, options = {}) {
   try {
@@ -969,24 +978,24 @@ function normalizeBridgeError(error) {
       suggestion: 'Confirm the target app is running and that the resolved bridge port belongs to this package.',
     };
   }
-  if (lower.includes('adb timed out')) {
-    return {
-      code: 'adb_timeout',
-      message,
-      suggestion: 'Check the device state and retry; if the bridge port is known, pass --port to skip package port discovery.',
-    };
-  }
-  if (error?.aiAppBridgePackageMismatch || lower.includes('bridge package mismatch')) {
-    return {
-      code: 'bridge_package_mismatch',
-      message,
-      suggestion: 'The resolved bridge port belongs to another package. Relaunch the target app and retry with the explicit packageName.',
-    };
-  }
-  if (error?.aiAppBridgePortDiscovery || lower.includes('bridge port discovery failed') || lower.includes('run-as') || lower.includes('package not found')) {
-    return {
-      code: 'bridge_port_discovery_failed',
-      message,
+  if (lower.includes('adb timed out')) {
+    return {
+      code: 'adb_timeout',
+      message,
+      suggestion: 'Check the device state and retry; if the bridge port is known, pass --port to skip package port discovery.',
+    };
+  }
+  if (error?.aiAppBridgePackageMismatch || lower.includes('bridge package mismatch')) {
+    return {
+      code: 'bridge_package_mismatch',
+      message,
+      suggestion: 'The resolved bridge port belongs to another package. Relaunch the target app and retry with the explicit packageName.',
+    };
+  }
+  if (error?.aiAppBridgePortDiscovery || lower.includes('bridge port discovery failed') || lower.includes('run-as') || lower.includes('package not found')) {
+    return {
+      code: 'bridge_port_discovery_failed',
+      message,
       suggestion: 'Install a debuggable build for the requested package or pass --port explicitly.',
     };
   }
@@ -1008,38 +1017,38 @@ function firstErrorLine(error) {
   return String(error?.message || error || 'unknown_error').split(/\r?\n/).find(Boolean) || 'unknown_error';
 }
 
-async function bridgeGet(ctx, requestPath) {
-  await ensureForward(ctx);
-  const body = await httpGet(bridgeUrl(ctx, requestPath));
-  const payload = JSON.parse(body);
-  verifyBridgeTargetPackage(ctx, payload, requestPath);
-  return payload;
-}
-
-async function bridgePost(ctx, requestPath, payload) {
-  await ensureForward(ctx);
-  const body = await httpPost(bridgeUrl(ctx, requestPath), payload);
-  const responsePayload = JSON.parse(body);
-  verifyBridgeTargetPackage(ctx, responsePayload, requestPath);
-  return responsePayload;
-}
-
-function bridgeUrl(ctx, requestPath) {
-  return `http://127.0.0.1:${ctx.hostPort || ctx.port}${requestPath}`;
-}
-
-function verifyBridgeTargetPackage(ctx, payload, requestPath) {
-  if (!ctx.explicitPackageName || !payload || typeof payload !== 'object') return;
-  const responsePackageName = payload.app && typeof payload.app === 'object'
-    ? payload.app.packageName
-    : undefined;
-  if (!responsePackageName || responsePackageName === ctx.packageName) return;
-  const error = new Error(`bridge package mismatch for ${requestPath}: expected ${ctx.packageName}, got ${responsePackageName}`);
-  error.aiAppBridgePackageMismatch = true;
-  error.expectedPackageName = ctx.packageName;
-  error.actualPackageName = responsePackageName;
-  throw error;
-}
+async function bridgeGet(ctx, requestPath) {
+  await ensureForward(ctx);
+  const body = await httpGet(bridgeUrl(ctx, requestPath));
+  const payload = JSON.parse(body);
+  verifyBridgeTargetPackage(ctx, payload, requestPath);
+  return payload;
+}
+
+async function bridgePost(ctx, requestPath, payload) {
+  await ensureForward(ctx);
+  const body = await httpPost(bridgeUrl(ctx, requestPath), payload);
+  const responsePayload = JSON.parse(body);
+  verifyBridgeTargetPackage(ctx, responsePayload, requestPath);
+  return responsePayload;
+}
+
+function bridgeUrl(ctx, requestPath) {
+  return `http://127.0.0.1:${ctx.hostPort || ctx.port}${requestPath}`;
+}
+
+function verifyBridgeTargetPackage(ctx, payload, requestPath) {
+  if (!ctx.explicitPackageName || !payload || typeof payload !== 'object') return;
+  const responsePackageName = payload.app && typeof payload.app === 'object'
+    ? payload.app.packageName
+    : undefined;
+  if (!responsePackageName || responsePackageName === ctx.packageName) return;
+  const error = new Error(`bridge package mismatch for ${requestPath}: expected ${ctx.packageName}, got ${responsePackageName}`);
+  error.aiAppBridgePackageMismatch = true;
+  error.expectedPackageName = ctx.packageName;
+  error.actualPackageName = responsePackageName;
+  throw error;
+}
 
 function httpGet(url) {
   return new Promise((resolve, reject) => {
@@ -1528,6 +1537,95 @@ async function packagePidsFor(ctx) {
   }
 }
 
+async function freezeApp(ctx, options = {}) {
+  return signalAppProcesses(ctx, options, 'SIGSTOP', 'freeze-app');
+}
+
+async function thawApp(ctx, options = {}) {
+  return signalAppProcesses(ctx, options, 'SIGCONT', 'thaw-app');
+}
+
+async function signalAppProcesses(ctx, options, signal, action) {
+  const pids = await targetAppPids(ctx, options);
+  if (pids.length === 0) {
+    return {
+      ok: false,
+      packageName: ctx.packageName,
+      action,
+      signal,
+      error: 'app_process_not_found',
+    };
+  }
+
+  const results = [];
+  for (const pid of pids) {
+    try {
+      const result = await adb(ctx, ['shell', 'run-as', ctx.packageName, 'kill', `-${signal}`, pid]);
+      results.push({
+        pid,
+        ok: true,
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+      });
+    } catch (error) {
+      results.push({
+        pid,
+        ok: false,
+        error: firstErrorLine(error),
+      });
+    }
+  }
+
+  const failed = results.filter((item) => !item.ok);
+  return {
+    ok: failed.length === 0,
+    packageName: ctx.packageName,
+    action,
+    signal,
+    pids,
+    results,
+    ...(failed.length > 0 ? { error: 'signal_failed' } : {}),
+  };
+}
+
+async function targetAppPids(ctx, options = {}) {
+  if (options.pid && options.pid !== true && options.pid !== 'current') {
+    const explicitPid = String(options.pid).trim();
+    return /^\d+$/.test(explicitPid) ? [explicitPid] : [];
+  }
+  const psPids = await packagePidsFromPs(ctx);
+  if (psPids.length > 0) return psPids;
+  return packagePidsFor(ctx);
+}
+
+async function packagePidsFromPs(ctx) {
+  if (!ctx.packageName) return [];
+  try {
+    const result = await adb(ctx, ['shell', 'ps', '-A', '-o', 'PID,NAME']);
+    return parsePackagePidsFromPs(result.stdout, ctx.packageName);
+  } catch (_) {
+    return [];
+  }
+}
+
+function parsePackagePidsFromPs(stdout, packageName) {
+  const pids = [];
+  const seen = new Set();
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || /^PID\s+NAME$/i.test(trimmed)) continue;
+    const match = /^(\d+)\s+(\S+)$/.exec(trimmed);
+    if (!match) continue;
+    const pid = match[1];
+    const processName = match[2];
+    if (processName !== packageName && !processName.startsWith(`${packageName}:`)) continue;
+    if (seen.has(pid)) continue;
+    seen.add(pid);
+    pids.push(pid);
+  }
+  return pids;
+}
+
 function parseWebViewDevToolsSockets(procNetUnix, packagePids = []) {
   const packagePidSet = new Set(packagePids.map(String));
   const sockets = [];
@@ -2843,19 +2941,19 @@ async function tapFlutterText(ctx, targetText, options = {}) {
   };
 }
 
-async function inputFlutterText(ctx, targetText, text) {
-  const operable = await flutterNodes(ctx);
-  const node = findFlutterNode(operable, targetText, 'input');
-  if (!node) {
-    throw new Error(`flutter input node not found: ${targetText}`);
-  }
-  const point = flutterNodePoint(node.input?.bounds || node.bounds, operable.viewport);
-  const result = await flutterAction(ctx, { action: 'inputText', text, x: point.x, y: point.y });
-  return {
-    ...result,
-    source: 'flutter-operable-tree',
-    targetText,
-    text,
+async function inputFlutterText(ctx, targetText, text) {
+  const operable = await flutterNodes(ctx);
+  const node = findFlutterNode(operable, targetText, 'input');
+  if (!node) {
+    throw new Error(`flutter input node not found: ${targetText}`);
+  }
+  const point = flutterNodePoint(node.input?.bounds || node.bounds, operable.viewport);
+  const result = await flutterAction(ctx, { action: 'inputText', text, x: point.x, y: point.y });
+  return {
+    ...result,
+    source: 'flutter-operable-tree',
+    targetText,
+    text,
     node,
     x: point.x,
     y: point.y,
@@ -3529,78 +3627,78 @@ function shouldDismissKeyboardForPoint({ point, viewport, keyboardVisible }) {
   };
 }
 
-async function inputText(ctx, text, options = {}) {
-  const bridgePayload = inputTextBridgePayload(text, options);
-  let bridgeAttempt = null;
-  try {
-    const bridgeResult = await bridgePost(ctx, '/v1/action/input-text', bridgePayload);
-    if (bridgeResult?.ok) {
-      const result = {
-        ...bridgeResult,
-        transport: 'bridge',
-        source: bridgeResult.source || 'native-view',
-        request: bridgePayload,
-      };
-      if (booleanOption(options.hideKeyboard)) {
-        result.keyboard = await hideKeyboard(ctx, options);
-      }
-      return result;
-    }
-    bridgeAttempt = {
-      ok: false,
-      command: 'input-text',
-      requestPath: '/v1/action/input-text',
-      result: bridgeResult,
-      error: bridgeResult?.error || 'bridge_input_failed',
-      message: bridgeResult?.message || 'The app bridge did not accept native text input.',
-    };
-  } catch (error) {
-    bridgeAttempt = buildBridgeFailureResult(ctx, 'input-text', '/v1/action/input-text', error);
-  }
-
-  if (!isAdbInputTextSafe(text)) {
-    return {
-      ok: false,
-      error: 'unicode_text_requires_bridge_input',
-      message: 'This text contains non-ASCII characters. Android adb shell input text cannot reliably enter Unicode; use an app build with AI App Bridge Android runtime 0.1.9+ and retry input-text/input_text.',
-      textLength: text.length,
-      bridge: bridgeAttempt,
-      suggestion: 'Update the target app bridge dependency to ai-app-bridge-android 0.1.9+ and pass --package-name so the CLI can discover the app bridge port.',
-    };
-  }
-
-  await adb(ctx, ['shell', 'input', 'text', text.replace(/ /g, '%s')]);
-  const result = {
-    ok: true,
-    transport: 'adb',
-    source: 'adb-input-text-fallback',
-    text,
-    bridge: bridgeAttempt,
-  };
-  if (booleanOption(options.hideKeyboard)) {
-    result.keyboard = await hideKeyboard(ctx, options);
-  }
-  return result;
-}
-
-function inputTextBridgePayload(text, options = {}) {
-  const payload = { text };
-  const x = Number(options.tapX);
-  const y = Number(options.tapY);
-  if (Number.isFinite(x) && Number.isFinite(y)) {
-    payload.x = x;
-    payload.y = y;
-  }
-  return payload;
-}
-
-function isAdbInputTextSafe(text) {
-  return /^[\x20-\x7e]*$/.test(String(text));
-}
-
-async function swipe(ctx, startX, startY, endX, endY, durationMs) {
-  await adb(ctx, ['shell', 'input', 'swipe', String(startX), String(startY), String(endX), String(endY), String(durationMs)]);
-  return { ok: true, transport: 'adb', startX, startY, endX, endY, durationMs };
+async function inputText(ctx, text, options = {}) {
+  const bridgePayload = inputTextBridgePayload(text, options);
+  let bridgeAttempt = null;
+  try {
+    const bridgeResult = await bridgePost(ctx, '/v1/action/input-text', bridgePayload);
+    if (bridgeResult?.ok) {
+      const result = {
+        ...bridgeResult,
+        transport: 'bridge',
+        source: bridgeResult.source || 'native-view',
+        request: bridgePayload,
+      };
+      if (booleanOption(options.hideKeyboard)) {
+        result.keyboard = await hideKeyboard(ctx, options);
+      }
+      return result;
+    }
+    bridgeAttempt = {
+      ok: false,
+      command: 'input-text',
+      requestPath: '/v1/action/input-text',
+      result: bridgeResult,
+      error: bridgeResult?.error || 'bridge_input_failed',
+      message: bridgeResult?.message || 'The app bridge did not accept native text input.',
+    };
+  } catch (error) {
+    bridgeAttempt = buildBridgeFailureResult(ctx, 'input-text', '/v1/action/input-text', error);
+  }
+
+  if (!isAdbInputTextSafe(text)) {
+    return {
+      ok: false,
+      error: 'unicode_text_requires_bridge_input',
+      message: 'This text contains non-ASCII characters. Android adb shell input text cannot reliably enter Unicode; use an app build with AI App Bridge Android runtime 0.1.9+ and retry input-text/input_text.',
+      textLength: text.length,
+      bridge: bridgeAttempt,
+      suggestion: 'Update the target app bridge dependency to ai-app-bridge-android 0.1.9+ and pass --package-name so the CLI can discover the app bridge port.',
+    };
+  }
+
+  await adb(ctx, ['shell', 'input', 'text', text.replace(/ /g, '%s')]);
+  const result = {
+    ok: true,
+    transport: 'adb',
+    source: 'adb-input-text-fallback',
+    text,
+    bridge: bridgeAttempt,
+  };
+  if (booleanOption(options.hideKeyboard)) {
+    result.keyboard = await hideKeyboard(ctx, options);
+  }
+  return result;
+}
+
+function inputTextBridgePayload(text, options = {}) {
+  const payload = { text };
+  const x = Number(options.tapX);
+  const y = Number(options.tapY);
+  if (Number.isFinite(x) && Number.isFinite(y)) {
+    payload.x = x;
+    payload.y = y;
+  }
+  return payload;
+}
+
+function isAdbInputTextSafe(text) {
+  return /^[\x20-\x7e]*$/.test(String(text));
+}
+
+async function swipe(ctx, startX, startY, endX, endY, durationMs) {
+  await adb(ctx, ['shell', 'input', 'swipe', String(startX), String(startY), String(endX), String(endY), String(durationMs)]);
+  return { ok: true, transport: 'adb', startX, startY, endX, endY, durationMs };
 }
 
 async function keyevent(ctx, keyCode) {
@@ -3710,6 +3808,59 @@ async function appopsSet(ctx, op, mode) {
   };
 }
 
+async function clearAppData(ctx) {
+  if (!ctx.explicitPackageName) {
+    throw new Error('packageName is required for clear-app-data');
+  }
+  let bridgeError = null;
+  try {
+    const bridgeResult = await bridgePost(ctx, '/v1/app/clear-data', {});
+    return {
+      ...bridgeResult,
+      packageName: ctx.packageName,
+      method: 'bridge-runtime',
+    };
+  } catch (error) {
+    bridgeError = firstErrorLine(error);
+  }
+
+  let result;
+  try {
+    result = await adb(ctx, clearAppDataAdbArgs(ctx.packageName));
+  } catch (error) {
+    return {
+      ok: false,
+      packageName: ctx.packageName,
+      action: 'clear-app-data',
+      error: 'clear_app_data_failed',
+      bridgeError,
+      message: error.message || String(error),
+    };
+  }
+  const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+  if (!/^Success\b/im.test(output)) {
+    return {
+      ok: false,
+      packageName: ctx.packageName,
+      error: 'clear_app_data_failed',
+      bridgeError,
+      output,
+    };
+  }
+  return {
+    ok: true,
+    packageName: ctx.packageName,
+    action: 'clear-app-data',
+    method: 'pm-clear',
+    bridgeError,
+    output,
+  };
+}
+
+function clearAppDataAdbArgs(packageName) {
+  return ['shell', 'pm', 'clear', packageName];
+}
+
 async function resolveLogcatPid(ctx, options) {
   if (options.pid && options.pid !== true && options.pid !== 'current') {
     return String(options.pid);
@@ -3725,17 +3876,17 @@ async function resolveLogcatPid(ctx, options) {
   return '';
 }
 
-function filterLogcat(text, options) {
-  const tags = splitCsv(options.tag || options.tags);
-  const grep = options.grep ? String(options.grep) : '';
-  const grepCaseSensitive = Boolean(options.grepCaseSensitive);
-  const minLevel = priorityValue(options.level || options.minLevel || '');
-  const pid = options.pid ? String(options.pid) : '';
-  const requiresAppPid = options.appPid || options.packagePid || options.pid === 'current';
-  if (requiresAppPid && !pid) {
-    return '';
-  }
-  const lines = String(text || '').split(/\r?\n/);
+function filterLogcat(text, options) {
+  const tags = splitCsv(options.tag || options.tags);
+  const grep = options.grep ? String(options.grep) : '';
+  const grepCaseSensitive = Boolean(options.grepCaseSensitive);
+  const minLevel = priorityValue(options.level || options.minLevel || '');
+  const pid = options.pid ? String(options.pid) : '';
+  const requiresAppPid = options.appPid || options.packagePid || options.pid === 'current';
+  if (requiresAppPid && !pid) {
+    return '';
+  }
+  const lines = String(text || '').split(/\r?\n/);
   const filtered = [];
   let previousIncluded = false;
   for (const line of lines) {
@@ -3818,134 +3969,134 @@ function adbFollow(ctx, args, durationMs) {
   });
 }
 
-async function launchApp(ctx, options = {}) {
-  if (options.component || options.activity) {
-    return launchActivity(ctx, options);
-  }
-
-  const candidates = await launcherActivityCandidates(ctx);
-  if (candidates.length === 0) {
-    return {
-      ok: false,
-      error: 'launcher_not_found',
-      packageName: ctx.packageName,
-      launcherCandidates: candidates,
-    };
-  }
-  if (candidates.length > 1) {
-    return {
-      ok: false,
-      error: 'launcher_ambiguous',
-      packageName: ctx.packageName,
-      launcherCandidates: candidates,
-      suggestion: 'Pass --component or --activity to choose the intended launcher Activity.',
-    };
-  }
-
-  return startActivity(ctx, candidates[0], options, {
-    packageName: ctx.packageName,
-    launcherCandidates: candidates,
-  });
-}
-
-async function launchActivity(ctx, options = {}) {
-  const component = normalizeActivityComponent(
-    ctx.packageName,
-    options.component || requiredString(options.activity, 'activity'),
-  );
-  return startActivity(ctx, component, options, { packageName: ctx.packageName });
-}
-
-async function launchNativeTest(ctx) {
-  const component = normalizeActivityComponent(ctx.packageName, ctx.nativeActivity);
-  return startActivity(ctx, component, {}, { packageName: ctx.packageName });
-}
-
-async function launchFlutter(ctx, initialRoute) {
-  const component = normalizeActivityComponent(ctx.packageName, ctx.flutterActivity);
-  const options = initialRoute ? { extra: [`ai_app_initial_route=${initialRoute}`] } : {};
-  const result = await startActivity(ctx, component, options, { packageName: ctx.packageName });
-  return { ...result, initialRoute };
-}
-
-async function launcherActivityCandidates(ctx) {
-  const result = await adb(ctx, [
-    'shell',
-    'cmd',
-    'package',
-    'query-activities',
-    '--brief',
-    '-a',
-    'android.intent.action.MAIN',
-    '-c',
-    'android.intent.category.LAUNCHER',
-    ctx.packageName,
-  ]);
-  return parseLauncherActivityCandidates(result.stdout);
-}
-
-function parseLauncherActivityCandidates(stdout) {
-  const candidates = [];
-  for (const line of String(stdout || '').split(/\r?\n/)) {
-    const candidate = line.trim();
-    if (/^[A-Za-z0-9_.$]+\/[A-Za-z0-9_.$]+$/.test(candidate) && !candidates.includes(candidate)) {
-      candidates.push(candidate);
-    }
-  }
-  return candidates;
-}
-
-function normalizeActivityComponent(packageName, activityOrComponent) {
-  const value = requiredString(activityOrComponent, 'activity');
-  if (value.includes('/')) return value;
-  return `${packageName}/${value}`;
-}
-
-async function startActivity(ctx, component, options = {}, extraResult = {}) {
-  const args = buildAmStartArgs(component, options);
-  const result = await adb(ctx, args);
-  return {
-    ok: true,
-    transport: 'adb',
-    component,
-    ...extraResult,
-    stdout: result.stdout.trim(),
-    stderr: result.stderr.trim(),
-  };
-}
-
-function buildAmStartArgs(component, options = {}) {
-  const args = ['shell', 'am', 'start'];
-  if (options.action) args.push('-a', options.action);
-  for (const category of optionList(options.category)) {
-    args.push('-c', category);
-  }
-  if (options.data) args.push('-d', options.data);
-  for (const extra of parseStartExtras(options.extra)) {
-    args.push('-e', extra.key, extra.value);
-  }
-  args.push('-n', component);
-  return args;
-}
-
-function parseStartExtras(rawExtras) {
-  return optionList(rawExtras).map((rawExtra) => {
-    const value = String(rawExtra);
-    const separator = value.indexOf('=');
-    if (separator <= 0) {
-      throw new Error('extra must use key=value');
-    }
-    return {
-      key: value.slice(0, separator),
-      value: value.slice(separator + 1),
-    };
-  });
-}
-
-function optionList(value) {
-  if (value === undefined || value === null || value === false || value === '') return [];
-  return Array.isArray(value) ? value : [value];
-}
+async function launchApp(ctx, options = {}) {
+  if (options.component || options.activity) {
+    return launchActivity(ctx, options);
+  }
+
+  const candidates = await launcherActivityCandidates(ctx);
+  if (candidates.length === 0) {
+    return {
+      ok: false,
+      error: 'launcher_not_found',
+      packageName: ctx.packageName,
+      launcherCandidates: candidates,
+    };
+  }
+  if (candidates.length > 1) {
+    return {
+      ok: false,
+      error: 'launcher_ambiguous',
+      packageName: ctx.packageName,
+      launcherCandidates: candidates,
+      suggestion: 'Pass --component or --activity to choose the intended launcher Activity.',
+    };
+  }
+
+  return startActivity(ctx, candidates[0], options, {
+    packageName: ctx.packageName,
+    launcherCandidates: candidates,
+  });
+}
+
+async function launchActivity(ctx, options = {}) {
+  const component = normalizeActivityComponent(
+    ctx.packageName,
+    options.component || requiredString(options.activity, 'activity'),
+  );
+  return startActivity(ctx, component, options, { packageName: ctx.packageName });
+}
+
+async function launchNativeTest(ctx) {
+  const component = normalizeActivityComponent(ctx.packageName, ctx.nativeActivity);
+  return startActivity(ctx, component, {}, { packageName: ctx.packageName });
+}
+
+async function launchFlutter(ctx, initialRoute) {
+  const component = normalizeActivityComponent(ctx.packageName, ctx.flutterActivity);
+  const options = initialRoute ? { extra: [`ai_app_initial_route=${initialRoute}`] } : {};
+  const result = await startActivity(ctx, component, options, { packageName: ctx.packageName });
+  return { ...result, initialRoute };
+}
+
+async function launcherActivityCandidates(ctx) {
+  const result = await adb(ctx, [
+    'shell',
+    'cmd',
+    'package',
+    'query-activities',
+    '--brief',
+    '-a',
+    'android.intent.action.MAIN',
+    '-c',
+    'android.intent.category.LAUNCHER',
+    ctx.packageName,
+  ]);
+  return parseLauncherActivityCandidates(result.stdout);
+}
+
+function parseLauncherActivityCandidates(stdout) {
+  const candidates = [];
+  for (const line of String(stdout || '').split(/\r?\n/)) {
+    const candidate = line.trim();
+    if (/^[A-Za-z0-9_.$]+\/[A-Za-z0-9_.$]+$/.test(candidate) && !candidates.includes(candidate)) {
+      candidates.push(candidate);
+    }
+  }
+  return candidates;
+}
+
+function normalizeActivityComponent(packageName, activityOrComponent) {
+  const value = requiredString(activityOrComponent, 'activity');
+  if (value.includes('/')) return value;
+  return `${packageName}/${value}`;
+}
+
+async function startActivity(ctx, component, options = {}, extraResult = {}) {
+  const args = buildAmStartArgs(component, options);
+  const result = await adb(ctx, args);
+  return {
+    ok: true,
+    transport: 'adb',
+    component,
+    ...extraResult,
+    stdout: result.stdout.trim(),
+    stderr: result.stderr.trim(),
+  };
+}
+
+function buildAmStartArgs(component, options = {}) {
+  const args = ['shell', 'am', 'start'];
+  if (options.action) args.push('-a', options.action);
+  for (const category of optionList(options.category)) {
+    args.push('-c', category);
+  }
+  if (options.data) args.push('-d', options.data);
+  for (const extra of parseStartExtras(options.extra)) {
+    args.push('-e', extra.key, extra.value);
+  }
+  args.push('-n', component);
+  return args;
+}
+
+function parseStartExtras(rawExtras) {
+  return optionList(rawExtras).map((rawExtra) => {
+    const value = String(rawExtra);
+    const separator = value.indexOf('=');
+    if (separator <= 0) {
+      throw new Error('extra must use key=value');
+    }
+    return {
+      key: value.slice(0, separator),
+      value: value.slice(separator + 1),
+    };
+  });
+}
+
+function optionList(value) {
+  if (value === undefined || value === null || value === false || value === '') return [];
+  return Array.isArray(value) ? value : [value];
+}
 
 async function smoke(ctx, options) {
   const summary = {
@@ -4304,6 +4455,7 @@ function requiredNumber(value, name) {
 
 module.exports = {
   buildBridgeFailureResult,
+  clearAppDataAdbArgs,
   defaultInstallerButtonTexts,
   artifactTimestamp,
   compactBridgeTree,
@@ -4311,41 +4463,42 @@ module.exports = {
   compactUiaTree,
   defaultArtifactDirectory,
   defaultArtifactPath,
-  findFlutterNode,
-  findTappableNodeByText,
-  filterLogcat,
-  firstErrorLine,
+  findFlutterNode,
+  findTappableNodeByText,
+  filterLogcat,
+  firstErrorLine,
   flutterNodePoint,
   flutterPhysicalViewport,
   helpText,
-  installerButtonTextsForSurface,
-  isAdbInputTextSafe,
-  isLikelyInstallerSurface,
+  installerButtonTextsForSurface,
+  isAdbInputTextSafe,
+  isLikelyInstallerSurface,
   nodeTapState,
-  normalizeBridgeError,
-  normalizeActivityComponent,
-  parseWebViewDevToolsSockets,
-  parseArgs,
-  parseKeyboardState,
-  parseLauncherActivityCandidates,
-  parseStartExtras,
-  parseUiaBounds,
+  normalizeBridgeError,
+  normalizeActivityComponent,
+  parseWebViewDevToolsSockets,
+  parseArgs,
+  parseKeyboardState,
+  parsePackagePidsFromPs,
+  parseLauncherActivityCandidates,
+  parseStartExtras,
+  parseUiaBounds,
   parseUiaViewport,
   parseComponentFromWindowLine,
   parseForegroundWindow,
   chooseWebViewDevToolsSocket,
   chooseWebViewPage,
-  shapeNetworkCapture,
-  compactNetworkRecord,
-  pruneGeneratedArtifacts,
-  shouldSkipInstallerTapForInstalledPackage,
-  shouldDismissKeyboardForPoint,
-  shouldUseDefaultPortFallback,
-  screenshotOutputPath,
-  statusSearchText,
-  uiautomatorLockPath,
-  verifyBridgeTargetPackage,
-  waitTextConditionsMet,
-  withFileLock,
-};
+  shapeNetworkCapture,
+  compactNetworkRecord,
+  pruneGeneratedArtifacts,
+  shouldSkipInstallerTapForInstalledPackage,
+  shouldDismissKeyboardForPoint,
+  shouldUseDefaultPortFallback,
+  screenshotOutputPath,
+  statusSearchText,
+  uiautomatorLockPath,
+  verifyBridgeTargetPackage,
+  waitTextConditionsMet,
+  withFileLock,
+};