@mobileaidev/ai-app-bridge 0.2.3 → 0.2.5

package/README.md

@@ -27,6 +27,27 @@ 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.
 
+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

@@ -976,6 +976,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 +1008,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) => {
@@ -4311,16 +4335,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

@@ -17,13 +17,15 @@ const serverInstructions = [
 ].join(' ');
 
 let buffer = Buffer.alloc(0);
-
-process.stdin.on('data', (chunk) => {
-  buffer = Buffer.concat([buffer, chunk]);
-  drainMessages();
-});
-
-process.stdin.on('error', () => {});
+
+function startServer() {
+  process.stdin.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    drainMessages();
+  });
+
+  process.stdin.on('error', () => {});
+}
 
 function drainMessages() {
   while (true) {
@@ -444,6 +446,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'] },
 ];
 
@@ -550,6 +553,9 @@ async function runGeneric(args = {}) {
       commandArgs[key] = args[key];
     }
   }
+  if (command === 'batch') {
+    return runBatch(commandArgs);
+  }
   return runBridgeChecked(command, commandArgs);
 }
 
@@ -564,10 +570,234 @@ function runBridgeChecked(command, args = {}) {
   }
   return runBridge(command, args);
 }
-
-async function runBridge(command, args) {
-  const cliArgs = [cliScript, command];
-  addCommonArgs(cliArgs, 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);
   addArg(cliArgs, 'initial-route', args.initialRoute);
   addArg(cliArgs, 'activity', args.activity);
   addArg(cliArgs, 'component', args.component);
@@ -601,33 +831,45 @@ async function runBridge(command, args) {
   addArg(cliArgs, 'page-url-filter', args.pageUrlFilter);
   addArg(cliArgs, 'url-filter', args.urlFilter);
   addArg(cliArgs, 'method', args.method);
-  addArg(cliArgs, 'status-code', args.statusCode);
-  addArg(cliArgs, 'compact', args.compact);
-  addArg(cliArgs, 'full', args.full);
-  addArg(cliArgs, 'no-bodies', args.noBodies);
-  addArg(cliArgs, 'duration-ms', args.durationMs);
-  addArg(cliArgs, 'include-response-body', args.includeResponseBody);
-  addArg(cliArgs, 'body-max-bytes', args.bodyMaxBytes);
-  addArg(cliArgs, 'max-events', args.maxEvents);
-  addArg(cliArgs, 'keep-forward', args.keepForward);
-  addArg(cliArgs, 'key-code', args.keyCode);
-  addArg(cliArgs, 'permission', args.permission);
-  addArg(cliArgs, 'op', args.op);
-  addArg(cliArgs, 'mode', args.mode);
-  addArg(cliArgs, 'script', args.script);
-  addArg(cliArgs, 'selector', args.selector);
+  addArg(cliArgs, 'status-code', args.statusCode);
+  addArg(cliArgs, 'compact', args.compact);
+  addArg(cliArgs, 'full', args.full);
+  addArg(cliArgs, 'text-filter', args.textFilter);
+  addArg(cliArgs, 'resource-id-filter', args.resourceIdFilter);
+  addArg(cliArgs, 'class-filter', args.classFilter);
+  addArg(cliArgs, 'visible-only', args.visibleOnly);
+  addArg(cliArgs, 'max-nodes', args.maxNodes);
+  addArg(cliArgs, 'max-depth', args.maxDepth);
+  addArg(cliArgs, 'no-bodies', args.noBodies);
+  addArg(cliArgs, 'duration-ms', args.durationMs);
+  addArg(cliArgs, 'include-response-body', args.includeResponseBody);
+  addArg(cliArgs, 'body-max-bytes', args.bodyMaxBytes);
+  addArg(cliArgs, 'max-events', args.maxEvents);
+  addArg(cliArgs, 'keep-forward', args.keepForward);
+  addArg(cliArgs, 'key-code', args.keyCode);
+  addArg(cliArgs, 'payload', args.payload);
+  addArg(cliArgs, 'delta', args.delta);
+  addArg(cliArgs, 'max-swipes', args.maxSwipes);
+  addArg(cliArgs, 'permission', args.permission);
+  addArg(cliArgs, 'op', args.op);
+  addArg(cliArgs, 'mode', args.mode);
+  addArg(cliArgs, 'script', args.script);
+  addArg(cliArgs, 'selector', args.selector);
   addArg(cliArgs, 'target-text', args.targetText);
   addArg(cliArgs, 'value', args.value);
   addArg(cliArgs, 'exact', args.exact);
   addArg(cliArgs, 'button-text', args.buttonText);
   addArg(cliArgs, 'resource-id', args.resourceId);
-  addArg(cliArgs, 'attempts', args.attempts);
-  addArg(cliArgs, 'interval-ms', args.intervalMs);
-  addArg(cliArgs, 'delta-x', args.deltaX);
-  addArg(cliArgs, 'delta-y', args.deltaY);
-  addArg(cliArgs, 'since-id', args.sinceId);
-  addArg(cliArgs, 'since-ms', args.sinceMs);
-  addArg(cliArgs, 'limit', args.limit);
+  addArg(cliArgs, 'attempts', args.attempts);
+  addArg(cliArgs, 'interval-ms', args.intervalMs);
+  addArg(cliArgs, 'delta-x', args.deltaX);
+  addArg(cliArgs, 'delta-y', args.deltaY);
+  addArg(cliArgs, 'require-text', args.requireText);
+  addArg(cliArgs, 'absent-text', args.absentText);
+  addArg(cliArgs, 'require-activity', args.requireActivity);
+  addArg(cliArgs, 'since-id', args.sinceId);
+  addArg(cliArgs, 'since-ms', args.sinceMs);
+  addArg(cliArgs, 'limit', args.limit);
   addArg(cliArgs, 'pid', args.pid);
   addArg(cliArgs, 'app-pid', args.appPid);
   addArg(cliArgs, 'tag', args.tag);
@@ -635,19 +877,21 @@ async function runBridge(command, args) {
   addArg(cliArgs, 'grep', args.grep);
   addArg(cliArgs, 'lines', args.lines);
   addArg(cliArgs, 'since', args.since);
-  addArg(cliArgs, 'follow', args.follow);
-  addArg(cliArgs, 'duration-sec', args.durationSec);
-  addArg(cliArgs, 'clear', args.clear);
-  return runProcess(cliArgs);
-}
+  addArg(cliArgs, 'follow', args.follow);
+  addArg(cliArgs, 'duration-sec', args.durationSec);
+  addArg(cliArgs, 'clear', args.clear);
+  addArg(cliArgs, 'skip-flutter-launch', args.skipFlutterLaunch);
+  return cliArgs;
+}
 
 async function runSmoke(args) {
   const cliArgs = [cliScript, 'smoke'];
-  addCommonArgs(cliArgs, args);
-  addArg(cliArgs, 'out-file', args.outFile);
-  addArg(cliArgs, 'artifact-dir', args.artifactDir || defaultArtifactDirFor('smoke', args));
-  return runProcess(cliArgs);
-}
+  addCommonArgs(cliArgs, args);
+  addArg(cliArgs, 'out-file', args.outFile);
+  addArg(cliArgs, 'artifact-dir', args.artifactDir || defaultArtifactDirFor('smoke', args));
+  addArg(cliArgs, 'skip-flutter-launch', args.skipFlutterLaunch);
+  return runProcess(cliArgs);
+}
 
 function defaultArtifactDirFor(command, args) {
   if (args.outFile) return '';
@@ -776,7 +1020,16 @@ function send(message) {
   process.stdout.write(body);
 }
 
-function writeLog(text) {
-  process.stderr.write(`${text}\n`);
-}
-
+function writeLog(text) {
+  process.stderr.write(`${text}\n`);
+}
+
+if (require.main === module) {
+  startServer();
+}
+
+module.exports = {
+  buildBridgeCliArgs,
+  runBatch,
+  startServer,
+};

package/package.json

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