@mobileaidev/ai-app-bridge 0.2.5 → 0.2.6

package/README.md

@@ -3,9 +3,10 @@
 ```bash
 npm install -g @mobileaidev/ai-app-bridge
 
-ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
+ai-app-bridge status --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge tree --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge install-apk --package-name io.github.mobileaidev.aiappbridge.sample --apk-path app-debug.apk
+ai-app-bridge clear-app-data --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge launch-app --package-name io.github.mobileaidev.aiappbridge.sample
 ai-app-bridge launch-activity --package-name io.github.mobileaidev.aiappbridge.sample --activity .MainActivity --extra route=/home
 ai-app-bridge screenshot --package-name io.github.mobileaidev.aiappbridge.sample
@@ -21,12 +22,17 @@ into the model context:
 - `capabilities` lists the bridge domains and command names.
 - `run` executes a selected command with command-specific arguments.
 
-This keeps install, launch, UI, Flutter, WebView, logcat, network, and
-permission capabilities discoverable without exposing dozens of full schemas at
-session start. Set `AI_APP_BRIDGE_MCP_SURFACE=full` before launching
+This keeps install, data reset, launch, UI, Flutter, WebView, logcat, network,
+and permission capabilities discoverable without exposing dozens of full schemas
+at session start. Set `AI_APP_BRIDGE_MCP_SURFACE=full` before launching
 `ai-app-bridge-mcp` only when a client needs the legacy one-tool-per-command
 surface.
 
+The MCP server accepts both standard `Content-Length` framed JSON-RPC messages
+and single-line JSON messages. Responses use the format of the first request on
+that connection, so standard MCP clients keep framed responses while local
+Node REPL scripts can send and read one JSON object per line.
+
 For multi-step app automation, call `run` with `command: "batch"`. Batch steps
 run serially in one MCP call, so a failed step can stop and mark the remaining
 steps as skipped without mixing results from different commands:

package/bin/ai-app-bridge.js

@@ -70,6 +70,7 @@ Device/action commands:
 
 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.
@@ -296,10 +297,12 @@ async function runCommand(command, options, ctx) {
       return keyboardState(ctx);
     case 'hide-keyboard':
       return hideKeyboard(ctx, options);
-    case 'install-apk':
-      return installApk(ctx, options);
-    case 'webview-pages':
-      return webviewPages(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':
       return webviewCdpCapture(ctx, { ...options, captureNetwork: true, captureConsole: true });
     case 'webview-console':
@@ -3700,17 +3703,70 @@ async function safePermissionState(ctx, permission) {
   }
 }
 
-async function appopsSet(ctx, op, mode) {
-  await adb(ctx, ['shell', 'appops', 'set', ctx.packageName, op, mode]);
-  return {
+async function appopsSet(ctx, op, mode) {
+  await adb(ctx, ['shell', 'appops', 'set', ctx.packageName, op, mode]);
+  return {
     ok: true,
     packageName: ctx.packageName,
     op,
     mode,
-  };
-}
-
-async function resolveLogcatPid(ctx, options) {
+  };
+}
+
+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);
   }
@@ -4303,8 +4359,9 @@ function requiredNumber(value, name) {
 }
 
 module.exports = {
-  buildBridgeFailureResult,
-  defaultInstallerButtonTexts,
+  buildBridgeFailureResult,
+  clearAppDataAdbArgs,
+  defaultInstallerButtonTexts,
   artifactTimestamp,
   compactBridgeTree,
   compactStatus,

package/bin/mcp-server.js

@@ -11,12 +11,13 @@ const supportedProtocolVersions = ['2025-06-18', '2024-11-05'];
 const defaultProtocolVersion = supportedProtocolVersions[0];
 const mcpSurface = (process.env.AI_APP_BRIDGE_MCP_SURFACE || 'compact').toLowerCase();
 const serverInstructions = [
-  'AI App Bridge observes and controls Android apps for agent workflows. Prefer these tools over raw adb when inspecting UI, text, WebView, logs, network, app install, launch, and permissions.',
+  'AI App Bridge observes and controls Android apps for agent workflows. Prefer these tools over raw adb when inspecting UI, text, WebView, logs, network, app install, data reset, launch, and permissions.',
   'Default surface is compact: call capabilities to discover domains, then call run with a command and arguments.',
   'Always pass packageName for app-specific commands, or pass an explicit port. Do not rely on a sample/default package in MCP sessions.',
 ].join(' ');
 
 let buffer = Buffer.alloc(0);
+let responseFormat = null;
 
 function startServer() {
   process.stdin.on('data', (chunk) => {
@@ -27,34 +28,77 @@ function startServer() {
   process.stdin.on('error', () => {});
 }
 
-function drainMessages() {
-  while (true) {
-    const delimiter = findHeaderDelimiter(buffer);
-    const headerEnd = delimiter.index;
-    if (headerEnd < 0) {
-      return;
-    }
-    const header = buffer.subarray(0, headerEnd).toString('utf8');
-    const match = /^Content-Length:\s*(\d+)$/im.exec(header);
-    if (!match) {
-      buffer = buffer.subarray(headerEnd + delimiter.length);
-      continue;
-    }
-    const contentLength = Number(match[1]);
-    const messageStart = headerEnd + delimiter.length;
-    const messageEnd = messageStart + contentLength;
-    if (buffer.length < messageEnd) {
-      return;
-    }
-    const body = buffer.subarray(messageStart, messageEnd).toString('utf8');
-    buffer = buffer.subarray(messageEnd);
-    handleMessage(body).catch((error) => {
-      writeLog(`unhandled message error: ${error.stack || error}`);
-    });
-  }
-}
-
-function findHeaderDelimiter(source) {
+function drainMessages() {
+  while (true) {
+    const parsed = readNextMessage(buffer);
+    if (!parsed) {
+      return;
+    }
+    buffer = parsed.remaining;
+    setResponseFormat(parsed.format);
+    handleMessage(parsed.body).catch((error) => {
+      writeLog(`unhandled message error: ${error.stack || error}`);
+    });
+  }
+}
+
+function readNextMessage(source) {
+  const text = source.toString('utf8');
+  if (/^Content-Length:/i.test(text)) {
+    return readContentLengthMessage(source);
+  }
+  return readLineJsonMessage(source);
+}
+
+function readContentLengthMessage(source) {
+  const delimiter = findHeaderDelimiter(source);
+  const headerEnd = delimiter.index;
+  if (headerEnd < 0) {
+    return null;
+  }
+  const header = source.subarray(0, headerEnd).toString('utf8');
+  const match = /^Content-Length:\s*(\d+)$/im.exec(header);
+  if (!match) {
+    return {
+      body: source.subarray(headerEnd + delimiter.length).toString('utf8'),
+      format: 'frame',
+      remaining: Buffer.alloc(0),
+    };
+  }
+  const contentLength = Number(match[1]);
+  const messageStart = headerEnd + delimiter.length;
+  const messageEnd = messageStart + contentLength;
+  if (source.length < messageEnd) {
+    return null;
+  }
+  return {
+    body: source.subarray(messageStart, messageEnd).toString('utf8'),
+    format: 'frame',
+    remaining: source.subarray(messageEnd),
+  };
+}
+
+function readLineJsonMessage(source) {
+  const lfIndex = source.indexOf('\n');
+  if (lfIndex < 0) {
+    return null;
+  }
+  const lineEnd = lfIndex > 0 && source[lfIndex - 1] === 13 ? lfIndex - 1 : lfIndex;
+  const body = source.subarray(0, lineEnd).toString('utf8');
+  return {
+    body,
+    format: 'line',
+    remaining: source.subarray(lfIndex + 1),
+  };
+}
+
+function setResponseFormat(format) {
+  if (!responseFormat) {
+    responseFormat = format;
+  }
+}
+
+function findHeaderDelimiter(source) {
   const crlfIndex = source.indexOf('\r\n\r\n');
   const lfIndex = source.indexOf('\n\n');
   if (crlfIndex < 0) {
@@ -264,14 +308,15 @@ function fullToolDefinitions() {
     bridgeTool('events', 'Read generic in-app event records.'),
     bridgeTool('uia_tree', 'Read UIAutomator XML for the current device window.'),
     bridgeTool('screenshot', 'Capture an ADB screenshot.'),
-    bridgeTool('install_apk', 'Install an APK through ADB while assisting device-side package-installer confirmation screens with UIAutomator.', {
-      apkPath: { type: 'string', description: 'Absolute or workspace-relative APK path.' },
-      allowDowngrade: { type: 'boolean', description: 'Pass -d to adb install.' },
-      streaming: { type: 'boolean', description: 'Use streaming install instead of the default --no-streaming mode.' },
-      installTimeoutMs: { type: 'number', description: 'Maximum time for adb install. Defaults to 180000 ms.' },
-      installerTimeoutMs: { type: 'number', description: 'Maximum time to keep assisting installer screens after adb install exits. Defaults to 90000 ms.' },
-      intervalMs: { type: 'number', description: 'Installer polling interval. Defaults to 700 ms.' },
-    }, ['apkPath']),
+    bridgeTool('install_apk', 'Install an APK through ADB while assisting device-side package-installer confirmation screens with UIAutomator.', {
+      apkPath: { type: 'string', description: 'Absolute or workspace-relative APK path.' },
+      allowDowngrade: { type: 'boolean', description: 'Pass -d to adb install.' },
+      streaming: { type: 'boolean', description: 'Use streaming install instead of the default --no-streaming mode.' },
+      installTimeoutMs: { type: 'number', description: 'Maximum time for adb install. Defaults to 180000 ms.' },
+      installerTimeoutMs: { type: 'number', description: 'Maximum time to keep assisting installer screens after adb install exits. Defaults to 90000 ms.' },
+      intervalMs: { type: 'number', description: 'Installer polling interval. Defaults to 700 ms.' },
+    }, ['apkPath']),
+    bridgeTool('clear_app_data', 'Clear target app local data through the bridge runtime. Requires packageName so it cannot target the sample package by default.', {}, ['packageName']),
     bridgeTool('launch_app', 'Launch the target package LAUNCHER Activity. If multiple launcher Activities exist, returns launcher_ambiguous with candidates unless activity or component is explicit.', launchProperties()),
     bridgeTool('launch_activity', 'Launch an explicit Android Activity component, optionally with action/data/category/string extras.', launchProperties()),
     bridgeTool('launch_native_test', 'Launch the debug native Android bridge test Activity.'),
@@ -405,6 +450,7 @@ const commandDefinitions = [
   { command: 'events', domain: 'core', summary: 'Read in-app event records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'sinceId', 'sinceMs', 'limit'] },
   { command: 'logcat', domain: 'diagnostics', summary: 'Read Android logcat with optional app pid, tag, level, and grep filters.', options: ['serial', 'packageName', 'pid', 'appPid', 'tag', 'level', 'grep', 'lines', 'since', 'follow', 'durationSec', 'clear'] },
   { command: 'install-apk', domain: 'app', summary: 'Install an APK and assist device-side installer confirmation screens.', options: ['serial', 'packageName', 'apkPath', 'allowDowngrade', 'streaming', 'installTimeoutMs', 'installerTimeoutMs', 'intervalMs'] },
+  { command: 'clear-app-data', domain: 'app', summary: 'Clear target app local data through the bridge runtime.', targetApp: true, options: ['serial', 'packageName'] },
   { command: 'launch-app', domain: 'app', summary: 'Launch the target package LAUNCHER Activity and report launcher candidates.', targetApp: true, options: ['serial', 'packageName', 'activity', 'component', 'action', 'category', 'data', 'extra'] },
   { command: 'launch-activity', domain: 'app', summary: 'Launch an explicit Android Activity component with optional string extras.', targetApp: true, options: ['serial', 'packageName', 'activity', 'component', 'action', 'category', 'data', 'extra'] },
   { command: 'launch-native-test', domain: 'app', summary: 'Launch the debug native bridge test Activity.', targetApp: true, options: ['serial', 'packageName'] },
@@ -481,6 +527,7 @@ async function callTool(name, args) {
     input_flutter_text: 'input-flutter-text',
     uia_tree: 'uia-tree',
     install_apk: 'install-apk',
+    clear_app_data: 'clear-app-data',
     launch_app: 'launch-app',
     launch_activity: 'launch-activity',
     launch_native_test: 'launch-native-test',
@@ -526,7 +573,7 @@ function capabilityPayload(args = {}) {
   return {
     ok: true,
     surface: mcpSurface === 'full' || mcpSurface === 'legacy' ? 'full' : 'compact',
-    usage: 'Use run with one of these command names. Prefer packageName for app-specific commands; install-apk, launch-app, UI, WebView, logcat, network, and permission workflows are supported.',
+    usage: 'Use run with one of these command names. Prefer packageName for app-specific commands; install-apk, clear-app-data, launch-app, UI, WebView, logcat, network, and permission workflows are supported.',
     domains,
   };
 }
@@ -564,6 +611,9 @@ function normalizeCommandName(value) {
 }
 
 function runBridgeChecked(command, args = {}) {
+  if (command === 'clear-app-data' && !args.packageName) {
+    return toolText('clear-app-data: packageName is required in MCP mode so the command cannot clear a default package.', true);
+  }
   const definition = commandByName.get(command);
   if (definition?.targetApp && !args.packageName && !args.port) {
     return toolText(`${command}: packageName or explicit port is required in MCP mode so the command cannot fall back to a default package.`, true);
@@ -1014,11 +1064,15 @@ function sendError(id, code, message) {
   });
 }
 
-function send(message) {
-  const body = Buffer.from(JSON.stringify(message), 'utf8');
-  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
-  process.stdout.write(body);
-}
+function send(message) {
+  const body = Buffer.from(JSON.stringify(message), 'utf8');
+  if (responseFormat === 'line') {
+    process.stdout.write(`${body.toString('utf8')}\n`);
+    return;
+  }
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  process.stdout.write(body);
+}
 
 function writeLog(text) {
   process.stderr.write(`${text}\n`);
@@ -1030,6 +1084,7 @@ if (require.main === module) {
 
 module.exports = {
   buildBridgeCliArgs,
+  readNextMessage,
   runBatch,
   startServer,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobileaidev/ai-app-bridge",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Desktop CLI and MCP server for AI App Bridge.",
   "repository": {
     "type": "git",