@mobileaidev/ai-app-bridge 0.2.15 → 0.3.0-rc.2

package/bin/mcp-server.js

@@ -1,46 +1,21 @@
 #!/usr/bin/env node
 
-const { spawn } = require('child_process');
-const path = require('path');
-
 const packageInfo = require('../package.json');
-const { IOSBridgeProvider } = require('./ios-provider');
-const { WebBridgeProvider } = require('./web-provider');
-const { defaultArtifactDirectory } = require('./artifact-paths');
-const bridgeDir = __dirname;
-const cliScript = path.join(bridgeDir, 'ai-app-bridge.js');
-const nodeBinary = process.env.AI_APP_BRIDGE_NODE || process.execPath;
+const runtimeClient = require('./runtime-client');
+const discovery = require('./command-discovery');
+const clientConnection = new AbortController();
+const { supportedTargets, commandDomains, supportedTargetsText, commandDomainsText, discoveryText } = discovery;
 const supportedProtocolVersions = ['2025-06-18', '2024-11-05'];
 const defaultProtocolVersion = supportedProtocolVersions[0];
-const mcpSurface = (process.env.AI_APP_BRIDGE_MCP_SURFACE || 'compact').toLowerCase();
-const supportedTargets = [
-  'Android native apps',
-  'Android WebView/H5/CDP',
-  'Flutter apps on Android and iOS',
-  'iOS native apps via AiAppBridgeIOS + WebDriverAgent/XCUITest',
-  'WKWebView',
-  'desktop Web Bridge sessions',
-];
-const commandDomains = {
-  core: 'status, tree, uia-tree, screenshot, logs, network, state, events',
-  app: 'install-apk, clear-app-data, launch-*, freeze-app/thaw-app, permission-*, appops-set',
-  action: 'tap, tap-text, tap-uia-text, input-text, swipe, keyevent, wait-text, keyboard-state, hide-keyboard',
-  flutter: 'flutter-tree, flutter-nodes, flutter-action, tap/input/scroll Flutter controls',
-  webview: 'h5-*, flutter-h5-*, webview-pages, webview-network, webview-console',
-  ios: 'ios-devices, ios-doctor, ios-setup, ios runtime evidence, ios-uia-tree/tap/input/swipe, ios-h5-*, ios-flutter-*',
-  web: 'web-session-start, web-sessions, web-status, web-dom, web-logs, web-network, web-state, web-events, web-command, web-click, web-input, web-wait, web-scroll',
-  diagnostics: 'logcat, smoke',
-  advanced: 'batch, forward, remove-forward',
-};
-const supportedTargetsText = `AI App Bridge supports ${supportedTargets.join('; ')}.`;
-const commandDomainsText = `Command domains: ${Object.entries(commandDomains).map(([domain, summary]) => `${domain}(${summary})`).join('; ')}.`;
-const discoveryText = 'Default MCP surface is compact: call capabilities to discover domains, commands, and options, then call run with the selected command and arguments.';
 const serverInstructions = [
+  'Intent, Script and individual commands share one runtime across CLI and MCP. Disconnecting a client leaves operations running; explicit task cancel or runtime stop owns cancellation. Platform capabilities do not imply full complex-App acceptance.',
+  'Use script status/wait for progress and resultRef; read the final output with script operation=result and the same operationId, including after runtime restart. A completed execution is separate from the business verdict.',
   supportedTargetsText,
   commandDomainsText,
   discoveryText,
   'Prefer AI App Bridge over raw adb, devicectl, or browser-specific scripts when inspecting UI, text, WebView/WKWebView, logs, network, app install, launch, permissions, or app-level Web evidence.',
-  'Always pass packageName for Android app-specific commands, or pass an explicit port. For iOS, pass bundleId plus deviceId when more than one iPhone is connected.',
+  'Always pass packageName for Android app-specific commands. Port only selects the host forwarding port. For iOS, pass bundleId plus deviceId when more than one iPhone is connected.',
+  'WDA App actions require the exact deviceId, wdaRunnerBundleId and wdaSessionId. A forwarded wdaUrl selects transport only; discover per-command requirements through capabilities.',
   'For Web Bridge sessions, start the provider, connect the browser SDK, then pass sessionId and targetId when needed.',
   'Use freeze-app/thaw-app only as an optional stabilization control for dynamic or transient screens: thaw before reads/actions/captures, freeze after evidence capture only when it helps reasoning, and thaw before the next operation or before finishing so the app is not left frozen.',
 ].join(' ');
@@ -51,8 +26,7 @@ ${supportedTargetsText}
 ${commandDomainsText}
 
 MCP surface:
-  compact (default)  exposes only capabilities and run.
-  full/legacy        exposes one tool per command; set AI_APP_BRIDGE_MCP_SURFACE=full.
+  capabilities and run are the only tools. Per-command aliases were removed.
 
 Discovery:
   1. Call capabilities with optional domain or command filters.
@@ -60,20 +34,22 @@ Discovery:
   3. Put command-specific options in arguments.
 
 Target ids:
-  Android app commands require packageName or explicit port.
-  iOS app commands use bundleId; add deviceId when multiple devices exist and wdaUrl for WDA actions.
+  Android app commands require packageName; port selects only the host forwarding port.
+  iOS app commands use bundleId and the deviceId required by capabilities.
+  WDA App actions require deviceId, wdaRunnerBundleId and wdaSessionId; wdaUrl is transport only.
   Web Bridge commands use sessionId; add targetId for multi-target pages.
 
 Examples:
   capabilities { "domain": "webview", "includeOptions": true }
-  run { "command": "screenshot", "packageName": "com.example.app" }
+  run { "command": "screenshot", "arguments": { "packageName": "com.example.app" } }
   run { "command": "web-session-start", "arguments": { "webPort": 18180 } }
 `;
-const iosProvider = new IOSBridgeProvider();
-const webProvider = new WebBridgeProvider();
-
 let buffer = Buffer.alloc(0);
 let responseFormat = null;
+const activeMessages = new Set();
+let stdinEnded = false;
+let shutdownPromise = null;
+let signalHandlersInstalled = false;
 
 function startServer() {
   process.stdin.on('data', (chunk) => {
@@ -82,6 +58,11 @@ function startServer() {
   });
 
   process.stdin.on('error', () => {});
+  process.stdin.on('end', () => {
+    stdinEnded = true;
+    maybeShutdownAfterMessages();
+  });
+  installSignalHandlers();
 }
 
 function drainMessages() {
@@ -92,12 +73,41 @@ function drainMessages() {
     }
     buffer = parsed.remaining;
     setResponseFormat(parsed.format);
-    handleMessage(parsed.body).catch((error) => {
+    const active = handleMessage(parsed.body).catch((error) => {
       writeLog(`unhandled message error: ${error.stack || error}`);
+    }).finally(() => {
+      activeMessages.delete(active);
+      maybeShutdownAfterMessages();
     });
+    activeMessages.add(active);
   }
 }
 
+function maybeShutdownAfterMessages() {
+  if (!stdinEnded) return;
+  void shutdownSharedResources();
+}
+
+function installSignalHandlers() {
+  if (signalHandlersInstalled) return;
+  signalHandlersInstalled = true;
+  for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.once(signal, () => {
+      stdinEnded = true;
+      void shutdownSharedResources().finally(() => process.exit(0));
+    });
+  }
+}
+
+async function shutdownSharedResources() {
+  if (shutdownPromise) return shutdownPromise;
+  shutdownPromise = (async () => {
+    clientConnection.abort();
+    await Promise.allSettled([...activeMessages]);
+  })();
+  return shutdownPromise;
+}
+
 function readNextMessage(source) {
   const text = source.toString('utf8');
   if (/^Content-Length:/i.test(text)) {
@@ -208,7 +218,7 @@ async function handleMessage(body) {
 
     if (message.method === 'tools/call') {
       const name = message.params?.name;
-      const args = message.params?.arguments || {};
+      const args = message.params?.arguments === undefined ? {} : message.params.arguments;
       const result = await callTool(name, args);
       sendResult(message.id, result);
       return;
@@ -228,1013 +238,44 @@ function negotiateProtocolVersion(requestedVersion) {
 }
 
 function toolDefinitions() {
-  if (mcpSurface === 'full' || mcpSurface === 'legacy') {
-    return fullToolDefinitions();
-  }
-  return compactToolDefinitions();
-}
-
-function compactToolDefinitions() {
-  return [
-    bridgeTool('capabilities', `List AI App Bridge capability domains and commands across Android, iOS, Flutter, WebView/H5/CDP, and Web Bridge targets. ${commandDomainsText}`, {
-      domain: { type: 'string', description: 'Optional domain filter: core, app, action, flutter, webview, ios, web, diagnostics, or advanced.' },
-      command: { type: 'string', description: 'Optional command name for detailed arguments, such as install-apk, launch-app, tree, input-text, webview-network, ios-setup, ios-tap, web-session-start, or web-command.' },
-      includeOptions: { type: 'boolean', description: 'Include per-command argument names. Defaults to false to keep output compact.' },
-    }),
-    bridgeTool('run', 'Run an AI App Bridge command from capabilities. Pass packageName/port for Android app commands, bundleId/deviceId for iOS app commands, and sessionId/targetId for Web Bridge commands.', {
-      command: { type: 'string', description: 'Command name from capabilities, using CLI form such as status, install-apk, launch-app, input-text, webview-network, ios-doctor, ios-setup, ios-status, ios-tap, web-session-start, web-status, or web-command.' },
-      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.' },
-      bundleId: { type: 'string', description: 'Target iOS app bundle identifier for ios-* commands.' },
-      deviceId: { type: 'string', description: 'iOS devicectl identifier, UDID, serial number, or device name.' },
-      sessionId: { type: 'string', description: 'Target Web Bridge SDK session id for web-* commands.' },
-      targetId: { type: 'string', description: 'Optional Web Bridge target id for multi-target pages.' },
-      iosHost: { type: 'string', description: 'iOS runtime host or CoreDevice tunnel IP.' },
-      iosPort: { type: 'number', description: 'iOS runtime port when auto-discovery is unavailable.' },
-      runtimeUrl: { type: 'string', description: 'Explicit iOS runtime base URL.' },
-      wdaUrl: { type: 'string', description: 'WebDriverAgent base URL for iOS full-control commands.' },
-      wdaSessionId: { type: 'string', description: 'Existing WebDriverAgent session id to reuse.' },
-      wdaBundleId: { type: 'string', description: 'Unique WebDriverAgentRunner bundle id for signing.' },
-      accessibilityId: { type: 'string', description: 'iOS accessibility identifier for element input.' },
-      elementId: { type: 'string', description: 'Existing WDA element id for element input.' },
-      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('h5_eval', 'Execute debug JavaScript in the current native Android WebView.', {
-      script: { type: 'string' },
-    }, ['script']),
-    bridgeTool('h5_click', 'Click a native Android WebView DOM element by CSS selector or text.', h5TargetSchema(), []),
-    bridgeTool('h5_input', 'Set text in a native Android WebView input by CSS selector or text.', {
-      ...h5TargetSchema(),
-      value: { type: 'string', description: 'Text value to set.' },
-    }, ['value']),
-    bridgeTool('h5_wait', 'Wait for a native Android WebView DOM element or body text.', {
-      ...h5TargetSchema(),
-      timeoutSec: { type: 'number', description: 'Maximum wait time. Defaults to 10 seconds.' },
-      intervalMs: { type: 'number', description: 'Polling interval. Defaults to 500 ms.' },
-    }),
-    bridgeTool('h5_scroll', 'Scroll a native Android WebView or scroll a DOM element into view.', {
-      ...h5TargetSchema(),
-      deltaX: { type: 'number', description: 'Window scroll delta X when no selector/text is supplied.' },
-      deltaY: { type: 'number', description: 'Window scroll delta Y when no selector/text is supplied.' },
-    }),
-    bridgeTool('flutter_h5_dom', 'Read DOM through a Flutter-registered H5 adapter.'),
-    bridgeTool('flutter_h5_eval', 'Execute JavaScript through a Flutter-registered H5 adapter.', {
-      script: { type: 'string' },
-    }, ['script']),
-    bridgeTool('flutter_h5_click', 'Click a Flutter H5 DOM element by CSS selector or text.', h5TargetSchema(), []),
-    bridgeTool('flutter_h5_input', 'Set text in a Flutter H5 input by CSS selector or text.', {
-      ...h5TargetSchema(),
-      value: { type: 'string', description: 'Text value to set.' },
-    }, ['value']),
-    bridgeTool('flutter_h5_wait', 'Wait for a Flutter H5 DOM element or body text.', {
-      ...h5TargetSchema(),
-      timeoutSec: { type: 'number', description: 'Maximum wait time. Defaults to 10 seconds.' },
-      intervalMs: { type: 'number', description: 'Polling interval. Defaults to 500 ms.' },
-    }),
-    bridgeTool('flutter_h5_scroll', 'Scroll a Flutter H5 document or DOM element into view.', {
-      ...h5TargetSchema(),
-      deltaX: { type: 'number', description: 'Window scroll delta X when no selector/text is supplied.' },
-      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', 'Optionally stop target app processes with SIGSTOP when a dynamic or transient screen needs stable evidence for review.', {
-      pid: { type: 'string', description: 'Optional explicit process id. Defaults to all processes named packageName or packageName:*.' },
-    }, ['packageName']),
-    bridgeTool('thaw_app', 'Resume target app processes with SIGCONT before reads, waits, captures, or actions, and before finishing any task that used freeze-app.', {
-      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.' },
-      tag: { type: 'string', description: 'Comma-separated exact logcat tags.' },
-      level: { type: 'string', description: 'Minimum Android log level: V,D,I,W,E,F.' },
-      grep: { type: 'string', description: 'Substring filter applied after pid/tag/level.' },
-      lines: { type: 'number', description: 'Input logcat tail line count before filtering.' },
-      since: { type: 'string', description: 'Passed to adb logcat -T.' },
-      follow: { type: 'boolean', description: 'Follow live logs for durationSec seconds.' },
-      durationSec: { type: 'number', description: 'Bounded live follow duration. Max 60 seconds.' },
-      clear: { type: 'boolean', description: 'Clear logcat before reading/following.' },
-    }),
-    bridgeTool('network', 'Read generic in-app network records.', {
-      compact: { type: 'boolean', description: 'Return one-line-sized network record summaries without bodies.' },
-      urlFilter: { type: 'string', description: 'Only retain records whose URL contains this string.' },
-      method: { type: 'string', description: 'Only retain records with this HTTP method.' },
-      statusCode: { type: 'number', description: 'Only retain records with this HTTP status.' },
-      noBodies: { type: 'boolean', description: 'Omit requestBody and responseBody fields from full output.' },
-      bodyMaxBytes: { type: 'number', description: 'Maximum request/response body bytes retained per record.' },
-    }),
-    bridgeTool('webview_pages', 'List attachable Android WebView DevTools/CDP pages for the target package.', {
-      webviewPort: { type: 'number', description: 'Local port used for adb forward. Defaults to the first free port at or above 9222.' },
-      socketName: { type: 'string', description: 'Explicit webview_devtools_remote socket name.' },
-      targetId: { type: 'string', description: 'Optional CDP target/page id.' },
-      pageUrlFilter: { type: 'string', description: 'Prefer a WebView page whose URL contains this string.' },
-      keepForward: { type: 'boolean', description: 'Leave the adb forward active after listing pages.' },
-    }),
-    bridgeTool('webview_network', 'Capture WebView fetch/XHR/resource Network events through Chrome DevTools Protocol.', {
-      webviewPort: { type: 'number', description: 'Local port used for adb forward. Defaults to the first free port at or above 9222.' },
-      socketName: { type: 'string', description: 'Explicit webview_devtools_remote socket name.' },
-      targetId: { type: 'string', description: 'Optional CDP target/page id.' },
-      pageUrlFilter: { type: 'string', description: 'Prefer a WebView page whose URL contains this string.' },
-      urlFilter: { type: 'string', description: 'Only retain Network requests whose URL contains this string.' },
-      durationMs: { type: 'number', description: 'Capture duration after attach. Defaults to 3000 ms.' },
-      script: { type: 'string', description: 'JavaScript expression to evaluate after Network/Runtime are enabled.' },
-      includeResponseBody: { type: 'boolean', description: 'Fetch response bodies with Network.getResponseBody when available.' },
-      bodyMaxBytes: { type: 'number', description: 'Maximum response/request body bytes retained per event.' },
-      maxEvents: { type: 'number', description: 'Maximum raw CDP events retained. Defaults to 200.' },
-    }),
-    bridgeTool('webview_console', 'Capture WebView console and log events through Chrome DevTools Protocol.', {
-      webviewPort: { type: 'number', description: 'Local port used for adb forward. Defaults to the first free port at or above 9222.' },
-      socketName: { type: 'string', description: 'Explicit webview_devtools_remote socket name.' },
-      targetId: { type: 'string', description: 'Optional CDP target/page id.' },
-      pageUrlFilter: { type: 'string', description: 'Prefer a WebView page whose URL contains this string.' },
-      durationMs: { type: 'number', description: 'Capture duration after attach. Defaults to 3000 ms.' },
-      script: { type: 'string', description: 'JavaScript expression to evaluate after Runtime is enabled.' },
-      maxEvents: { type: 'number', description: 'Maximum raw CDP events retained. Defaults to 200.' },
-    }),
-    bridgeTool('state', 'Read generic in-app state records.'),
-    bridgeTool('events', 'Read generic in-app event records.'),
-    bridgeTool('uia_tree', 'Read UIAutomator XML for the current device window.'),
-    bridgeTool('screenshot', 'Capture an ADB screenshot.'),
-    bridgeTool('install_apk', 'Install an APK through ADB while assisting device-side package-installer confirmation screens with UIAutomator.', {
-      apkPath: { type: 'string', description: 'Absolute or workspace-relative APK path.' },
-      allowDowngrade: { type: 'boolean', description: 'Pass -d to adb install.' },
-      streaming: { type: 'boolean', description: 'Use streaming install instead of the default --no-streaming mode.' },
-      installTimeoutMs: { type: 'number', description: 'Maximum time for adb install. Defaults to 180000 ms.' },
-      installerTimeoutMs: { type: 'number', description: 'Maximum time to keep assisting installer screens after adb install exits. Defaults to 90000 ms.' },
-      intervalMs: { type: 'number', description: 'Installer polling interval. Defaults to 700 ms.' },
-    }, ['apkPath']),
-    bridgeTool('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' },
-    }, ['tapX', 'tapY']),
-    bridgeTool('tap_text', 'Tap the center of an Android View node by exact text or contentDescription.', {
-      targetText: { type: 'string' },
-      noAutoHideKeyboard: { type: 'boolean', description: 'Disable the default keyboard-risk guard before tapping lower-screen app nodes.' },
-    }, ['targetText']),
-    bridgeTool('wait_text', 'Wait until text appears in status, Android tree, or UIAutomator tree.', {
-      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('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.' },
-      intervalMs: { type: 'number', description: 'Delay between dismiss attempts. Defaults to 500 ms.' },
-    }),
-    bridgeTool('swipe', 'Swipe device coordinates through ADB.', {
-      startX: { type: 'number' },
-      startY: { type: 'number' },
-      endX: { type: 'number' },
-      endY: { type: 'number' },
-      durationMs: { type: 'number' },
-    }, ['startX', 'startY', 'endX', 'endY']),
-    bridgeTool('keyevent', 'Send an Android keyevent through ADB.', {
-      keyCode: { type: 'number' },
-    }, ['keyCode']),
-    bridgeTool('permission_state', 'Read Android runtime permission state from dumpsys package.', {
-      permission: { type: 'string' },
-    }, ['permission']),
-    bridgeTool('permission_grant', 'Grant an Android runtime permission with adb pm grant, then read state.', {
-      permission: { type: 'string' },
-    }, ['permission']),
-    bridgeTool('permission_revoke', 'Revoke an Android runtime permission with adb pm revoke, then read state.', {
-      permission: { type: 'string' },
-    }, ['permission']),
-    bridgeTool('appops_set', 'Set an Android app-op mode with adb appops set.', {
-      op: { type: 'string' },
-      mode: { type: 'string' },
-    }, ['op', 'mode']),
-    bridgeTool('tap_uia_text', 'Tap a UIAutomator node by text without relying on the in-app tree.', {
-      targetText: { type: 'string' },
-      exact: { type: 'boolean' },
-    }, ['targetText']),
-    bridgeTool('permission_dialog', 'Tap a visible Android permission dialog allow button through UIAutomator.', {
-      targetText: { type: 'string', description: 'Optional custom allow-button text.' },
-      buttonText: { type: 'string', description: 'Optional comma-separated allow-button texts.' },
-      resourceId: { type: 'string', description: 'Optional permission button resource id.' },
-      attempts: { type: 'number' },
-      intervalMs: { type: 'number' },
-      exact: { type: 'boolean' },
-    }),
-    {
-      name: 'run_smoke',
-      description: 'Run the full Android + Flutter bridge smoke test.',
-      inputSchema: baseSchema(),
-    },
+    { name: 'capabilities', description: 'Discover commands and their exact argument schemas. Include options or select one command for the complete contract.',
+      inputSchema: { type: 'object', additionalProperties: false, properties: {
+        domain: { type: 'string' }, command: { type: 'string' }, includeOptions: { type: 'boolean' },
+      } } },
+    { name: 'run', description: 'Execute a command from capabilities. All command parameters, including target identity, belong in arguments.',
+      inputSchema: { type: 'object', additionalProperties: false, required: ['command'], properties: {
+        command: { type: 'string' }, arguments: { type: 'object', additionalProperties: true },
+      } } },
   ];
 }
 
-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',
-    properties: {
-      serial: { type: 'string', description: 'ADB serial. Optional when one device is connected.' },
-      adb: { type: 'string', description: 'ADB executable path or command.' },
-      port: { type: 'number', description: 'Raw bridge port override. Defaults to 18080; agents should prefer packageName when targeting a known app.' },
-      packageName: { type: 'string', description: 'Target Android package name. Use this when default 18080 is unreachable or multiple bridge-enabled apps are installed; the CLI discovers the app bridge port from package-private state.' },
-      initialRoute: { type: 'string', description: 'Flutter initial route for launch_flutter.' },
-      outFile: { type: 'string', description: 'Screenshot output path for screenshot.' },
-      artifactDir: { type: 'string', description: 'Directory for generated default artifacts such as screenshots.' },
-      sinceId: { type: 'number', description: 'Capture query lower bound by record id.' },
-      sinceMs: { type: 'number', description: 'Capture query lower bound by timestamp milliseconds.' },
-      limit: { type: 'number', description: 'Maximum capture records to return.' },
-      ...extraProperties,
-    },
-    required: extraRequired,
-    additionalProperties: false,
-  };
-}
-
-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: '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: 'Optionally stop target app processes with SIGSTOP when dynamic UI needs stable evidence.', targetApp: true, options: ['serial', 'packageName', 'pid'] },
-  { command: 'thaw-app', domain: 'app', summary: 'Resume target app processes with SIGCONT before reads, waits, captures, actions, or final handoff.', 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: 'ios-doctor', domain: 'ios', summary: 'Check Xcode, connected iPhone, AiAppBridgeIOS runtime, and WebDriverAgent readiness.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'wdaUrl'] },
-  { command: 'ios-setup', domain: 'ios', summary: 'Verify full-control iOS setup; can install/launch the app and start WDA when signing inputs are supplied.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'appPath', 'iosHost', 'iosPort', 'runtimeUrl', 'wdaUrl', 'wdaProjectPath', 'wdaBundleId', 'teamId', 'startWda'] },
-  { command: 'ios-devices', domain: 'ios', summary: 'List iOS devices known to xcrun devicectl.', targetKind: 'ios-device', options: ['deviceId'] },
-  { command: 'ios-install-app', domain: 'ios', summary: 'Install an iOS .app bundle through devicectl.', targetKind: 'ios-app', options: ['deviceId', 'appPath'] },
-  { command: 'ios-launch-app', domain: 'ios', summary: 'Launch an iOS app by bundle identifier through devicectl.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'terminateExisting'] },
-  { command: 'ios-status', domain: 'ios', summary: 'Read AiAppBridgeIOS runtime status.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
-  { command: 'ios-tree', domain: 'ios', summary: 'Read UIKit tree from the AiAppBridgeIOS runtime.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
-  { command: 'ios-logs', domain: 'ios', summary: 'Read in-app iOS log records.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'ios-network', domain: 'ios', summary: 'Read in-app iOS network records.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'ios-state', domain: 'ios', summary: 'Read in-app iOS state records.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'ios-events', domain: 'ios', summary: 'Read in-app iOS event records.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'ios-h5-dom', domain: 'ios', summary: 'Read WKWebView DOM from the AiAppBridgeIOS runtime.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
-  { command: 'ios-h5-eval', domain: 'ios', summary: 'Execute JavaScript in WKWebView through the AiAppBridgeIOS runtime.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'script'] },
-  { command: 'ios-flutter-tree', domain: 'ios', summary: 'Read Flutter iOS layout snapshot from the runtime.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
-  { command: 'ios-flutter-nodes', domain: 'ios', summary: 'Read Flutter iOS operable nodes from the runtime.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl'] },
-  { command: 'ios-flutter-action', domain: 'ios', summary: 'Dispatch a Flutter iOS action through the runtime.', targetKind: 'ios-app', options: ['deviceId', 'bundleId', 'iosHost', 'iosPort', 'runtimeUrl', 'payload'] },
-  { command: 'ios-screenshot', domain: 'ios', summary: 'Capture an iOS device screenshot through devicectl.', targetKind: 'ios-device', options: ['deviceId', 'outFile', 'artifactDir', 'displayUniqueId'] },
-  { command: 'ios-wda-status', domain: 'ios', summary: 'Check WebDriverAgent status.', targetKind: 'ios-device', options: ['wdaUrl'] },
-  { command: 'ios-uia-tree', domain: 'ios', summary: 'Read the XCUITest/WebDriverAgent UI tree.', targetKind: 'ios-device', options: ['bundleId', 'wdaUrl', 'wdaSessionId'] },
-  { command: 'ios-tap', domain: 'ios', summary: 'Tap iOS device coordinates through WebDriverAgent.', targetKind: 'ios-device', options: ['bundleId', 'wdaUrl', 'wdaSessionId', 'tapX', 'tapY'] },
-  { command: 'ios-input', domain: 'ios', summary: 'Type text through WebDriverAgent, optionally tapping coordinates first.', targetKind: 'ios-device', options: ['bundleId', 'wdaUrl', 'wdaSessionId', 'text', 'tapX', 'tapY', 'accessibilityId', 'elementId', 'clearFirst'] },
-  { command: 'ios-swipe', domain: 'ios', summary: 'Swipe through WebDriverAgent.', targetKind: 'ios-device', options: ['bundleId', 'wdaUrl', 'wdaSessionId', 'startX', 'startY', 'endX', 'endY', 'durationMs'] },
-  { command: 'web-provider-status', domain: 'web', summary: 'Read desktop Web Bridge provider status.', options: [] },
-  { command: 'web-session-start', domain: 'web', summary: 'Start the desktop Web Bridge WebSocket session server.', options: ['host', 'webPort', 'path', 'token'] },
-  { command: 'web-connect-info', domain: 'web', summary: 'Read the Web Bridge endpoint and token for SDK clients.', options: [] },
-  { command: 'web-sessions', domain: 'web', summary: 'List connected Web Bridge SDK sessions.', options: [] },
-  { command: 'web-status', domain: 'web', summary: 'Read status and capture counts for a Web Bridge session.', targetKind: 'web-target', options: ['sessionId'] },
-  { command: 'web-dom', domain: 'web', summary: 'Read or refresh a Web Bridge DOM snapshot.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'refresh', 'timeoutMs'] },
-  { command: 'web-logs', domain: 'web', summary: 'Read Web Bridge log records.', targetKind: 'web-target', options: ['sessionId', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'web-network', domain: 'web', summary: 'Read Web Bridge network records.', targetKind: 'web-target', options: ['sessionId', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'web-state', domain: 'web', summary: 'Read Web Bridge state records.', targetKind: 'web-target', options: ['sessionId', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'web-events', domain: 'web', summary: 'Read Web Bridge event records.', targetKind: 'web-target', options: ['sessionId', 'sinceId', 'sinceMs', 'limit'] },
-  { command: 'web-command', domain: 'web', summary: 'Run a whitelisted command in a connected Web Bridge SDK session.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'name', 'arguments', 'timeoutMs'] },
-  { command: 'web-click', domain: 'web', summary: 'Click a DOM element through the Web Bridge SDK command path.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'targetText', 'timeoutMs'] },
-  { command: 'web-input', domain: 'web', summary: 'Set text in a DOM input through the Web Bridge SDK command path.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'value', 'timeoutMs'] },
-  { command: 'web-wait', domain: 'web', summary: 'Wait for text or selector through the Web Bridge SDK command path.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'targetText', 'timeoutMs'] },
-  { command: 'web-scroll', domain: 'web', summary: 'Scroll a Web Bridge DOM target.', targetKind: 'web-target', options: ['sessionId', 'targetId', 'selector', 'deltaX', 'deltaY', 'timeoutMs'] },
-  { 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',
-    h5_click: 'h5-click',
-    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',
-    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',
-    keyboard_state: 'keyboard-state',
-    hide_keyboard: 'hide-keyboard',
-    webview_pages: 'webview-pages',
-    webview_network: 'webview-network',
-    webview_console: 'webview-console',
-    permission_state: 'permission-state',
-    permission_grant: 'permission-grant',
-    permission_revoke: 'permission-revoke',
-    appops_set: 'appops-set',
-    tap_uia_text: 'tap-uia-text',
-    permission_dialog: 'permission-dialog',
-  };
-  const command = commandMap[name] || normalizeCommandName(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 result = capabilityPayload(args);
+    return toolJson(result, result.ok === false);
   }
-
-  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',
-    supportedTargets,
-    commandDomains,
-    usage: `${supportedTargetsText} ${discoveryText} Use run with one of these command names. Prefer packageName for Android app commands, bundleId/deviceId for iOS, and sessionId/targetId for Web Bridge sessions.`,
-    domains,
-  };
-}
-
-function shapeCommandDefinition(definition, includeOptions) {
-  return {
-    command: definition.command,
-    summary: definition.summary,
-    targetApp: Boolean(definition.targetApp),
-    targetKind: definition.targetKind || (definition.targetApp ? 'android-app' : 'none'),
-    ...(includeOptions ? { options: definition.options || [] } : {}),
-  };
+  if (name === 'run') return runGeneric(args);
+  return toolJson({ ok: false, error: 'unknown_tool', message: `Unknown tool: ${name}. Use capabilities or run.`, dispatched: false, ambiguous: false }, true);
 }
 
+// MCP only adapts the shared execution reply to its tool-result format.
+const capabilityPayload = discovery.capabilities;
 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 sharedRunArgKeys()) {
-    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 sharedRunArgKeys() {
-  return [
-    'adb',
-    'serial',
-    'port',
-    'packageName',
-    'artifactDir',
-    'sessionId',
-    'targetId',
-    'webPort',
-    'deviceId',
-    'bundleId',
-    'iosHost',
-    'iosPort',
-    'runtimeUrl',
-    'wdaUrl',
-    'wdaSessionId',
-    'wdaProjectPath',
-    'wdaBundleId',
-    'accessibilityId',
-    'elementId',
-    'teamId',
-    'appPath',
-    'xcodebuild',
-    'devicectl',
-  ];
-}
-
-function runBridgeChecked(command, args = {}) {
-  const definition = commandByName.get(command);
-  if (definition?.domain === 'ios') {
-    return runIOSChecked(command, args);
-  }
-  if (definition?.domain === 'web') {
-    return runWebChecked(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);
-  }
-  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 runWebChecked(command, args = {}) {
-  const result = await webProvider.run(command, args);
-  return toolJson(result, result?.ok === false);
-}
-
-async function runIOSChecked(command, args = {}) {
-  const result = await iosProvider.run(command, args);
-  return toolJson(result, result?.ok === false);
-}
-
-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 sharedRunArgKeys()) {
-    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 sharedRunArgKeys()) {
-      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,
-        bundleId: stepArgs.bundleId,
-        deviceId: stepArgs.deviceId,
-        sessionId: stepArgs.sessionId,
-        targetId: stepArgs.targetId,
-        port: stepArgs.port,
-        iosPort: stepArgs.iosPort,
-        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,
-        bundleId: stepArgs.bundleId,
-        deviceId: stepArgs.deviceId,
-        port: stepArgs.port,
-        iosPort: stepArgs.iosPort,
-        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.bundleId) summary.bundleId = payload.bundleId;
-  if (payload.endpoint) summary.endpoint = payload.endpoint;
-  if (payload.wdaUrl) summary.wdaUrl = payload.wdaUrl;
-  if (payload.device?.identifier) summary.deviceId = payload.device.identifier;
-  if (payload.selectedDevice?.identifier) summary.deviceId = payload.selectedDevice.identifier;
-  if (payload.sessionId) summary.sessionId = payload.sessionId;
-  if (payload.targetId) summary.targetId = payload.targetId;
-  if (payload.session?.sessionId) summary.sessionId = payload.session.sessionId;
-  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.sessionCount !== undefined) summary.sessionCount = payload.sessionCount;
-  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, 'device-id', args.deviceId);
-  addArg(cliArgs, 'bundle-id', args.bundleId);
-  addArg(cliArgs, 'app-path', args.appPath);
-  addArg(cliArgs, 'ios-host', args.iosHost);
-  addArg(cliArgs, 'ios-port', args.iosPort);
-  addArg(cliArgs, 'runtime-url', args.runtimeUrl);
-  addArg(cliArgs, 'wda-url', args.wdaUrl);
-  addArg(cliArgs, 'wda-session-id', args.wdaSessionId);
-  addArg(cliArgs, 'wda-project-path', args.wdaProjectPath);
-  addArg(cliArgs, 'wda-bundle-id', args.wdaBundleId);
-  addArg(cliArgs, 'accessibility-id', args.accessibilityId);
-  addArg(cliArgs, 'element-id', args.elementId);
-  addArg(cliArgs, 'clear-first', args.clearFirst);
-  addArg(cliArgs, 'team-id', args.teamId);
-  addArg(cliArgs, 'start-wda', args.startWda);
-  addArg(cliArgs, 'devicectl', args.devicectl);
-  addArg(cliArgs, 'xcodebuild', args.xcodebuild);
-  addArg(cliArgs, 'display-unique-id', args.displayUniqueId);
-  addArg(cliArgs, 'terminate-existing', args.terminateExisting);
-  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);
-  addArg(cliArgs, 'tap-y', args.tapY);
-  addArg(cliArgs, 'target-text', args.targetText);
-  addArg(cliArgs, 'no-auto-hide-keyboard', args.noAutoHideKeyboard);
-  addArg(cliArgs, 'timeout-sec', args.timeoutSec);
-  addArg(cliArgs, 'text', args.text);
-  addArg(cliArgs, 'hide-keyboard', args.hideKeyboard);
-  addArg(cliArgs, 'force', args.force);
-  addArg(cliArgs, 'start-x', args.startX);
-  addArg(cliArgs, 'start-y', args.startY);
-  addArg(cliArgs, 'end-x', args.endX);
-  addArg(cliArgs, 'end-y', args.endY);
-  addArg(cliArgs, 'duration-ms', args.durationMs);
-  addArg(cliArgs, 'allow-downgrade', args.allowDowngrade);
-  addArg(cliArgs, 'streaming', args.streaming);
-  addArg(cliArgs, 'install-timeout-ms', args.installTimeoutMs);
-  addArg(cliArgs, 'installer-timeout-ms', args.installerTimeoutMs);
-  addArg(cliArgs, 'webview-port', args.webviewPort);
-  addArg(cliArgs, 'socket-name', args.socketName);
-  addArg(cliArgs, 'target-id', args.targetId);
-  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, '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, 'pid', args.pid);
-  addArg(cliArgs, 'app-pid', args.appPid);
-  addArg(cliArgs, 'tag', args.tag);
-  addArg(cliArgs, 'level', args.level);
-  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;
-}
-
-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);
-}
-
-function defaultArtifactDirFor(command, args) {
-  if (args.outFile) return '';
-  if (command !== 'screenshot' && command !== 'smoke') return '';
-  return defaultArtifactDirectory();
-}
-
-function addCommonArgs(cliArgs, args) {
-  addArg(cliArgs, 'adb', args.adb);
-  addArg(cliArgs, 'serial', args.serial);
-  addArg(cliArgs, 'port', args.port);
-  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);
+  return toolResultForReply(await runtimeClient.run(args, { signal: clientConnection.signal }));
 }
 
-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, {
-      cwd: bridgeDir,
-      windowsHide: true,
-    });
-    let stdout = '';
-    let stderr = '';
-    child.stdout.on('data', (chunk) => {
-      stdout += chunk.toString();
-    });
-    child.stderr.on('data', (chunk) => {
-      stderr += chunk.toString();
-    });
-    child.on('error', (error) => {
-      resolve(toolText(`failed to start Node bridge CLI: ${error.message}`, true));
-    });
-    child.on('close', (code) => {
-      const text = [
-        stdout.trim(),
-        stderr.trim() ? `stderr:\n${stderr.trim()}` : '',
-        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) {
-  if (code === 0 || cliArgs.includes('--package-name') || cliArgs.includes('--port')) {
-    return '';
-  }
-  const output = `${stdout}\n${stderr}`;
-  if (!/HTTP timeout: http:\/\/127\.0\.0\.1:18080\//.test(output)) {
-    return '';
+function toolResultForReply({ value: result, history }) {
+  let tool;
+  if (typeof result === 'string') tool = toolText(result);
+  else if (Buffer.isBuffer(result)) tool = toolText(result.toString('utf8'));
+  else if (result === undefined) tool = toolJson({ ok: false, error: 'runtime_result_missing', dispatched: null, ambiguous: true }, true);
+  else {
+    if (history && result && typeof result === 'object' && !Array.isArray(result)) result = { ...result, _history: history };
+    tool = toolJson(result, Boolean(result && typeof result === 'object' && result.ok === false));
   }
-  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.';
+  if (history) tool._meta = { 'ai-app-bridge/history': history };
+  return tool;
 }
 
 function toolText(text, isError = false) {
@@ -1288,12 +329,14 @@ if (require.main === module) {
 }
 
 module.exports = {
-  buildBridgeCliArgs,
+  capabilityPayload,
+  callTool,
+  toolDefinitions,
+  toolResultForReply,
   commandDomains,
-  defaultArtifactDirFor,
   mcpHelpText,
   readNextMessage,
-  runBatch,
+  runGeneric,
   startServer,
   supportedTargets,
 };