@mobileaidev/ai-app-bridge 0.2.4 → 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,38 @@ 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:
+
+```json
+{
+  "command": "batch",
+  "arguments": {
+    "defaults": {
+      "packageName": "io.github.mobileaidev.aiappbridge.sample"
+    },
+    "steps": [
+      { "id": "launch", "command": "launch-app" },
+      { "id": "wait-home", "command": "wait-text", "arguments": { "targetText": "Home" } },
+      { "id": "capture-logs", "command": "logs", "arguments": { "limit": 20 } }
+    ],
+    "stopOnError": true
+  }
+}
+```
+
 WebView network and console capture use Android WebView DevTools/CDP when the
 target app is debuggable and WebView debugging is enabled.
 

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':
@@ -976,6 +979,13 @@ function normalizeBridgeError(error) {
       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',
@@ -1001,21 +1011,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));
-  return JSON.parse(body);
-}
-
-async function bridgePost(ctx, requestPath, payload) {
-  await ensureForward(ctx);
-  const body = await httpPost(bridgeUrl(ctx, requestPath), payload);
-  return JSON.parse(body);
-}
-
-function bridgeUrl(ctx, requestPath) {
-  return `http://127.0.0.1:${ctx.hostPort || ctx.port}${requestPath}`;
-}
+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) => {
@@ -3676,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);
   }
@@ -4279,8 +4359,9 @@ function requiredNumber(value, name) {
 }
 
 module.exports = {
-  buildBridgeFailureResult,
-  defaultInstallerButtonTexts,
+  buildBridgeFailureResult,
+  clearAppDataAdbArgs,
+  defaultInstallerButtonTexts,
   artifactTimestamp,
   compactBridgeTree,
   compactStatus,
@@ -4311,16 +4392,17 @@ module.exports = {
   parseForegroundWindow,
   chooseWebViewDevToolsSocket,
   chooseWebViewPage,
-  shapeNetworkCapture,
-  compactNetworkRecord,
-  pruneGeneratedArtifacts,
-  shouldSkipInstallerTapForInstalledPackage,
+  shapeNetworkCapture,
+  compactNetworkRecord,
+  pruneGeneratedArtifacts,
+  shouldSkipInstallerTapForInstalledPackage,
   shouldDismissKeyboardForPoint,
   shouldUseDefaultPortFallback,
   screenshotOutputPath,
-  statusSearchText,
-  uiautomatorLockPath,
-  waitTextConditionsMet,
-  withFileLock,
-};
+  statusSearchText,
+  uiautomatorLockPath,
+  verifyBridgeTargetPackage,
+  waitTextConditionsMet,
+  withFileLock,
+};
 

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'] },
@@ -446,6 +492,7 @@ const commandDefinitions = [
   { command: 'webview-console', domain: 'webview', summary: 'Capture WebView console/log events through CDP.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'durationMs', 'script', 'maxEvents'] },
   { command: 'forward', domain: 'advanced', summary: 'Create the ADB port forward for the bridge.', targetApp: true, options: ['serial', 'packageName', 'port'] },
   { command: 'remove-forward', domain: 'advanced', summary: 'Remove the ADB port forward for the bridge.', options: ['serial', 'port'] },
+  { command: 'batch', domain: 'advanced', summary: 'Run multiple AI App Bridge commands serially in one MCP call.', options: ['defaults', 'steps', 'stopOnError', 'includeRaw', 'maxRawChars'] },
   { command: 'smoke', domain: 'diagnostics', summary: 'Run the native sample smoke test.', options: ['serial', 'packageName', 'outFile', 'artifactDir', 'skipFlutterLaunch'] },
 ];
 
@@ -480,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',
@@ -525,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,
   };
 }
@@ -552,6 +600,9 @@ async function runGeneric(args = {}) {
       commandArgs[key] = args[key];
     }
   }
+  if (command === 'batch') {
+    return runBatch(commandArgs);
+  }
   return runBridgeChecked(command, commandArgs);
 }
 
@@ -560,17 +611,240 @@ 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);
   }
   return runBridge(command, args);
 }
-
+
+async function runBatch(args = {}, runner = runBridgeChecked) {
+  const startedAtMs = Date.now();
+  const mode = args.mode ? String(args.mode) : 'serial';
+  if (mode !== 'serial') {
+    return toolJson({ ok: false, error: 'batch_mode_not_supported', mode }, true);
+  }
+  const steps = Array.isArray(args.steps) ? args.steps : [];
+  if (steps.length === 0) {
+    return toolJson({ ok: false, error: 'batch_steps_required' }, true);
+  }
+  const maxSteps = args.maxSteps === undefined ? 30 : Number(args.maxSteps);
+  if (!Number.isInteger(maxSteps) || maxSteps < 1) {
+    return toolJson({ ok: false, error: 'invalid_max_steps', maxSteps: args.maxSteps }, true);
+  }
+  if (steps.length > maxSteps) {
+    return toolJson({ ok: false, error: 'batch_too_many_steps', stepCount: steps.length, maxSteps }, true);
+  }
+
+  const defaults = args.defaults && typeof args.defaults === 'object' ? { ...args.defaults } : {};
+  for (const key of ['adb', 'serial', 'port', 'packageName', 'artifactDir']) {
+    if (args[key] !== undefined && defaults[key] === undefined) {
+      defaults[key] = args[key];
+    }
+  }
+
+  const normalizedSteps = [];
+  const seenIds = new Set();
+  for (let index = 0; index < steps.length; index += 1) {
+    const rawStep = steps[index] && typeof steps[index] === 'object' ? steps[index] : {};
+    const stepId = String(rawStep.id || `step_${index + 1}`);
+    if (seenIds.has(stepId)) {
+      return toolJson({ ok: false, error: 'duplicate_batch_step_id', stepId }, true);
+    }
+    seenIds.add(stepId);
+    const command = normalizeCommandName(rawStep.command);
+    if (!commandByName.has(command)) {
+      return toolJson({ ok: false, error: 'unknown_batch_step_command', stepId, command: rawStep.command || '' }, true);
+    }
+    if (command === 'batch') {
+      return toolJson({ ok: false, error: 'nested_batch_not_supported', stepId }, true);
+    }
+    normalizedSteps.push({ ...rawStep, id: stepId, command });
+  }
+
+  const stopOnError = args.stopOnError !== false;
+  const includeRaw = Boolean(args.includeRaw);
+  const maxRawChars = args.maxRawChars === undefined ? 4000 : Number(args.maxRawChars);
+  if (!Number.isInteger(maxRawChars) || maxRawChars < 0) {
+    return toolJson({ ok: false, error: 'invalid_max_raw_chars', maxRawChars: args.maxRawChars }, true);
+  }
+  const results = [];
+  let stopped = false;
+
+  for (const step of normalizedSteps) {
+    if (stopped) {
+      results.push({
+        id: step.id,
+        command: step.command,
+        status: 'skipped',
+        ok: false,
+        skipped: true,
+        reason: 'stopOnError',
+      });
+      continue;
+    }
+
+    const stepStartedAtMs = Date.now();
+    const stepArgs = {
+      ...defaults,
+      ...(step.arguments && typeof step.arguments === 'object' ? step.arguments : {}),
+    };
+    for (const key of ['adb', 'serial', 'port', 'packageName']) {
+      if (step[key] !== undefined) {
+        stepArgs[key] = step[key];
+      }
+    }
+    try {
+      const toolResult = await runner(step.command, stepArgs);
+      const parsed = parseToolResult(toolResult);
+      const passed = !parsed.isError && parsed.payload?.ok !== false;
+      const stepResult = {
+        id: step.id,
+        command: step.command,
+        status: passed ? 'passed' : 'failed',
+        ok: passed,
+        packageName: stepArgs.packageName,
+        port: stepArgs.port,
+        durationMs: Date.now() - stepStartedAtMs,
+        summary: summarizeToolPayload(parsed),
+      };
+      if (!passed) {
+        stepResult.error = parsed.payload?.error || firstTextLine(parsed.text) || 'command_failed';
+      }
+      if (includeRaw) {
+        stepResult.result = parsed.payload || undefined;
+        stepResult.rawText = parsed.payload ? undefined : truncateText(parsed.text, maxRawChars);
+      }
+      results.push(stepResult);
+      if (!passed && stopOnError) {
+        stopped = true;
+      }
+    } catch (error) {
+      const stepResult = {
+        id: step.id,
+        command: step.command,
+        status: 'failed',
+        ok: false,
+        packageName: stepArgs.packageName,
+        port: stepArgs.port,
+        durationMs: Date.now() - stepStartedAtMs,
+        error: error.message || String(error),
+      };
+      results.push(stepResult);
+      if (stopOnError) {
+        stopped = true;
+      }
+    }
+  }
+
+  const failed = results.filter((item) => item.status === 'failed').length;
+  const skipped = results.filter((item) => item.status === 'skipped').length;
+  const passed = results.filter((item) => item.status === 'passed').length;
+  return toolJson({
+    ok: failed === 0,
+    batchId: args.batchId || generatedBatchId(),
+    mode,
+    stopOnError,
+    stepCount: normalizedSteps.length,
+    passed,
+    failed,
+    skipped,
+    durationMs: Date.now() - startedAtMs,
+    steps: results,
+  }, failed > 0);
+}
+
 async function runBridge(command, args) {
   return runProcess(buildBridgeCliArgs(command, args));
 }
 
+function parseToolResult(toolResult) {
+  const text = String(toolResult?.content?.[0]?.text || '');
+  try {
+    return {
+      isError: Boolean(toolResult?.isError),
+      text,
+      payload: JSON.parse(text),
+    };
+  } catch (_) {
+    return {
+      isError: Boolean(toolResult?.isError),
+      text,
+      payload: null,
+    };
+  }
+}
+
+function summarizeToolPayload(parsed) {
+  const payload = parsed.payload;
+  if (!payload || typeof payload !== 'object') {
+    return { text: truncateText(parsed.text, 500) };
+  }
+  const summary = {
+    ok: payload.ok,
+    error: payload.error || null,
+  };
+  if (payload.packageName) summary.packageName = payload.packageName;
+  if (payload.app?.packageName) summary.app = payload.app.packageName;
+  if (payload.activity) summary.activity = payload.activity;
+  if (payload.component) summary.component = payload.component;
+  if (payload.transport) summary.transport = payload.transport;
+  if (payload.source) summary.source = payload.source;
+  if (payload.path) summary.path = payload.path;
+  if (payload.debugBridge) {
+    summary.bridge = {
+      version: payload.debugBridge.version,
+      port: payload.debugBridge.port,
+    };
+  }
+  if (payload.count !== undefined) summary.count = payload.count;
+  if (payload.nodeCount !== undefined) summary.nodeCount = payload.nodeCount;
+  if (Array.isArray(payload.items)) summary.items = payload.items.length;
+  if (payload.values && typeof payload.values === 'object') {
+    summary.values = Object.keys(payload.values).length;
+  }
+  if (payload.counts) summary.counts = payload.counts;
+  if (Array.isArray(payload.requests)) summary.requests = payload.requests.length;
+  if (Array.isArray(payload.console)) summary.console = payload.console.length;
+  if (payload.flutter?.layout?.operable) {
+    summary.flutterOperable = {
+      ok: payload.flutter.layout.operable.ok,
+      count: payload.flutter.layout.operable.count,
+    };
+  }
+  if (payload.result && typeof payload.result === 'object') {
+    summary.result = {
+      ok: payload.result.ok,
+      error: payload.result.error || null,
+      value: truncateText(payload.result.value, 200),
+      bodyText: truncateText(payload.result.bodyText, 200),
+    };
+  }
+  return summary;
+}
+
+function truncateText(value, maxChars) {
+  if (value === undefined || value === null) return value;
+  const text = String(value);
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}...`;
+}
+
+function firstTextLine(value) {
+  const lines = String(value || '').split(/\r?\n/).filter((line) => line.trim());
+  return lines.find((line) => {
+    const text = line.trim().toLowerCase();
+    return text !== 'stderr:' && text !== 'stdout:';
+  }) || lines[0] || '';
+}
+
+function generatedBatchId() {
+  return `batch-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
 function buildBridgeCliArgs(command, args = {}) {
   const cliArgs = [cliScript, command];
   addCommonArgs(cliArgs, args);
@@ -790,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`);
@@ -806,5 +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.4",
+  "version": "0.2.6",
   "description": "Desktop CLI and MCP server for AI App Bridge.",
   "repository": {
     "type": "git",