@mobileaidev/ai-app-bridge 0.2.5 → 0.2.7

package/bin/mcp-server.js

@@ -4,56 +4,101 @@ const { spawn } = require('child_process');
 const path = require('path');
 
 const packageInfo = require('../package.json');
-const bridgeDir = __dirname;
-const cliScript = path.join(bridgeDir, 'ai-app-bridge.js');
-const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
-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.',
-  '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);
-
-function startServer() {
-  process.stdin.on('data', (chunk) => {
-    buffer = Buffer.concat([buffer, chunk]);
-    drainMessages();
-  });
-
-  process.stdin.on('error', () => {});
-}
+const bridgeDir = __dirname;
+const cliScript = path.join(bridgeDir, 'ai-app-bridge.js');
+const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
+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, 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.',
+  'When freezing is available, keep the target app frozen while the model thinks or plans. Thaw only immediately before reading app content or performing an app action, freeze again as soon as that evidence/action result is captured, and thaw once more before finishing the overall task so the app is not left frozen.',
+].join(' ');
+
+let buffer = Buffer.alloc(0);
+let responseFormat = null;
+
+function startServer() {
+  process.stdin.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    drainMessages();
+  });
+
+  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) {
+    const parsed = readNextMessage(buffer);
+    if (!parsed) {
       return;
     }
-    const body = buffer.subarray(messageStart, messageEnd).toString('utf8');
-    buffer = buffer.subarray(messageEnd);
-    handleMessage(body).catch((error) => {
+    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');
@@ -80,27 +125,27 @@ async function handleMessage(body) {
   }
 
   try {
-    if (message.method === 'initialize') {
-      sendResult(message.id, {
-        protocolVersion: negotiateProtocolVersion(message.params?.protocolVersion),
-        capabilities: {
-          tools: {},
-        },
-        serverInfo: {
-          name: 'ai-app-bridge',
-          title: 'AI App Bridge',
-          version: packageInfo.version,
-        },
-        instructions: serverInstructions,
-      });
-      return;
-    }
-
-    if (message.method === 'ping') {
-      sendResult(message.id, {});
-      return;
-    }
-
+    if (message.method === 'initialize') {
+      sendResult(message.id, {
+        protocolVersion: negotiateProtocolVersion(message.params?.protocolVersion),
+        capabilities: {
+          tools: {},
+        },
+        serverInfo: {
+          name: 'ai-app-bridge',
+          title: 'AI App Bridge',
+          version: packageInfo.version,
+        },
+        instructions: serverInstructions,
+      });
+      return;
+    }
+
+    if (message.method === 'ping') {
+      sendResult(message.id, {});
+      return;
+    }
+
     if (message.method === 'tools/list') {
       sendResult(message.id, { tools: toolDefinitions() });
       return;
@@ -118,62 +163,62 @@ async function handleMessage(body) {
   } catch (error) {
     sendError(message.id, -32000, error.message || String(error));
   }
-}
-
-function negotiateProtocolVersion(requestedVersion) {
-  if (supportedProtocolVersions.includes(requestedVersion)) {
-    return requestedVersion;
-  }
-  return defaultProtocolVersion;
-}
-
-function toolDefinitions() {
-  if (mcpSurface === 'full' || mcpSurface === 'legacy') {
-    return fullToolDefinitions();
-  }
-  return compactToolDefinitions();
-}
-
-function compactToolDefinitions() {
-  return [
-    bridgeTool('capabilities', 'List AI App Bridge capability domains and commands. Call this first when planning Android app automation; then use run to execute the selected command.', {
-      domain: { type: 'string', description: 'Optional domain filter such as core, app, action, flutter, webview, or diagnostics.' },
-      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, or webview-network.' },
-      includeOptions: { type: 'boolean', description: 'Include per-command argument names. Defaults to false to keep output compact.' },
-    }),
-    bridgeTool('run', 'Run an AI App Bridge command. Use capabilities first to choose the command. Always pass packageName for app-specific commands.', {
-      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, tree, webview-network, or logcat.' },
-      packageName: { type: 'string', description: 'Target Android package for app-specific commands. Strongly recommended.' },
-      serial: { type: 'string', description: 'ADB serial when multiple devices are connected.' },
-      port: { type: 'number', description: 'Explicit bridge port when packageName discovery is not available.' },
-      adb: { type: 'string', description: 'ADB executable path or command.' },
-      arguments: {
-        type: 'object',
-        description: 'Command-specific arguments from capabilities. Example: {"apkPath":"app-debug.apk","allowDowngrade":true}.',
-        additionalProperties: true,
-      },
-    }, ['command']),
-  ];
-}
-
-function fullToolDefinitions() {
-  return [
+}
+
+function negotiateProtocolVersion(requestedVersion) {
+  if (supportedProtocolVersions.includes(requestedVersion)) {
+    return requestedVersion;
+  }
+  return defaultProtocolVersion;
+}
+
+function toolDefinitions() {
+  if (mcpSurface === 'full' || mcpSurface === 'legacy') {
+    return fullToolDefinitions();
+  }
+  return compactToolDefinitions();
+}
+
+function compactToolDefinitions() {
+  return [
+    bridgeTool('capabilities', 'List AI App Bridge capability domains and commands. Call this first when planning Android app automation; then use run to execute the selected command.', {
+      domain: { type: 'string', description: 'Optional domain filter such as core, app, action, flutter, webview, or diagnostics.' },
+      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, or webview-network.' },
+      includeOptions: { type: 'boolean', description: 'Include per-command argument names. Defaults to false to keep output compact.' },
+    }),
+    bridgeTool('run', 'Run an AI App Bridge command. Use capabilities first to choose the command. Always pass packageName for app-specific commands.', {
+      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, freeze-app, thaw-app, input-text, tree, webview-network, or logcat.' },
+      packageName: { type: 'string', description: 'Target Android package for app-specific commands. Strongly recommended.' },
+      serial: { type: 'string', description: 'ADB serial when multiple devices are connected.' },
+      port: { type: 'number', description: 'Explicit bridge port when packageName discovery is not available.' },
+      adb: { type: 'string', description: 'ADB executable path or command.' },
+      arguments: {
+        type: 'object',
+        description: 'Command-specific arguments from capabilities. Example: {"apkPath":"app-debug.apk","allowDowngrade":true}.',
+        additionalProperties: true,
+      },
+    }, ['command']),
+  ];
+}
+
+function fullToolDefinitions() {
+  return [
     bridgeTool('status', 'Read compact bridge status, app info, capture counts, and Flutter layout summary. If default port 18080 times out, agents should retry with the target Android packageName so the CLI can discover the app bridge port.', {
       full: { type: 'boolean', description: 'Return the full raw status payload, including large Flutter widget dumps.' },
     }),
-    bridgeTool('tree', 'Read the Android View tree from the in-app bridge.'),
-    bridgeTool('flutter_tree', 'Read the latest Flutter widget/layout snapshot.'),
-    bridgeTool('flutter_nodes', 'Read Flutter operable nodes from the Flutter action bridge.'),
-    bridgeTool('tap_flutter_text', 'Tap a Flutter node by visible text through the Flutter-aware bridge path.', {
-      targetText: { type: 'string', description: 'Flutter node text to tap.' },
-    }, ['targetText']),
-    bridgeTool('input_flutter_text', 'Set Flutter TextField text through the Flutter action bridge. Use this for Flutter Chinese/Unicode input; do not use raw adb shell input text.', {
-      text: { type: 'string', description: 'Text to set.' },
-      tapX: { type: 'number', description: 'Optional physical X coordinate for the Flutter input target.' },
-      tapY: { type: 'number', description: 'Optional physical Y coordinate for the Flutter input target.' },
-      hideKeyboard: { type: 'boolean', description: 'Hide the soft keyboard after setting text.' },
-    }, ['text']),
-    bridgeTool('h5_dom', 'Read native Android WebView DOM from the current Activity.'),
+    bridgeTool('tree', 'Read the Android View tree from the in-app bridge.'),
+    bridgeTool('flutter_tree', 'Read the latest Flutter widget/layout snapshot.'),
+    bridgeTool('flutter_nodes', 'Read Flutter operable nodes from the Flutter action bridge.'),
+    bridgeTool('tap_flutter_text', 'Tap a Flutter node by visible text through the Flutter-aware bridge path.', {
+      targetText: { type: 'string', description: 'Flutter node text to tap.' },
+    }, ['targetText']),
+    bridgeTool('input_flutter_text', 'Set Flutter TextField text through the Flutter action bridge. Use this for Flutter Chinese/Unicode input; do not use raw adb shell input text.', {
+      text: { type: 'string', description: 'Text to set.' },
+      tapX: { type: 'number', description: 'Optional physical X coordinate for the Flutter input target.' },
+      tapY: { type: 'number', description: 'Optional physical Y coordinate for the Flutter input target.' },
+      hideKeyboard: { type: 'boolean', description: 'Hide the soft keyboard after setting text.' },
+    }, ['text']),
+    bridgeTool('h5_dom', 'Read native Android WebView DOM from the current Activity.'),
     bridgeTool('h5_eval', 'Execute debug JavaScript in the current native Android WebView.', {
       script: { type: 'string' },
     }, ['script']),
@@ -212,6 +257,12 @@ function fullToolDefinitions() {
       deltaY: { type: 'number', description: 'Window scroll delta Y when no selector/text is supplied.' },
     }),
     bridgeTool('logs', 'Read generic in-app log records.'),
+    bridgeTool('freeze_app', 'Stop the target app processes with SIGSTOP after app content is captured, preventing playback or animation from changing the observed evidence.', {
+      pid: { type: 'string', description: 'Optional explicit process id. Defaults to all processes named packageName or packageName:*.' },
+    }, ['packageName']),
+    bridgeTool('thaw_app', 'Resume the target app processes with SIGCONT before reading app content or dispatching actions, so bridge endpoints can answer.', {
+      pid: { type: 'string', description: 'Optional explicit process id. Defaults to all processes named packageName or packageName:*.' },
+    }, ['packageName']),
     bridgeTool('logcat', 'Read Android logcat through ADB with optional pid/tag/level/grep filters.', {
       pid: { type: 'string', description: 'Use "current" for the current app pid, or pass a numeric pid.' },
       appPid: { type: 'boolean', description: 'Filter by the current package pid.' },
@@ -272,10 +323,11 @@ function fullToolDefinitions() {
       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('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.'),
-    bridgeTool('launch_flutter', 'Launch the Flutter Activity, optionally with an initial route.'),
+    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.'),
+    bridgeTool('launch_flutter', 'Launch the Flutter Activity, optionally with an initial route.'),
     bridgeTool('tap', 'Tap device coordinates through ADB.', {
       tapX: { type: 'number' },
       tapY: { type: 'number' },
@@ -288,12 +340,12 @@ function fullToolDefinitions() {
       targetText: { type: 'string' },
       timeoutSec: { type: 'number' },
     }, ['targetText']),
-    bridgeTool('input_text', 'Set native Android text through the in-app bridge. Use this for Chinese/Unicode; always pass packageName so the tool targets the intended app.', {
-      text: { type: 'string', description: 'Text to set in the focused or coordinate-matched native EditText.' },
-      tapX: { type: 'number', description: 'Optional X coordinate used to choose a native EditText target.' },
-      tapY: { type: 'number', description: 'Optional Y coordinate used to choose a native EditText target.' },
-      hideKeyboard: { type: 'boolean', description: 'Hide the soft keyboard after setting text.' },
-    }, ['text', 'packageName']),
+    bridgeTool('input_text', 'Set native Android text through the in-app bridge. Use this for Chinese/Unicode; always pass packageName so the tool targets the intended app.', {
+      text: { type: 'string', description: 'Text to set in the focused or coordinate-matched native EditText.' },
+      tapX: { type: 'number', description: 'Optional X coordinate used to choose a native EditText target.' },
+      tapY: { type: 'number', description: 'Optional Y coordinate used to choose a native EditText target.' },
+      hideKeyboard: { type: 'boolean', description: 'Hide the soft keyboard after setting text.' },
+    }, ['text', 'packageName']),
     bridgeTool('keyboard_state', 'Read Android soft-keyboard visibility from dumpsys input_method.'),
     bridgeTool('hide_keyboard', 'Hide the Android soft keyboard when it is visible.', {
       force: { type: 'boolean', description: 'Send keyboard-dismiss keys even when the visibility probe says the keyboard is hidden.' },
@@ -342,29 +394,29 @@ function fullToolDefinitions() {
   ];
 }
 
-function bridgeTool(name, description, properties = {}, required = []) {
-  return {
-    name,
-    description,
-    inputSchema: baseSchema(properties, required),
-  };
-}
-
-function launchProperties() {
-  return {
-    activity: { type: 'string', description: 'Activity class, such as .MainActivity or com.example.MainActivity.' },
-    component: { type: 'string', description: 'Explicit Android component, such as com.example/.MainActivity.' },
-    action: { type: 'string', description: 'Intent action for explicit Activity launch.' },
-    category: { type: 'string', description: 'Intent category.' },
-    data: { type: 'string', description: 'Intent data URI.' },
-    extra: {
-      type: 'object',
-      additionalProperties: { type: 'string' },
-      description: 'String intent extras as an object of key/value pairs.',
-    },
-  };
-}
-
+function bridgeTool(name, description, properties = {}, required = []) {
+  return {
+    name,
+    description,
+    inputSchema: baseSchema(properties, required),
+  };
+}
+
+function launchProperties() {
+  return {
+    activity: { type: 'string', description: 'Activity class, such as .MainActivity or com.example.MainActivity.' },
+    component: { type: 'string', description: 'Explicit Android component, such as com.example/.MainActivity.' },
+    action: { type: 'string', description: 'Intent action for explicit Activity launch.' },
+    category: { type: 'string', description: 'Intent category.' },
+    data: { type: 'string', description: 'Intent data URI.' },
+    extra: {
+      type: 'object',
+      additionalProperties: { type: 'string' },
+      description: 'String intent extras as an object of key/value pairs.',
+    },
+  };
+}
+
 function baseSchema(extraProperties = {}, extraRequired = []) {
   return {
     type: 'object',
@@ -386,83 +438,86 @@ function baseSchema(extraProperties = {}, extraRequired = []) {
   };
 }
 
-function h5TargetSchema() {
-  return {
-    selector: { type: 'string', description: 'CSS selector for the target DOM element.' },
+function h5TargetSchema() {
+  return {
+    selector: { type: 'string', description: 'CSS selector for the target DOM element.' },
     targetText: { type: 'string', description: 'Text, value, aria-label, placeholder, id, name, or role to match.' },
     exact: { type: 'boolean', description: 'Require exact text match instead of substring match.' },
-  };
-}
-
-const commandDefinitions = [
-  { command: 'status', domain: 'core', summary: 'Read bridge status, app/device metadata, capture counts, and Flutter summary.', targetApp: true, options: ['packageName', 'port', 'serial', 'full'] },
-  { command: 'tree', domain: 'core', summary: 'Read Android View tree from the in-app bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes', 'maxDepth'] },
-  { command: 'uia-tree', domain: 'core', summary: 'Read UIAutomator XML for the current foreground window.', options: ['serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes'] },
-  { command: 'screenshot', domain: 'core', summary: 'Capture a screenshot, with foreground package verification when packageName is supplied.', options: ['serial', 'packageName', 'outFile', 'artifactDir'] },
-  { command: 'logs', domain: 'core', summary: 'Read in-app log records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'network', domain: 'core', summary: 'Read in-app network records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'compact', 'urlFilter', 'method', 'statusCode', 'noBodies', 'bodyMaxBytes', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'state', domain: 'core', summary: 'Read in-app state records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'sinceId', 'sinceMs', 'limit'] },
-  { 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: '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'] },
-  { command: 'launch-flutter', domain: 'app', summary: 'Launch the Flutter Activity, optionally with an initial route.', targetApp: true, options: ['serial', 'packageName', 'initialRoute'] },
-  { command: 'permission-state', domain: 'app', summary: 'Read Android runtime permission state.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
-  { command: 'permission-grant', domain: 'app', summary: 'Grant an Android runtime permission.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
-  { command: 'permission-revoke', domain: 'app', summary: 'Revoke an Android runtime permission.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
-  { command: 'permission-dialog', domain: 'app', summary: 'Tap a visible Android permission dialog allow button.', options: ['serial', 'targetText', 'buttonText', 'resourceId', 'attempts', 'intervalMs', 'exact'] },
-  { command: 'appops-set', domain: 'app', summary: 'Set an Android app-op mode.', targetApp: true, options: ['serial', 'packageName', 'op', 'mode'] },
-  { command: 'tap', domain: 'action', summary: 'Tap device coordinates through ADB.', options: ['serial', 'tapX', 'tapY'] },
-  { command: 'tap-text', domain: 'action', summary: 'Tap a visible Android View node by text/contentDescription through the bridge tree.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'noAutoHideKeyboard'] },
-  { command: 'tap-uia-text', domain: 'action', summary: 'Tap a UIAutomator node by text without relying on the in-app tree.', options: ['serial', 'targetText', 'exact'] },
-  { command: 'wait-text', domain: 'action', summary: 'Wait until text appears in bridge status/tree or UIAutomator output.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'timeoutSec', 'requireText', 'absentText', 'requireActivity'] },
-  { command: 'input-text', domain: 'action', summary: 'Set native Android text through the in-app bridge; use this for Chinese/Unicode.', targetApp: true, options: ['serial', 'packageName', 'text', 'tapX', 'tapY', 'hideKeyboard'] },
-  { command: 'keyboard-state', domain: 'action', summary: 'Read Android soft keyboard visibility.', options: ['serial'] },
-  { command: 'hide-keyboard', domain: 'action', summary: 'Hide the Android soft keyboard.', options: ['serial', 'force', 'intervalMs'] },
-  { command: 'swipe', domain: 'action', summary: 'Swipe device coordinates through ADB.', options: ['serial', 'startX', 'startY', 'endX', 'endY', 'durationMs'] },
-  { command: 'keyevent', domain: 'action', summary: 'Send an Android keyevent through ADB.', options: ['serial', 'keyCode'] },
-  { command: 'flutter-tree', domain: 'flutter', summary: 'Read the latest Flutter layout snapshot.', targetApp: true, options: ['serial', 'packageName', 'port'] },
-  { command: 'flutter-nodes', domain: 'flutter', summary: 'Read Flutter operable nodes.', targetApp: true, options: ['serial', 'packageName', 'port'] },
-  { command: 'flutter-action', domain: 'flutter', summary: 'Dispatch a raw Flutter action payload.', targetApp: true, options: ['serial', 'packageName', 'payload'] },
-  { command: 'tap-flutter-text', domain: 'flutter', summary: 'Tap a Flutter node by visible text.', targetApp: true, options: ['serial', 'packageName', 'targetText'] },
-  { command: 'input-flutter-text', domain: 'flutter', summary: 'Set Flutter TextField text through the Flutter action bridge.', targetApp: true, options: ['serial', 'packageName', 'text', 'tapX', 'tapY', 'hideKeyboard'] },
-  { command: 'scroll-flutter', domain: 'flutter', summary: 'Scroll Flutter content by delta or until text is visible.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'delta', 'maxSwipes'] },
-  { command: 'h5-dom', domain: 'webview', summary: 'Read native Android WebView DOM.', targetApp: true, options: ['serial', 'packageName', 'port'] },
-  { command: 'h5-eval', domain: 'webview', summary: 'Execute JavaScript in the current native Android WebView.', targetApp: true, options: ['serial', 'packageName', 'script'] },
-  { command: 'h5-click', domain: 'webview', summary: 'Click a native WebView element by selector or text.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'exact'] },
-  { command: 'h5-input', domain: 'webview', summary: 'Set text in a native WebView input.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'value', 'exact'] },
-  { command: 'h5-wait', domain: 'webview', summary: 'Wait for native WebView text or selector.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'timeoutSec', 'intervalMs'] },
-  { command: 'h5-scroll', domain: 'webview', summary: 'Scroll native WebView content or a DOM element into view.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'deltaX', 'deltaY'] },
-  { command: 'flutter-h5-dom', domain: 'webview', summary: 'Read DOM through a Flutter H5 adapter.', targetApp: true, options: ['serial', 'packageName', 'port'] },
-  { command: 'flutter-h5-eval', domain: 'webview', summary: 'Execute JavaScript through a Flutter H5 adapter.', targetApp: true, options: ['serial', 'packageName', 'script'] },
-  { command: 'flutter-h5-click', domain: 'webview', summary: 'Click a Flutter H5 DOM element.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'exact'] },
-  { command: 'flutter-h5-input', domain: 'webview', summary: 'Set text in a Flutter H5 input.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'value', 'exact'] },
-  { command: 'flutter-h5-wait', domain: 'webview', summary: 'Wait for Flutter H5 text or selector.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'timeoutSec', 'intervalMs'] },
-  { command: 'flutter-h5-scroll', domain: 'webview', summary: 'Scroll Flutter H5 content or a DOM element into view.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'deltaX', 'deltaY'] },
-  { command: 'webview-pages', domain: 'webview', summary: 'List attachable Android WebView DevTools/CDP pages.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'keepForward'] },
-  { command: 'webview-network', domain: 'webview', summary: 'Capture WebView Network events through CDP.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'urlFilter', 'durationMs', 'script', 'includeResponseBody', 'bodyMaxBytes', 'maxEvents'] },
-  { 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'] },
-];
-
-const commandByName = new Map(commandDefinitions.map((definition) => [definition.command, definition]));
-
-async function callTool(name, args) {
-  if (name === 'capabilities') {
-    return toolJson(capabilityPayload(args));
-  }
-  if (name === 'run') {
-    return runGeneric(args);
-  }
-  if (name === 'run_smoke') {
-    return runSmoke(args);
-  }
-  const commandMap = {
+  };
+}
+
+const commandDefinitions = [
+  { command: 'status', domain: 'core', summary: 'Read bridge status, app/device metadata, capture counts, and Flutter summary.', targetApp: true, options: ['packageName', 'port', 'serial', 'full'] },
+  { command: 'tree', domain: 'core', summary: 'Read Android View tree from the in-app bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes', 'maxDepth'] },
+  { command: 'uia-tree', domain: 'core', summary: 'Read UIAutomator XML for the current foreground window.', options: ['serial', 'compact', 'textFilter', 'resourceIdFilter', 'classFilter', 'visibleOnly', 'maxNodes'] },
+  { command: 'screenshot', domain: 'core', summary: 'Capture a screenshot, with foreground package verification when packageName is supplied.', options: ['serial', 'packageName', 'outFile', 'artifactDir'] },
+  { command: 'logs', domain: 'core', summary: 'Read in-app log records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'network', domain: 'core', summary: 'Read in-app network records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'compact', 'urlFilter', 'method', 'statusCode', 'noBodies', 'bodyMaxBytes', 'sinceId', 'sinceMs', 'limit'] },
+  { command: 'state', domain: 'core', summary: 'Read in-app state records from the bridge.', targetApp: true, options: ['packageName', 'port', 'serial', 'sinceId', 'sinceMs', 'limit'] },
+  { 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: 'freeze-app', domain: 'app', summary: 'Stop target app processes with SIGSTOP after content capture to keep observed evidence stable.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
+  { command: 'thaw-app', domain: 'app', summary: 'Resume target app processes with SIGCONT before content capture or actions so bridge data can be read.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
+  { 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'] },
+  { command: 'launch-flutter', domain: 'app', summary: 'Launch the Flutter Activity, optionally with an initial route.', targetApp: true, options: ['serial', 'packageName', 'initialRoute'] },
+  { command: 'permission-state', domain: 'app', summary: 'Read Android runtime permission state.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
+  { command: 'permission-grant', domain: 'app', summary: 'Grant an Android runtime permission.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
+  { command: 'permission-revoke', domain: 'app', summary: 'Revoke an Android runtime permission.', targetApp: true, options: ['serial', 'packageName', 'permission'] },
+  { command: 'permission-dialog', domain: 'app', summary: 'Tap a visible Android permission dialog allow button.', options: ['serial', 'targetText', 'buttonText', 'resourceId', 'attempts', 'intervalMs', 'exact'] },
+  { command: 'appops-set', domain: 'app', summary: 'Set an Android app-op mode.', targetApp: true, options: ['serial', 'packageName', 'op', 'mode'] },
+  { command: 'tap', domain: 'action', summary: 'Tap device coordinates through ADB.', options: ['serial', 'tapX', 'tapY'] },
+  { command: 'tap-text', domain: 'action', summary: 'Tap a visible Android View node by text/contentDescription through the bridge tree.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'noAutoHideKeyboard'] },
+  { command: 'tap-uia-text', domain: 'action', summary: 'Tap a UIAutomator node by text without relying on the in-app tree.', options: ['serial', 'targetText', 'exact'] },
+  { command: 'wait-text', domain: 'action', summary: 'Wait until text appears in bridge status/tree or UIAutomator output.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'timeoutSec', 'requireText', 'absentText', 'requireActivity'] },
+  { command: 'input-text', domain: 'action', summary: 'Set native Android text through the in-app bridge; use this for Chinese/Unicode.', targetApp: true, options: ['serial', 'packageName', 'text', 'tapX', 'tapY', 'hideKeyboard'] },
+  { command: 'keyboard-state', domain: 'action', summary: 'Read Android soft keyboard visibility.', options: ['serial'] },
+  { command: 'hide-keyboard', domain: 'action', summary: 'Hide the Android soft keyboard.', options: ['serial', 'force', 'intervalMs'] },
+  { command: 'swipe', domain: 'action', summary: 'Swipe device coordinates through ADB.', options: ['serial', 'startX', 'startY', 'endX', 'endY', 'durationMs'] },
+  { command: 'keyevent', domain: 'action', summary: 'Send an Android keyevent through ADB.', options: ['serial', 'keyCode'] },
+  { command: 'flutter-tree', domain: 'flutter', summary: 'Read the latest Flutter layout snapshot.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'flutter-nodes', domain: 'flutter', summary: 'Read Flutter operable nodes.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'flutter-action', domain: 'flutter', summary: 'Dispatch a raw Flutter action payload.', targetApp: true, options: ['serial', 'packageName', 'payload'] },
+  { command: 'tap-flutter-text', domain: 'flutter', summary: 'Tap a Flutter node by visible text.', targetApp: true, options: ['serial', 'packageName', 'targetText'] },
+  { command: 'input-flutter-text', domain: 'flutter', summary: 'Set Flutter TextField text through the Flutter action bridge.', targetApp: true, options: ['serial', 'packageName', 'text', 'tapX', 'tapY', 'hideKeyboard'] },
+  { command: 'scroll-flutter', domain: 'flutter', summary: 'Scroll Flutter content by delta or until text is visible.', targetApp: true, options: ['serial', 'packageName', 'targetText', 'delta', 'maxSwipes'] },
+  { command: 'h5-dom', domain: 'webview', summary: 'Read native Android WebView DOM.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'h5-eval', domain: 'webview', summary: 'Execute JavaScript in the current native Android WebView.', targetApp: true, options: ['serial', 'packageName', 'script'] },
+  { command: 'h5-click', domain: 'webview', summary: 'Click a native WebView element by selector or text.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'exact'] },
+  { command: 'h5-input', domain: 'webview', summary: 'Set text in a native WebView input.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'value', 'exact'] },
+  { command: 'h5-wait', domain: 'webview', summary: 'Wait for native WebView text or selector.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'timeoutSec', 'intervalMs'] },
+  { command: 'h5-scroll', domain: 'webview', summary: 'Scroll native WebView content or a DOM element into view.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'deltaX', 'deltaY'] },
+  { command: 'flutter-h5-dom', domain: 'webview', summary: 'Read DOM through a Flutter H5 adapter.', targetApp: true, options: ['serial', 'packageName', 'port'] },
+  { command: 'flutter-h5-eval', domain: 'webview', summary: 'Execute JavaScript through a Flutter H5 adapter.', targetApp: true, options: ['serial', 'packageName', 'script'] },
+  { command: 'flutter-h5-click', domain: 'webview', summary: 'Click a Flutter H5 DOM element.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'exact'] },
+  { command: 'flutter-h5-input', domain: 'webview', summary: 'Set text in a Flutter H5 input.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'value', 'exact'] },
+  { command: 'flutter-h5-wait', domain: 'webview', summary: 'Wait for Flutter H5 text or selector.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'timeoutSec', 'intervalMs'] },
+  { command: 'flutter-h5-scroll', domain: 'webview', summary: 'Scroll Flutter H5 content or a DOM element into view.', targetApp: true, options: ['serial', 'packageName', 'selector', 'targetText', 'deltaX', 'deltaY'] },
+  { command: 'webview-pages', domain: 'webview', summary: 'List attachable Android WebView DevTools/CDP pages.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'keepForward'] },
+  { command: 'webview-network', domain: 'webview', summary: 'Capture WebView Network events through CDP.', targetApp: true, options: ['serial', 'packageName', 'webviewPort', 'socketName', 'targetId', 'pageUrlFilter', 'urlFilter', 'durationMs', 'script', 'includeResponseBody', 'bodyMaxBytes', 'maxEvents'] },
+  { 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'] },
+];
+
+const commandByName = new Map(commandDefinitions.map((definition) => [definition.command, definition]));
+
+async function callTool(name, args) {
+  if (name === 'capabilities') {
+    return toolJson(capabilityPayload(args));
+  }
+  if (name === 'run') {
+    return runGeneric(args);
+  }
+  if (name === 'run_smoke') {
+    return runSmoke(args);
+  }
+  const commandMap = {
     flutter_tree: 'flutter-tree',
     h5_dom: 'h5-dom',
     h5_eval: 'h5-eval',
@@ -470,21 +525,24 @@ async function callTool(name, args) {
     h5_input: 'h5-input',
     h5_wait: 'h5-wait',
     h5_scroll: 'h5-scroll',
+    freeze_app: 'freeze-app',
+    thaw_app: 'thaw-app',
     flutter_h5_dom: 'flutter-h5-dom',
     flutter_h5_eval: 'flutter-h5-eval',
     flutter_h5_click: 'flutter-h5-click',
     flutter_h5_input: 'flutter-h5-input',
-    flutter_h5_wait: 'flutter-h5-wait',
-    flutter_h5_scroll: 'flutter-h5-scroll',
-    flutter_nodes: 'flutter-nodes',
-    tap_flutter_text: 'tap-flutter-text',
-    input_flutter_text: 'input-flutter-text',
-    uia_tree: 'uia-tree',
-    install_apk: 'install-apk',
-    launch_app: 'launch-app',
-    launch_activity: 'launch-activity',
-    launch_native_test: 'launch-native-test',
-    launch_flutter: 'launch-flutter',
+    flutter_h5_wait: 'flutter-h5-wait',
+    flutter_h5_scroll: 'flutter-h5-scroll',
+    flutter_nodes: 'flutter-nodes',
+    tap_flutter_text: 'tap-flutter-text',
+    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',
+    launch_flutter: 'launch-flutter',
     tap_text: 'tap-text',
     wait_text: 'wait-text',
     input_text: 'input-text',
@@ -499,313 +557,319 @@ async function callTool(name, args) {
     appops_set: 'appops-set',
     tap_uia_text: 'tap-uia-text',
     permission_dialog: 'permission-dialog',
-  };
-  const command = commandMap[name] || name;
-  return runBridgeChecked(command, args);
-}
-
-function capabilityPayload(args = {}) {
-  const includeOptions = Boolean(args.includeOptions);
-  const requestedCommand = args.command ? normalizeCommandName(args.command) : '';
-  if (requestedCommand) {
-    const definition = commandByName.get(requestedCommand);
-    return {
-      ok: Boolean(definition),
-      command: requestedCommand,
-      ...(definition ? shapeCommandDefinition(definition, true) : { error: 'unknown_command' }),
-    };
-  }
-
-  const requestedDomain = args.domain ? String(args.domain) : '';
-  const domains = {};
-  for (const definition of commandDefinitions) {
-    if (requestedDomain && definition.domain !== requestedDomain) continue;
-    if (!domains[definition.domain]) domains[definition.domain] = [];
-    domains[definition.domain].push(shapeCommandDefinition(definition, includeOptions));
-  }
-  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.',
-    domains,
-  };
-}
-
-function shapeCommandDefinition(definition, includeOptions) {
-  return {
-    command: definition.command,
-    summary: definition.summary,
-    targetApp: Boolean(definition.targetApp),
-    ...(includeOptions ? { options: definition.options || [] } : {}),
-  };
-}
-
-async function runGeneric(args = {}) {
-  const command = normalizeCommandName(args.command);
-  if (!commandByName.has(command)) {
-    return toolText(`unknown command: ${args.command || ''}`, true);
-  }
-  const commandArgs = {
-    ...(args.arguments && typeof args.arguments === 'object' ? args.arguments : {}),
-  };
-  for (const key of ['adb', 'serial', 'port', 'packageName']) {
-    if (args[key] !== undefined && commandArgs[key] === undefined) {
-      commandArgs[key] = args[key];
-    }
-  }
-  if (command === 'batch') {
-    return runBatch(commandArgs);
-  }
-  return runBridgeChecked(command, commandArgs);
-}
-
-function normalizeCommandName(value) {
-  return String(value || '').trim().replace(/_/g, '-');
-}
-
-function runBridgeChecked(command, args = {}) {
-  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);
-  addArg(cliArgs, 'initial-route', args.initialRoute);
-  addArg(cliArgs, 'activity', args.activity);
-  addArg(cliArgs, 'component', args.component);
-  addArg(cliArgs, 'action', args.action);
-  addRepeatedArg(cliArgs, 'category', args.category);
-  addArg(cliArgs, 'data', args.data);
-  addExtraArgs(cliArgs, args.extra);
-  addArg(cliArgs, 'out-file', args.outFile);
+  };
+  const command = commandMap[name] || name;
+  return runBridgeChecked(command, args);
+}
+
+function capabilityPayload(args = {}) {
+  const includeOptions = Boolean(args.includeOptions);
+  const requestedCommand = args.command ? normalizeCommandName(args.command) : '';
+  if (requestedCommand) {
+    const definition = commandByName.get(requestedCommand);
+    return {
+      ok: Boolean(definition),
+      command: requestedCommand,
+      ...(definition ? shapeCommandDefinition(definition, true) : { error: 'unknown_command' }),
+    };
+  }
+
+  const requestedDomain = args.domain ? String(args.domain) : '';
+  const domains = {};
+  for (const definition of commandDefinitions) {
+    if (requestedDomain && definition.domain !== requestedDomain) continue;
+    if (!domains[definition.domain]) domains[definition.domain] = [];
+    domains[definition.domain].push(shapeCommandDefinition(definition, includeOptions));
+  }
+  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, clear-app-data, launch-app, freeze/thaw, UI, WebView, logcat, network, and permission workflows are supported.',
+    domains,
+  };
+}
+
+function shapeCommandDefinition(definition, includeOptions) {
+  return {
+    command: definition.command,
+    summary: definition.summary,
+    targetApp: Boolean(definition.targetApp),
+    ...(includeOptions ? { options: definition.options || [] } : {}),
+  };
+}
+
+async function runGeneric(args = {}) {
+  const command = normalizeCommandName(args.command);
+  if (!commandByName.has(command)) {
+    return toolText(`unknown command: ${args.command || ''}`, true);
+  }
+  const commandArgs = {
+    ...(args.arguments && typeof args.arguments === 'object' ? args.arguments : {}),
+  };
+  for (const key of ['adb', 'serial', 'port', 'packageName']) {
+    if (args[key] !== undefined && commandArgs[key] === undefined) {
+      commandArgs[key] = args[key];
+    }
+  }
+  if (command === 'batch') {
+    return runBatch(commandArgs);
+  }
+  return runBridgeChecked(command, commandArgs);
+}
+
+function normalizeCommandName(value) {
+  return String(value || '').trim().replace(/_/g, '-');
+}
+
+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);
+  }
+  if ((command === 'freeze-app' || command === 'thaw-app') && !args.packageName) {
+    return toolText(`${command}: packageName is required in MCP mode so the command cannot signal 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);
+  addArg(cliArgs, 'initial-route', args.initialRoute);
+  addArg(cliArgs, 'activity', args.activity);
+  addArg(cliArgs, 'component', args.component);
+  addArg(cliArgs, 'action', args.action);
+  addRepeatedArg(cliArgs, 'category', args.category);
+  addArg(cliArgs, 'data', args.data);
+  addExtraArgs(cliArgs, args.extra);
+  addArg(cliArgs, 'out-file', args.outFile);
   addArg(cliArgs, 'artifact-dir', args.artifactDir || defaultArtifactDirFor(command, args));
   addArg(cliArgs, 'apk-path', args.apkPath);
   addArg(cliArgs, 'tap-x', args.tapX);
@@ -831,45 +895,45 @@ function buildBridgeCliArgs(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, '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, '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, '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, '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);
@@ -877,21 +941,21 @@ function buildBridgeCliArgs(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);
-  addArg(cliArgs, 'skip-flutter-launch', args.skipFlutterLaunch);
-  return 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));
-  addArg(cliArgs, 'skip-flutter-launch', args.skipFlutterLaunch);
-  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 '';
@@ -906,35 +970,35 @@ function addCommonArgs(cliArgs, args) {
   addArg(cliArgs, 'package-name', args.packageName);
 }
 
-function addArg(cliArgs, name, value) {
-  if (value === undefined || value === null || value === '' || value === false) {
-    return;
-  }
-  cliArgs.push(`--${name}`, String(value));
-}
-
-function addRepeatedArg(cliArgs, name, value) {
-  if (Array.isArray(value)) {
-    for (const item of value) addArg(cliArgs, name, item);
-    return;
-  }
-  addArg(cliArgs, name, value);
-}
-
-function addExtraArgs(cliArgs, value) {
-  if (Array.isArray(value)) {
-    for (const item of value) addArg(cliArgs, 'extra', item);
-    return;
-  }
-  if (value && typeof value === 'object') {
-    for (const [key, extraValue] of Object.entries(value)) {
-      addArg(cliArgs, 'extra', `${key}=${extraValue}`);
-    }
-    return;
-  }
-  addArg(cliArgs, 'extra', value);
-}
-
+function addArg(cliArgs, name, value) {
+  if (value === undefined || value === null || value === '' || value === false) {
+    return;
+  }
+  cliArgs.push(`--${name}`, String(value));
+}
+
+function addRepeatedArg(cliArgs, name, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) addArg(cliArgs, name, item);
+    return;
+  }
+  addArg(cliArgs, name, value);
+}
+
+function addExtraArgs(cliArgs, value) {
+  if (Array.isArray(value)) {
+    for (const item of value) addArg(cliArgs, 'extra', item);
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const [key, extraValue] of Object.entries(value)) {
+      addArg(cliArgs, 'extra', `${key}=${extraValue}`);
+    }
+    return;
+  }
+  addArg(cliArgs, 'extra', value);
+}
+
 function runProcess(cliArgs) {
   return new Promise((resolve) => {
     const child = spawn(nodeBinary, cliArgs, {
@@ -959,23 +1023,23 @@ function runProcess(cliArgs) {
         code === 0 ? '' : `exitCode: ${code}`,
         retryWithPackageNameHint(cliArgs, stdout, stderr, code),
       ].filter(Boolean).join('\n\n');
-      resolve(toolText(text || emptyProcessText(cliArgs), code !== 0));
-    });
-  });
-}
-
-function emptyProcessText(cliArgs) {
-  const command = cliArgs[1] || '';
-  if (command === 'logcat' && cliArgs.includes('--app-pid')) {
-    return 'logcat: no matching lines for current app pid';
-  }
-  if (command === 'logcat') {
-    return 'logcat: no matching lines';
-  }
-  return 'ok';
-}
-
-function retryWithPackageNameHint(cliArgs, stdout, stderr, code) {
+      resolve(toolText(text || emptyProcessText(cliArgs), code !== 0));
+    });
+  });
+}
+
+function emptyProcessText(cliArgs) {
+  const command = cliArgs[1] || '';
+  if (command === 'logcat' && cliArgs.includes('--app-pid')) {
+    return 'logcat: no matching lines for current app pid';
+  }
+  if (command === 'logcat') {
+    return 'logcat: no matching lines';
+  }
+  return 'ok';
+}
+
+function retryWithPackageNameHint(cliArgs, stdout, stderr, code) {
   if (code === 0 || cliArgs.includes('--package-name') || cliArgs.includes('--port')) {
     return '';
   }
@@ -986,25 +1050,25 @@ function retryWithPackageNameHint(cliArgs, stdout, stderr, code) {
   return 'agentHint: Default bridge port 18080 accepted the connection but did not answer. If you know the target app, retry this tool with packageName so the CLI can discover that app bridge port.';
 }
 
-function toolText(text, isError = false) {
-  return {
-    content: [
-      {
-        type: 'text',
+function toolText(text, isError = false) {
+  return {
+    content: [
+      {
+        type: 'text',
         text,
       },
     ],
-    isError,
-  };
-}
-
-function toolJson(value, isError = false) {
-  return toolText(JSON.stringify(value, null, 2), isError);
-}
-
-function sendResult(id, result) {
-  send({ jsonrpc: '2.0', id, result });
-}
+    isError,
+  };
+}
+
+function toolJson(value, isError = false) {
+  return toolText(JSON.stringify(value, null, 2), isError);
+}
+
+function sendResult(id, result) {
+  send({ jsonrpc: '2.0', id, result });
+}
 
 function sendError(id, code, message) {
   send({
@@ -1016,20 +1080,25 @@ function sendError(id, code, message) {
 
 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`);
-}
-
-if (require.main === module) {
-  startServer();
-}
-
-module.exports = {
-  buildBridgeCliArgs,
-  runBatch,
-  startServer,
-};
+function writeLog(text) {
+  process.stderr.write(`${text}\n`);
+}
+
+if (require.main === module) {
+  startServer();
+}
+
+module.exports = {
+  buildBridgeCliArgs,
+  readNextMessage,
+  runBatch,
+  startServer,
+};