Preface¶

DSH extends by packaging external capabilities as plugins. For developers needing to debug Android apps locally, a common pain point is how to expose ADB capabilities to the model securely: covering device discovery, app management, system services, UI hierarchy, input, file transfer, and logs, while avoiding the model freely concatenating commands in the host shell, and imposing limits on devices, timeouts, and output size.

adb-dsh-plugin registers the locally available Android Debug Bridge (ADB) as a DSH tool. It does not start an additional proxy service nor does it concatenate commands in the host shell; all ADB processes are started via Harness’s ctx.subprocess service and inherit cancellation and timeout signals from the tool invocation.

What is this¶

adb-dsh-plugin is a DSH plugin under the MIT license for controlling Android devices via ADB. The plugin name in package.json is adb-dsh-plugin, version 0.1.0. The repository address is:

https://github.com/mang0cola/adb_dsh_plugin

It targets DSH use cases where adb is already available locally, registering capabilities such as device info, app packages, system services, UI hierarchy, input, file transfer, and logs as callable tools for the model.

Core Capabilities¶

The verified tool capabilities are listed below:

adb_packages, adb_system_services, adb_service_dump, and adb_app_info are all read-only tools, independent of enableShell or enableAppManagement. adb_app_info returns structured fields suitable for direct model use by default; if specific Package Manager details are needed, pass includeRawDump: true. The raw output is still subject to maxOutputBytes limits and marked as truncated via the truncated flag.

Environment Requirements¶

Verified requirements:

• Node.js ^22.19.0 || >=24
• pnpm
• adb available in PATH

The README mentions that requirements are the same as the current DeepSeek Harness 0.1.0-rc.5.

Installation and Enablement¶

Local development, testing, and building¶

In the plugin directory, install dependencies, run tests, and build:

cd ~/Desktop/side_projects/adb_dsh_plugin
pnpm install
pnpm test
pnpm build

If a test device is connected and authorized, you can run local device functional tests:

pnpm test:device

This test covers device discovery, device info, UI hierarchy, screenshots, side-effect-free keycodes, structured app info, permissions and four major components, system services, logs, and a file push/pull roundtrip located at /data/local/tmp/adb_dsh_plugin_function_test.txt; temporary files on the host and device are automatically cleaned up after the test ends. Please run this only on devices where testing is allowed.

Source code overlay¶

Copy the development config template:

cd ~/Desktop/side_projects/adb_dsh_plugin
cp cordis.dev.example.yml cordis.dev.yml

After modifying the absolute paths in cordis.dev.yml, stop the existing pnpm dsh web and start from the Harness repository:

cd ~/Desktop/playground/deepseek-harness
pnpm dsh web --patch ~/Desktop/side_projects/adb_dsh_plugin/cordis.dev.yml

cordis.dev.yml is a local file containing local paths and personal permission policies, not included in Git. If the plugin directory is moved, the absolute paths inside need to be updated synchronously.

Install as web profile bundle¶

After building the plugin, you can install the local checkout to the web profile:

cd ~/Desktop/playground/deepseek-harness
pnpm dsh plugin --profile web add ~/Desktop/side_projects/adb_dsh_plugin
pnpm dsh web

dsh.bundle in package.json causes cordis.patch.yml to be automatically added to the profile’s bundle layer.

After updating plugin code, rebuild is required:

pnpm build

Then restart dsh. Changes to the bundle list also require a restart.

Uninstall¶

cd ~/Desktop/playground/deepseek-harness
pnpm dsh plugin --profile web remove adb-dsh-plugin

Typical Usage¶

After connecting and authorizing the device, you can try the following prompts sequentially in the Web UI.

Call adb_devices to list devices, then read the system, screen, and battery info of the unique online device.

This prompt will first list the device, then read the device info.

Call adb_packages to list third-party apps, returning package names, version codes, install sources, and APK paths, without modifying the device.

Call adb_app_info to view com.example.app: summarize requested permissions and their authorization status, and list activity, service, broadcast receiver, and content provider components separately.

First use adb_system_services to find the package service, then use adb_service_dump to view its current status, read-only only.

Use adb_ui_hierarchy to view the current interface, find the clickable node with text "Settings" and tell me its bounds, do not click yet.

Image models can also use:

Call adb_screenshot to view the current device screen and describe the interface, do not execute any clicks.

Screenshots are only executed when the model declares support for image input and Harness has mounted the attachment service; otherwise, the tool will suggest using adb_ui_hierarchy.

Configuration and Security¶

By adding config to the plugin row in the overlay, you can override default values:

- insert:
    - id: adb-tools
      name: '/absolute/path/to/adb_dsh_plugin/src/index.ts'
      config:
        adbPath: adb
        defaultSerial: emulator-5554
        allowedSerials:
          - emulator-5554
        commandTimeoutMs: 30000
        transferTimeoutMs: 180000
        maxOutputBytes: 1048576
        maxScreenshotBytes: 16777216
        processGraceMs: 1000
        enableShell: false
        enableDeviceControl: true
        enableFileTransfer: true
        enableAppManagement: true
        enableDestructiveActions: false
        enableScreenshots: true
        enableUiHierarchy: true
        restrictHostPathsToWorkspace: true

The configuration above sets the ADB path, device whitelist, timeouts, output limits, and tool switches in the overlay plugin row.

Key restrictions are as follows:

• When serial is not passed, the plugin uses defaultSerial or the unique online and allowed device sequentially; when multiple online devices are connected, the model must explicitly pass serial.
• allowedSerials: [] means allow all ADB-visible devices; production environments are recommended to set allowedSerials and only enable tools that are strictly necessary.
• adb_shell is not registered by default and requires explicit enablement; arbitrary shell and cleanup/uninstall apps are disabled by default.
• clear_data and uninstall of adb_app are only executed when enableDestructiveActions: true.
• restrictHostPathsToWorkspace: true resolves real paths and rejects accessing host files outside the session workspace via absolute paths, .., or symbolic links.
• When the output limit is exceeded, only the bounded results are kept and explicitly marked as truncated.
• UI hierarchy prioritizes the accessibility tree; when the device’s uiautomator returns an empty tree, it falls back to the native View hierarchy of the visible windows via Android WindowManager. This fallback path cannot guarantee complete semantics inside Jetpack Compose/WebView; use screenshots in conjunction when necessary.

Applicable Scenarios and Notes¶

adb-dsh-plugin is suitable for local DSH debugging, Android device status checks, app and component queries, UI hierarchy checks, logcat retrieval, file push/pull, and controlled environment clicks, swipes, safe ASCII text input, and keyevents.

Please note:

• ADB authorization itself grants the host high-level control over the device.
• Harness’s host file sandbox does not restrict device-side clicks, app management, or adb shell side effects.
• The plugin starts ADB processes via Harness’s ctx.subprocess service and inherits cancellation and timeout signals from the tool invocation; it runs these subprocesses with the local permissions available to the current DSH process.
• It is recommended to check the source code, dependencies, and MIT license before installation.
• Verified materials do not provide star count or directory page URL; the installation method provided here is checking out locally and adding it to the web profile.
• GitHub Repository:

https://github.com/mang0cola/adb_dsh_plugin