mobile-debug-mcp 0.34.0 → 0.36.0

package/scripts/agent-plugin.mjs

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict'
-import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { copyFileSync, cpSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import path from 'node:path'
 
@@ -43,22 +43,53 @@ const cursorManifest = {
     },
   },
 }
+const antigravityManifest = {
+  $schema: 'https://antigravity.google/schemas/v1/plugin.json',
+  ...sharedMetadata,
+  displayName: extensions['com.openai'].interface.displayName,
+  logo: 'assets/mobile-debug-tools.svg',
+  suggestedPrompts: extensions['com.openai'].interface.defaultPrompt,
+}
+const antigravityMcp = {
+  mcpServers: Object.fromEntries(Object.entries(codexMcp.mcpServers).map(([name, server]) => {
+    const { type: _transport, ...settings } = server
+    return [name, settings]
+  })),
+}
+const mcpConfigs = [
+  ['.mcp.json', codexMcp],
+  ['mcp_config.json', antigravityMcp],
+]
 const manifests = [
   ['.codex-plugin/plugin.json', codexManifest],
   ['.claude-plugin/plugin.json', claudeManifest],
   ['.cursor-plugin/plugin.json', cursorManifest],
+  ['.antigravity-plugin/plugin.json', antigravityManifest],
 ]
 
+const cursorFiles = [
+  ['.cursor-plugin/plugin.json', `${JSON.stringify(cursorManifest, null, 2)}\n`],
+  ['skills/mobile-debug-mcp/SKILL.md', readFileSync(packagedSkill)],
+  ['LICENSE', readFileSync(sourceLicense)],
+  ['README.md', '# Mobile Debug Tools for Cursor\n\nGenerated by `npm run sync:agent-plugin`; edit the canonical plugin source.\n\nCopy the contents of this directory into `~/.cursor/plugins/local/mobile-debug-tools`,\nthen run Developer: Reload Window and check Customize for the skill and MCP server.\nDo not copy the portable parent plugin: its `${PLUGIN_DATA}` variable is not expanded by Cursor.\n\nSetup and support: https://github.com/clivejefferies/mobile-debug-tools\n'],
+]
 if (process.argv[2] === '--sync') {
   copyFileSync(sourceLicense, packagedLicense)
-  writeFileSync(path.join(pluginRoot, '.mcp.json'), `${JSON.stringify(codexMcp, null, 2)}\n`)
+  for (const [relativePath, contents] of cursorFiles) {
+    const target = path.join(pluginRoot, 'cursor', relativePath)
+    mkdirSync(path.dirname(target), { recursive: true })
+    writeFileSync(target, contents)
+  }
+  for (const [relativePath, config] of mcpConfigs) {
+    writeFileSync(path.join(pluginRoot, relativePath), `${JSON.stringify(config, null, 2)}\n`)
+  }
   for (const [relativePath, manifest] of manifests) {
     const manifestPath = path.join(pluginRoot, relativePath)
     mkdirSync(path.dirname(manifestPath), { recursive: true })
     writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`)
   }
 }
-else if (process.argv[2] !== '--check') throw new Error('Use --sync or --check')
+else if (!['--check', '--export-antigravity'].includes(process.argv[2])) throw new Error('Use --sync, --check or --export-antigravity <new-directory>')
 
 assert.equal(plugin.$schema, 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json')
 assert.equal(plugin.name, 'mobile-debug-tools')
@@ -73,7 +104,10 @@ assert.equal(server.command, 'npx')
 assert.deepEqual(server.args, ['--yes', `${packageInfo.name}@${packageInfo.version}`, 'server'])
 assert.equal(server.cwd, '${PLUGIN_DATA}', 'npx must run outside the same-named source checkout')
 assert.deepEqual(readFileSync(packagedLicense), readFileSync(sourceLicense), 'packaged license must match its source')
-assert.deepEqual(JSON.parse(readFileSync(path.join(pluginRoot, '.mcp.json'), 'utf8')), codexMcp, 'Codex MCP configuration must match the portable plugin')
+for (const [relativePath, config] of mcpConfigs) {
+  assert.deepEqual(JSON.parse(readFileSync(path.join(pluginRoot, relativePath), 'utf8')), config, `${relativePath} must match the portable MCP configuration`)
+}
+assert.ok(readFileSync(path.join(pluginRoot, antigravityManifest.logo)).length > 0, 'Antigravity logo must be bundled')
 for (const [relativePath, expectedManifest] of manifests) {
   assert.deepEqual(
     JSON.parse(readFileSync(path.join(pluginRoot, relativePath), 'utf8')),
@@ -81,6 +115,9 @@ for (const [relativePath, expectedManifest] of manifests) {
     `${relativePath} must match the portable plugin`,
   )
 }
+for (const [relativePath, contents] of cursorFiles) {
+  assert.deepEqual(readFileSync(path.join(pluginRoot, 'cursor', relativePath)), Buffer.from(contents), `Cursor native ${relativePath} must match its source`)
+}
 for (const marketplacePath of [
   '.agents/plugins/marketplace.json',
   '.claude-plugin/marketplace.json',
@@ -90,9 +127,22 @@ for (const marketplacePath of [
   assert.equal(marketplace.name, plugin.name, `${marketplacePath} name must match the plugin`)
   assert.equal(marketplace.plugins.length, 1, `${marketplacePath} must expose one plugin`)
   assert.equal(marketplace.plugins[0].name, plugin.name, `${marketplacePath} plugin name must match`)
-  assert.equal(marketplace.plugins[0].source?.path ?? marketplace.plugins[0].source, './agent-plugin', `${marketplacePath} source must point to the plugin`)
+  assert.equal(marketplace.plugins[0].source?.path ?? marketplace.plugins[0].source, marketplacePath.startsWith('.cursor-plugin') ? './agent-plugin/cursor' : './agent-plugin', `${marketplacePath} source must point to the plugin`)
 }
 const skillName = readFileSync(packagedSkill, 'utf8').match(/^---\r?\nname: ([a-z0-9-]+)\r?\n/)?.[1]
 assert.equal(skillName, path.basename(path.dirname(packagedSkill)), 'packaged skill directory must match its frontmatter name')
 
 console.log('Agent plugin package is in sync')
+
+if (process.argv[2] === '--export-antigravity') {
+  assert.ok(process.argv[3], 'Supply a new output directory for the Antigravity export')
+  const target = path.resolve(process.argv[3])
+  // Refuse existing directories rather than overwrite source or stale package files.
+  mkdirSync(target)
+  writeFileSync(path.join(target, 'plugin.json'), `${JSON.stringify(antigravityManifest, null, 2)}\n`)
+  writeFileSync(path.join(target, 'mcp_config.json'), `${JSON.stringify(antigravityMcp, null, 2)}\n`)
+  copyFileSync(path.join(pluginRoot, '.antigravity-plugin/README.md'), path.join(target, 'README.md'))
+  copyFileSync(packagedLicense, path.join(target, 'LICENSE'))
+  for (const directory of ['skills', 'assets']) cpSync(path.join(pluginRoot, directory), path.join(target, directory), { recursive: true, filter: file => path.basename(file) !== '.DS_Store' && !path.basename(file).startsWith('._') })
+  console.log(`Antigravity package exported to ${target}`)
+}

package/scripts/architecture-graph.mjs

@@ -0,0 +1,69 @@
+import ts from 'typescript'
+import path from 'node:path'
+import { isBuiltin } from 'node:module'
+import { extractGraph } from 'archunit'
+
+// ArchUnitTS 2.5.4 extracts static imports. Add re-exports, import types and
+// literal dynamic imports using the same project's TypeScript resolution.
+export async function architectureGraph(configFile = 'tsconfig.json') {
+  const configPath = path.resolve(configFile)
+  const root = path.dirname(configPath)
+  const config = ts.readConfigFile(configPath, ts.sys.readFile)
+  if (config.error) throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
+  const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, root)
+  if (parsed.errors.length) throw new Error(ts.formatDiagnosticsWithColorAndContext(parsed.errors, {
+    getCanonicalFileName: file => file, getCurrentDirectory: () => root, getNewLine: () => '\n'
+  }))
+  const graph = await extractGraph(configPath, { clearCache: true })
+  const local = file => path.relative(root, file).split(path.sep).join('/')
+  const edges = new Map(graph.map(edge => [JSON.stringify([edge.source, edge.target]), edge]))
+  const recorded = new Set()
+  for (const file of parsed.fileNames) {
+    const code = ts.sys.readFile(file)
+    if (code === undefined) throw new Error(`Cannot read architecture source: ${file}`)
+    const ast = ts.createSourceFile(file, code, ts.ScriptTarget.Latest, true)
+    const source = local(file)
+    function add(specifier, typeOnly = false) {
+      const module = specifier.text
+      const resolved = ts.resolveModuleName(module, file, parsed.options, ts.sys).resolvedModule
+      if (!resolved && !isBuiltin(module)) throw new Error(`Unresolved dependency: ${source} -> ${module}`)
+      const external = !resolved || !!resolved.isExternalLibraryImport
+      const target = resolved ? local(resolved.resolvedFileName) : module.replace(/^(?!node:)/, 'node:')
+      const key = JSON.stringify([source, target])
+      const kind = typeOnly ? 'type' : 'value'
+      const previous = edges.get(key)
+      // Replace the initial static classification, then union repeated dependencies.
+      if (previous && recorded.has(key)) {
+        previous.importKinds = [...new Set([...previous.importKinds, kind])]
+      } else edges.set(key, { source, target, external, importKinds: [kind] })
+      recorded.add(key)
+    }
+    function visit(node) {
+      if (ts.isImportDeclaration(node)) {
+        const clause = node.importClause
+        const bindings = clause?.namedBindings
+        const typeOnly = clause?.isTypeOnly || (!clause?.name && bindings && ts.isNamedImports(bindings) &&
+          bindings.elements.length > 0 && bindings.elements.every(element => element.isTypeOnly))
+        add(node.moduleSpecifier, !!typeOnly)
+      } else if (ts.isExportDeclaration(node) && node.moduleSpecifier) {
+        const bindings = node.exportClause
+        const typeOnly = node.isTypeOnly || (bindings && ts.isNamedExports(bindings) &&
+          bindings.elements.length > 0 && bindings.elements.every(element => element.isTypeOnly))
+        add(node.moduleSpecifier, !!typeOnly)
+      } else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+        if (!node.moduleReference.expression) throw new Error(`Missing import target in ${source}`)
+        add(node.moduleReference.expression, node.isTypeOnly)
+      } else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+        add(node.argument.literal, true)
+      } else if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(node.expression) && node.expression.text === 'require'))) {
+        const argument = node.arguments[0]
+        if (!argument || !ts.isStringLiteralLike(argument)) throw new Error(`Nonliteral dependency in ${source}; architecture cannot resolve it`)
+        add(argument)
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(ast)
+  }
+  return [...edges.values()]
+}

package/scripts/check-architecture.mjs

@@ -0,0 +1,47 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { gatherDependOnFileViolations, gatherCycleViolations, projectEdges, perEdge, perInternalEdge } from 'archunit'
+import { architectureGraph } from './architecture-graph.mjs'
+
+export const architectureRules = [
+  {
+    name: 'Shared contracts stay independent of application implementations',
+    source: /^src\/contracts\//,
+    forbidden: /^src\/(?!contracts\/)/
+  },
+  {
+    name: 'Capabilities and shared modules cannot import the MCP server layer',
+    source: /^src\/(?!server(?:\/|-core\.ts$|\.ts$))/,
+    forbidden: /^src\/server(?:\/|-core\.ts$|\.ts$)/
+  },
+  {
+    name: 'Pure interaction calculations cannot import native I/O or service facades',
+    source: /^src\/interact\/(?:adjustment\/(?:adjustment-plan|control-values|control-geometry|slider-labels)|targeting\/(?:candidate-scoring|candidate-ancestor|candidate-result|nearby-control|element-helpers|resolved-elements|tap-target|target-scope)|waits\/(?:ui-change-helpers|ui-wait-condition)|assertions\/state-comparison)\.ts$/,
+    forbidden: /^(?:node:(?:child_process|fs|net|http|https)(?:\/|$)|src\/(?:utils\/(?:android|ios)\/|(?:interact|observe|manage)\/(?:index|android|ios)\.ts$))/
+  }
+]
+const filter = regExp => ({ regExp, options: { target: 'path', matching: 'partial' } })
+
+export function checkArchitecture(graph) {
+  const projected = projectEdges(graph, perEdge())
+  const results = architectureRules.map(rule => ({
+    name: rule.name,
+    violations: gatherDependOnFileViolations(projected, [filter(rule.source)], [filter(rule.forbidden)], true)
+  }))
+  const runtime = graph.filter(edge => edge.importKinds.includes('value') || !edge.importKinds.includes('type'))
+  results.push({ name: 'Production runtime dependencies must be cycle-free',
+    violations: gatherCycleViolations(projectEdges(runtime, perInternalEdge()), []) })
+  return results
+}
+
+async function main() {
+  const graph = await architectureGraph(process.argv[2])
+  const results = checkArchitecture(graph)
+  const failures = results.filter(result => result.violations.length)
+  for (const result of failures) console.error(`${result.name}\n${JSON.stringify(result.violations, null, 2)}`)
+  if (failures.length) process.exitCode = 1
+  else console.log(`Architecture: PASS (${results.length} rules; ${graph.filter(edge => edge.source !== edge.target).length} dependency edges, including type, dynamic and re-export dependencies)`)
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(error => { console.error(error); process.exitCode = 1 })
+}

package/scripts/code-quality-baseline.json

@@ -0,0 +1 @@
+[]

package/scripts/code-quality.mjs

@@ -0,0 +1,161 @@
+import { ESLint } from 'eslint'
+import { createHash } from 'node:crypto'
+import ts from 'typescript'
+import { parse } from '@typescript-eslint/parser'
+import { readFile, readdir } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+export const limits = Object.freeze({ 'max-lines': 500, 'class-lines': 300,
+  'max-lines-per-function': 80, complexity: 20, 'max-depth': 4, 'explicit-any': 0 })
+const functionKinds = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression'])
+const measuredRules = new Set(['max-lines', 'max-lines-per-function', 'complexity', 'max-depth'])
+
+function children(node) {
+  return Object.entries(node).filter(([key]) => !['parent', 'tokens', 'comments', 'loc', 'range'].includes(key))
+    .flatMap(([, value]) => Array.isArray(value) ? value : [value])
+    .filter(value => value && typeof value === 'object' && typeof value.type === 'string')
+}
+function label(node, parent) {
+  if (node.id?.name) return node.id.name
+  if (parent?.type === 'MethodDefinition' || parent?.type === 'Property' || parent?.type === 'PropertyDefinition') {
+    const name = parent.key.name ?? parent.key.value ?? '[computed]'
+    return ['get', 'set'].includes(parent.kind) ? `${parent.kind}:${name}` : name
+  }
+  if (parent?.type === 'VariableDeclarator') return parent.id.name ?? '[destructured]'
+  if (parent?.type === 'CallExpression' || parent?.type === 'NewExpression') {
+    const callee = parent.callee.name ?? parent.callee.property?.name ?? '[call]'
+    return `${callee}:argument${parent.arguments.indexOf(node)}`
+  }
+  return `[${node.type}]`
+}
+function syntax(code) {
+  const ast = parse(code, { loc: true, range: true, comment: true, sourceType: 'module', ecmaVersion: 'latest' })
+  const symbols = [], anys = [], imports = []
+  function visit(node, parent, scope = '<module>') {
+    if (['TSInterfaceDeclaration', 'TSTypeAliasDeclaration'].includes(node.type)) scope = `${scope}/${node.id.name}`
+    if (functionKinds.has(node.type) || node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
+      const anonymous = !node.id?.name && !['MethodDefinition', 'Property', 'PropertyDefinition', 'VariableDeclarator'].includes(parent?.type)
+      const suffix = anonymous ? ':' + createHash('sha256').update(code.slice(...node.range).replace(/\s/g, '')).digest('hex').slice(0, 12) : ''
+      scope = `${scope}/${label(node, parent)}${suffix}`
+      symbols.push({ node, identity: scope })
+    }
+    if (node.type === 'TSAnyKeyword') anys.push({ node, identity: scope })
+    if (['ImportDeclaration', 'ExportNamedDeclaration', 'ExportAllDeclaration', 'ImportExpression', 'TSImportType'].includes(node.type) && node.source) {
+      imports.push({ node, value: node.source.value })
+    }
+    if (node.type === 'CallExpression' && node.callee.name === 'require' && node.arguments[0]?.type === 'Literal') {
+      imports.push({ node, value: node.arguments[0].value })
+    }
+    for (const child of children(node)) visit(child, node, scope)
+  }
+  visit(ast, null)
+  return { ast, symbols, anys, imports }
+}
+function lineCount(code, comments, start = 0, end = code.length) {
+  const chars = code.split('')
+  for (const c of comments) for (let i = c.range[0]; i < c.range[1]; i++) if (chars[i] !== '\n') chars[i] = ' '
+  return chars.slice(start, end).join('').split('\n').filter(line => line.trim()).length
+}
+const eslint = new ESLint({ overrideConfig: [{ files: ['**/*.ts'], linterOptions: { noInlineConfig: true }, rules: {
+  'max-lines': ['error', { max: limits['max-lines'], skipBlankLines: true, skipComments: true }],
+  'max-lines-per-function': ['error', { max: limits['max-lines-per-function'], skipBlankLines: true, skipComments: true }],
+  complexity: ['error', { max: limits.complexity, variant: 'classic' }], 'max-depth': ['error', limits['max-depth']]
+} }] })
+
+export async function measure(file, code) {
+  if (file.endsWith('.java')) {
+    const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, code)
+    const comments = []
+    for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+      if ([ts.SyntaxKind.SingleLineCommentTrivia, ts.SyntaxKind.MultiLineCommentTrivia].includes(token)) {
+        comments.push({ range: [scanner.getTokenPos(), scanner.getTextPos()] })
+      }
+    }
+    const value = lineCount(code, comments)
+    return value > limits['max-lines'] ? [{ file, rule: 'max-lines', symbol: '<module>', value, line: 1 }] : []
+  }
+  const { ast, symbols, anys, imports } = syntax(code)
+  const findings = []
+  const add = (rule, symbol, value, line) => findings.push({ file, rule, symbol, value, line })
+  const identities = new Set()
+  for (const { node, identity } of symbols) {
+    if (identities.has(identity) && !identity.includes(':argument')) add('duplicate-symbol', identity, 1, node.loc.start.line)
+    identities.add(identity)
+    if (node.type.startsWith('Class')) {
+      const value = lineCount(code, ast.comments, ...node.range)
+      if (value > limits['class-lines']) add('class-lines', identity, value, node.loc.start.line)
+    }
+  }
+  const anyCounts = new Map()
+  for (const { node, identity } of anys) {
+    const current = anyCounts.get(identity) ?? { value: 0, line: node.loc.start.line }
+    current.value++; anyCounts.set(identity, current)
+  }
+  for (const [identity, { value, line }] of anyCounts) add('explicit-any', identity, value, line)
+  const [result] = await eslint.lintText(code, { filePath: file })
+  for (const m of result.messages.filter(m => measuredRules.has(m.ruleId))) {
+    const value = Number(/(?:has too many lines \(|complexity of |nested too deeply \()([\d]+)/.exec(m.message)?.[1])
+    if (!Number.isFinite(value)) throw new Error(`Cannot read ${m.ruleId} metric: ${m.message}`)
+    const candidates = symbols.filter(({ node }) => m.line >= node.loc.start.line && m.line <= node.loc.end.line)
+      .sort((a, b) => a.node.range[1] - a.node.range[0] - (b.node.range[1] - b.node.range[0]))
+    const symbol = m.ruleId === 'max-lines' ? '<module>' : candidates[0]?.identity ?? '<module>'
+    add(m.ruleId, symbol, value, m.line)
+  }
+  for (const comment of ast.comments) {
+    if (/(?:eslint-(?:disable|enable)|^\s*eslint\s)/.test(comment.value) &&
+      (!/eslint-(?:disable|enable)(?:-next-line|-line)?\s+(?!-)[\w@]/.test(comment.value) ||
+      /max-lines|complexity|max-depth|no-explicit-any|code-quality/.test(comment.value))) {
+      add('inline-suppression', '<module>', 1, comment.loc.start.line)
+    }
+  }
+  if (file.startsWith('src/interact/') || file.startsWith('src/runtime/')) {
+    for (const { node, value } of imports) if (typeof value === 'string' && /(?:^|\/)server(?:\/|-core)/.test(value)) {
+      add('import-boundary', '<module>', 1, node.loc.start.line)
+    }
+  }
+  // Multiple nested blocks can report depth in the same function; retain its maximum.
+  return [...findings.reduce((out, f) => {
+    const key = `${f.rule}:${f.symbol}`
+    if (!out.has(key) || out.get(key).value < f.value) out.set(key, f)
+    return out
+  }, new Map()).values()]
+}
+export function compare(findings, baseline) {
+  const errors = [], entries = new Map()
+  const key = f => JSON.stringify([f.file, f.rule, f.symbol])
+  for (const b of baseline) {
+    if (!b.file || !b.rule || !b.symbol || !b.reason || !Number.isInteger(b.value) || b.value < 1) {
+      errors.push('Invalid baseline entry'); continue
+    }
+    if (entries.has(key(b))) errors.push(`Duplicate baseline entry: ${key(b)}`)
+    entries.set(key(b), b)
+  }
+  for (const f of findings) {
+    const b = entries.get(key(f))
+    if (['duplicate-symbol', 'inline-suppression', 'import-boundary'].includes(f.rule) || !b || f.value > b.value) {
+      errors.push(`${f.file}:${f.line}: ${f.rule} ${f.symbol} = ${f.value}; allowed ${b?.value ?? limits[f.rule] ?? 0}`)
+    } else if (f.value < b.value) errors.push(`Lower baseline ceiling for ${key(f)}: ${b.value} -> ${f.value}`)
+    entries.delete(key(f))
+  }
+  for (const b of entries.values()) errors.push(`Remove obsolete baseline entry: ${key(b)}`)
+  return errors
+}
+export async function collect(root = 'src') {
+  const out = []
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const file = path.posix.join(root, entry.name)
+    if (entry.isDirectory()) out.push(...await collect(file))
+    else if (/\.(ts|java)$/.test(file)) out.push(...await measure(file, await readFile(file, 'utf8')))
+  }
+  return out
+}
+async function main() {
+  const baseline = JSON.parse(await readFile(new URL('./code-quality-baseline.json', import.meta.url), 'utf8'))
+  const errors = compare(await collect(), baseline)
+  if (errors.length) { console.error(errors.join('\n')); process.exitCode = 1 }
+  else console.log('Code quality: PASS (size, complexity, nesting, types, boundaries and legacy ceilings)')
+}
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(error => { console.error(error); process.exitCode = 1 })
+}

package/src/contracts/execution-controls.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod'
+
+export const verificationModes = ['none', 'light', 'full'] as const
+export const responseModes = ['compact', 'debug'] as const
+export const verificationModeSchema = z.enum(verificationModes)
+export const responseModeSchema = z.enum(responseModes)
+export type VerificationMode = z.infer<typeof verificationModeSchema>
+export type ResponseMode = z.infer<typeof responseModeSchema>
+
+export const verificationModeJson = { type: 'string', enum: [...verificationModes] }
+export const responseModeJson = { type: 'string', enum: [...responseModes] }
+
+export function interactionControls(args: Record<string, unknown>) {
+  const verificationMode = ((typeof args.verificationMode === 'string' ? args.verificationMode : undefined) as VerificationMode | undefined) ?? 'full'
+  const responseMode = ((typeof args.responseMode === 'string' ? args.responseMode : undefined) as ResponseMode | undefined) ?? 'debug'
+  if (!verificationModes.includes(verificationMode) || !responseModes.includes(responseMode)) throw new Error('INVALID_ARGUMENT')
+  for (const key of ['verificationMode', 'responseMode']) if (args[key] !== undefined && typeof args[key] !== 'string') throw new Error('INVALID_ARGUMENT')
+  for (const key of ['actionTimeoutMs', 'verificationTimeoutMs']) if (args[key] !== undefined && (typeof args[key] !== 'number' || !Number.isInteger(args[key]))) throw new Error('INVALID_ARGUMENT')
+  const actionTimeoutMs = (typeof args.actionTimeoutMs === 'number' && Number.isFinite(args.actionTimeoutMs) ? args.actionTimeoutMs : undefined)
+  const verificationTimeoutMs = (typeof args.verificationTimeoutMs === 'number' && Number.isFinite(args.verificationTimeoutMs) ? args.verificationTimeoutMs : undefined)
+  return { verificationMode, responseMode,
+    actionTimeoutMs: actionTimeoutMs === undefined ? undefined : Math.max(100, Math.min(30000, actionTimeoutMs)),
+    verificationTimeoutMs: verificationTimeoutMs === undefined ? 3000 : Math.max(100, Math.min(60000, verificationTimeoutMs)) }
+
+}
+

package/src/contracts/selector.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+
+export type UiSelector = {
+  text?: string
+  resource_id?: string
+  accessibility_id?: string
+  contains?: boolean
+}
+
+export const selectorSchema = z.object({
+  text: z.string().min(1).optional(), resource_id: z.string().min(1).optional(),
+  accessibility_id: z.string().min(1).optional(), contains: z.boolean().optional()
+}).strict().refine(value => !!(value.text || value.resource_id || value.accessibility_id), 'Selector requires a target')
+
+export const selectorJson = { type: 'object', additionalProperties: false, properties: {
+  text: { type: 'string', minLength: 1 }, resource_id: { type: 'string', minLength: 1 }, accessibility_id: { type: 'string', minLength: 1 }, contains: { type: 'boolean' }
+}, anyOf: ['text', 'resource_id', 'accessibility_id'].map(key => ({ required: [key] })) }

package/src/contracts/target.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+import { selectorSchema as selector, selectorJson } from './selector.js'
+
+export interface DeviceTarget { platform?: 'android' | 'ios'; deviceId?: string }
+export type ScrollSelector = { text?: string; resourceId?: string; contentDesc?: string; className?: string }
+const pollIntervalMs = z.number().int().min(50).max(1000).optional()
+export const waitForSchema = z.object({
+  condition: z.enum(['exists', 'visible', 'clickable']).optional(),
+  timeoutMs: z.number().int().min(100).max(10000).optional(), pollIntervalMs,
+  match: z.object({ index: z.number().int().nonnegative().optional() }).strict().optional()
+}).strict()
+export const targetFields = { selector: selector.optional(), elementId: z.string().min(1).optional() }
+export const exactlyOneTarget = (value: { selector?: unknown, elementId?: string }) => Number(!!value.selector) + Number(!!value.elementId) === 1
+export const tapElementControlsSchema = z.object({
+  elementId: z.string().min(1).optional(), selector: selector.optional(), waitFor: waitForSchema.optional()
+}).strict().refine(value => Number(!!value.elementId) + Number(!!value.selector) === 1 && (!value.elementId || !value.waitFor))
+
+export const targetJson = { selector: selectorJson, elementId: { type: 'string', minLength: 1 } }
+export const oneTargetJson = [{ required: ['selector'], not: { required: ['elementId'] } }, { required: ['elementId'], not: { required: ['selector'] } }]

package/src/contracts/ui.ts

@@ -0,0 +1,94 @@
+export interface UIElementState {
+  checked?: boolean | null;
+  selected?: boolean | string | { id: string; label?: string } | null;
+  focused?: boolean | null;
+  expanded?: boolean | null;
+  enabled?: boolean | null;
+  text_value?: string | null;
+  value?: number | string | null;
+  raw_value?: number | string | null;
+  value_range?: {
+    min: number;
+    max: number;
+    step?: number | null;
+  } | null;
+  step?: number | null;
+}
+
+export interface SelectorConfidence {
+  score: number;
+  reason: string;
+}
+
+export interface UIResolutionSelector {
+  value: string | null;
+  confidence: SelectorConfidence | null;
+}
+
+export interface UIElementSemanticMetadata {
+  is_clickable: boolean;
+  is_container: boolean;
+  semantic_role?: 'slider' | 'stepper' | 'dropdown' | 'segmented_control' | 'custom_adjustable' | 'composite_control' | null;
+  supported_actions?: string[] | null;
+  adjustable?: boolean | null;
+  state_shape?: 'continuous' | 'discrete' | 'semantic' | null;
+}
+
+export interface LoadingState {
+  active: boolean;
+  signal: string;
+  source: string;
+}
+
+export interface SnapshotDelta {
+  previous_snapshot_revision: number | null;
+  added_elements: number;
+  removed_elements: number;
+  mutated_elements: number;
+  total_elements: number;
+}
+
+export interface StateDelta {
+  base_snapshot_revision: number | null;
+  snapshot_revision: number;
+  added: UIElement[];
+  removed: Array<{ stable_id?: string; resourceId?: string; contentDescription?: string; text?: string; index: number }>;
+  changed: UIElement[];
+  truncated: boolean;
+  omitted_changes?: number;
+}
+
+export interface UIElement {
+  text: string | null;
+  contentDescription: string | null;
+  type: string;
+  clickable: boolean;
+  enabled: boolean;
+  visible: boolean;
+  bounds: [number, number, number, number];
+  resourceId: string | null;
+  parentId?: number;
+  children?: number[];
+  center?: [number, number];
+  depth?: number;
+  state?: UIElementState | null;
+  stable_id?: string | null;
+  role?: string | null;
+  test_tag?: string | null;
+  selector?: UIResolutionSelector | null;
+  semantic?: UIElementSemanticMetadata | null;
+}
+
+export interface ReadinessSummary {
+  state: 'loading' | 'transitioning' | 'settled' | 'unknown' | 'unresponsive' | 'debugger_paused';
+  scope: 'device_ui';
+  basis: 'observed' | 'heuristic' | 'insufficient';
+  captured_at_ms: number | null;
+  sample_count: number;
+  stable_for_ms: number;
+  snapshot_session_id: string | null;
+  snapshot_revision: number | null;
+  evidence: Array<{ code: string; source: string; captured_at_ms: number | null; snapshot_revision: number | null }>;
+  limitations: string[];
+  capabilities: { loading: boolean; transitioning: boolean; settled: boolean; unresponsive: boolean; debugger_paused: boolean };
+}

package/src/debugger/android.ts

@@ -3,7 +3,7 @@ import { execFile } from 'node:child_process'
 import { promisify } from 'node:util'
 import { DebuggerError, debuggerRemaining, debuggerSignal, nativeError } from './worker.js'
 const exec = promisify(execFile)
-export interface DebugTarget { app_id: string; pid: number; process_name: string; start_identity: string; uid: number }
+export interface DebugTarget { app_id: string; pid: number; process_name: string; start_identity: string; uid: number | null; executable_path?: string }
 export interface DebugNative {
   candidates(device: string, app: string): Promise<DebugTarget[]>
   identity(device: string, target: DebugTarget): Promise<DebugTarget>
@@ -34,7 +34,8 @@ export class AndroidDebugNative implements DebugNative {
     // `adb jdwp` is a subscription, not a one-shot command. Bound the sample.
     let jdwpOutput: string
     try { jdwpOutput = (await exec(resolveAdbCmd(), ['-s', device, 'jdwp'], { timeout: debuggerRemaining(500), signal: debuggerSignal(), maxBuffer: 1024 * 1024 })).stdout }
-    catch (e: any) {
+    catch (error: unknown) {
+      const e = error as { killed?: boolean; stderr?: string; stdout?: string }
       if (debuggerSignal()?.aborted) throw new DebuggerError('DEBUGGER_CANCELLED')
       debuggerRemaining(1)
       if (!e.killed || e.stderr?.trim()) throw nativeError(e, 'DEVICE_UNAVAILABLE')

package/src/debugger/diagnostics.ts

@@ -0,0 +1,43 @@
+/** Only catalog values cross the debugger error boundary. Never inspect exception text. */
+export const stages = ['prerequisite', 'compilation', 'worker_start', 'ipc', 'target_resolution', 'forwarding', 'attach', 'command', 'transport', 'cleanup', 'unknown'] as const
+export const reasons = ['unavailable', 'unsupported', 'spawn_failed', 'process_exited', 'invalid_message', 'message_limit', 'write_failed', 'connection_refused', 'transport_lost', 'timeout', 'cancelled', 'operation_failed', 'unknown'] as const
+export type DiagnosticStage = typeof stages[number]
+export type DiagnosticReason = typeof reasons[number]
+export interface DebuggerDiagnostic { stage: DiagnosticStage; reason: DiagnosticReason; recovery: string }
+const recovery: Record<DiagnosticStage, string> = {
+  prerequisite: 'Check JDK 17+ availability, including java, javac and jdk.jdi.',
+  compilation: 'Check the JDK compiler and worker source/cache availability.',
+  worker_start: 'Check Java worker launch availability. Inspect session state and cleanup before attaching again.',
+  ipc: 'Inspect session state and cleanup. Detach before attempting a fresh attach.',
+  target_resolution: 'Check the explicit device and running debuggable app/process.',
+  forwarding: 'Check the explicit device and debugger forwarding availability.',
+  attach: 'Check the running debuggable target and whether another debugger is attached. Inspect cleanup before a fresh attach.',
+  command: 'Inspect debugger session state and cleanup before another state-changing command.',
+  transport: 'Inspect session state and cleanup. Detach before attempting a fresh attach; execution state may be unknown.',
+  cleanup: 'Retry detach_debugger and inspect cleanup.remaining_resources. Do not kill the app or ADB server.',
+  unknown: 'Inspect debugger session state and cleanup; the failure cause is unknown.'
+}
+export function diagnostic(stage: DiagnosticStage, reason: DiagnosticReason): DebuggerDiagnostic {
+  const guidance = reason === 'timeout' || reason === 'cancelled'
+    ? 'Execution may be uncertain. Inspect session state and cleanup before another state-changing command.' : recovery[stage]
+  return { stage, reason, recovery: guidance }
+}
+export function parseDiagnostic(value: unknown): DebuggerDiagnostic {
+  if (!value || typeof value !== 'object') throw new Error('INVALID_WORKER_DIAGNOSTIC')
+  const { stage, reason } = value as Record<string, unknown>
+  if (!stages.includes(stage as DiagnosticStage) || !reasons.includes(reason as DiagnosticReason)) throw new Error('INVALID_WORKER_DIAGNOSTIC')
+  return diagnostic(stage as DiagnosticStage, reason as DiagnosticReason)
+}
+export class DebuggerError extends Error {
+  constructor(public code: string, public diagnostic?: DebuggerDiagnostic) { super(code) }
+}
+const validationCodes = new Set(['INVALID_ARGUMENT', 'DEBUGGER_BUSY', 'DEBUGGER_NOT_FOUND', 'DEBUGGER_PAUSED', 'DEBUGGER_NOT_PAUSED', 'DEBUGGER_STALE_REFERENCE'])
+export function classify(error: unknown, stage: DiagnosticStage, fallback: string, reason: DiagnosticReason = 'unknown'): DebuggerError {
+  const existing = error instanceof DebuggerError ? error : new DebuggerError(fallback)
+  if (existing.diagnostic || validationCodes.has(existing.code)) return existing
+  const knownReason = existing.code === 'DEBUGGER_TIMEOUT' ? 'timeout' : existing.code === 'DEBUGGER_CANCELLED' ? 'cancelled' : reason
+  return new DebuggerError(existing.code, diagnostic(stage, knownReason))
+}
+export async function atStage<T>(stage: DiagnosticStage, fallback: string, operation: () => Promise<T>): Promise<T> {
+  try { return await operation() } catch (error) { throw classify(error, stage, fallback) }
+}

package/src/debugger/guard.ts

@@ -1,6 +1,11 @@
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { DebuggerError } from './worker.js'
-let pauseProvider: (device: string) => any = () => null
+interface PauseEvidence {
+  debug_session_id: string
+  captured_at_ms: number
+  target: unknown
+}
+let pauseProvider: (device: string, platform?: string) => PauseEvidence | null = () => null
 export function registerDebuggerPauseProvider(provider: typeof pauseProvider) { pauseProvider = provider }
 const context = new AsyncLocalStorage<{ platform: string; device: string; dispatched: boolean }>()
 export function withDebuggerGuard<T>(platform: string, device: string, operation: () => Promise<T>) {
@@ -9,13 +14,13 @@ export function withDebuggerGuard<T>(platform: string, device: string, operation
 // Synchronous checks and native submission share a JS turn with pause updates.
 export function checkDebuggerGuard(dispatch = false) {
   const current = context.getStore()
-  if (!current || current.platform !== 'android') return
-  if (pauseProvider(current.device)) throw new DebuggerError('DEBUGGER_PAUSED')
+  if (!current) return
+  if (pauseProvider(current.device, current.platform)) throw new DebuggerError('DEBUGGER_PAUSED')
   if (dispatch) current.dispatched = true
 }
 export function guardDispatched() { return context.getStore()?.dispatched ?? false }
-export function pausedReadiness(device: string) {
-  const paused = pauseProvider(device)
+export function pausedReadiness(device: string, platform = 'android') {
+  const paused = pauseProvider(device, platform)
   if (!paused) return null
   return { state: 'debugger_paused' as const, scope: 'device_ui' as const, basis: 'observed' as const,
     captured_at_ms: paused.captured_at_ms, sample_count: 0, stable_for_ms: 0, snapshot_session_id: null, snapshot_revision: null,