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

package/bin/android-permissions.js

@@ -0,0 +1,152 @@
+'use strict';
+
+const { execFileBounded } = require('./shared-kernel/execution-io');
+const { checkExecution } = require('./shared-kernel/execution-scope');
+const { CommandError, executionFields } = require('./command-errors');
+const { executeAndroidShell } = require('./shared-kernel/android-shell-execution');
+const execute = (file, args, { timeout, mutation, actionId, ...options }) => mutation
+  ? executeAndroidShell({ adb: file, serial: args[1], argv: args.slice(3), timeoutMs: timeout, actionId })
+  : execFileBounded(file, args, { ...options, timeoutMs: timeout, encoding: 'utf8' });
+const REQUEST_PERMISSIONS = 'android.content.pm.action.REQUEST_PERMISSIONS';
+
+function requireTarget(args) {
+  for (const field of ['packageName', 'permission']) {
+    if (typeof args[field] !== 'string' || !/^[A-Za-z][A-Za-z0-9_]*(?:\.[A-Za-z0-9_]+)+$/.test(args[field])) {
+      throw new CommandError('invalid_argument', `${field} must be a qualified Android identifier.`, { field });
+    }
+  }
+  if (typeof args.serial !== 'string' || !args.serial.trim()) throw new CommandError('missing_argument', 'serial is required.', { field: 'serial' });
+  if (args.userId !== undefined && (!Number.isSafeInteger(args.userId) || args.userId < 0 || args.userId > 2147483647)) {
+    throw new CommandError('invalid_argument', 'userId must be a non-negative Android user ID.', { field: 'userId' });
+  }
+}
+
+async function androidCommand(args, values, run = execute, { mutation = false } = {}) {
+  checkExecution();
+  return run(args.adb || process.env.ADB || 'adb', ['-s', args.serial, ...values], {
+    timeout: args.adbTimeoutMs || 15000, maxBuffer: 16 * 1024 * 1024, mutation,
+    actionId: args.runtimeActionId ?? args.requestId,
+  });
+}
+
+function block(lines, start) {
+  const indent = lines[start].search(/\S/);
+  let end = start + 1;
+  while (end < lines.length && (!lines[end].trim() || lines[end].search(/\S/) > indent)) end++;
+  return lines.slice(start + 1, end);
+}
+
+function uniqueBlock(lines, predicate, error) {
+  const indexes = lines.flatMap((line, i) => predicate(line.trim()) ? [i] : []);
+  if (indexes.length !== 1) throw new CommandError(error, 'Android did not provide one unambiguous package/user permission record.');
+  return { header: lines[indexes[0]].trim(), lines: block(lines, indexes[0]) };
+}
+
+function parsePermissionState(text, { packageName, permission, userId }) {
+  const pkg = uniqueBlock(text.split(/\r?\n/), line => line.startsWith(`Package [${packageName}] (`), 'permission_package_not_found');
+  const appId = pkg.lines.map(line => /^\s+(?:appId|userId)=(\d+)\s*$/.exec(line)).filter(Boolean);
+  if (appId.length !== 1 || Number(appId[0][1]) >= 100000) throw new CommandError('permission_state_unsupported', 'Android package appId is unavailable or ambiguous.');
+  const user = uniqueBlock(pkg.lines, line => line.startsWith(`User ${userId}:`), 'permission_user_not_found');
+  if (!/\binstalled=true\b/.test(user.header)) throw new CommandError('permission_package_not_installed', 'The package is not installed for the requested Android user.');
+  const runtime = uniqueBlock(user.lines, line => line === 'runtime permissions:', 'runtime_permission_not_found');
+  const matches = runtime.lines.filter(line => line.trim().startsWith(`${permission}:`));
+  const match = matches.length === 1 && /^\s*[^:]+:\s+granted=(true|false),\s*flags=\[([^\]]*)\]\s*$/.exec(matches[0]);
+  if (!matches.length) throw new CommandError('runtime_permission_not_found', 'The requested permission has no runtime permission record for this package and user.');
+  if (!match) throw new CommandError('permission_state_unsupported', 'Android returned an unrecognized runtime permission record.');
+  const flags = match[2].trim() ? match[2].split('|').map(value => value.trim()) : [];
+  if (flags.some(value => !/^[A-Z][A-Z0-9_]*$/.test(value)) || new Set(flags).size !== flags.length) {
+    throw new CommandError('permission_state_unsupported', 'Android returned unrecognized permission flags.');
+  }
+  return { packageName, permission, userId, uid: userId * 100000 + Number(appId[0][1]), granted: match[1] === 'true', flags: flags.sort() };
+}
+
+async function readPermissionState(args, run = execute) {
+  requireTarget(args);
+  try {
+    let userId = args.userId;
+    if (userId === undefined) {
+      const current = (await androidCommand(args, ['shell', 'am', 'get-current-user'], run)).stdout.trim();
+      if (!/^\d+$/.test(current) || Number(current) > 2147483647) throw new CommandError('permission_user_unknown', 'Android current user could not be determined.');
+      userId = Number(current);
+    }
+    const dump = await androidCommand(args, ['shell', 'dumpsys', 'package', args.packageName], run);
+    return { ok: true, source: 'android-package-manager', serial: args.serial,
+      ...parsePermissionState(dump.stdout, { ...args, userId }), capturedAtMs: Date.now() };
+  } catch (error) {
+    if (error instanceof CommandError) throw error;
+    throw new CommandError('permission_query_failed', 'Android permission state could not be read.', { details: { cause: error.code || null } });
+  }
+}
+
+async function changePermission(args, action, run = execute) {
+  if (!['grant', 'revoke'].includes(action)) throw new TypeError('Unknown permission mutation');
+  const before = await readPermissionState(args, run);
+  const target = { ...args, userId: before.userId };
+  let failure = null;
+  let execution;
+  try { execution = await androidCommand(target, ['shell', 'pm', action, '--user', String(before.userId), args.packageName, args.permission], run, { mutation: true }); }
+  catch (error) { failure = error; }
+  if (failure?.settled === false) throw failure;
+  try { checkExecution(); }
+  catch (error) { throw Object.assign(error, executionFields(failure || execution)); }
+  let after; let queryError;
+  try { after = await readPermissionState(target, run); }
+  catch (error) { queryError = error.code || 'permission_query_failed'; }
+  const details = { action, before, after: after || null, queryError: queryError || null };
+  if (failure) {
+    const response = [failure.stderr, failure.stdout].filter(Boolean).join('\n');
+    const denied = /\bjava\.lang\.SecurityException:/.test(response);
+    const unchanged = after && after.uid === before.uid && after.granted === before.granted && JSON.stringify(after.flags) === JSON.stringify(before.flags);
+    const reason = response.split(/\r?\n/).find(line => line.includes('Exception:')) || response.trim().slice(0, 1024);
+    throw new CommandError(denied ? 'permission_change_denied' : 'permission_change_failed',
+      denied ? 'Android does not authorize this ADB identity to change runtime permissions.' : 'Android rejected or did not acknowledge the permission change.', {
+        details: { ...details, cause: failure.code || null, reason: reason.slice(0, 1024) || null }, dispatched: failure.code !== 'ENOENT',
+        ambiguous: failure.code !== 'ENOENT' && !(denied && unchanged),
+        ...executionFields(failure),
+      });
+  }
+  if (!after || after.uid !== before.uid || after.granted !== (action === 'grant')) {
+    throw new CommandError('permission_verification_failed', 'The permission change was submitted but its resulting state was not verified.', { details, ...executionFields(execution), dispatched: true, ambiguous: !after || after.uid !== before.uid });
+  }
+  return { ...after, action, before, verified: true, dispatched: true, ambiguous: false, ...executionFields(execution) };
+}
+
+function activityIdentity(value) {
+  const match = /ActivityRecord\{([^\s{}]+) u(\d+) ([^\s{}]+\/[^\s{}]+)\s/.exec(value);
+  if (!match) return null;
+  const [packageName, activity] = match[3].split('/');
+  // Android's flattened ComponentName may abbreviate the class with a leading dot.
+  const component = `${packageName}/${activity.startsWith('.') ? packageName + activity : activity}`;
+  return { token: match[1], userId: Number(match[2]), component, packageName };
+}
+
+// ActivityManager supplies requester identity even when Intent extras are redacted.
+// It does not expose the requested permission list here; the Agent must inspect
+// the actual dialog, and PackageManager independently verifies the named permission.
+function parsePermissionRequest(text) {
+  const lines = text.split(/\r?\n/);
+  const tops = lines.filter(line => /^\s*topResumedActivity=/.test(line)).map(activityIdentity);
+  if (tops.length !== 1 || !tops[0]) throw new CommandError('permission_request_unsupported', 'One top-resumed Android Activity could not be identified.');
+  const records = lines.flatMap((line, i) => /^\s*\* Hist\s+#\d+: ActivityRecord\{/.test(line) ? [{ ...activityIdentity(line), lines: block(lines, i) }] : []);
+  const requests = records.filter(record => record.lines.some(line => line.trim().startsWith('Intent {') && line.includes(`act=${REQUEST_PERMISSIONS} `)));
+  const current = records.filter(record => record.token === tops[0].token && record.component === tops[0].component && record.userId === tops[0].userId);
+  if (current.length !== 1) throw new CommandError('permission_request_unsupported', 'The top-resumed Activity has no unique detailed record.');
+  const result = { source: 'android-activity-manager', foreground: tops[0], activeRequestTokens: requests.map(record => record.token), request: null };
+  if (!requests.includes(current[0])) return result;
+  const origin = current[0].lines.map(line => /\blaunchedFromUid=(\d+) launchedFromPackage=([^\s]+).*\buserId=(\d+)\s*$/.exec(line)).filter(Boolean);
+  if (origin.length !== 1 || Number(origin[0][3]) !== tops[0].userId) throw new CommandError('permission_request_unsupported', 'The runtime permission requester is unavailable or ambiguous.');
+  result.request = { ...tops[0], action: REQUEST_PERMISSIONS, requesterPackage: origin[0][2], requesterUid: Number(origin[0][1]) };
+  return result;
+}
+
+async function readPermissionRequest(args, run = execute) {
+  try {
+    const dump = await androidCommand(args, ['shell', 'dumpsys', 'activity', 'activities'], run);
+    return { ...parsePermissionRequest(dump.stdout), capturedAtMs: Date.now() };
+  } catch (error) {
+    if (error instanceof CommandError) throw error;
+    throw new CommandError('permission_request_query_failed', 'Android runtime permission request could not be read.', { details: { cause: error.code || null } });
+  }
+}
+
+module.exports = { readPermissionState, changePermission, readPermissionRequest, parsePermissionState, parsePermissionRequest, androidCommand };

package/bin/android-uia-xml.js

@@ -0,0 +1,74 @@
+'use strict';
+
+// Legacy `uiautomator dump` serializes every accessibility node as `<node>`.
+// Appium's persistent UiAutomator2 server instead serializes the Android class
+// name as the XML element name (for example `<android.view.View>`). Keep one
+// lightweight scanner for both wire formats so summary, actions, compaction,
+// and persistence redaction cannot drift apart.
+const XML_TAG_PATTERN = /<\s*(\/?)\s*([A-Za-z_][A-Za-z0-9_.:$-]*)(?:\s+(?:[^"'<>]|"[^"]*"|'[^']*')*)?\s*\/?>/g;
+const XML_OPENING_TAG_PATTERN = /^<\s*([A-Za-z_][A-Za-z0-9_.:$-]*)(?:\s|\/?>)/;
+
+function visitAndroidUiHierarchyTags(value, visitor) {
+  const text = String(value || '');
+  const pattern = new RegExp(XML_TAG_PATTERN.source, XML_TAG_PATTERN.flags);
+  let insideHierarchy = false;
+  let match;
+  while ((match = pattern.exec(text)) !== null) {
+    const tag = match[0];
+    const closing = match[1] === '/';
+    const tagName = match[2];
+    const selfClosing = /\/\s*>$/.test(tag);
+    if (tagName.toLowerCase() === 'hierarchy') {
+      insideHierarchy = !closing && !selfClosing;
+      continue;
+    }
+    if (!insideHierarchy) continue;
+    if (visitor({
+      tag,
+      tagName,
+      closing,
+      selfClosing,
+      start: match.index,
+      end: pattern.lastIndex,
+    }) === false) return false;
+  }
+  return true;
+}
+
+function looksLikeAndroidUiHierarchyXml(value) {
+  const text = String(value || '').trimStart();
+  const withoutDeclaration = text.replace(/^<\?xml\s[^?]*\?>\s*/i, '');
+  if (!/^<hierarchy(?:\s|>)/i.test(withoutDeclaration)) return false;
+  let foundElement = false;
+  visitAndroidUiHierarchyTags(withoutDeclaration, ({ closing }) => {
+    if (closing) return;
+    foundElement = true;
+    return false;
+  });
+  return foundElement;
+}
+
+function replaceAndroidUiOpeningTags(value, transform) {
+  const text = String(value || '');
+  let output = '';
+  let cursor = 0;
+  visitAndroidUiHierarchyTags(text, ({ tag, tagName, closing, start, end }) => {
+    if (closing) return;
+    output += text.slice(cursor, start);
+    output += transform(tag, tagName);
+    cursor = end;
+  });
+  return cursor === 0 ? text : output + text.slice(cursor);
+}
+
+function isAndroidUiElementOpeningTag(value) {
+  const match = XML_OPENING_TAG_PATTERN.exec(String(value || ''));
+  return Boolean(match && match[1].toLowerCase() !== 'hierarchy');
+}
+
+module.exports = {
+  isAndroidUiElementOpeningTag,
+  looksLikeAndroidUiHierarchyXml,
+  replaceAndroidUiOpeningTags,
+  visitAndroidUiHierarchyTags,
+};

package/bin/artifact-paths.js

@@ -1,11 +1,15 @@
 const { execFileSync } = require('child_process');
 const fs = require('fs');
 const path = require('path');
+const { requestDirectory } = require('./shared-kernel/request-context');
 
 const artifactDirectoryName = 'ai_app_bridge_artifacts';
+const generatedArtifactRetention = 20;
+const generatedArtifactMaxAgeMs = 24 * 60 * 60 * 1000;
+const generatedArtifactMaxBytes = 64 * 1024 * 1024;
 
 function defaultArtifactDirectory(options = {}) {
-  const cwd = path.resolve(options.cwd || process.cwd());
+  const cwd = path.resolve(options.cwd || requestDirectory());
   const gitRoot = gitOutput(cwd, ['rev-parse', '--show-toplevel']);
   if (!gitRoot) {
     return path.join(cwd, 'build', artifactDirectoryName);
@@ -34,6 +38,104 @@ function defaultArtifactPath(prefix, extension, options = {}) {
   return path.join(directory, name);
 }
 
+async function pruneGeneratedArtifacts(options = {}) {
+  const keep = positiveIntegerOption(options.keep, generatedArtifactRetention);
+  const maxAgeMs = nonNegativeNumberOption(options.maxAgeMs, generatedArtifactMaxAgeMs);
+  const maxBytes = nonNegativeNumberOption(options.maxBytes, generatedArtifactMaxBytes);
+  const nowMs = finiteNumberOption(options.nowMs, Date.now());
+  const result = {
+    keep,
+    maxAgeMs,
+    maxBytes,
+    matched: 0,
+    deleted: 0,
+    deletedExpired: 0,
+    deletedForCount: 0,
+    deletedForBytes: 0,
+    bytesBefore: 0,
+    bytesAfter: 0,
+  };
+  const directory = path.resolve(options.directory || requestDirectory());
+  const prefix = sanitizeArtifactName(options.prefix || 'artifact');
+  const extension = sanitizeArtifactExtension(options.extension || 'bin');
+  const currentPath = options.currentPath ? path.resolve(options.currentPath) : '';
+  const pattern = new RegExp(`^${escapeRegExp(prefix)}-\\d{8}-\\d{6}-\\d{3}-\\d+-[a-z0-9]+\\.${escapeRegExp(extension)}$`);
+
+  let entries;
+  try {
+    entries = await fs.promises.readdir(directory, { withFileTypes: true });
+  } catch (error) {
+    return { ...result, error: firstErrorLine(error) };
+  }
+
+  const files = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !pattern.test(entry.name)) continue;
+    const filePath = path.join(directory, entry.name);
+    try {
+      const stat = await fs.promises.stat(filePath);
+      files.push({
+        name: entry.name,
+        path: path.resolve(filePath),
+        mtimeMs: stat.mtimeMs,
+        size: stat.size,
+      });
+    } catch (_) {
+      // Ignore files that disappear while pruning.
+    }
+  }
+
+  result.matched = files.length;
+  result.bytesBefore = files.reduce((total, file) => total + file.size, 0);
+  result.bytesAfter = result.bytesBefore;
+  files.sort((left, right) => (right.mtimeMs - left.mtimeMs) || right.name.localeCompare(left.name));
+
+  const keepSet = new Set();
+  let retainedBytes = 0;
+  const current = files.find((file) => file.path === currentPath);
+  if (current) {
+    keepSet.add(current.path);
+    retainedBytes += current.size;
+  }
+
+  const deletionReasons = new Map();
+  const expiresBeforeMs = nowMs - maxAgeMs;
+  for (const file of files) {
+    if (keepSet.has(file.path)) continue;
+    if (file.mtimeMs < expiresBeforeMs) {
+      deletionReasons.set(file.path, 'expired');
+      continue;
+    }
+    if (keepSet.size >= keep) {
+      deletionReasons.set(file.path, 'count');
+      continue;
+    }
+    if (retainedBytes + file.size > maxBytes) {
+      deletionReasons.set(file.path, 'bytes');
+      continue;
+    }
+    keepSet.add(file.path);
+    retainedBytes += file.size;
+  }
+
+  for (const file of files) {
+    const reason = deletionReasons.get(file.path);
+    if (!reason) continue;
+    try {
+      await fs.promises.rm(file.path, { force: true });
+      result.deleted += 1;
+      result.bytesAfter -= file.size;
+      if (reason === 'expired') result.deletedExpired += 1;
+      if (reason === 'count') result.deletedForCount += 1;
+      if (reason === 'bytes') result.deletedForBytes += 1;
+    } catch (_) {
+      // Pruning is best-effort and should not make screenshot capture fail.
+    }
+  }
+  result.overBudgetBytes = Math.max(0, result.bytesAfter - maxBytes);
+  return result;
+}
+
 function projectRoots(cwd, gitRoot) {
   const roots = [];
   const resolvedGitRoot = path.resolve(gitRoot);
@@ -156,11 +258,35 @@ function sanitizeArtifactExtension(value) {
   return sanitizeArtifactName(String(value || 'bin').replace(/^\.+/, '')) || 'bin';
 }
 
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function firstErrorLine(error) {
+  return String(error?.message || error || 'unknown error').split(/\r?\n/, 1)[0];
+}
+
+function positiveIntegerOption(value, fallback) {
+  const number = Number(value);
+  return Number.isInteger(number) && number > 0 ? number : fallback;
+}
+
+function nonNegativeNumberOption(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? number : fallback;
+}
+
+function finiteNumberOption(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
 module.exports = {
   artifactDirectoryCandidates,
   artifactTimestamp,
   defaultArtifactDirectory,
   defaultArtifactPath,
+  pruneGeneratedArtifacts,
   sanitizeArtifactExtension,
   sanitizeArtifactName,
 };

package/bin/bridge-forward.js

@@ -0,0 +1,56 @@
+'use strict';
+
+async function listForwards(ctx, adb) {
+  const { stdout } = await adb(ctx, ['forward', '--list']);
+  return stdout.trim().split(/\r?\n/).filter(Boolean).map((line) => {
+    const [serial, local, remote] = line.trim().split(/\s+/);
+    return { serial, local, remote };
+  });
+}
+
+function forwardMismatch(expected, actual) {
+  const error = new Error(`bridge forward mismatch: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+  error.aiAppBridgeForwardMismatch = true;
+  return error;
+}
+
+async function createBridgeForward(ctx, endpoint, adb) {
+  const serial = ctx.serial || (await adb(ctx, ['get-serialno'])).stdout.trim();
+  const forwards = await listForwards(ctx, adb);
+  const remote = `localabstract:${endpoint.socketName}`;
+  const existing = ctx.explicitPort
+    ? forwards.find((entry) => entry.local === `tcp:${ctx.port}`)
+    : forwards.find((entry) => entry.serial === serial && entry.remote === remote && /^tcp:\d+$/.test(entry.local));
+  if (existing) {
+    if (existing.serial !== serial || existing.remote !== remote) {
+      throw forwardMismatch({ serial, local: `tcp:${ctx.port}`, remote }, existing);
+    }
+    return { serial, hostPort: Number(existing.local.slice(4)), reused: true };
+  }
+
+  // ADB allocates the host port; the remote address is the discovered App runtime.
+  const { stdout } = await adb(ctx, ['forward', '--no-rebind', `tcp:${ctx.explicitPort ? ctx.port : 0}`, remote]);
+  const hostPort = ctx.explicitPort ? ctx.port : Number(stdout.trim());
+  if (!Number.isInteger(hostPort) || hostPort < 1 || hostPort > 65535) {
+    throw new Error(`ADB returned an invalid allocated host port: ${stdout.trim()}`);
+  }
+  return { serial, hostPort, reused: false };
+}
+
+async function verifyBridgeForward(ctx, connection, adb) {
+  const expected = { serial: connection.serial, local: `tcp:${connection.hostPort}`, remote: `localabstract:${connection.endpoint.socketName}` };
+  const actual = (await listForwards(ctx, adb)).find((entry) => entry.local === expected.local);
+  if (!actual || actual.serial !== expected.serial || actual.remote !== expected.remote) {
+    throw forwardMismatch(expected, actual || null);
+  }
+}
+
+async function removeBridgeForward(ctx, adb) {
+  const local = `tcp:${ctx.port}`;
+  const actual = (await listForwards(ctx, adb)).find(entry => entry.local === local);
+  if (!actual || actual.serial !== ctx.serial) throw forwardMismatch({ serial: ctx.serial, local }, actual || null);
+  await adb(ctx, ['forward', '--remove', local]);
+  return { ok: true, serial: ctx.serial, removed: local, remote: actual.remote };
+}
+
+module.exports = { createBridgeForward, verifyBridgeForward, removeBridgeForward };

package/bin/command-discovery.js

@@ -0,0 +1,86 @@
+'use strict';
+
+const { commandDefinitions, isolatedCommandDefinitions, commandByName, isolatedByName, commandSchema, commandContract } = require('./command-registry');
+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 = {
+  execution: 'intent for observed decisions; script for repeatable local code with progress, persisted results and assertions; runtime and device-ownership controls',
+  evidence: 'export and verify retained execution evidence',
+  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, 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, ios-tap/ios-input/ios-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',
+  advanced: 'uia-runtime maintenance, 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 = 'Discover domains, commands and argument schemas with capabilities, then run the selected command with its arguments.';
+function capabilityPayload(args = {}) {
+  if (!args || typeof args !== 'object' || Array.isArray(args)) return { ok: false, error: 'invalid_argument', field: 'arguments', dispatched: false, ambiguous: false };
+  const invalidKey = Object.keys(args).find(key => !['command', 'domain', 'includeOptions'].includes(key));
+  if (invalidKey) return { ok: false, error: 'unsupported_argument', field: invalidKey, dispatched: false, ambiguous: false };
+  for (const [key, type] of [['command', 'string'], ['domain', 'string'], ['includeOptions', 'boolean']]) {
+    if (Object.hasOwn(args, key) && typeof args[key] !== type) return { ok: false, error: 'invalid_argument', field: key, dispatched: false, ambiguous: false };
+  }
+  if (args.command && args.domain) return { ok: false, error: 'invalid_argument', field: 'domain', message: 'Use command or domain, not both.', dispatched: false, ambiguous: false };
+  const includeOptions = args.includeOptions === true;
+  const requestedCommand = args.command ? normalizeCommandName(args.command) : '';
+  if (requestedCommand) {
+    const definition = commandByName.get(requestedCommand) || isolatedByName.get(requestedCommand);
+    return {
+      ok: Boolean(definition),
+      command: requestedCommand,
+      ...(definition ? shapeCommandDefinition(definition, true) : { error: 'unknown_command' }),
+    };
+  }
+
+  const requestedDomain = args.domain ? String(args.domain) : '';
+  const domains = {};
+  if (requestedDomain && !Object.hasOwn(commandDomains, requestedDomain)) return { ok: false, error: 'unknown_domain', field: 'domain', dispatched: false, ambiguous: false };
+  for (const definition of [...isolatedCommandDefinitions, ...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: '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) {
+  const shaped = {
+    command: definition.command,
+    summary: definition.summary,
+    targetApp: Boolean(definition.targetApp),
+    ...commandContract(definition.command),
+    ...(includeOptions ? { options: Object.keys(commandSchema(definition.command).properties), inputSchema: commandSchema(definition.command) } : {}),
+    contractVersion: 'aab.command/v1',
+  };
+  if (definition.command === 'script') {
+    const { catalogPayload } = require('./script/script-catalog');
+    shaped.runtime = 'trusted-local-code';
+    shaped.warning = 'Script source is trusted-local-code, not an OS sandbox.';
+    shaped.catalog = catalogPayload();
+  }
+  return shaped;
+}
+
+
+function normalizeCommandName(value) { return typeof value === 'string' ? value : ''; }
+module.exports = { capabilities: capabilityPayload, commandDomains, supportedTargets, supportedTargetsText, commandDomainsText, discoveryText };

package/bin/command-errors.js

@@ -0,0 +1,60 @@
+'use strict';
+
+// `error` is a stable machine-readable code; `message` is for the caller.
+// Unknown dispatch state stays null. Only the rejecting/dispatching layer can
+// claim that an action was not sent.
+class CommandError extends Error {
+  constructor(code, message, { field, details, dispatched = false, ambiguous = false, settled, executionReceipt, executionReceipts, exitCode } = {}) {
+    super(message);
+    this.code = code;
+    this.field = field;
+    this.details = details;
+    this.dispatched = dispatched;
+    this.ambiguous = ambiguous;
+    for (const [name, value] of Object.entries({ settled, executionReceipt, executionReceipts, exitCode })) {
+      if (value !== undefined) this[name] = value;
+    }
+  }
+}
+
+function commandFailure(error, command) {
+  const known = error instanceof CommandError;
+  const code = typeof error?.code === 'string' && /^[a-z][a-z0-9_]*$/.test(error.code)
+    ? error.code : 'command_failed';
+  return {
+    ok: false,
+    error: code,
+    message: error?.message || String(error),
+    ...(command ? { command } : {}),
+    ...(error?.field !== undefined ? { field: error.field } : {}),
+    ...(error?.details !== undefined ? { details: error.details } : {}),
+    dispatched: typeof error?.dispatched === 'boolean' ? error.dispatched : null,
+    ambiguous: known ? error.ambiguous : error?.ambiguous !== false,
+    ...executionFields(error),
+    ...(error?._feedback ? { _feedback: error._feedback } : {}),
+  };
+}
+
+function executionFields(value) {
+  return Object.fromEntries(['settled', 'dispatched', 'ambiguous', 'executionReceipt', 'executionReceipts', 'exitCode']
+    .filter(name => value?.[name] !== undefined).map(name => [name, value[name]]));
+}
+
+function normalizeCommandResult(result, command) {
+  if (!result || typeof result !== 'object' || Buffer.isBuffer(result) || Array.isArray(result)) return result;
+  if (result.ok !== false && result.error == null) return result;
+  const original = typeof result.error === 'object' ? result.error?.code : result.error;
+  const code = typeof original === 'string' && /^[a-z][a-z0-9_]*$/.test(original)
+    ? original : 'command_failed';
+  return {
+    ...result,
+    ok: false,
+    error: code,
+    message: result.message || result.error?.message || (typeof original === 'string' ? original : 'Command failed without an error reason.'),
+    ...(command ? { command } : {}),
+    dispatched: typeof result.dispatched === 'boolean' ? result.dispatched : null,
+    ambiguous: typeof result.ambiguous === 'boolean' ? result.ambiguous : result.dispatched !== false,
+  };
+}
+
+module.exports = { CommandError, commandFailure, normalizeCommandResult, executionFields };