droid-mcp-shell-core/io.droidmcp.shell/ShellBackend

ShellBackend

Abstraction over a privileged shell-command pipeline.

Implementations:

ShizukuShellBackend (:droid-mcp-shizuku) — shell-UID execution via Shizuku.newProcess, no root needed.
RootShellBackend (:droid-mcp-root) — root-UID execution via a per-call libsu shell.

Tools in :droid-mcp-shell-core are parameterised over ShellBackend so the LLM-facing surface is identical across backends. Register one backend's tool set — the tool names are the same, so a second set replaces the first.

Inheritors

NoOpShellBackend

Properties

name

abstract val name: String

One-line description of what this backend is, surfaced in tool errors ("Shizuku", "Root (libsu)"). Helps the LLM disambiguate when one tool errors with "shell_unavailable" and the host registered multiple backends.

Functions

availabilityProblem

open fun availabilityProblem(): ShellException?

Why the backend can't run commands right now, or null when it can. Lets tools tell "not running / not checked" (ShellException.NotAvailable → shell_unavailable) apart from "access denied" (ShellException.PermissionDenied → shell_permission_denied). The default only knows isAvailable.

exec

abstract suspend fun exec(command: String, args: List<String> = emptyList()): ShellResult

Run command with args as a shell process. Returns stdout/stderr/exit. Implementations should NOT throw on non-zero exit codes — surface them via ShellResult.exitCode so tools can decide whether that's an error.

execBinary

open suspend fun execBinary(command: String, args: List<String> = emptyList()): ShellResult

Run command with args and return raw stdout bytes. Defaults to exec — backends whose exec is already binary-safe (Shizuku) don't need to override. Backends with a text-only output API (libsu) MUST override with a binary-safe path (e.g. temp-file roundtrip).

isAvailable

abstract fun isAvailable(): Boolean

True when the backend is currently reachable — Shizuku binder pingable with permission granted, or su available, depending on the impl. Tools call this for fast-fail before constructing a command.