From 415b93f94327f66028ad91a2ba10d73599910cfe Mon Sep 17 00:00:00 2001 From: Kurt Himebauch <136133082+xXJSONDeruloXx@users.noreply.github.com> Date: Wed, 7 Oct 2026 23:50:58 -0400 Subject: [PATCH] feat: agent bridge wayland and gamescope coverage (#406) * feat: run a guest agent in every session for commands, focus and the Steam client's DevTools * feat: give the agent bridge game, input, UI and experiment commands behind a Setup toggle * feat: droiddeckctl commands for the new bridge, a scenario runner and contract tests * feat: run cleanup steps after every scenario run so a failure cannot leak into the next * feat: restart a session that died between scenario runs with start --reuse * fix: give droiddeckctl stop its own, longer wait for the session's logs * fix: harden debugging tools access and output --- .../com/droiddeck/launcher/MainActivity.kt | 11 +- .../com/droiddeck/launcher/SessionActivity.kt | 2 + .../droiddeck/launcher/agent/AgentAccess.kt | 48 ++ .../launcher/agent/AgentBridgeProvider.kt | 146 +++- .../com/droiddeck/launcher/agent/AgentEnv.kt | 222 ++++++ .../droiddeck/launcher/agent/AgentGuest.kt | 128 ++++ .../droiddeck/launcher/agent/AgentInput.kt | 221 ++++++ .../launcher/agent/AgentStartActivity.kt | 11 + .../com/droiddeck/launcher/agent/AgentUi.kt | 157 ++++ .../droiddeck/launcher/core/HostProcess.kt | 4 +- .../launcher/session/SessionFiles.kt | 1 + .../launcher/session/SessionService.kt | 10 +- .../launcher/session/SessionState.kt | 3 + .../droiddeck/launcher/ui/FrontEndGames.kt | 3 +- .../com/droiddeck/launcher/ui/FrontEndRail.kt | 2 + .../droiddeck/launcher/ui/FrontEndScreen.kt | 3 + .../droiddeck/launcher/ui/FrontEndSetup.kt | 1 + .../droiddeck/launcher/ui/SessionOverlay.kt | 10 +- .../droiddeck/launcher/ui/SettingsWidgets.kt | 6 +- .../com/droiddeck/launcher/ui/SteamHome.kt | 3 +- .../com/droiddeck/launcher/ui/TestTags.kt | 14 + app/src/main/res/values-es/strings.xml | 1 + app/src/main/res/values-fr/strings.xml | 1 + app/src/main/res/values-ja/strings.xml | 1 + app/src/main/res/values-ko/strings.xml | 1 + app/src/main/res/values-ru/strings.xml | 1 + app/src/main/res/values-zh-rCN/strings.xml | 1 + app/src/main/res/values-zh-rHK/strings.xml | 1 + app/src/main/res/values-zh-rTW/strings.xml | 1 + app/src/main/res/values/strings.xml | 1 + .../launcher/agent/AgentSecurityTest.kt | 266 +++++++ docs/agent-control.md | 202 ++++- tools/droiddeck-scenario | 245 +++++++ tools/droiddeckctl | 566 ++++++++++++--- .../overlay/usr/local/bin/droiddeck-agent | 687 ++++++++++++++++++ .../overlay/usr/local/bin/droiddeck-session | 13 + tools/linuxfs/preload/net.c | 87 ++- tools/scenarios/skyrim-launcher-focus.json | 83 +++ tools/scenarios/steam-game-focus.json | 70 ++ tools/tests/test_cdp_guard.py | 118 +++ tools/tests/test_droiddeck_agent.py | 250 +++++++ tools/tests/test_droiddeckctl.py | 353 +++++++++ 42 files changed, 3787 insertions(+), 168 deletions(-) create mode 100644 app/src/main/java/com/droiddeck/launcher/agent/AgentAccess.kt create mode 100644 app/src/main/java/com/droiddeck/launcher/agent/AgentEnv.kt create mode 100644 app/src/main/java/com/droiddeck/launcher/agent/AgentGuest.kt create mode 100644 app/src/main/java/com/droiddeck/launcher/agent/AgentInput.kt create mode 100644 app/src/main/java/com/droiddeck/launcher/agent/AgentUi.kt create mode 100644 app/src/main/java/com/droiddeck/launcher/ui/TestTags.kt create mode 100644 app/src/test/java/com/droiddeck/launcher/agent/AgentSecurityTest.kt create mode 100755 tools/droiddeck-scenario create mode 100755 tools/linuxfs/overlay/usr/local/bin/droiddeck-agent create mode 100644 tools/scenarios/skyrim-launcher-focus.json create mode 100644 tools/scenarios/steam-game-focus.json create mode 100644 tools/tests/test_cdp_guard.py create mode 100644 tools/tests/test_droiddeck_agent.py create mode 100644 tools/tests/test_droiddeckctl.py diff --git a/app/src/main/java/com/droiddeck/launcher/MainActivity.kt b/app/src/main/java/com/droiddeck/launcher/MainActivity.kt index 90a3a5d5f3..b8f7bcc62c 100644 --- a/app/src/main/java/com/droiddeck/launcher/MainActivity.kt +++ b/app/src/main/java/com/droiddeck/launcher/MainActivity.kt @@ -35,6 +35,7 @@ import com.droiddeck.launcher.runtime.LinuxRuntimeInstaller import com.droiddeck.launcher.runtime.DeckyManager import com.droiddeck.launcher.session.SessionService import com.droiddeck.launcher.ui.PackageRow +import com.droiddeck.launcher.ui.exposeTestTags import com.droiddeck.launcher.session.OfflineMode import com.droiddeck.launcher.session.ProtonExtras import com.droiddeck.launcher.session.ComponentsManager @@ -355,6 +356,7 @@ class MainActivity : ComponentActivity() { private var emulatorList by mutableStateOf>(emptyList()) private var runningLabel by mutableStateOf(null) private var logsEnabled by mutableStateOf(true) + private var agentCommands by mutableStateOf(false) private var showRoms by mutableStateOf(false) private var homeAppSelected by mutableStateOf(false) private var homeScreenEnabled by mutableStateOf(false) @@ -526,7 +528,7 @@ class MainActivity : ComponentActivity() { updates.start() setContent { DroidDeckTheme(theme, appScale = appScale) { - com.droiddeck.launcher.ui.FocusGlideHost(androidx.compose.ui.Modifier.fillMaxSize()) { + com.droiddeck.launcher.ui.FocusGlideHost(androidx.compose.ui.Modifier.fillMaxSize().exposeTestTags()) { val sm = settingsMode val page: (@Composable () -> Unit)? = when { sm != null -> { { ModeSettingsHost(sm) } } @@ -546,7 +548,7 @@ class MainActivity : ComponentActivity() { busy = busy, stage = stage, percent = percent, desktopInstalled = desktopInstalled, offlineAccount = offlineAccount, offline = offline, - frameGenLabel = frameGenLabel, romsDir = romsDir, logsEnabled = logsEnabled, + frameGenLabel = frameGenLabel, romsDir = romsDir, logsEnabled = logsEnabled, agentCommands = agentCommands, steamGames = steamGames, emulators = emulatorList, running = runningLabel, frameGen = FrameGen.mode(this), lossless = lossless, @@ -658,6 +660,10 @@ class MainActivity : ComponentActivity() { SessionPrefs.setLogsEnabled(this, !SessionPrefs.logsEnabled(this)) logsEnabled = SessionPrefs.logsEnabled(this) }, + onAgentCommands = { + com.droiddeck.launcher.agent.AgentAccess.setCommandsEnabled(this, !com.droiddeck.launcher.agent.AgentAccess.commandsEnabled(this)) + agentCommands = com.droiddeck.launcher.agent.AgentAccess.commandsEnabled(this) + }, onShareLogs = { SessionLogShare.prepare(this, { SessionLogShare.latest(this) }) { zip -> if (zip == null) android.widget.Toast.makeText(this, R.string.main_no_logs_yet, android.widget.Toast.LENGTH_LONG).show() @@ -1492,6 +1498,7 @@ class MainActivity : ComponentActivity() { frameGenLabel = FrameGen.label(this) romsDir = SessionPrefs.romsDir(this).takeIf { it.isNotEmpty() } logsEnabled = SessionPrefs.logsEnabled(this) + agentCommands = com.droiddeck.launcher.agent.AgentAccess.commandsEnabled(this) runningLabel = if (SessionState.running) when (SessionState.mode) { SessionService.MODE_DESKTOP -> getString(R.string.rail_desktop) SessionService.MODE_RUN -> Library.nameForProgram(SessionState.program) diff --git a/app/src/main/java/com/droiddeck/launcher/SessionActivity.kt b/app/src/main/java/com/droiddeck/launcher/SessionActivity.kt index 364bef141b..5ad2b641a2 100644 --- a/app/src/main/java/com/droiddeck/launcher/SessionActivity.kt +++ b/app/src/main/java/com/droiddeck/launcher/SessionActivity.kt @@ -362,6 +362,7 @@ class SessionActivity : ComponentActivity(), SurfaceHolder.Callback { val bridge = PadBridge(File(LinuxRuntime.sessionRoot(this), "dev/input")) padBridge = bridge + SessionState.padBridge = bridge padMotion = com.droiddeck.launcher.input.PadMotion(this) { @Suppress("DEPRECATION") (if (Build.VERSION.SDK_INT >= 30) display else windowManager.defaultDisplay)?.rotation ?: android.view.Surface.ROTATION_0 @@ -2052,6 +2053,7 @@ class SessionActivity : ComponentActivity(), SurfaceHolder.Callback { closeSecondScreen(reset = false) if (::hud.isInitialized) hud.stop() padBridge?.stop() + if (SessionState.padBridge === padBridge) SessionState.padBridge = null padMotion?.stop() if (SessionState.deckPadListener === deckPadListener) SessionState.deckPadListener = null if (SessionState.endListener === endListener) SessionState.endListener = null diff --git a/app/src/main/java/com/droiddeck/launcher/agent/AgentAccess.kt b/app/src/main/java/com/droiddeck/launcher/agent/AgentAccess.kt new file mode 100644 index 0000000000..e43ba8669c --- /dev/null +++ b/app/src/main/java/com/droiddeck/launcher/agent/AgentAccess.kt @@ -0,0 +1,48 @@ +package com.droiddeck.launcher.agent + +import android.content.Context + +/** + * Who may run code through the agent bridge. Reading state, starting and stopping sessions, + * launching and quitting games and sending input only need the shell (the provider's DUMP + * permission). Running commands in the guest, evaluating JavaScript in the Steam client, session + * environment, binary overrides and preference writes reach inside the app's sandbox - the guest + * holds the Steam login - which the shell of a stock device otherwise cannot. They require + * Setup > Session > Debugging tools to be on, in every build. The bridge itself cannot turn it on. + */ +object AgentAccess { + const val MAX_REQUEST_CHARS = 256 * 1024 + private const val PREFS = "agent" + private const val KEY_COMMANDS = "commands" + + /** The preferences file the bridge must never write: set-pref refuses it. */ + const val PROTECTED_PREFS = PREFS + + fun commandsAllowed(context: Context): Boolean = + prefs(context).getBoolean(KEY_COMMANDS, false) + + /** The Setup toggle's own state. */ + fun commandsEnabled(context: Context): Boolean = prefs(context).getBoolean(KEY_COMMANDS, false) + + fun setCommandsEnabled(context: Context, enabled: Boolean) { + prefs(context).edit().putBoolean(KEY_COMMANDS, enabled).apply() + if (!enabled) runCatching { AgentEnv.revoke(context) } + .onFailure { android.util.Log.w("AgentAccess", "Could not finish clearing debugging experiments") } + } + + fun requireCommands(context: Context) { + if (!commandsAllowed(context)) throw AgentException( + "AGENT_COMMANDS_DISABLED", + "Debugging tools are off: turn on Setup > Session > Debugging tools on the device", + ) + } + + fun requireStart(context: Context, request: org.json.JSONObject) { + if (request.optString("mode") == "run") requireCommands(context) + } + + private fun prefs(context: Context) = context.getSharedPreferences(PREFS, Context.MODE_PRIVATE) +} + +/** A refusal with a stable code, answered as {"ok": false, "error": {code, message}}. */ +class AgentException(val code: String, message: String) : RuntimeException(message) diff --git a/app/src/main/java/com/droiddeck/launcher/agent/AgentBridgeProvider.kt b/app/src/main/java/com/droiddeck/launcher/agent/AgentBridgeProvider.kt index 4e8b066eb8..80648e8875 100644 --- a/app/src/main/java/com/droiddeck/launcher/agent/AgentBridgeProvider.kt +++ b/app/src/main/java/com/droiddeck/launcher/agent/AgentBridgeProvider.kt @@ -10,13 +10,14 @@ import android.net.Uri import android.os.Binder import android.os.Bundle import android.os.Process +import android.util.Base64 import com.droiddeck.launcher.BuildConfig +import com.droiddeck.launcher.frontend.GameLaunchLink import com.droiddeck.launcher.runtime.LinuxRuntime import com.droiddeck.launcher.runtime.LinuxRuntimeInstaller import com.droiddeck.launcher.session.SessionArtifacts import com.droiddeck.launcher.session.SessionEvents import com.droiddeck.launcher.session.SessionPhase -import com.droiddeck.launcher.session.SessionPaths import com.droiddeck.launcher.session.SessionService import com.droiddeck.launcher.session.SessionState import org.json.JSONArray @@ -25,7 +26,14 @@ import java.io.File import java.util.concurrent.CountDownLatch import java.util.concurrent.TimeUnit -/** A shell-only control surface, installed only by debug builds. */ +/** + * The shell's control surface (docs/agent-control.md), in every build: the provider and its start + * Activity need android.permission.DUMP, held by the shell and privileged or explicitly granted callers. Commands that + * reach into the app's sandbox are further gated by [AgentAccess]. + * + * A method's request is JSON, base64-encoded in the "request" extra; every answer is JSON in the + * "json" key of the returned Bundle, {"ok": true, ...} or {"ok": false, "error": {code, message}}. + */ class AgentBridgeProvider : ContentProvider() { override fun onCreate(): Boolean { val appContext = context?.applicationContext ?: return false @@ -48,17 +56,53 @@ class AgentBridgeProvider : ContentProvider() { } val response = try { - when (method) { - "state" -> state(context).put("ok", true) - "start" -> error("USE_DROIDDECKCTL", "Start sessions with tools/droiddeckctl so Android launches a visible Activity") - "stop" -> stop(context) - "resume" -> resume(context) - else -> error("UNKNOWN_COMMAND", "Unknown agent command '$method'") + val request = decode(extras?.getString(EXTRA_REQUEST)) + // Binder identity is the shell's; everything below acts as the app. + val token = Binder.clearCallingIdentity() + try { + dispatch(context, method, request) + } finally { + Binder.restoreCallingIdentity(token) } + } catch (e: AgentException) { + error(e.code, e.message ?: e.code) } catch (e: Exception) { error("COMMAND_FAILED", e.message ?: e.javaClass.simpleName) } - return Bundle().apply { putString(RESULT_JSON, response.toString()) } + val json = response.toString().let { + if (it.length <= 384 * 1024) it else error("RESPONSE_TOO_LARGE", "Reduce the command output or select fewer fields").toString() + } + return Bundle().apply { putString(RESULT_JSON, json) } + } + + private fun dispatch(context: Context, method: String, request: JSONObject): JSONObject = when (method) { + "state" -> state(context).put("ok", true) + "start" -> error("USE_DROIDDECKCTL", "Start sessions with tools/droiddeckctl so Android launches a visible Activity") + "stop" -> stop(context) + "resume" -> resume(context) + "launch" -> launch(context, request) + "focus" -> guest(context, JSONObject().put("kind", "focus"), 15_000) + "quit" -> guest(context, JSONObject().put("kind", "quit").put("appId", request.opt("appId")) + .put("timeout", request.optDouble("timeout", 15.0)), timeoutMs(request, 15.0, 30_000)) + "input" -> AgentInput.handle(request) + "ui" -> AgentUi.handle(request) + "guest" -> { + AgentAccess.requireCommands(context) + guest(context, JSONObject(request.toString()).put("kind", "exec"), timeoutMs(request, 30.0, 10_000)) + } + "cdp" -> { + AgentAccess.requireCommands(context) + guest(context, JSONObject(request.toString()).put("kind", "cdp"), timeoutMs(request, 15.0, 5_000)) + } + "env" -> env(context, request) + "override" -> { + AgentAccess.requireCommands(context) + AgentEnv.override(context, request.optString("name")).put("ok", true).put("command", "override") + } + "prefs" -> prefs(context, request) + "access" -> JSONObject().put("ok", true).put("commands", AgentAccess.commandsAllowed(context)) + .put("debugBuild", BuildConfig.DEBUG).put("inbox", AgentEnv.inbox(context).absolutePath) + else -> error("UNKNOWN_COMMAND", "Unknown agent command '$method'") } private fun state(context: Context): JSONObject { @@ -91,13 +135,31 @@ class AgentBridgeProvider : ContentProvider() { .put("status", SessionState.failureStatus ?: JSONObject.NULL) session.put("failure", failure) + // gamescope's focus as last published by the guest agent, without the window lists + // (the focus command returns those, fresh). + val focus = AgentGuest.focus(context)?.let { snap -> + JSONObject() + .put("focusedApp", snap.opt("focusedApp") ?: JSONObject.NULL) + .put("focusedWindow", snap.opt("focusedWindow") ?: JSONObject.NULL) + .put("focusableApps", snap.optJSONArray("focusableApps") ?: JSONArray()) + .put("baselayerAppIds", snap.optJSONArray("baselayerAppIds") ?: JSONArray()) + .put("seq", snap.optInt("seq")) + .put("t", snap.optLong("t")) + } + session.put("focus", focus ?: JSONObject.NULL) + + val hello = AgentGuest.hello(context) return JSONObject() - .put("schema", 1) + .put("schema", SCHEMA) .put("build", BuildConfig.BUILD_LABEL) .put("appVersion", context.packageManager.getPackageInfo(context.packageName, 0).versionName) .put("runtime", JSONObject() .put("installed", LinuxRuntime.isInstalled(context)) .put("version", runtimeVersion ?: JSONObject.NULL)) + .put("agent", JSONObject() + .put("guest", hello != null) + .put("guestFocus", hello?.optBoolean("focus") ?: false) + .put("commands", AgentAccess.commandsAllowed(context))) .put("session", session) } @@ -131,6 +193,67 @@ class AgentBridgeProvider : ContentProvider() { return JSONObject().put("ok", true).put("command", "resume") } + private fun launch(context: Context, request: JSONObject): JSONObject { + val appId = request.optString("appId") + if (!GameLaunchLink.validId(appId)) throw AgentException("INVALID_APP_ID", "appId must be a decimal Steam app id") + if (!SessionState.running || SessionState.mode != SessionService.MODE_STEAM) { + throw AgentException("NO_STEAM_SESSION", "Games launch inside a running Steam session") + } + if (!SessionService.launchGame(context, appId)) throw AgentException("LAUNCH_REJECTED", "The session did not accept the launch") + SessionEvents.record("agent.launch_requested", mapOf("appId" to appId)) + return JSONObject().put("ok", true).put("command", "launch").put("appId", appId) + } + + private fun env(context: Context, request: JSONObject): JSONObject { + AgentAccess.requireCommands(context) + val result = when (val op = request.optString("op", "list")) { + "list" -> AgentEnv.list(context) + "set" -> { + val lines = request.optJSONArray("lines") ?: JSONArray() + AgentEnv.set(context, List(lines.length()) { lines.optString(it) }, request.optBoolean("persistent")) + } + "clear" -> AgentEnv.clear(context, request.optString("scope", "next")) + else -> throw AgentException("INVALID_REQUEST", "env op '$op' is not list, set or clear") + } + return result.put("ok", true).put("command", "env") + } + + private fun prefs(context: Context, request: JSONObject): JSONObject { + AgentAccess.requireCommands(context) + val file = request.optString("file") + val result = when (val op = request.optString("op", "get")) { + "get" -> AgentPrefs.get(context, file) + "set" -> AgentPrefs.set(context, file, request.optString("key"), request.optString("type", "string"), + if (request.isNull("value")) null else request.optString("value")) + else -> throw AgentException("INVALID_REQUEST", "prefs op '$op' is not get or set") + } + return result.put("ok", true).put("command", "prefs") + } + + /** A guest agent request; its own answer already carries ok or error. */ + private fun guest(context: Context, request: JSONObject, timeoutMs: Long): JSONObject = + AgentGuest.call(context, request, timeoutMs) + + /** The guest's own timeout plus slack for the round trip. */ + private fun timeoutMs(request: JSONObject, defaultSeconds: Double, slackMs: Long): Long { + val seconds = if (request.has("timeout")) request.opt("timeout")?.toString()?.toDoubleOrNull() + ?: throw AgentException("INVALID_REQUEST", "timeout must be a number") else defaultSeconds + if (!seconds.isFinite() || seconds <= 0 || seconds > 600) { + throw AgentException("INVALID_REQUEST", "timeout must be a positive number no greater than 600 seconds") + } + return (seconds * 1000).toLong() + slackMs + } + + private fun decode(encoded: String?): JSONObject { + if (encoded.isNullOrBlank()) return JSONObject() + if (encoded.length > AgentAccess.MAX_REQUEST_CHARS) throw AgentException("INVALID_REQUEST", "The encoded request exceeds 256 KiB") + return try { + JSONObject(String(Base64.decode(encoded, Base64.DEFAULT), Charsets.UTF_8)) + } catch (e: Exception) { + throw AgentException("INVALID_REQUEST", "The request extra is not base64 JSON") + } + } + private fun error(code: String, message: String) = JSONObject() .put("ok", false) .put("error", JSONObject().put("code", code).put("message", message)) @@ -143,6 +266,9 @@ class AgentBridgeProvider : ContentProvider() { companion object { const val RESULT_JSON = "json" + const val EXTRA_REQUEST = "request" + /** 2 added agent and session.focus; everything in 1 is unchanged. */ + const val SCHEMA = 2 private val recoveryComplete = CountDownLatch(1) fun awaitRecovery() { diff --git a/app/src/main/java/com/droiddeck/launcher/agent/AgentEnv.kt b/app/src/main/java/com/droiddeck/launcher/agent/AgentEnv.kt new file mode 100644 index 0000000000..83ea0ccd11 --- /dev/null +++ b/app/src/main/java/com/droiddeck/launcher/agent/AgentEnv.kt @@ -0,0 +1,222 @@ +package com.droiddeck.launcher.agent + +import android.content.Context +import android.util.Log +import com.droiddeck.launcher.runtime.LinuxRuntime +import org.json.JSONArray +import org.json.JSONObject +import java.io.File +import java.nio.file.Files +import java.nio.file.LinkOption.NOFOLLOW_LINKS +import java.nio.file.StandardOpenOption.READ + +/** + * Experiment switches an agent sets without touching Download/droiddeck-env or rebuilding the apk: + * + * - environment lines (KEY=VALUE) for the session, applied after the user's own droiddeck-env, so + * they win. "next" lines are taken by the next session that starts and dropped when it ends; + * "persistent" ones stay until cleared. + * - binary overrides: a file pushed to the app's external files (agent-inbox/) is installed + * as /opt/droiddeck-agent/bin/ in the rootfs and put first on the next session's PATH - + * a gamescope build under test, say. Removed when that session ends. + * + * Kept in the app's own files (agent-env.json), never in a place the shell can write. + */ +object AgentEnv { + private const val TAG = "AgentEnv" + private const val FILE = "agent-env.json" + private const val GUEST_BIN = "/opt/droiddeck-agent/bin" + private const val BASE_PATH = "/usr/local/bin:/usr/bin:/bin" + private val NAME = Regex("[A-Za-z0-9._-]{1,64}") + private val KEY = Regex("[A-Za-z_][A-Za-z0-9_]*") + private val lock = Any() + + fun inbox(context: Context): File = File(context.getExternalFilesDir(null), "agent-inbox") + + fun list(context: Context): JSONObject = synchronized(lock) { + AgentAccess.requireCommands(context) + load(context) + } + + /** Add [lines] for the next session ([persistent] = every session until cleared). */ + fun set(context: Context, lines: List, persistent: Boolean): JSONObject = synchronized(lock) { + AgentAccess.requireCommands(context) + if (lines.any { line -> KEY.matchEntire(line.substringBefore('=', "")) == null || !line.contains('=') || line.any { it == '\n' || it == '\r' || it == '\u0000' } }) { + throw AgentException("INVALID_ENV", "Environment entries must be single KEY=VALUE lines without NUL bytes") + } + val state = load(context) + val key = if (persistent) "persistent" else "pending" + val merged = merge(strings(state.optJSONArray(key)), lines) + state.put(key, JSONArray(merged)) + save(context, state) + state + } + + /** Drop lines: [scope] is "next", "persistent" or "all". */ + fun clear(context: Context, scope: String): JSONObject = synchronized(lock) { + AgentAccess.requireCommands(context) + val state = load(context) + when (scope) { + "next" -> state.put("pending", JSONArray()) + "persistent" -> state.put("persistent", JSONArray()) + "all" -> { state.put("pending", JSONArray()); state.put("persistent", JSONArray()); state.put("pendingOverrides", JSONArray()) } + else -> throw AgentException("INVALID_SCOPE", "Scope must be next, persistent or all") + } + save(context, state) + state + } + + /** Install agent-inbox/[name] as an override for the next session. */ + fun override(context: Context, name: String): JSONObject = synchronized(lock) { + AgentAccess.requireCommands(context) + if (NAME.matchEntire(name) == null || name in setOf(".", "..")) throw AgentException("INVALID_NAME", "Override names are letters, digits, '.', '_' and '-'") + val source = File(inbox(context), name) + if (Files.isSymbolicLink(source.toPath())) throw AgentException("INVALID_NAME", "The override must be a regular file") + if (!source.isFile) throw AgentException("NO_SUCH_FILE", "Push the binary to ${source.path} first") + val target = File(bin(context), name) + target.parentFile?.mkdirs() + val staged = File.createTempFile("override-", ".tmp", target.parentFile) + try { + Files.newInputStream(source.toPath(), READ, NOFOLLOW_LINKS).use { input -> staged.outputStream().use { input.copyTo(it) } } + } catch (e: Exception) { + staged.delete() + throw AgentException("OVERRIDE_FAILED", "Could not stage the override") + } + if (!staged.setExecutable(true, false) || !staged.renameTo(target)) { + staged.delete() + throw AgentException("OVERRIDE_FAILED", "Could not install $name in the rootfs") + } + source.delete() + val state = load(context) + state.put("pendingOverrides", JSONArray(merge(strings(state.optJSONArray("pendingOverrides")), listOf(name)))) + save(context, state) + state.put("installed", "$GUEST_BIN/$name") + } + + /** + * At session start: the lines this session gets, after the user's droiddeck-env. Pending lines + * and overrides become this session's own, to be dropped by [endSession]. + */ + fun beginSession(context: Context): List = synchronized(lock) { + if (!AgentAccess.commandsAllowed(context)) { + revoke(context) + return@synchronized emptyList() + } + val state = load(context) + val active = strings(state.optJSONArray("pending")) + val overrides = strings(state.optJSONArray("pendingOverrides")) + state.put("active", JSONArray(active)).put("pending", JSONArray()) + state.put("activeOverrides", JSONArray(overrides)).put("pendingOverrides", JSONArray()) + save(context, state) + // Anything else there was left by a session that never reached endSession (the app died). + bin(context).listFiles() + ?.filter { it.name !in overrides }?.forEach { it.delete() } + val lines = strings(state.optJSONArray("persistent")) + active + val withPath = if (overrides.isEmpty()) lines else lines + "PATH=$GUEST_BIN:${pathOf(lines)}" + if (withPath.isNotEmpty()) Log.i(TAG, "agent environment keys for this session: ${withPath.map { it.substringBefore('=') }}") + withPath + } + + fun revoke(context: Context) = synchronized(lock) { + val state = load(context) + for (key in listOf("pending", "active", "persistent", "pendingOverrides", "activeOverrides")) state.put(key, JSONArray()) + save(context, state) + bin(context).listFiles()?.forEach { it.delete() } + } + + /** At session end: this session's lines and override binaries go. */ + fun endSession(context: Context) = synchronized(lock) { + val state = load(context) + val overrides = strings(state.optJSONArray("activeOverrides")) + val pending = strings(state.optJSONArray("pendingOverrides")) + val bin = bin(context) + overrides.filter { it !in pending }.forEach { File(bin, it).delete() } + state.put("active", JSONArray()).put("activeOverrides", JSONArray()) + save(context, state) + } + + /** A PATH= line among [lines] (the user's or an agent's) is extended rather than replaced. */ + private fun pathOf(lines: List) = + lines.lastOrNull { it.startsWith("PATH=") }?.substringAfter('=')?.takeIf { it.isNotBlank() } ?: BASE_PATH + + private fun bin(context: Context): File { + val root = LinuxRuntime.rootDir(context).canonicalFile.toPath() + val directory = root.resolve(GUEST_BIN.removePrefix("/")) + var path = directory + while (path != root) { + if (Files.isSymbolicLink(path)) throw AgentException("OVERRIDE_FAILED", "The override directory must not contain symbolic links") + path = path.parent + } + return directory.toFile() + } + + private fun merge(existing: List, added: List): List { + val keys = added.map { it.substringBefore('=') }.toSet() + return existing.filter { it.substringBefore('=') !in keys } + added + } + + private fun strings(array: JSONArray?): List = + if (array == null) emptyList() else List(array.length()) { array.optString(it) }.filter { it.isNotEmpty() } + + private fun load(context: Context): JSONObject { + val file = File(context.filesDir, FILE) + val state = try { if (file.isFile) JSONObject(file.readText()) else JSONObject() } catch (e: Exception) { JSONObject() } + for (key in listOf("pending", "active", "persistent", "pendingOverrides", "activeOverrides")) { + if (!state.has(key)) state.put(key, JSONArray()) + } + return state + } + + private fun save(context: Context, state: JSONObject) { + val file = File(context.filesDir, FILE) + val staged = File(context.filesDir, "$FILE.tmp") + staged.writeText(state.toString()) + if (!staged.renameTo(file)) { + staged.delete() + throw AgentException("ENV_WRITE_FAILED", "Could not save the debugging environment") + } + } +} + +/** Typed writes to the app's SharedPreferences, for driving a settings matrix without the UI. */ +object AgentPrefs { + fun set(context: Context, file: String, key: String, type: String, value: String?): JSONObject { + AgentAccess.requireCommands(context) + validateFile(file) + if (file == AgentAccess.PROTECTED_PREFS) throw AgentException("PROTECTED_PREFS", "The agent preferences are set on the device only") + if (file.isBlank() || key.isBlank()) throw AgentException("INVALID_PREF", "file and key are required") + val prefs = context.getSharedPreferences(file, Context.MODE_PRIVATE) + val previous = prefs.all[key] + val editor = prefs.edit() + try { + when (type) { + "remove" -> editor.remove(key) + "bool" -> editor.putBoolean(key, value?.toBooleanStrictOrNull() ?: throw NumberFormatException("not true/false")) + "int" -> editor.putInt(key, value!!.toInt()) + "long" -> editor.putLong(key, value!!.toLong()) + "float" -> editor.putFloat(key, value!!.toFloat()) + "string" -> editor.putString(key, value ?: "") + else -> throw AgentException("INVALID_PREF", "type must be bool, int, long, float, string or remove") + } + } catch (e: RuntimeException) { + if (e is AgentException) throw e + throw AgentException("INVALID_PREF", "The value is not a $type") + } + if (!editor.commit()) throw AgentException("PREF_WRITE_FAILED", "Could not write $file/$key") + return JSONObject().put("file", file).put("key", key).put("type", type) + .put("previous", previous ?: JSONObject.NULL).put("value", prefs.all[key] ?: JSONObject.NULL) + } + + fun get(context: Context, file: String): JSONObject { + AgentAccess.requireCommands(context) + validateFile(file) + val all = context.getSharedPreferences(file, Context.MODE_PRIVATE).all + return JSONObject().put("file", file).put("values", JSONObject(all.mapValues { it.value ?: JSONObject.NULL })) + } + + private fun validateFile(file: String) { + if (!Regex("[A-Za-z0-9_-][A-Za-z0-9._-]{0,127}").matches(file)) { + throw AgentException("INVALID_PREF", "Preference files must be simple names") + } + } +} diff --git a/app/src/main/java/com/droiddeck/launcher/agent/AgentGuest.kt b/app/src/main/java/com/droiddeck/launcher/agent/AgentGuest.kt new file mode 100644 index 0000000000..fbf3f84e9e --- /dev/null +++ b/app/src/main/java/com/droiddeck/launcher/agent/AgentGuest.kt @@ -0,0 +1,128 @@ +package com.droiddeck.launcher.agent + +import android.content.Context +import android.os.FileObserver +import android.util.Log +import com.droiddeck.launcher.runtime.LinuxRuntime +import com.droiddeck.launcher.session.SessionEvents +import com.droiddeck.launcher.session.SessionState +import org.json.JSONObject +import java.io.File +import java.util.UUID + +/** + * The app's side of the guest agent (tools/linuxfs/overlay/usr/local/bin/droiddeck-agent): requests + * go in as files under the session root's agent directory and answers come back the same way, so + * whatever runs does so inside the live session with its own environment. + */ +object AgentGuest { + private const val TAG = "AgentGuest" + private const val POLL_MS = 50L + private val lock = Any() + private var observer: FileObserver? = null + private var lastFocusKey: String? = null + + fun dir(context: Context) = File(LinuxRuntime.sessionRoot(context), "agent") + + /** + * Before each session: nothing of the last one's daemon, answers or focus may be read as + * current. Then watch for the new daemon's hello and focus snapshots, which go into the + * session's events.jsonl. + */ + fun reset(context: Context) { + synchronized(lock) { + observer?.stopWatching() + observer = null + lastFocusKey = null + val dir = dir(context) + dir.deleteRecursively() + dir.mkdirs() + @Suppress("DEPRECATION") + observer = object : FileObserver(dir.path, MOVED_TO or CLOSE_WRITE) { + override fun onEvent(event: Int, path: String?) { + when (path) { + "hello.json" -> readJson(File(dir, path))?.let { + SessionEvents.record("agent.ready", mapOf("pid" to it.optInt("pid"), "focus" to it.optBoolean("focus"))) + } + "focus.json" -> readJson(File(dir, path))?.let(::recordFocus) + } + } + }.also { it.startWatching() } + } + } + + /** At the end of a session: no more events for a folder that is being closed. */ + fun stop() { + synchronized(lock) { + observer?.stopWatching() + observer = null + } + } + + private fun recordFocus(snapshot: JSONObject) { + val fields = linkedMapOf( + "focusedApp" to snapshot.opt("focusedApp"), + "focusableApps" to snapshot.optJSONArray("focusableApps")?.toString(), + "baselayerAppIds" to snapshot.optJSONArray("baselayerAppIds")?.toString(), + ) + val key = fields.values.joinToString("|") + synchronized(lock) { + if (key == lastFocusKey) return + lastFocusKey = key + } + SessionEvents.record("focus.changed", fields + ("seq" to snapshot.optInt("seq"))) + } + + /** The daemon's hello, when it is running in the current session. */ + fun hello(context: Context): JSONObject? { + if (!SessionState.running) return null + val hello = readJson(File(dir(context), "hello.json")) ?: return null + val pid = hello.optInt("pid", -1) + return hello.takeIf { pid > 1 && File("/proc/$pid").exists() } + } + + /** The newest focus snapshot the daemon published, when a session is running. */ + fun focus(context: Context): JSONObject? = + if (SessionState.running) readJson(File(dir(context), "focus.json")) else null + + /** Send one request and wait for its answer. Throws [AgentException] with a stable code. */ + fun call(context: Context, request: JSONObject, timeoutMs: Long): JSONObject { + if (request.optString("kind") in setOf("exec", "cdp")) AgentAccess.requireCommands(context) + if (!SessionState.running) throw AgentException("NO_ACTIVE_SESSION", "There is no running session") + hello(context) ?: throw AgentException("AGENT_UNAVAILABLE", "The guest agent is not running in this session (yet)") + val dir = dir(context) + val requests = File(dir, "req").apply { mkdirs() } + val answers = File(dir, "resp").apply { mkdirs() } + val id = UUID.randomUUID().toString() + val staged = File(requests, "$id.json.tmp") + val published = File(requests, "$id.json") + val answer = File(answers, "$id.json") + staged.writeText(request.toString()) + if (!staged.renameTo(published)) { + staged.delete() + throw AgentException("AGENT_UNAVAILABLE", "Could not hand the request to the guest agent") + } + val deadline = System.currentTimeMillis() + timeoutMs + while (System.currentTimeMillis() < deadline) { + if (answer.isFile) { + if (answer.length() > 1024 * 1024) { + answer.delete() + throw AgentException("RESPONSE_TOO_LARGE", "The guest response exceeds 1 MiB") + } + val result = readJson(answer) + answer.delete() + return result ?: throw AgentException("INVALID_AGENT_RESPONSE", "The guest agent's answer was not JSON") + } + Thread.sleep(POLL_MS) + } + published.delete() + Log.w(TAG, "no answer to ${request.optString("kind")} in ${timeoutMs}ms") + throw AgentException("TIMEOUT", "The guest agent did not answer within ${timeoutMs / 1000}s") + } + + private fun readJson(file: File): JSONObject? = try { + if (file.isFile && file.length() <= 1024 * 1024) JSONObject(file.readText()) else null + } catch (e: Exception) { + null + } +} diff --git a/app/src/main/java/com/droiddeck/launcher/agent/AgentInput.kt b/app/src/main/java/com/droiddeck/launcher/agent/AgentInput.kt new file mode 100644 index 0000000000..e2c8674b4c --- /dev/null +++ b/app/src/main/java/com/droiddeck/launcher/agent/AgentInput.kt @@ -0,0 +1,221 @@ +package com.droiddeck.launcher.agent + +import com.droiddeck.launcher.input.PadState +import com.droiddeck.launcher.session.SessionState +import com.droiddeck.launcher.wayland.WaylandCompositor +import org.json.JSONObject + +/** + * Input into the running session the way a player gives it: keys and touches through the + * compositor (what the session screen sends), and the virtual pad through the same PadBridge the + * on-screen controls drive, so games that ignore touch still see a controller. + */ +object AgentInput { + /** Out of the way of real fingers, which Android numbers from 0. */ + private const val TOUCH_ID = 9 + private const val TOUCH_SCALE_X = 1919f + private const val TOUCH_SCALE_Y = 1079f + + fun handle(request: JSONObject): JSONObject { + if (!SessionState.running || !SessionState.firstFrameSeen) { + throw AgentException("SESSION_NOT_READY", "Input needs a running session that has drawn its first frame") + } + return when (val type = request.optString("type")) { + "key" -> key(request) + "text" -> text(request) + "tap" -> tap(request) + "swipe" -> swipe(request) + "pad" -> pad(request) + "stick" -> stick(request) + "trigger" -> trigger(request) + else -> throw AgentException("INVALID_INPUT", "Unknown input type '$type'") + }.put("ok", true).put("command", "input").put("type", request.optString("type")) + } + + private fun key(request: JSONObject): JSONObject { + val name = request.optString("key") + val code = KEYS[name.uppercase()] ?: name.toIntOrNull() + ?: throw AgentException("INVALID_INPUT", "Unknown key '$name' (a name such as ENTER or an evdev code)") + val modifiers = request.optJSONArray("modifiers")?.let { array -> + List(array.length()) { i -> + KEYS[array.optString(i).uppercase()] ?: throw AgentException("INVALID_INPUT", "Unknown modifier '${array.optString(i)}'") + } + }.orEmpty() + when (val action = request.optString("action", "tap")) { + "down" -> WaylandCompositor.nativeSendKey(code, 1) + "up" -> WaylandCompositor.nativeSendKey(code, 0) + "tap" -> { + modifiers.forEach { WaylandCompositor.nativeSendKey(it, 1) } + WaylandCompositor.nativeSendKey(code, 1) + hold(request, 40) + WaylandCompositor.nativeSendKey(code, 0) + modifiers.asReversed().forEach { WaylandCompositor.nativeSendKey(it, 0) } + } + else -> throw AgentException("INVALID_INPUT", "Key action '$action' is not tap, down or up") + } + return JSONObject().put("code", code) + } + + /** Typed as key presses (US layout), which reaches X programs that have no text-input support. */ + private fun text(request: JSONObject): JSONObject { + val text = request.optString("text") + if (request.optBoolean("commit")) { + WaylandCompositor.textInputCommit(text) + return JSONObject().put("length", text.length).put("via", "text-input") + } + val missing = text.filter { TYPED[it] == null } + if (missing.isNotEmpty()) throw AgentException("INVALID_INPUT", "Cannot type '${missing.toSet().joinToString("")}' as keys; use commit") + val delay = request.optLong("delayMs", 15) + for (ch in text) { + val (code, shift) = TYPED.getValue(ch) + if (shift) WaylandCompositor.nativeSendKey(KEYS.getValue("LEFTSHIFT"), 1) + WaylandCompositor.nativeSendKey(code, 1) + WaylandCompositor.nativeSendKey(code, 0) + if (shift) WaylandCompositor.nativeSendKey(KEYS.getValue("LEFTSHIFT"), 0) + Thread.sleep(delay) + } + return JSONObject().put("length", text.length).put("via", "keys") + } + + private fun tap(request: JSONObject): JSONObject { + val (x, y) = point(request, "x", "y") + WaylandCompositor.nativeSendTouch(0, TOUCH_ID, x, y) + hold(request, 60) + WaylandCompositor.nativeSendTouch(2, TOUCH_ID, x, y) + return JSONObject().put("touch", org.json.JSONArray().put(x).put(y)) + } + + private fun swipe(request: JSONObject): JSONObject { + val (x1, y1) = point(request, "x", "y") + val (x2, y2) = point(request, "x2", "y2") + val duration = request.optLong("durationMs", 300).coerceIn(16, 10_000) + val steps = (duration / 16).toInt().coerceAtLeast(2) + WaylandCompositor.nativeSendTouch(0, TOUCH_ID, x1, y1) + for (i in 1..steps) { + Thread.sleep(duration / steps) + WaylandCompositor.nativeSendTouch(1, TOUCH_ID, x1 + (x2 - x1) * i / steps, y1 + (y2 - y1) * i / steps) + } + WaylandCompositor.nativeSendTouch(2, TOUCH_ID, x2, y2) + return JSONObject().put("from", org.json.JSONArray().put(x1).put(y1)).put("to", org.json.JSONArray().put(x2).put(y2)) + } + + /** + * A point in the compositor's touch space (0..1919 x 0..1079 whatever the session's size), from + * the session's output pixels (space "output", the default: what the guest draws at) or 0..1 + * fractions (space "fraction"). + */ + private fun point(request: JSONObject, xKey: String, yKey: String): Pair { + if (!request.has(xKey) || !request.has(yKey)) throw AgentException("INVALID_INPUT", "$xKey and $yKey are required") + val x = request.getDouble(xKey) + val y = request.getDouble(yKey) + val (fx, fy) = when (val space = request.optString("space", "output")) { + "fraction" -> x to y + "output" -> { + val (w, h) = SessionState.outputSize + x / (w - 1).coerceAtLeast(1) to y / (h - 1).coerceAtLeast(1) + } + else -> throw AgentException("INVALID_INPUT", "space '$space' is not output or fraction") + } + return (fx.coerceIn(0.0, 1.0) * TOUCH_SCALE_X).toInt() to (fy.coerceIn(0.0, 1.0) * TOUCH_SCALE_Y).toInt() + } + + private fun pad(request: JSONObject): JSONObject { + val bridge = SessionState.padBridge ?: throw AgentException("NO_PAD", "The session has no virtual pad") + val name = request.optString("button").lowercase() + if (name == "qam") { + bridge.triggerQam() + return JSONObject().put("button", name) + } + val button = BUTTONS[name] + if (button == null && name !in DPAD) throw AgentException("INVALID_INPUT", "Unknown pad button '$name'") + val apply = { s: PadState, down: Boolean -> + when (name) { + "up" -> s.up = down + "down" -> s.down = down + "left" -> s.left = down + "right" -> s.right = down + else -> s.press(button!!, down) + } + } + when (val action = request.optString("action", "tap")) { + "down" -> bridge.applyTouch { apply(it, true) } + "up" -> bridge.applyTouch { apply(it, false) } + "tap" -> { + bridge.applyTouch { apply(it, true) } + hold(request, 120) + bridge.applyTouch { apply(it, false) } + } + else -> throw AgentException("INVALID_INPUT", "Pad action '$action' is not tap, down or up") + } + return JSONObject().put("button", name) + } + + private fun stick(request: JSONObject): JSONObject { + val bridge = SessionState.padBridge ?: throw AgentException("NO_PAD", "The session has no virtual pad") + val right = request.optString("stick", "left") == "right" + val x = request.optDouble("x", 0.0).toFloat().coerceIn(-1f, 1f) + val y = request.optDouble("y", 0.0).toFloat().coerceIn(-1f, 1f) + bridge.applyTouch { if (right) { it.rightX = x; it.rightY = y } else { it.leftX = x; it.leftY = y } } + hold(request, 300) + bridge.applyTouch { if (right) { it.rightX = 0f; it.rightY = 0f } else { it.leftX = 0f; it.leftY = 0f } } + return JSONObject().put("stick", if (right) "right" else "left") + } + + private fun trigger(request: JSONObject): JSONObject { + val bridge = SessionState.padBridge ?: throw AgentException("NO_PAD", "The session has no virtual pad") + val right = request.optString("trigger", "right") == "right" + val value = request.optDouble("value", 1.0).toFloat().coerceIn(0f, 1f) + bridge.applyTouch { if (right) it.rightTrigger = value else it.leftTrigger = value } + hold(request, 200) + bridge.applyTouch { if (right) it.rightTrigger = 0f else it.leftTrigger = 0f } + return JSONObject().put("trigger", if (right) "right" else "left") + } + + private fun hold(request: JSONObject, defaultMs: Long) = + Thread.sleep(request.optLong("holdMs", defaultMs).coerceIn(0, 10_000)) + + private val DPAD = setOf("up", "down", "left", "right") + + private val BUTTONS = mapOf( + "a" to PadState.A, "b" to PadState.B, "x" to PadState.X, "y" to PadState.Y, + "lb" to PadState.LB, "rb" to PadState.RB, "select" to PadState.SELECT, "back" to PadState.SELECT, + "start" to PadState.START, "menu" to PadState.START, "l3" to PadState.L3, "r3" to PadState.R3, + "guide" to PadState.GUIDE, "steam" to PadState.GUIDE, + ) + + /** Linux evdev codes (input-event-codes.h) by name. */ + private val KEYS: Map = buildMap { + "1234567890".forEachIndexed { i, c -> put(c.toString(), 2 + i) } + "QWERTYUIOP".forEachIndexed { i, c -> put(c.toString(), 16 + i) } + "ASDFGHJKL".forEachIndexed { i, c -> put(c.toString(), 30 + i) } + "ZXCVBNM".forEachIndexed { i, c -> put(c.toString(), 44 + i) } + (1..10).forEach { put("F$it", 58 + it) } + put("F11", 87); put("F12", 88) + putAll(mapOf( + "ESC" to 1, "MINUS" to 12, "EQUAL" to 13, "BACKSPACE" to 14, "TAB" to 15, "LEFTBRACE" to 26, + "RIGHTBRACE" to 27, "ENTER" to 28, "LEFTCTRL" to 29, "SEMICOLON" to 39, "APOSTROPHE" to 40, + "GRAVE" to 41, "LEFTSHIFT" to 42, "BACKSLASH" to 43, "COMMA" to 51, "DOT" to 52, "SLASH" to 53, + "RIGHTSHIFT" to 54, "LEFTALT" to 56, "SPACE" to 57, "CAPSLOCK" to 58, "RIGHTCTRL" to 97, + "RIGHTALT" to 100, "HOME" to 102, "UP" to 103, "PAGEUP" to 104, "LEFT" to 105, "RIGHT" to 106, + "END" to 107, "DOWN" to 108, "PAGEDOWN" to 109, "INSERT" to 110, "DELETE" to 111, "LEFTMETA" to 125, + "CTRL" to 29, "SHIFT" to 42, "ALT" to 56, "META" to 125, "SUPER" to 125, "RETURN" to 28, "ESCAPE" to 1, + )) + } + + /** US-layout characters as (evdev code, shift). */ + private val TYPED: Map> = buildMap { + for (c in 'a'..'z') put(c, KEYS.getValue(c.uppercase()) to false) + for (c in 'A'..'Z') put(c, KEYS.getValue(c.toString()) to true) + for (c in '0'..'9') put(c, KEYS.getValue(c.toString()) to false) + "!@#$%^&*()".forEachIndexed { i, c -> put(c, KEYS.getValue(((i + 1) % 10).toString()) to true) } + putAll(mapOf( + ' ' to (57 to false), '\n' to (28 to false), '\t' to (15 to false), + '-' to (12 to false), '_' to (12 to true), '=' to (13 to false), '+' to (13 to true), + '[' to (26 to false), '{' to (26 to true), ']' to (27 to false), '}' to (27 to true), + ';' to (39 to false), ':' to (39 to true), '\'' to (40 to false), '"' to (40 to true), + '`' to (41 to false), '~' to (41 to true), '\\' to (43 to false), '|' to (43 to true), + ',' to (51 to false), '<' to (51 to true), '.' to (52 to false), '>' to (52 to true), + '/' to (53 to false), '?' to (53 to true), + )) + } +} diff --git a/app/src/main/java/com/droiddeck/launcher/agent/AgentStartActivity.kt b/app/src/main/java/com/droiddeck/launcher/agent/AgentStartActivity.kt index 9e35ca46c9..99a6f784c6 100644 --- a/app/src/main/java/com/droiddeck/launcher/agent/AgentStartActivity.kt +++ b/app/src/main/java/com/droiddeck/launcher/agent/AgentStartActivity.kt @@ -38,6 +38,10 @@ class AgentStartActivity : Activity() { Log.e(TAG, "missing agent start request") return null } + if (encoded.length > AgentAccess.MAX_REQUEST_CHARS) { + Log.w(TAG, "agent start request is too large") + return null + } return try { JSONObject(String(Base64.decode(encoded, Base64.DEFAULT), Charsets.UTF_8)) } catch (e: Exception) { @@ -47,6 +51,13 @@ class AgentStartActivity : Activity() { } private fun startSession(request: JSONObject) { + try { + AgentAccess.requireStart(this, request) + } catch (e: AgentException) { + Log.w(TAG, e.code) + finish() + return + } val requestedMode = request.optString("mode") val sessionMode = when (requestedMode) { "steam" -> SessionService.MODE_STEAM diff --git a/app/src/main/java/com/droiddeck/launcher/agent/AgentUi.kt b/app/src/main/java/com/droiddeck/launcher/agent/AgentUi.kt new file mode 100644 index 0000000000..6153da0f30 --- /dev/null +++ b/app/src/main/java/com/droiddeck/launcher/agent/AgentUi.kt @@ -0,0 +1,157 @@ +package com.droiddeck.launcher.agent + +import android.os.Build +import android.os.Handler +import android.os.Looper +import android.view.View +import android.view.ViewGroup +import android.view.inspector.WindowInspector +import androidx.compose.ui.platform.ViewRootForTest +import androidx.compose.ui.semantics.SemanticsActions +import androidx.compose.ui.semantics.SemanticsConfiguration +import androidx.compose.ui.semantics.SemanticsNode +import androidx.compose.ui.semantics.SemanticsProperties +import androidx.compose.ui.semantics.getOrNull +import androidx.compose.ui.text.AnnotatedString +import org.json.JSONArray +import org.json.JSONObject +import java.util.concurrent.CountDownLatch +import java.util.concurrent.TimeUnit +import java.util.concurrent.atomic.AtomicReference + +/** + * The app's own UI as an agent sees it: every Compose node in every window of the process (popups + * and menus included), read from Compose's semantics rather than through UI Automator, which on a + * dual-screen device dumps whichever window has focus - often not this app's. Nodes carry their + * test tag (ui/TestTags.kt), text, content description, role, state and on-screen bounds; click + * and set-text act on a node by tag or text, so a test needs no coordinates. + */ +object AgentUi { + private const val TIMEOUT_MS = 5_000L + /** Setup's Debugging tools toggle: the bridge never acts on its own gate (AgentAccess). */ + private const val GATE_TAG = "setting-agent-commands" + + fun handle(request: JSONObject): JSONObject = when (val op = request.optString("op", "dump")) { + "dump" -> onMain { dump(request.optBoolean("all")) } + "click" -> onMain { act(request) { node -> perform(node, SemanticsActions.OnClick) } } + "set-text" -> onMain { + val text = request.optString("text") + act(request) { node -> + node.config.getOrNull(SemanticsActions.SetText)?.action?.invoke(AnnotatedString(text)) + ?: throw AgentException("NOT_EDITABLE", "That node takes no text") + } + } + else -> throw AgentException("INVALID_REQUEST", "ui op '$op' is not dump, click or set-text") + }.put("ok", true).put("command", "ui") + + private fun roots(): List> { + if (Build.VERSION.SDK_INT < 29) throw AgentException("UNSUPPORTED", "The UI dump needs Android 10 or later") + val found = mutableListOf>() + fun walk(view: View) { + if (view is ViewRootForTest) found += view to view + if (view is ViewGroup) for (i in 0 until view.childCount) walk(view.getChildAt(i)) + } + WindowInspector.getGlobalWindowViews().filter { it.isAttachedToWindow && it.isShown }.forEach(::walk) + return found + } + + private fun dump(all: Boolean): JSONObject { + val windows = JSONArray() + for ((view, root) in roots()) { + val nodes = JSONArray() + val location = IntArray(2).also { view.getLocationOnScreen(it) } + fun visit(node: SemanticsNode) { + val json = describe(node, location) + if (all || json.has("tag") || json.has("text") || json.has("description") || json.optBoolean("clickable")) nodes.put(json) + node.children.forEach(::visit) + } + visit(root.semanticsOwner.rootSemanticsNode) + windows.put(JSONObject() + .put("display", view.display?.displayId ?: JSONObject.NULL) + .put("window", view.rootView.javaClass.simpleName) + .put("nodes", nodes)) + } + return JSONObject().put("windows", windows) + } + + private fun describe(node: SemanticsNode, origin: IntArray): JSONObject { + val config = node.config + val json = JSONObject().put("id", node.id) + config.getOrNull(SemanticsProperties.TestTag)?.let { json.put("tag", it) } + val text = textFields(config) + text.keys().forEach { json.put(it, text.get(it)) } + config.getOrNull(SemanticsProperties.Role)?.let { json.put("role", it.toString()) } + config.getOrNull(SemanticsProperties.ToggleableState)?.let { json.put("toggle", it.name) } + config.getOrNull(SemanticsProperties.Selected)?.let { json.put("selected", it) } + config.getOrNull(SemanticsProperties.Focused)?.let { json.put("focused", it) } + if (config.contains(SemanticsProperties.Disabled)) json.put("disabled", true) + if (config.contains(SemanticsActions.OnClick)) json.put("clickable", true) + if (config.contains(SemanticsActions.SetText)) json.put("editable", true) + val b = node.boundsInWindow + json.put("bounds", JSONArray() + .put(origin[0] + b.left.toInt()).put(origin[1] + b.top.toInt()) + .put(origin[0] + b.right.toInt()).put(origin[1] + b.bottom.toInt())) + return json + } + + internal fun textFields(config: SemanticsConfiguration): JSONObject { + val password = config.contains(SemanticsProperties.Password) + val json = JSONObject() + for ((key, value) in listOf( + "text" to config.getOrNull(SemanticsProperties.Text)?.joinToString(" ") { it.text }, + "editableText" to config.getOrNull(SemanticsProperties.EditableText)?.text, + "description" to config.getOrNull(SemanticsProperties.ContentDescription)?.joinToString(" "), + "state" to config.getOrNull(SemanticsProperties.StateDescription), + )) value?.let { json.put(key, if (password) "" else it) } + return json + } + + /** + * The node a request names by "tag" (exact) or "match" (text or description containing it, + * ignoring case); "index" picks among several, in tree order. + */ + private fun act(request: JSONObject, action: (SemanticsNode) -> Unit): JSONObject { + val tag = request.optString("tag").takeIf { it.isNotEmpty() } + val text = if (tag == null) request.optString("match").takeIf { it.isNotEmpty() } else null + if (tag == null && text == null) throw AgentException("INVALID_REQUEST", "Name the node by tag or match") + val matches = mutableListOf>() + for ((view, root) in roots()) { + val origin = IntArray(2).also { view.getLocationOnScreen(it) } + fun visit(node: SemanticsNode) { + val config = node.config + val hit = if (tag != null) config.getOrNull(SemanticsProperties.TestTag) == tag + else (config.getOrNull(SemanticsProperties.Text)?.joinToString(" ") { it.text } + ?: config.getOrNull(SemanticsProperties.ContentDescription)?.joinToString(" ") ?: "") + .contains(text!!, ignoreCase = true) + if (hit) matches += node to origin + node.children.forEach(::visit) + } + visit(root.semanticsOwner.rootSemanticsNode) + } + val index = request.optInt("index", 0) + val (node, origin) = matches.getOrNull(index) + ?: throw AgentException("NO_SUCH_NODE", "No node with ${if (tag != null) "tag '$tag'" else "text '$text'"} (${matches.size} found)") + if (generateSequence(node) { it.parent }.any { it.config.getOrNull(SemanticsProperties.TestTag) == GATE_TAG }) { + throw AgentException("PROTECTED_CONTROL", "Debugging tools are switched on the device only") + } + action(node) + return JSONObject().put("matches", matches.size).put("node", describe(node, origin)) + } + + private fun perform(node: SemanticsNode, key: androidx.compose.ui.semantics.SemanticsPropertyKey Boolean>>) { + val action = node.config.getOrNull(key)?.action ?: throw AgentException("NOT_CLICKABLE", "That node has no click action") + action() + } + + private fun onMain(block: () -> T): T { + if (Looper.myLooper() == Looper.getMainLooper()) return block() + val result = AtomicReference>() + val done = CountDownLatch(1) + Handler(Looper.getMainLooper()).post { + result.set(runCatching(block)) + done.countDown() + } + if (!done.await(TIMEOUT_MS, TimeUnit.MILLISECONDS)) throw AgentException("TIMEOUT", "The UI thread did not answer") + return result.get().getOrThrow() + } +} diff --git a/app/src/main/java/com/droiddeck/launcher/core/HostProcess.kt b/app/src/main/java/com/droiddeck/launcher/core/HostProcess.kt index 79334af3be..550d55a529 100644 --- a/app/src/main/java/com/droiddeck/launcher/core/HostProcess.kt +++ b/app/src/main/java/com/droiddeck/launcher/core/HostProcess.kt @@ -40,7 +40,7 @@ object HostProcess { if (onLine == null) builder.redirectOutput(File("/dev/null")) val process = builder.start() val pid = pidOf(process) - Log.i(TAG, "started pid $pid: $command") + Log.i(TAG, "started pid $pid: ${argv.first()} (${argv.size - 1} arguments)") if (onLine != null) { Thread({ try { @@ -59,7 +59,7 @@ object HostProcess { } pid } catch (e: Exception) { - Log.e(TAG, "could not start: $command", e) + Log.e(TAG, "could not start: ${argv.first()}", e) -1 } } diff --git a/app/src/main/java/com/droiddeck/launcher/session/SessionFiles.kt b/app/src/main/java/com/droiddeck/launcher/session/SessionFiles.kt index afc798db3e..39956183a5 100644 --- a/app/src/main/java/com/droiddeck/launcher/session/SessionFiles.kt +++ b/app/src/main/java/com/droiddeck/launcher/session/SessionFiles.kt @@ -41,6 +41,7 @@ object SessionFiles { "libblfastpath.so" to "usr/local/lib/libblfastpath.so", "libssbs.so" to "usr/local/lib/libssbs.so", "usr/local/bin/droiddeck-session" to "usr/local/bin/droiddeck-session", + "usr/local/bin/droiddeck-agent" to "usr/local/bin/droiddeck-agent", "usr/local/bin/steam-compatibility" to "usr/local/bin/steam-compatibility", "usr/local/bin/droiddeck-clipboard" to "usr/local/bin/droiddeck-clipboard", "usr/local/bin/droiddeck-steam-install" to "usr/local/bin/droiddeck-steam-install", diff --git a/app/src/main/java/com/droiddeck/launcher/session/SessionService.kt b/app/src/main/java/com/droiddeck/launcher/session/SessionService.kt index 0ea919b1c8..037e5a2014 100644 --- a/app/src/main/java/com/droiddeck/launcher/session/SessionService.kt +++ b/app/src/main/java/com/droiddeck/launcher/session/SessionService.kt @@ -293,7 +293,7 @@ class SessionService : Service() { val lines = FileUtils.readString(file)?.lines().orEmpty() .map { it.trim() } .filter { it.isNotEmpty() && !it.startsWith("#") && it.contains('=') && !it.startsWith("=") } - if (lines.isNotEmpty()) Log.i(TAG, "extra environment from ${file.path}: $lines") + if (lines.isNotEmpty()) Log.i(TAG, "extra environment keys from ${file.path}: ${lines.map { it.substringBefore('=') }}") return lines } @@ -324,6 +324,7 @@ class SessionService : Service() { val runtimeDir = File(filesDir, ".wayland-rt").apply { mkdirs() } killStragglers() SessionFiles.stage(this, root) + com.droiddeck.launcher.agent.AgentGuest.reset(this) val sessionDir = openSessionFolder() val sessionLog = File(sessionDir, "session.log") @@ -423,7 +424,7 @@ class SessionService : Service() { } guest.add(program) guest.addAll(SessionState.programArgs) - Log.i(TAG, "run: $program ${SessionState.programArgs.joinToString(" ")} under gamescope") + Log.i(TAG, "run: $program (${SessionState.programArgs.size} arguments) under gamescope") } // Android has no /dev/shm; the cache stands in for it and, unlike the real thing, keeps @@ -659,6 +660,8 @@ class SessionService : Service() { // (ZINK_DESCRIPTORS=lazy, MESA_*), gamescope's, the client's - whatever the experiment // needs, without a build per attempt. extraEnv().forEach { guest.add(it) } + // The agent bridge's experiment lines (AgentEnv), after the user's so an agent's win. + com.droiddeck.launcher.agent.AgentEnv.beginSession(this).forEach { guest.add(it) } // Core masks, Bannerlator's two (cfca3912). The client's is sent whenever the override is // on, even naming every core: it exists to undo the pin Steam applies to its own interface // renderer, and the scheduler's default is exactly what that pin takes away. A game's is @@ -1404,6 +1407,9 @@ class SessionService : Service() { SessionState.pipActive = false pipTask = false SessionState.guestPid = -1 + com.droiddeck.launcher.agent.AgentGuest.stop() + runCatching { com.droiddeck.launcher.agent.AgentEnv.endSession(this) } + .onFailure { Log.w(TAG, "clearing the agent's session environment", it) } releaseLocks() if (status == 0) { SessionEvents.transition(SessionPhase.IDLE, "session.stopped", mapOf("status" to status)) diff --git a/app/src/main/java/com/droiddeck/launcher/session/SessionState.kt b/app/src/main/java/com/droiddeck/launcher/session/SessionState.kt index c6c03f7dbb..af47468ccb 100644 --- a/app/src/main/java/com/droiddeck/launcher/session/SessionState.kt +++ b/app/src/main/java/com/droiddeck/launcher/session/SessionState.kt @@ -80,6 +80,9 @@ object SessionState { /** Told (on the thread that changed it) whenever [deckPad] changes. */ @Volatile var deckPadListener: (() -> Unit)? = null + /** The session screen's virtual pad, for the agent bridge's pad input (AgentInput). */ + @Volatile var padBridge: com.droiddeck.launcher.input.PadBridge? = null + /** What the second screen shows, and on which display: kept for the session, so a screen * turned off (sleep, a closed lid) or an activity recreated brings it back as it was. */ @Volatile var secondScreenMode = com.droiddeck.launcher.input.SecondScreenMode.NONE diff --git a/app/src/main/java/com/droiddeck/launcher/ui/FrontEndGames.kt b/app/src/main/java/com/droiddeck/launcher/ui/FrontEndGames.kt index 01bd1ff0a3..c373f672b4 100644 --- a/app/src/main/java/com/droiddeck/launcher/ui/FrontEndGames.kt +++ b/app/src/main/java/com/droiddeck/launcher/ui/FrontEndGames.kt @@ -1,5 +1,6 @@ package com.droiddeck.launcher.ui +import androidx.compose.ui.platform.testTag import com.droiddeck.launcher.R import androidx.compose.ui.res.stringResource import androidx.compose.foundation.LocalIndication @@ -71,7 +72,7 @@ internal fun GamesPage(s: FrontEndState, a: FrontEndActions, selected: String, o Rise(0) { PageHeader(stringResource(R.string.content_games)) } Rise(1) { Note(stringResource(if (s.shortcutPicker && s.shortcutLibraryScanning) R.string.game_shortcut_scanning else R.string.games_empty)) } if (!s.shortcutPicker) Rise(2) { - Actions { PrimaryButton(stringResource(R.string.games_play_steam), enabled = !s.busy, main = true, icon = Icons.Filled.PlayArrow, modifier = Modifier.padding(top = 12.dp), onClick = a.onPlay) } + Actions { PrimaryButton(stringResource(R.string.games_play_steam), enabled = !s.busy, main = true, icon = Icons.Filled.PlayArrow, modifier = Modifier.padding(top = 12.dp).testTag("play-steam"), onClick = a.onPlay) } } GameFileFolderActions(s, a) } diff --git a/app/src/main/java/com/droiddeck/launcher/ui/FrontEndRail.kt b/app/src/main/java/com/droiddeck/launcher/ui/FrontEndRail.kt index 211f082a8f..efd4319ca0 100644 --- a/app/src/main/java/com/droiddeck/launcher/ui/FrontEndRail.kt +++ b/app/src/main/java/com/droiddeck/launcher/ui/FrontEndRail.kt @@ -1,5 +1,6 @@ package com.droiddeck.launcher.ui +import androidx.compose.ui.platform.testTag import com.droiddeck.launcher.R import androidx.compose.ui.res.stringResource import androidx.compose.ui.focus.focusRequester @@ -162,6 +163,7 @@ private fun RailItem( contentAlignment = Alignment.Center, modifier = Modifier .then(if (frontFocus != null) Modifier.focusRequester(frontFocus.railFor(key)) else Modifier) + .testTag("rail-$key") .graphicsLayer { scaleX = scale; scaleY = scale } .size(width = if (iconOnly) 52.dp else 80.dp, height = height) .clip(Shape14) diff --git a/app/src/main/java/com/droiddeck/launcher/ui/FrontEndScreen.kt b/app/src/main/java/com/droiddeck/launcher/ui/FrontEndScreen.kt index 75eaab1520..8781f419bf 100644 --- a/app/src/main/java/com/droiddeck/launcher/ui/FrontEndScreen.kt +++ b/app/src/main/java/com/droiddeck/launcher/ui/FrontEndScreen.kt @@ -91,6 +91,8 @@ class FrontEndState( val frameGenLabel: String, val romsDir: String?, val logsEnabled: Boolean, + /** Setup's Debugging tools toggle (AgentAccess): off unless the user turns it on. */ + val agentCommands: Boolean = false, val steamGames: List, val emulators: List, val running: String?, @@ -166,6 +168,7 @@ class FrontEndActions( val onFiles: () -> Unit, val onBrowseFiles: (File) -> Unit = {}, val onLogs: () -> Unit, + val onAgentCommands: () -> Unit = {}, val onShareLogs: () -> Unit = {}, val onClearLogs: () -> Unit = {}, val onOffline: () -> Unit, diff --git a/app/src/main/java/com/droiddeck/launcher/ui/FrontEndSetup.kt b/app/src/main/java/com/droiddeck/launcher/ui/FrontEndSetup.kt index 3dc904acf4..5965758003 100644 --- a/app/src/main/java/com/droiddeck/launcher/ui/FrontEndSetup.kt +++ b/app/src/main/java/com/droiddeck/launcher/ui/FrontEndSetup.kt @@ -307,6 +307,7 @@ internal fun SetupPanel( } } ToggleRow(host, "logs", stringResource(R.string.setup_logs), stringResource(R.string.setup_logs_hint), s.logsEnabled) { a.onLogs() } + ToggleRow(host, "agent-commands", stringResource(R.string.setup_agent_commands), null, s.agentCommands) { a.onAgentCommands() } ActionRow(stringResource(R.string.setup_latest_logs), stringResource(R.string.drawer_logs_hint), stringResource(R.string.drawer_share_logs), a.onShareLogs, progress = com.droiddeck.launcher.session.SessionLogShare.progress) ActionRow(stringResource(R.string.setup_saved_logs), stringResource(R.string.setup_saved_logs_hint, com.droiddeck.launcher.session.SessionPaths.KEEP_SESSIONS), stringResource(R.string.setup_clear_logs), a.onClearLogs) diff --git a/app/src/main/java/com/droiddeck/launcher/ui/SessionOverlay.kt b/app/src/main/java/com/droiddeck/launcher/ui/SessionOverlay.kt index 38cd3b41af..4a5d4fe882 100644 --- a/app/src/main/java/com/droiddeck/launcher/ui/SessionOverlay.kt +++ b/app/src/main/java/com/droiddeck/launcher/ui/SessionOverlay.kt @@ -1,5 +1,6 @@ package com.droiddeck.launcher.ui +import androidx.compose.ui.platform.testTag import androidx.compose.ui.draw.alpha import androidx.compose.animation.core.Animatable import androidx.compose.foundation.Canvas @@ -310,7 +311,7 @@ internal fun SessionDrawer(open: Boolean, requestedPage: SessionDrawerPage, cont modifier = Modifier.fillMaxSize() .clickable(interactionSource = remember { MutableInteractionSource() }, indication = null) { host.open = null; a.onClose() }, ) - androidx.compose.foundation.layout.BoxWithConstraints(modifier = Modifier.fillMaxSize(), contentAlignment = Alignment.CenterEnd) { + androidx.compose.foundation.layout.BoxWithConstraints(modifier = Modifier.fillMaxSize().exposeTestTags(), contentAlignment = Alignment.CenterEnd) { // A 4:3 or near-square screen (under 440dp tall) gets tighter padding and a shorter tab row, // so the settings keep most of the height; a narrow one keeps some of the game in view. val short = maxHeight < 440.dp @@ -621,7 +622,7 @@ private fun StopSessionButton(modifier: Modifier = Modifier, onClick: () -> Unit val stopDescription = stringResource(R.string.stop_session) Row( verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(6.dp), - modifier = modifier.heightIn(min = 44.dp).semantics { contentDescription = stopDescription } + modifier = modifier.heightIn(min = 44.dp).semantics { contentDescription = stopDescription }.testTag("drawer-stop") .clip(shape).background(fill).glideBorder(hot, shape, colors.error.copy(alpha = 0.9f), colors.error.copy(alpha = 0.55f)) .hoverable(src).clickable(interactionSource = src, indication = LocalIndication.current, onClick = onClick) .controllerConfirm(onClick = onClick) @@ -732,6 +733,7 @@ private fun DrawerPageTabs(page: SessionDrawerPage, pages: List ChoiceRow( val open = host.open == key SettingsRow(label, hint, highlighted = open, hintLines = hintLines) { Box { - ValueChip(options.firstOrNull { it.first == selected }?.second ?: "-", open, enabled, modifier = chipModifier) { host.open = if (open) null else key } + ValueChip(options.firstOrNull { it.first == selected }?.second ?: "-", open, enabled, modifier = chipModifier.testTag("setting-$key")) { host.open = if (open) null else key } AnchoredMenu(open, onDismiss = { if (host.open == key) host.open = null }, title = label, note = note) { firstItemFocus -> options.forEachIndexed { index, (value, text) -> MenuItem(text, checked = value == selected, focusRequester = if (index == 0) firstItemFocus else null) { @@ -472,7 +474,7 @@ fun ChoiceRow( @Composable fun ToggleRow(host: MenuHost, key: String, label: String, hint: String?, checked: Boolean, enabled: Boolean = true, chipModifier: Modifier = Modifier, onChange: (Boolean) -> Unit) = SettingsRow(label, hint) { - ToggleSwitch(checked, enabled, label, chipModifier) { host.open = null; onChange(it) } + ToggleSwitch(checked, enabled, label, chipModifier.testTag("setting-$key")) { host.open = null; onChange(it) } } /** An on/off switch: one tap or one A press flips it, where a menu of On and Off took three. */ diff --git a/app/src/main/java/com/droiddeck/launcher/ui/SteamHome.kt b/app/src/main/java/com/droiddeck/launcher/ui/SteamHome.kt index 1184b3078f..be8df6b3de 100644 --- a/app/src/main/java/com/droiddeck/launcher/ui/SteamHome.kt +++ b/app/src/main/java/com/droiddeck/launcher/ui/SteamHome.kt @@ -1,5 +1,6 @@ package com.droiddeck.launcher.ui +import androidx.compose.ui.platform.testTag import com.droiddeck.launcher.R import androidx.compose.ui.res.stringResource import androidx.compose.animation.core.FastOutSlowInEasing @@ -91,7 +92,7 @@ internal fun SteamHome(s: FrontEndState, a: FrontEndActions, modifier: Modifier) Spacer(Modifier.height(18.dp)) Row(verticalAlignment = Alignment.CenterVertically, horizontalArrangement = Arrangement.spacedBy(10.dp)) { // Enabled without a runtime: the session's loading screen installs it first. - PrimaryButton(stringResource(R.string.games_play_steam), enabled = !s.busy, main = true, large = true, icon = Icons.Filled.PlayArrow, onClick = a.onPlay) + PrimaryButton(stringResource(R.string.games_play_steam), enabled = !s.busy, main = true, large = true, icon = Icons.Filled.PlayArrow, modifier = Modifier.testTag("play-steam"), onClick = a.onPlay) Cog(size = 54.dp, onClick = a.onSteamSettings) } } diff --git a/app/src/main/java/com/droiddeck/launcher/ui/TestTags.kt b/app/src/main/java/com/droiddeck/launcher/ui/TestTags.kt new file mode 100644 index 0000000000..12c5ee390a --- /dev/null +++ b/app/src/main/java/com/droiddeck/launcher/ui/TestTags.kt @@ -0,0 +1,14 @@ +package com.droiddeck.launcher.ui + +import androidx.compose.ui.ExperimentalComposeUiApi +import androidx.compose.ui.Modifier +import androidx.compose.ui.semantics.semantics +import androidx.compose.ui.semantics.testTagsAsResourceId + +/** + * Compose test tags as Android resource ids below this node, so UI Automator (`uiautomator dump`, + * droiddeckctl ui-dump) sees stable ids such as `rail-steam` or `setting-logs` rather than only + * labels that change with the language. Tags are named in docs/agent-control.md. + */ +@OptIn(ExperimentalComposeUiApi::class) +fun Modifier.exposeTestTags(): Modifier = semantics { testTagsAsResourceId = true } diff --git a/app/src/main/res/values-es/strings.xml b/app/src/main/res/values-es/strings.xml index 797d3e358e..06c467c797 100644 --- a/app/src/main/res/values-es/strings.xml +++ b/app/src/main/res/values-es/strings.xml @@ -613,6 +613,7 @@ Sesión Registros de sesión Se guardan tras cada sesión + Herramientas de depuración Últimos registros de sesión Registros de sesión guardados Conserva los %1$d más recientes diff --git a/app/src/main/res/values-fr/strings.xml b/app/src/main/res/values-fr/strings.xml index 61e76e8f78..4278e2efae 100644 --- a/app/src/main/res/values-fr/strings.xml +++ b/app/src/main/res/values-fr/strings.xml @@ -514,6 +514,7 @@ Session Journaux de session Enregistré après chaque fin de session + Outils de débogage Derniers journaux de session Journaux de session enregistrés Conserver les %1$d plus récents diff --git a/app/src/main/res/values-ja/strings.xml b/app/src/main/res/values-ja/strings.xml index 12f3435ab3..88b1a611ce 100644 --- a/app/src/main/res/values-ja/strings.xml +++ b/app/src/main/res/values-ja/strings.xml @@ -611,6 +611,7 @@ セッション セッションログ 各セッション終了後に保存 + デバッグツール 最新のセッションログ 保存されたセッションログ 最新の%1$d件を保持 diff --git a/app/src/main/res/values-ko/strings.xml b/app/src/main/res/values-ko/strings.xml index ee6c278dc1..ee8e9a3519 100644 --- a/app/src/main/res/values-ko/strings.xml +++ b/app/src/main/res/values-ko/strings.xml @@ -611,6 +611,7 @@ 세션 세션 로그 각 세션 종료 후 저장 + 디버깅 도구 최신 세션 로그 저장된 세션 로그 최신 %1$d개 유지 diff --git a/app/src/main/res/values-ru/strings.xml b/app/src/main/res/values-ru/strings.xml index e0a1a5b04b..092f1adaf7 100644 --- a/app/src/main/res/values-ru/strings.xml +++ b/app/src/main/res/values-ru/strings.xml @@ -516,6 +516,7 @@ Сессия Журналы сессии Сохраняется после каждой сессии + Инструменты отладки Последние журналы сессии Сохраненные журналы сессии Хранить последние %1$d diff --git a/app/src/main/res/values-zh-rCN/strings.xml b/app/src/main/res/values-zh-rCN/strings.xml index 6139fecb80..e055fb9705 100644 --- a/app/src/main/res/values-zh-rCN/strings.xml +++ b/app/src/main/res/values-zh-rCN/strings.xml @@ -611,6 +611,7 @@ 会话 会话日志 每次会话后保存 + 调试工具 最新会话日志 已保存的会话日志 保留最新的 %1$d 个 diff --git a/app/src/main/res/values-zh-rHK/strings.xml b/app/src/main/res/values-zh-rHK/strings.xml index 6fda24b772..1a2e010b2c 100644 --- a/app/src/main/res/values-zh-rHK/strings.xml +++ b/app/src/main/res/values-zh-rHK/strings.xml @@ -611,6 +611,7 @@ 會話 會話記錄 每次會話後儲存 + 偵錯工具 最新的會話記錄 已儲存的會話記錄 保留最新的 %1$d 個 diff --git a/app/src/main/res/values-zh-rTW/strings.xml b/app/src/main/res/values-zh-rTW/strings.xml index 6af7eb6cf8..ebe3aff9bb 100644 --- a/app/src/main/res/values-zh-rTW/strings.xml +++ b/app/src/main/res/values-zh-rTW/strings.xml @@ -611,6 +611,7 @@ 工作階段 工作階段日誌 每次工作階段結束後儲存 + 偵錯工具 最新工作階段日誌 已儲存的工作階段日誌 保留最新的 %1$d 個 diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml index 71799ae61b..a240c5adbc 100644 --- a/app/src/main/res/values/strings.xml +++ b/app/src/main/res/values/strings.xml @@ -616,6 +616,7 @@ Session Session logs Saved after each session + Debugging tools Latest session logs Saved session logs Keeps the newest %1$d diff --git a/app/src/test/java/com/droiddeck/launcher/agent/AgentSecurityTest.kt b/app/src/test/java/com/droiddeck/launcher/agent/AgentSecurityTest.kt new file mode 100644 index 0000000000..499645c3e8 --- /dev/null +++ b/app/src/test/java/com/droiddeck/launcher/agent/AgentSecurityTest.kt @@ -0,0 +1,266 @@ +package com.droiddeck.launcher.agent + +import android.content.Context +import android.os.Bundle +import android.os.Process +import android.util.Base64 +import androidx.compose.ui.semantics.SemanticsConfiguration +import androidx.compose.ui.semantics.SemanticsProperties +import androidx.compose.ui.text.AnnotatedString +import com.droiddeck.launcher.runtime.LinuxRuntime +import org.json.JSONObject +import org.junit.Assert.* +import org.junit.After +import org.junit.Before +import org.junit.Test +import org.junit.runner.RunWith +import org.robolectric.Robolectric +import org.robolectric.RobolectricTestRunner +import org.robolectric.RuntimeEnvironment +import org.robolectric.Shadows.shadowOf +import org.robolectric.annotation.Config +import org.robolectric.shadows.ShadowBinder +import org.robolectric.shadows.ShadowLog +import java.io.File +import java.nio.file.Files + +@RunWith(RobolectricTestRunner::class) +@Config(sdk = [28], manifest = Config.NONE) +class AgentSecurityTest { + private lateinit var context: Context + + @Before fun prepare() { + context = RuntimeEnvironment.getApplication() + AgentAccess.setCommandsEnabled(context, false) + ShadowBinder.setCallingUid(Process.myUid()) + ShadowLog.clear() + } + + @After fun cleanup() { + ShadowBinder.setCallingUid(Process.myUid()) + AgentAccess.setCommandsEnabled(context, false) + } + + private fun refused(code: String, action: () -> Unit): AgentException { + try { + action() + throw AssertionError("Expected $code") + } catch (e: AgentException) { + assertEquals(code, e.code) + return e + } + } + + private fun call(provider: AgentBridgeProvider, method: String, request: JSONObject = JSONObject()): JSONObject { + val extras = Bundle().apply { + putString("request", Base64.encodeToString(request.toString().toByteArray(), Base64.NO_WRAP)) + } + return JSONObject(provider.call(method, null, extras).getString("json")!!) + } + + @Test fun commandsRequireTheToggleInEveryBuild() { + assertFalse(AgentAccess.commandsAllowed(context)) + refused("AGENT_COMMANDS_DISABLED") { AgentAccess.requireCommands(context) } + AgentAccess.setCommandsEnabled(context, true) + assertTrue(AgentAccess.commandsAllowed(context)) + AgentAccess.requireCommands(context) + AgentAccess.setCommandsEnabled(context, false) + assertFalse(AgentAccess.commandsAllowed(context)) + } + + @Test fun runCannotBypassTheToggle() { + refused("AGENT_COMMANDS_DISABLED") { AgentAccess.requireStart(context, JSONObject().put("mode", "run")) } + AgentAccess.requireStart(context, JSONObject().put("mode", "steam")) + AgentAccess.requireStart(context, JSONObject().put("mode", "desktop")) + val blocked = Robolectric.buildActivity(AgentStartActivity::class.java).get() + val start = AgentStartActivity::class.java.getDeclaredMethod("startSession", JSONObject::class.java).apply { isAccessible = true } + val request = JSONObject().put("mode", "run").put("program", "/usr/bin/sh") + start.invoke(blocked, request) + assertTrue(blocked.isFinishing) + assertNull(shadowOf(blocked).nextStartedActivity) + AgentAccess.setCommandsEnabled(context, true) + AgentAccess.requireStart(context, JSONObject().put("mode", "run")) + val allowed = Robolectric.buildActivity(AgentStartActivity::class.java).get() + start.invoke(allowed, request) + assertEquals("/usr/bin/sh", shadowOf(allowed).nextStartedActivity.getStringExtra("program")) + } + + @Test fun providerRefusesPrivilegedMethodsBeforePerformingThem() { + val provider = Robolectric.buildContentProvider(AgentBridgeProvider::class.java).create().get() + for (method in listOf("guest", "cdp", "override", "prefs", "env")) { + assertEquals(method, "AGENT_COMMANDS_DISABLED", call(provider, method).getJSONObject("error").getString("code")) + } + assertFalse(call(provider, "access").getBoolean("commands")) + assertTrue(call(provider, "state").getBoolean("ok")) + } + + @Test fun providerChecksCallerPermissionBeforeDecoding() { + val provider = Robolectric.buildContentProvider(AgentBridgeProvider::class.java).create().get() + ShadowBinder.setCallingUid(Process.myUid() + 10001) + try { + provider.call("access", null, Bundle().apply { putString("request", "invalid") }) + throw AssertionError("Expected permission refusal") + } catch (e: SecurityException) { + assertTrue(e.message!!.contains("DUMP")) + } + } + + @Test fun oversizedRequestsAreRefused() { + val provider = Robolectric.buildContentProvider(AgentBridgeProvider::class.java).create().get() + val response = provider.call("access", null, Bundle().apply { putString("request", "A".repeat(256 * 1024 + 1)) }) + assertEquals("INVALID_REQUEST", JSONObject(response.getString("json")!!).getJSONObject("error").getString("code")) + } + + @Test fun oversizedResponsesReturnAnErrorInsteadOfOverflowingBinder() { + AgentAccess.setCommandsEnabled(context, true) + context.getSharedPreferences("session", Context.MODE_PRIVATE).edit().putString("large", "x".repeat(400 * 1024)).commit() + val provider = Robolectric.buildContentProvider(AgentBridgeProvider::class.java).create().get() + val response = call(provider, "prefs", JSONObject().put("file", "session")) + assertEquals("RESPONSE_TOO_LARGE", response.getJSONObject("error").getString("code")) + } + + @Test fun invalidTimeoutsAreRefusedBeforeDispatchingToTheGuest() { + AgentAccess.setCommandsEnabled(context, true) + val provider = Robolectric.buildContentProvider(AgentBridgeProvider::class.java).create().get() + for (value in listOf("NaN", "Infinity", "invalid", "0", "601")) { + val response = call(provider, "guest", JSONObject().put("timeout", value)) + assertEquals(value, "INVALID_REQUEST", response.getJSONObject("error").getString("code")) + } + } + + @Test fun directEnvironmentAndPreferenceCallsAlsoRequireConsent() { + refused("AGENT_COMMANDS_DISABLED") { AgentEnv.list(context) } + refused("AGENT_COMMANDS_DISABLED") { AgentEnv.set(context, listOf("TEST=value"), false) } + refused("AGENT_COMMANDS_DISABLED") { AgentEnv.clear(context, "all") } + refused("AGENT_COMMANDS_DISABLED") { AgentEnv.override(context, "gamescope") } + refused("AGENT_COMMANDS_DISABLED") { AgentPrefs.get(context, "session") } + refused("AGENT_COMMANDS_DISABLED") { AgentPrefs.set(context, "session", "test", "bool", "true") } + } + + @Test fun disablingDiscardsEnvironmentAndBinaryOverrides() { + AgentAccess.setCommandsEnabled(context, true) + AgentEnv.set(context, listOf("NEXT=one"), false) + AgentEnv.set(context, listOf("PERSISTENT=two"), true) + File(AgentEnv.inbox(context).apply { mkdirs() }, "gamescope").writeText("test binary") + AgentEnv.override(context, "gamescope") + val installed = File(LinuxRuntime.rootDir(context), "opt/droiddeck-agent/bin/gamescope") + assertTrue(installed.isFile) + AgentAccess.setCommandsEnabled(context, false) + assertFalse(installed.exists()) + assertTrue(AgentEnv.beginSession(context).isEmpty()) + AgentAccess.setCommandsEnabled(context, true) + val state = AgentEnv.list(context) + for (key in listOf("pending", "persistent", "active", "pendingOverrides", "activeOverrides")) { + assertEquals(key, 0, state.getJSONArray(key).length()) + } + } + + @Test fun oldPersistedExperimentsCannotApplyWhileDisabled() { + File(context.filesDir, "agent-env.json").writeText("""{"pending":["TEST=one"],"persistent":["TEST=two"]}""") + assertTrue(AgentEnv.beginSession(context).isEmpty()) + AgentAccess.setCommandsEnabled(context, true) + assertEquals(0, AgentEnv.list(context).getJSONArray("persistent").length()) + } + + @Test fun authorisedExperimentsKeepTheirSessionLifecycle() { + AgentAccess.setCommandsEnabled(context, true) + AgentEnv.set(context, listOf("TEST=old", "STICKY=1"), true) + AgentEnv.set(context, listOf("TEST=new"), false) + assertEquals(listOf("TEST=old", "STICKY=1", "TEST=new"), AgentEnv.beginSession(context)) + AgentEnv.endSession(context) + assertEquals(listOf("TEST=old", "STICKY=1"), AgentEnv.beginSession(context)) + } + + @Test fun environmentValuesAreNotLogged() { + AgentAccess.setCommandsEnabled(context, true) + AgentEnv.set(context, listOf("CUSTOM=synthetic-private-value"), false) + AgentEnv.beginSession(context) + assertFalse(ShadowLog.getLogsForTag("AgentEnv").any { it.msg.contains("synthetic-private-value") }) + assertTrue(ShadowLog.getLogsForTag("AgentEnv").any { it.msg.contains("CUSTOM") }) + } + + @Test fun passwordSemanticsNeverReturnTextOrDescriptions() { + val config = SemanticsConfiguration().apply { + this[SemanticsProperties.Password] = Unit + this[SemanticsProperties.Text] = listOf(AnnotatedString("synthetic-secret")) + this[SemanticsProperties.EditableText] = AnnotatedString("synthetic-secret") + this[SemanticsProperties.ContentDescription] = listOf("synthetic-secret") + this[SemanticsProperties.StateDescription] = "synthetic-secret" + } + val result = AgentUi.textFields(config) + for (key in listOf("text", "editableText", "description", "state")) assertEquals("", result.getString(key)) + assertFalse(result.toString().contains("synthetic-secret")) + } + + @Test fun ordinarySemanticsStayReadableForAgents() { + val config = SemanticsConfiguration().apply { + this[SemanticsProperties.Text] = listOf(AnnotatedString("Play Steam")) + this[SemanticsProperties.StateDescription] = "On" + } + val result = AgentUi.textFields(config) + assertEquals("Play Steam", result.getString("text")) + assertEquals("On", result.getString("state")) + } + + @Test fun disablingDoesNotCrashOrLeaveQueuedValuesWhenCleanupIsUnsafe() { + AgentAccess.setCommandsEnabled(context, true) + AgentEnv.set(context, listOf("TEST=value"), true) + val outside = File(context.filesDir, "cleanup-outside").apply { mkdirs() } + val privateFile = File(outside, "keep").apply { writeText("private") } + val link = File(LinuxRuntime.rootDir(context).apply { mkdirs() }, "opt") + Files.createSymbolicLink(link.toPath(), outside.toPath()) + try { + AgentAccess.setCommandsEnabled(context, false) + assertFalse(AgentAccess.commandsAllowed(context)) + val state = JSONObject(File(context.filesDir, "agent-env.json").readText()) + assertEquals(0, state.getJSONArray("persistent").length()) + assertEquals("private", privateFile.readText()) + } finally { + Files.delete(link.toPath()) + } + } + + @Test fun invalidEnvironmentErrorsDoNotEchoValues() { + AgentAccess.setCommandsEnabled(context, true) + for (line in listOf("=synthetic-private-value", "TEST=synthetic-private-value\nOTHER=x", "TEST=synthetic-private-value\u0000")) { + val error = refused("INVALID_ENV") { AgentEnv.set(context, listOf(line), false) } + assertFalse(error.message!!.contains("synthetic-private-value")) + } + } + + @Test fun preferencesCannotWriteTheGateOrUsePathAliases() { + AgentAccess.setCommandsEnabled(context, true) + refused("PROTECTED_PREFS") { AgentPrefs.set(context, "agent", "commands", "bool", "true") } + for (name in listOf("../agent", "./agent", "/agent", "agent/../agent")) { + refused("INVALID_PREF") { AgentPrefs.set(context, name, "commands", "bool", "true") } + refused("INVALID_PREF") { AgentPrefs.get(context, name) } + } + assertTrue(AgentPrefs.set(context, "session", "test", "bool", "true").getBoolean("value")) + val error = refused("INVALID_PREF") { AgentPrefs.set(context, "session", "test", "int", "synthetic-private-value") } + assertFalse(error.message!!.contains("synthetic-private-value")) + } + + @Test fun overrideRefusesLinksAndTraversalNames() { + AgentAccess.setCommandsEnabled(context, true) + for (name in listOf(".", "..", "../gamescope")) refused("INVALID_NAME") { AgentEnv.override(context, name) } + val target = File(context.filesDir, "private-source").apply { writeText("private") } + val link = File(AgentEnv.inbox(context).apply { mkdirs() }, "linked") + Files.createSymbolicLink(link.toPath(), target.toPath()) + refused("INVALID_NAME") { AgentEnv.override(context, "linked") } + } + + @Test fun overrideNeverFollowsItsInstallDirectoryLink() { + AgentAccess.setCommandsEnabled(context, true) + val outside = File(context.filesDir, "outside").apply { mkdirs() } + val root = LinuxRuntime.rootDir(context).apply { mkdirs() } + val link = File(root, "opt") + Files.createSymbolicLink(link.toPath(), outside.toPath()) + try { + File(AgentEnv.inbox(context).apply { mkdirs() }, "gamescope").writeText("test binary") + refused("OVERRIDE_FAILED") { AgentEnv.override(context, "gamescope") } + assertTrue(outside.listFiles()!!.isEmpty()) + } finally { + Files.delete(link.toPath()) + } + } +} diff --git a/docs/agent-control.md b/docs/agent-control.md index 77e4ce583e..62ad534ada 100644 --- a/docs/agent-control.md +++ b/docs/agent-control.md @@ -1,41 +1,191 @@ # Agent control -The debug APK exposes a ContentProvider at `content://com.droiddeck.launcher.agent` and an Activity for starting sessions. Android's shell-only `DUMP` permission protects both. They are absent from release APKs. +`tools/droiddeckctl` drives DroidDeck on a real device over ADB, for agents and scripts that test +the app end to end: start and stop sessions, launch and quit Steam games, wait for a game to have +focus, send input, inspect the app's UI and gamescope's windows, run commands inside the session, +and collect logs, screenshots and recordings. `tools/droiddeck-scenario` repeats a scripted test +and reports every run. -Build and install the debug APK: +## How it works + +- **The provider** `content://com.droiddeck.launcher.agent` (`agent/AgentBridgeProvider.kt`) + answers each command with JSON. It and the session-start Activity (`AgentStartActivity`) are in + every build and require `android.permission.DUMP`, held by the ADB shell and privileged or + explicitly granted callers. The provider checks the calling permission before decoding requests. +- **The guest agent** `droiddeck-agent` runs inside every session (started by + `droiddeck-session`). It runs commands with the session's own environment, publishes gamescope's + focus, and talks to the Steam client's DevTools, which only accepts guest processes. The app and + the agent exchange request and answer files under the session root (`files/session/agent`). +- **The UI dump** reads the app's Compose semantics from inside the app (`agent/AgentUi.kt`), so it + works on every display and window. UI Automator, by contrast, dumps whichever window has focus, + which on a dual-screen device is often another app's. + +## Access + +Player controls and observations work over authorized ADB on any build: `state`, `start`, `stop`, +`resume`, `wait`, `launch`, `quit`, `focus`, `input`, `ui`, `logs`, `screenshot`, `record`, `displays`, +`wake`, and `access`. + +**Setup > Session > Debugging tools** is off by default in every build, including debug builds. +It enables `run`, `guest`, `cdp`, all `env` operations, `override`, and `prefs`. The toggle switches +directly without a confirmation dialog. The bridge refuses to change it through `ui` or preference +writes. The existing preference key, `setting-agent-commands` test tag, JSON command names, and +`AGENT_COMMANDS_DISABLED` error code are unchanged. Refusals exit 7; `droiddeckctl access` reports +whether commands are enabled. + +Disabling the toggle clears queued and persistent agent environment settings and installed binary +overrides. Disabled settings cannot apply at the next session start. Already running commands and +effects already applied to a session are not undone; stop and restart that session to discard them. + +Authorized command execution runs inside the runtime containing Steam's saved login. CDP evaluates +JavaScript in the authenticated Steam client, and preferences can contain private values. These +capabilities remain unrestricted when enabled: the toggle is an explicit opt-in, not credential +isolation or a sandbox against the authorized caller. Main already supported arbitrary guest +programs through `run`; restricting credential access would require addressing that route too. +ADB access remains a trust boundary, and ADB input can operate the device's own toggle. + +The helper exchanges private files with the app and adds no network listener. The guarded Steam +DevTools port is bound to loopback and accepts only peers with a fresh private registration for a +live socket descriptor, matching socket inode, destination port, and address family. The existing +x86_64 Decky loader exception remains: that mode does not enable the guest-only acceptance guard. + +Requests are limited to 256 KiB of encoded JSON. Guest responses and DevTools messages are limited +to 1 MiB; provider replies above 384 Ki characters return `RESPONSE_TOO_LARGE` to avoid overflowing +Binder. Command output retains at most 256 KiB per stream while continuing to drain both streams. +Timeouts must be finite, positive, and no greater than 600 seconds, and terminate the command's +process group. Override installation refuses path traversal and symbolic links. + +Automatic process logs record environment keys and argument counts rather than values or full +argument lists. UI nodes marked as passwords redact text, editable text, descriptions, and state +text. This does not redact arbitrary authorized command results, CDP data, preferences, or screen +captures. Scenario directories are owner-only and JSON reports are written with mode 0600. Review +artifacts before sharing; a live `logs` pull copies the current folder without a fresh export scrub. + +## Device selection and output + +The CLI resolves one authorized device using `ADB_SERIAL` or `ANDROID_SERIAL` when set. Otherwise it +de-duplicates transports that report the same device serial and asks for an explicit serial if +multiple devices remain. Pass `--serial` before the command to choose directly; set `ADB` (or pass +`--adb`) to choose an adb executable. `tools/deploy_local.sh` uses the same resolver. + +Every command writes one JSON object to stdout and its resolved serial to stderr. Exit codes: 0 +success, 2 invalid or rejected command, 3 ADB or device error, 4 session error, 5 timeout, 6 +artifact or file error, 7 debugging tools disabled. + +## Commands ```sh -./gradlew assembleDebug --console=plain -adb install -r app/build/outputs/apk/debug/app-debug.apk -``` - -The provider can also be called directly for state, stop, and resume: - -```sh -adb shell content call --uri content://com.droiddeck.launcher.agent --method state -adb shell content call --uri content://com.droiddeck.launcher.agent --method stop -``` - -Start requests go through `tools/droiddeckctl`, which launches the protected debug Activity from the ADB shell. Calling the provider's `start` method directly returns an error because a background provider cannot reliably open the session screen. - -The host CLI resolves one authorized device using `ADB_SERIAL` or `ANDROID_SERIAL` when set. Otherwise it deduplicates transports that report the same device serial and asks for an explicit serial if multiple devices remain. - -```sh -tools/droiddeckctl state --json -tools/droiddeckctl start steam -tools/droiddeckctl wait ready --timeout 90 +tools/droiddeckctl state # schema 2, below +tools/droiddeckctl start steam --wait # --ui desktop, --url steam://..., --timeout +tools/droiddeckctl start steam --wait --reuse # keep a Steam session that is already up tools/droiddeckctl start desktop tools/droiddeckctl run /usr/bin/foo -- arg1 arg2 +tools/droiddeckctl wait ready|idle|failed # --timeout (default 90 s) tools/droiddeckctl stop tools/droiddeckctl resume + +tools/droiddeckctl launch 489830 --wait # Steam game by app id; --wait = until it has focus +tools/droiddeckctl wait focused 489830 # gamescope focuses it AND Steam lists it focusable +tools/droiddeckctl wait game # any app but the Steam client (769) has focus +tools/droiddeckctl quit 489830 # Steam's TerminateApp, then SIGTERM/SIGKILL +tools/droiddeckctl focus # focus properties and every Xwayland server's windows + +tools/droiddeckctl input key ENTER # names (ESC, F1, UP, A...) or evdev codes; --mod CTRL +tools/droiddeckctl input text 'hello world' # as US-layout keys; --commit for text-input +tools/droiddeckctl input tap 640 360 # session output pixels; --space fraction for 0..1 +tools/droiddeckctl input swipe 100 600 100 100 --duration 400 +tools/droiddeckctl input pad a # a b x y lb rb start select guide qam up down left right +tools/droiddeckctl input stick left 0 -1 --hold 500 +tools/droiddeckctl input trigger right 1.0 + +tools/droiddeckctl ui dump # tagged, labelled and clickable nodes; --all for every node +tools/droiddeckctl ui click rail-steam # by test tag +tools/droiddeckctl ui click --match "Play" # by text or description; --index for the nth match +tools/droiddeckctl ui set-text some-field --text abc + +tools/droiddeckctl guest -- xprop -root GAMESCOPE_FOCUSED_APP # --timeout --env K=V --cwd --stdin --check +tools/droiddeckctl cdp targets +tools/droiddeckctl cdp eval 'SteamClient.Apps.GetMyRunningApps?.()' # --target, --no-await +tools/droiddeckctl env set DXVK_HUD=fps # next session only; --persistent until cleared +tools/droiddeckctl env list +tools/droiddeckctl env clear [next|persistent|all] +tools/droiddeckctl override gamescope ./gamescope # first on the next session's PATH, removed after it +tools/droiddeckctl prefs get session +tools/droiddeckctl prefs set session some_key true --type bool # returns the previous value + tools/droiddeckctl logs latest ./session-artifacts -tools/droiddeckctl screenshot ./screen.png +tools/droiddeckctl screenshot ./screen.png --display 4 +tools/droiddeckctl record ./clip.mp4 --seconds 8 --display 0 +tools/droiddeckctl displays # logical ids, names, sizes, capture ids +tools/droiddeckctl wake # wake the screen, dismiss the keyguard ``` -Every command writes JSON to stdout and reports its resolved ADB serial to stderr. Exit codes are 0 for success, 2 for invalid or rejected commands, 3 for ADB/device errors, 4 for session failures, 5 for timeouts, and 6 for artifact or file errors. Set `ADB` to select an adb executable (or pass `--adb`); pass `--serial` before the command to select a device directly. +A sleeping device suspends the session and hides the app's windows from `ui dump`; `wake` first. -`start` accepts `steam` or `desktop`. Steam starts in Big Picture by default; `--ui desktop` selects the client's desktop UI, and `--url steam://...` passes a client URL. Use `--wait` to wait for `READY` as part of `start`. `run` accepts a program path and optional guest arguments. +`input` needs a session that has drawn its first frame. Pad input goes through the session screen's +virtual pad, the same one the on-screen controls drive, so games that ignore touch still respond. +`launch`, `quit` and `cdp` need a Steam session; `focus` and `wait focused` need gamescope (every +mode except the desktop). -The `state` response uses schema 1 and includes the build label, runtime version, session ID and phase, mode, requested program, suspend and first-frame state, output size, guest PID, failure details, and artifact paths. Phases are `IDLE`, `PREPARING`, `INSTALLING_RUNTIME`, `STARTING_COMPOSITOR`, `STARTING_GUEST`, `STARTING_STEAM`, `READY`, `SUSPENDED`, `STOPPING`, and `FAILED`. Each session also writes `events.jsonl` alongside its existing artifacts. +## State (schema 2) -`tools/deploy_local.sh` uses the same device resolver. If multiple distinct devices are connected, select one with `ADB_SERIAL` or `ANDROID_SERIAL`. +`state` returns `schema`, `build`, `appVersion`, `runtime {installed, version}`, +`agent {guest, guestFocus, commands}` and `session`: + +- `id`, `phase`, `running`, `mode`, `program`, `steamUi`, `steamUrl`, `suspended`, `pip`, + `firstFrame`, `output` [w, h], `refreshHz`, `lastTransitionAt`, `guestPid`, `installing` +- `logDir`, `eventsFile`, `artifactsAvailable`, `artifactsComplete`, `failure {code, message, status}` +- `focus`: gamescope's focus as the guest agent last published it, or null: + `focusedApp`, `focusedWindow`, `focusableApps`, `baselayerAppIds`, `seq`, `t`. + +Phases: `IDLE`, `PREPARING`, `INSTALLING_RUNTIME`, `STARTING_COMPOSITOR`, `STARTING_GUEST`, +`STARTING_STEAM`, `READY`, `SUSPENDED`, `STOPPING`, `FAILED`. Schema 2 only added `agent` and +`session.focus`; every schema 1 field is unchanged. + +A game the player can see is `focusedApp == appId` **and** `appId in focusableApps`. +`GAMESCOPE_FOCUSABLE_WINDOWS` is what the Steam client orders the base layer from: a game missing +there stays behind the client's loading screen however healthy its window looks +(docs/development/steam-focus-debugging.md). `focus` returns the full snapshot, including each +server's windows with map state, override-redirect, app id, `WM_STATE`, pid, class, opacity and +`_NET_WM_STATE`. + +## Events + +Each session writes `events.jsonl` beside its other artifacts: the lifecycle (`session.created`, +`compositor.started`, `guest.exited`, ...) plus `agent.ready` (the guest agent is up), +`focus.changed` (the focused app, focusable apps or base-layer order changed) and +`agent.launch_requested`. + +## UI test tags + +Compose test tags are exposed as resource ids (`ui/TestTags.kt`), so both `ui dump` and UI +Automator show them: + +| Tag | Where | +|---|---| +| `rail-steam`, `rail-games`, `rail-desktop`, `rail-store`, `rail-components`, `rail-android-apps`, `rail-setup`, `rail-updates` | the front end's rail | +| `play-steam` | Play on the Steam and Games pages | +| `setting-` | every toggle and choice row, by its key (`setting-logs`, `setting-agent-commands`, ...) | +| `tab-` | a page's tab strip (Setup's Overview, Controller, Session, Launcher...), by position | +| `drawer-tab-controller`, `-second_screen`, `-display`, `-effects`, `-games`, `-session` | the session drawer's pages | +| `drawer-stop`, `drawer-stop-confirm`, `drawer-stop-cancel` | stopping a session from the drawer | + +## Scenarios + +`tools/droiddeck-scenario` runs a JSON scenario: `setup` once, `steps` `repeat` times, `teardown` +once. Each run starts with `before` (typically `start steam --wait --reuse`, so a session that died +in one run, to a crash or the low-memory killer, is started again for the next) and ends with +`after`, whether it passed or not, so a failed run cannot leave a game running into the next. A list step is a droiddeckctl command line; `{"assert": "dotted.path", "equals"|"in"| +"contains"|"not"|"exists": ...}` checks the last answer; `{"sleep"}`, `{"screenshot"}` and +`{"record"}` do what they say. A failing run keeps a screenshot, the focus snapshot and the +session's logs in its folder, and `report.json` sums up the runs. + +```sh +tools/droiddeck-scenario tools/scenarios/steam-game-focus.json --var appId=489830 --repeat 10 --keep-going +``` + +`tools/scenarios/steam-game-focus.json` launches a game, checks it has focus the way a player +sees it, and quits it: the test that catches a game left behind Steam's loading screen, which only +shows up in some fraction of launches. A game with a launcher of its own needs the launcher pressed +through first, since the launcher window carries the game's app id too: +`tools/scenarios/skyrim-launcher-focus.json` taps Skyrim's Play before checking. diff --git a/tools/droiddeck-scenario b/tools/droiddeck-scenario new file mode 100755 index 0000000000..2a37eebfb6 --- /dev/null +++ b/tools/droiddeck-scenario @@ -0,0 +1,245 @@ +#!/usr/bin/env python3 +"""Run a device scenario through droiddeckctl, repeatedly, and report each run. + +A scenario is JSON (stdlib only, no YAML): + + { + "name": "skyrim-focus", + "vars": {"appId": 489830}, + "repeat": 6, + "setup": [["wake"]], + "before": [["start", "steam", "--wait", "--reuse", "--timeout", "180"]], + "steps": [["launch", "${appId}", "--wait", "--timeout", "240"], + {"assert": "session.focus.focusedApp", "equals": "${appId}"}, + {"screenshot": "in-game"}, + ["quit", "${appId}"]], + "after": [["quit", "${appId}"]], + "teardown": [["stop"]] + } + +A list step is a droiddeckctl command line; its JSON answer becomes "last". An assert step checks +a dotted path in the last answer ("equals", "in", "contains", "exists", "not"); {"sleep": s}, +{"screenshot": "name"} and {"record": "name", "seconds": s} do what they say. ${var} is replaced +from "vars" and --var KEY=VALUE. setup and teardown run once; steps run "repeat" times (or +--repeat), each preceded by "before" (a failure there fails the run) and followed by "after" +whether it passed or not, so a failed run cannot leave a game running into the next and a session +that died in one run is started again for the next. A failing run gets a screenshot, the focus state and the session's logs in +its folder. + + tools/droiddeck-scenario tools/scenarios/steam-game-focus.json --var appId=489830 --out ./runs + +Exit status: 0 when every run passed, 1 when any failed, 2 for a bad scenario or a failed setup. +""" + +from __future__ import annotations + +import argparse +import importlib.machinery +import importlib.util +import json +import os +import re +import sys +import time +from pathlib import Path + +HERE = Path(__file__).resolve().parent +sys.path.insert(0, str(HERE)) +_loader = importlib.machinery.SourceFileLoader("droiddeckctl", str(HERE / "droiddeckctl")) +_spec = importlib.util.spec_from_loader("droiddeckctl", _loader) +ctl = importlib.util.module_from_spec(_spec) +_loader.exec_module(ctl) + + +class StepFailed(Exception): + pass + + +def write_json(path: Path, value) -> None: + with os.fdopen(os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600), "w") as stream: + os.fchmod(stream.fileno(), 0o600) + json.dump(value, stream, indent=2, sort_keys=True) + + +def substitute(value, variables: dict): + if isinstance(value, str): + whole = re.fullmatch(r"\$\{(\w+)\}", value) + if whole and whole.group(1) in variables: + return variables[whole.group(1)] + return re.sub(r"\$\{(\w+)\}", lambda m: str(variables.get(m.group(1), m.group(0))), value) + if isinstance(value, list): + return [substitute(v, variables) for v in value] + if isinstance(value, dict): + return {k: substitute(v, variables) for k, v in value.items()} + return value + + +def lookup(data, path: str): + for part in path.split("."): + if isinstance(data, list) and part.isdigit(): + data = data[int(part)] if int(part) < len(data) else None + elif isinstance(data, dict): + data = data.get(part) + else: + return None + return data + + +def check(step: dict, last: dict) -> None: + path = step["assert"] + value = lookup(last, path) + if "equals" in step and value != step["equals"]: + raise StepFailed(f"{path} is {value!r}, expected {step['equals']!r}") + if "not" in step and value == step["not"]: + raise StepFailed(f"{path} is {value!r}") + if "in" in step and value not in step["in"]: + raise StepFailed(f"{path} is {value!r}, expected one of {step['in']!r}") + if "contains" in step and (not isinstance(value, (list, str)) or step["contains"] not in value): + raise StepFailed(f"{path} is {value!r}, expected it to contain {step['contains']!r}") + if step.get("exists") is True and value is None: + raise StepFailed(f"{path} is missing") + + +class Runner: + def __init__(self, adb: str, serial: str, out: Path, global_args: list[str]): + self.adb = adb + self.serial = serial + self.out = out + self.global_args = global_args + self.parser = ctl.build_parser() + + def ctl(self, words: list) -> dict: + args = self.parser.parse_args(self.global_args + [str(w) for w in words]) + try: + return ctl.execute(args, self.adb, self.serial) + except ctl.ControlError as exc: + raise StepFailed(f"droiddeckctl {' '.join(map(str, words))}: {exc.code}: {exc}") from exc + + def run_steps(self, steps: list, folder: Path, log: list) -> None: + last: dict = {} + for index, step in enumerate(steps): + started = time.monotonic() + entry = {"step": index, "what": step} + try: + if isinstance(step, list): + last = self.ctl(step) + entry["result"] = last + elif "assert" in step: + check(step, last) + elif "sleep" in step: + time.sleep(float(step["sleep"])) + elif "screenshot" in step: + entry["result"] = ctl.screenshot(self.adb, self.serial, str(folder / f"{step['screenshot']}.png"), + step.get("display")) + elif "record" in step: + entry["result"] = ctl.record(self.adb, self.serial, str(folder / f"{step['record']}.mp4"), + float(step.get("seconds", 10)), step.get("display")) + else: + raise StepFailed(f"Unknown step {step!r}") + entry["ok"] = True + except (StepFailed, ctl.ControlError) as exc: + entry["ok"] = False + entry["error"] = str(exc) + raise StepFailed(f"step {index} {json.dumps(step)}: {exc}") from exc + finally: + entry["seconds"] = round(time.monotonic() - started, 2) + log.append(entry) + + def evidence(self, folder: Path) -> dict: + """What a failed run leaves behind: the screen, gamescope's focus, the session's logs.""" + found = {} + for name, action in ( + ("screenshot", lambda: ctl.screenshot(self.adb, self.serial, str(folder / "failure.png"), None)), + ("focus", lambda: self.ctl(["focus"])), + ("logs", lambda: self.ctl(["logs", "latest", str(folder / "session")])), + ): + try: + found[name] = action() + except Exception as exc: # evidence is best effort + found[name] = {"ok": False, "error": str(exc)} + write_json(folder / "evidence.json", found) + return {k: v.get("ok", True) if isinstance(v, dict) else True for k, v in found.items()} + + +def main(argv: list[str] | None = None) -> int: + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + parser.add_argument("scenario") + parser.add_argument("--var", action="append", default=[], metavar="KEY=VALUE") + parser.add_argument("--repeat", type=int) + parser.add_argument("--out", default="scenario-runs") + parser.add_argument("--adb") + parser.add_argument("--serial") + parser.add_argument("--keep-going", action="store_true", help="run every repeat even after a failure") + args = parser.parse_args(argv) + + try: + scenario = json.loads(Path(args.scenario).read_text()) + except (OSError, ValueError) as exc: + print(json.dumps({"ok": False, "error": f"Cannot read scenario: {exc}"})) + return 2 + variables = dict(scenario.get("vars", {})) + for item in args.var: + key, _, value = item.partition("=") + variables[key] = int(value) if value.lstrip("-").isdigit() else value + scenario = substitute(scenario, variables) + repeat = args.repeat or int(scenario.get("repeat", 1)) + + adb = ctl.adb_path(args.adb) + serial = ctl.resolve_serial(adb, args.serial, log=True) + out = Path(args.out).expanduser().resolve() / f"{scenario.get('name', 'scenario')}-{time.strftime('%Y%m%d-%H%M%S')}" + out.mkdir(parents=True, exist_ok=True, mode=0o700) + global_args = (["--adb", adb] if args.adb else []) + ["--serial", serial] + runner = Runner(adb, serial, out, global_args) + report = {"name": scenario.get("name"), "serial": serial, "vars": variables, "repeat": repeat, + "out": str(out), "runs": []} + + status = 0 + setup_log: list = [] + try: + runner.run_steps(scenario.get("setup", []), out, setup_log) + for run in range(1, repeat + 1): + folder = out / f"run-{run:02d}" + folder.mkdir(mode=0o700) + log: list = [] + started = time.monotonic() + result = {"run": run, "folder": str(folder)} + try: + runner.run_steps(scenario.get("before", []) + scenario.get("steps", []), folder, log) + result["ok"] = True + except StepFailed as exc: + result["ok"] = False + result["error"] = str(exc) + result["evidence"] = runner.evidence(folder) + status = 1 + after: list = [] + try: + runner.run_steps(scenario.get("after", []), folder, after) + except StepFailed as exc: + result["afterError"] = str(exc) + log.extend({**entry, "after": True} for entry in after) + result["seconds"] = round(time.monotonic() - started, 2) + write_json(folder / "steps.json", log) + report["runs"].append(result) + print(f"run {run}/{repeat}: {'PASS' if result['ok'] else 'FAIL ' + result['error']}", file=sys.stderr) + if not result["ok"] and not args.keep_going: + break + except StepFailed as exc: + report["setupError"] = str(exc) + status = 2 + finally: + teardown_log: list = [] + try: + runner.run_steps(scenario.get("teardown", []), out, teardown_log) + except StepFailed as exc: + report["teardownError"] = str(exc) + write_json(out / "setup.json", setup_log + teardown_log) + + passed = sum(1 for r in report["runs"] if r["ok"]) + report.update({"ok": status == 0, "passed": passed, "failed": len(report["runs"]) - passed}) + write_json(out / "report.json", report) + print(json.dumps(report, indent=2, sort_keys=True)) + return status + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/droiddeckctl b/tools/droiddeckctl index b73c5ac29f..db21fa31a5 100755 --- a/tools/droiddeckctl +++ b/tools/droiddeckctl @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -"""Control a debug DroidDeck build over ADB.""" +"""Control a DroidDeck build over ADB (docs/agent-control.md).""" from __future__ import annotations @@ -7,16 +7,21 @@ import argparse import base64 import json import os +import re import shutil import subprocess import sys import time from pathlib import Path -from adb_device import DeviceResolutionError, resolve_serial +sys.path.insert(0, str(Path(__file__).resolve().parent)) +from adb_device import DeviceResolutionError, resolve_serial # noqa: E402 AUTHORITY = "content://com.droiddeck.launcher.agent" +PACKAGE = "com.droiddeck.launcher" +STEAM_CLIENT_APP = 769 +REQUEST_CAP = 256 * 1024 class ControlError(RuntimeError): @@ -46,7 +51,7 @@ def adb_path(configured: str | None) -> str: raise ControlError("adb not found; set ADB, ANDROID_HOME, or ANDROID_SDK_ROOT", "ADB_NOT_FOUND") -def run_adb(adb: str, serial: str, *args: str, timeout: int = 30) -> subprocess.CompletedProcess[bytes]: +def run_adb(adb: str, serial: str, *args: str, timeout: float = 30) -> subprocess.CompletedProcess[bytes]: try: return subprocess.run( [adb, "-s", serial, *args], capture_output=True, check=False, timeout=timeout @@ -59,7 +64,7 @@ def _content_result(output: str) -> dict: marker = "json=" start = output.find(marker) if start < 0: - detail = output.strip() or "The debug agent provider returned no result" + detail = output.strip() or "The agent provider returned no result" raise ControlError(detail, "INVALID_PROVIDER_RESPONSE") raw = output[start + len(marker):].lstrip() try: @@ -71,14 +76,22 @@ def _content_result(output: str) -> dict: raise ControlError("Could not decode the agent provider response", "INVALID_PROVIDER_RESPONSE") from exc -def provider_call(adb: str, serial: str, method: str, arg: str | None = None, request: dict | None = None) -> dict: +def encode_request(request: dict) -> str: + encoded = base64.b64encode(json.dumps(request, separators=(",", ":")).encode()).decode() + if len(encoded) > REQUEST_CAP: + raise ControlError("The encoded request exceeds 256 KiB", "INVALID_REQUEST") + return encoded + + +def provider_call(adb: str, serial: str, method: str, arg: str | None = None, request: dict | None = None, + timeout: float = 30) -> dict: command = ["shell", "content", "call", "--uri", AUTHORITY, "--method", method] if arg is not None: command.extend(["--arg", arg]) if request is not None: - encoded = base64.b64encode(json.dumps(request, separators=(",", ":")).encode()).decode() + encoded = encode_request(request) command.extend(["--extra", f"request:s:{encoded}"]) - result = run_adb(adb, serial, *command) + result = run_adb(adb, serial, *command, timeout=timeout) output = (result.stdout + result.stderr).decode(errors="replace") response = _content_result(output) if result.returncode != 0 and response.get("ok") is not False: @@ -86,8 +99,16 @@ def provider_call(adb: str, serial: str, method: str, arg: str | None = None, re return response +def checked(response: dict, default_code: str) -> dict: + """A provider or guest answer, raised as a ControlError when it carries ok: false.""" + if response.get("ok") is False: + error = response.get("error", {}) + raise ControlError(error.get("message", default_code), error.get("code", default_code)) + return response + + def start_agent_activity(adb: str, serial: str, request: dict) -> None: - encoded = base64.b64encode(json.dumps(request, separators=(",", ":")).encode()).decode() + encoded = encode_request(request) result = run_adb( adb, serial, @@ -96,7 +117,7 @@ def start_agent_activity(adb: str, serial: str, request: dict) -> None: "start", "-W", "-n", - "com.droiddeck.launcher/.agent.AgentStartActivity", + f"{PACKAGE}/.agent.AgentStartActivity", "--es", "request", encoded, @@ -126,23 +147,18 @@ def confirm_start(adb: str, serial: str, request: dict, previous: dict) -> dict: def get_state(adb: str, serial: str) -> dict: - response = provider_call(adb, serial, "state") - if response.get("ok") is False: - error = response.get("error", {}) - raise ControlError(error.get("message", "state failed"), error.get("code", "STATE_FAILED")) - return response + return checked(provider_call(adb, serial, "state"), "STATE_FAILED") -def wait_for_phase(adb: str, serial: str, wanted: str, timeout: float) -> dict: +def wait_until(adb: str, serial: str, describe: str, done, timeout: float, poll: float = 1.0) -> dict: + """Poll state until done(state) is true. A failed session ends the wait at once.""" deadline = time.monotonic() + timeout - last_state: dict | None = None while True: - last_state = get_state(adb, serial) - session = last_state.get("session", {}) - phase = session.get("phase") - if phase == wanted: - return last_state - if phase == "FAILED" and wanted != "FAILED": + state = get_state(adb, serial) + session = state.get("session", {}) + if done(state): + return state + if session.get("phase") == "FAILED": failure = session.get("failure") or {} raise ControlError( f"Session failed ({failure.get('code', 'FAILED')}): {failure.get('message', 'unknown error')}", @@ -150,10 +166,35 @@ def wait_for_phase(adb: str, serial: str, wanted: str, timeout: float) -> dict: ) remaining = deadline - time.monotonic() if remaining <= 0: + focus = session.get("focus") or {} raise ControlError( - f"Timed out waiting for {wanted}; last phase was {phase}", "TIMEOUT" + f"Timed out waiting for {describe}; phase {session.get('phase')}, focused app {focus.get('focusedApp')}", + "TIMEOUT", ) - time.sleep(min(1.0, remaining)) + time.sleep(min(poll, remaining)) + + +def wait_for_phase(adb: str, serial: str, wanted: str, timeout: float) -> dict: + if wanted == "FAILED": + deadline = time.monotonic() + timeout + while True: + state = get_state(adb, serial) + if state.get("session", {}).get("phase") == "FAILED": + return state + if time.monotonic() > deadline: + raise ControlError("Timed out waiting for FAILED", "TIMEOUT") + time.sleep(1) + return wait_until(adb, serial, wanted, lambda s: s.get("session", {}).get("phase") == wanted, timeout) + + +def focused(state: dict, app_id: int | None) -> bool: + """The game has focus the way a player sees it: gamescope focuses it and it is in the list the + Steam client orders the base layer from. app_id None means any game (not the client).""" + focus = state.get("session", {}).get("focus") or {} + current = focus.get("focusedApp") + if app_id is None: + return current not in (None, 0, STEAM_CLIENT_APP) + return current == app_id and app_id in (focus.get("focusableApps") or []) def wait_for_artifacts(adb: str, serial: str, state: dict, timeout: float) -> dict: @@ -174,14 +215,123 @@ def add_serial(response: dict, serial: str) -> dict: return response +# --- displays ------------------------------------------------------------------------------------ + +def displays(adb: str, serial: str) -> list[dict]: + """Logical displays with the SurfaceFlinger (physical) id screencap and screenrecord want.""" + result = run_adb(adb, serial, "shell", "dumpsys", "display", timeout=30) + text = result.stdout.decode(errors="replace") + devices = dict(re.findall(r'DisplayDeviceInfo\{"([^"]+)": uniqueId="local:(\d+)"', text)) + out = [] + for block in re.split(r"\n Display (?=\d+:)", text)[1:]: + logical = int(block.split(":", 1)[0]) + device = re.search(r"mPrimaryDisplayDevice=(.+)", block) + size = re.search(r"real (\d+) x (\d+)", block) + name = device.group(1).strip() if device else None + out.append({ + "display": logical, + "name": name, + "physicalId": devices.get(name) if name else None, + "size": [int(size.group(1)), int(size.group(2))] if size else None, + }) + return out + + +def physical_display(adb: str, serial: str, logical: int | None) -> str | None: + if logical is None: + return None + for d in displays(adb, serial): + if d["display"] == logical: + if not d["physicalId"]: + raise ControlError(f"Display {logical} has no physical id to capture", "NO_SUCH_DISPLAY") + return d["physicalId"] + raise ControlError(f"No display {logical}; see `droiddeckctl displays`", "NO_SUCH_DISPLAY") + + +def screenshot(adb: str, serial: str, path: str, display: int | None) -> dict: + destination = Path(path).expanduser().resolve() + physical = physical_display(adb, serial, display) + command = ["exec-out", "screencap", "-p"] + (["-d", physical] if physical else []) + result = run_adb(adb, serial, *command, timeout=30) + if result.returncode != 0 or not result.stdout.startswith(b"\x89PNG"): + detail = result.stderr.decode(errors="replace").strip() + raise ControlError(detail or "screencap failed", "SCREENSHOT_FAILED") + try: + destination.parent.mkdir(parents=True, exist_ok=True) + destination.write_bytes(result.stdout) + except OSError as exc: + raise ControlError(str(exc), "FILE_IO") from exc + return {"ok": True, "command": "screenshot", "path": str(destination), "display": display} + + +def record(adb: str, serial: str, path: str, seconds: float, display: int | None) -> dict: + destination = Path(path).expanduser().resolve() + remote = "/data/local/tmp/droiddeckctl-record.mp4" + physical = physical_display(adb, serial, display) + command = ["shell", "screenrecord", "--time-limit", str(max(1, min(180, int(seconds))))] + if physical: + command += ["--display-id", physical] + result = run_adb(adb, serial, *command, remote, timeout=seconds + 30) + if result.returncode != 0: + raise ControlError(result.stderr.decode(errors="replace").strip() or "screenrecord failed", "RECORD_FAILED") + try: + destination.parent.mkdir(parents=True, exist_ok=True) + except OSError as exc: + raise ControlError(str(exc), "FILE_IO") from exc + pulled = run_adb(adb, serial, "pull", remote, str(destination), timeout=120) + run_adb(adb, serial, "shell", "rm", "-f", remote) + if pulled.returncode != 0: + raise ControlError(pulled.stderr.decode(errors="replace").strip() or "adb pull failed", "RECORD_FAILED") + return {"ok": True, "command": "record", "path": str(destination), "seconds": seconds, "display": display} + + +# --- commands ------------------------------------------------------------------------------------ + +def start_session(adb: str, serial: str, request: dict) -> dict: + if request.get("mode") == "run": + require_commands(adb, serial) + current = get_state(adb, serial) + if current["session"].get("phase") not in {"IDLE", "FAILED"} or current["session"].get("running"): + raise ControlError("A session is already starting or running", "SESSION_ACTIVE") + start_agent_activity(adb, serial, request) + return confirm_start(adb, serial, request, current["session"]) + + +def require_commands(adb: str, serial: str) -> dict: + access = checked(provider_call(adb, serial, "access"), "ACCESS_FAILED") + if access.get("commands") is not True: + raise ControlError("Debugging tools are off: turn on Setup > Session > Debugging tools on the device", + "AGENT_COMMANDS_DISABLED") + return access + + +def input_request(args: argparse.Namespace) -> dict: + kind = args.input_type + if kind == "key": + return {"type": "key", "key": args.key, "action": args.action, "modifiers": args.mod or [], "holdMs": args.hold} + if kind == "text": + return {"type": "text", "text": args.text, "commit": args.commit} + if kind == "tap": + return {"type": "tap", "x": args.x, "y": args.y, "space": args.space, "holdMs": args.hold} + if kind == "swipe": + return {"type": "swipe", "x": args.x, "y": args.y, "x2": args.x2, "y2": args.y2, + "space": args.space, "durationMs": args.duration} + if kind == "pad": + return {"type": "pad", "button": args.button, "action": args.action, "holdMs": args.hold} + if kind == "stick": + return {"type": "stick", "stick": args.stick, "x": args.x, "y": args.y, "holdMs": args.hold} + if kind == "trigger": + return {"type": "trigger", "trigger": args.trigger, "value": args.value, "holdMs": args.hold} + raise ControlError(f"Unknown input type {kind}", "INVALID_INPUT") + + def execute(args: argparse.Namespace, adb: str, serial: str) -> dict: - if args.command == "state": + command = args.command + + if command == "state": return add_serial(get_state(adb, serial), serial) - if args.command == "start": - current = get_state(adb, serial) - if current["session"].get("phase") not in {"IDLE", "FAILED"} or current["session"].get("running"): - raise ControlError("A session is already starting or running", "SESSION_ACTIVE") + if command == "start": request = {"mode": args.mode} if args.mode == "steam": if args.ui == "desktop": @@ -190,59 +340,152 @@ def execute(args: argparse.Namespace, adb: str, serial: str) -> dict: if not args.url.startswith("steam://"): raise ControlError("Steam URL must start with steam://", "INVALID_STEAM_URL") request["steamUrl"] = args.url - start_agent_activity(adb, serial, request) - started = confirm_start(adb, serial, request, current["session"]) + if args.reuse: + # A scenario's per-run "before": keep a session of this mode that is already up, so only + # a run after one that ended (a crash, the low-memory killer) starts a new one. + current = get_state(adb, serial)["session"] + wanted = {"steam": "steam", "desktop": "lxqt"}[args.mode] + if current.get("running") and current.get("mode") == wanted and current.get("phase") not in {"STOPPING", "FAILED"}: + state = wait_for_phase(adb, serial, "READY", args.timeout) if args.wait else get_state(adb, serial) + return add_serial(dict(state, reused=True), serial) + started = start_session(adb, serial, request) if args.wait: return add_serial(wait_for_phase(adb, serial, "READY", args.timeout), serial) session = started["session"] - return add_serial({ - "ok": True, - "command": "start", - "mode": args.mode, - "sessionId": session.get("id"), - "phase": session.get("phase"), - }, serial) + return add_serial({"ok": True, "command": "start", "mode": args.mode, + "sessionId": session.get("id"), "phase": session.get("phase")}, serial) - if args.command == "run": - current = get_state(adb, serial) - if current["session"].get("phase") not in {"IDLE", "FAILED"} or current["session"].get("running"): - raise ControlError("A session is already starting or running", "SESSION_ACTIVE") + if command == "run": program_args = args.arguments[1:] if args.arguments[:1] == ["--"] else args.arguments - request = {"mode": "run", "program": args.program, "programArgs": program_args} - start_agent_activity(adb, serial, request) - started = confirm_start(adb, serial, request, current["session"]) + started = start_session(adb, serial, {"mode": "run", "program": args.program, "programArgs": program_args}) session = started["session"] - return add_serial({ - "ok": True, - "command": "start", - "mode": "run", - "sessionId": session.get("id"), - "phase": session.get("phase"), - }, serial) + return add_serial({"ok": True, "command": "start", "mode": "run", + "sessionId": session.get("id"), "phase": session.get("phase")}, serial) - if args.command == "wait": + if command == "wait": + if args.phase == "focused": + if args.app_id is None: + raise ControlError("wait focused needs an app id", "INVALID_ARGUMENTS") + return add_serial(wait_until(adb, serial, f"app {args.app_id} to have focus", + lambda s: focused(s, args.app_id), args.timeout, 0.5), serial) + if args.phase == "game": + return add_serial(wait_until(adb, serial, "a game to have focus", + lambda s: focused(s, None), args.timeout, 0.5), serial) phases = {"ready": "READY", "idle": "IDLE", "failed": "FAILED"} return add_serial(wait_for_phase(adb, serial, phases[args.phase], args.timeout), serial) - if args.command == "stop": + if command == "stop": current = get_state(adb, serial) if current["session"].get("phase") in {"IDLE", "FAILED"}: - return add_serial(wait_for_artifacts(adb, serial, current, args.timeout), serial) - response = provider_call(adb, serial, "stop") - if response.get("ok") is False: - error = response.get("error", {}) - raise ControlError(error.get("message", "stop failed"), error.get("code", "STOP_FAILED")) + return add_serial(wait_for_artifacts(adb, serial, current, args.artifact_timeout), serial) + checked(provider_call(adb, serial, "stop"), "STOP_FAILED") state = wait_for_phase(adb, serial, "IDLE", args.timeout) - return add_serial(wait_for_artifacts(adb, serial, state, args.timeout), serial) + return add_serial(wait_for_artifacts(adb, serial, state, args.artifact_timeout), serial) - if args.command == "resume": - response = provider_call(adb, serial, "resume") - if response.get("ok") is False: - error = response.get("error", {}) - raise ControlError(error.get("message", "resume failed"), error.get("code", "RESUME_FAILED")) + if command == "resume": + return add_serial(checked(provider_call(adb, serial, "resume"), "RESUME_FAILED"), serial) + + if command == "launch": + response = checked(provider_call(adb, serial, "launch", request={"appId": str(args.app_id)}), "LAUNCH_FAILED") + if args.wait: + state = wait_until(adb, serial, f"app {args.app_id} to have focus", + lambda s: focused(s, args.app_id), args.timeout, 0.5) + response["focus"] = state["session"].get("focus") return add_serial(response, serial) - if args.command == "logs": + if command == "quit": + response = provider_call(adb, serial, "quit", request={"appId": args.app_id, "timeout": args.timeout}, + timeout=args.timeout + 40) + return add_serial(checked(response, "QUIT_FAILED"), serial) + + if command == "focus": + return add_serial(checked(provider_call(adb, serial, "focus", timeout=40), "FOCUS_FAILED"), serial) + + if command == "guest": + argv = args.argv[1:] if args.argv[:1] == ["--"] else args.argv + if not argv: + raise ControlError("guest needs a command after --", "INVALID_ARGUMENTS") + env = {} + for item in args.env or []: + key, sep, value = item.partition("=") + if not sep: + raise ControlError(f"--env takes KEY=VALUE, not {item}", "INVALID_ARGUMENTS") + env[key] = value + request = {"argv": argv, "timeout": args.timeout, "env": env} + if args.cwd: + request["cwd"] = args.cwd + if args.stdin is not None: + request["stdin"] = args.stdin + response = checked(provider_call(adb, serial, "guest", request=request, timeout=args.timeout + 40), "GUEST_FAILED") + if args.check and response.get("exitCode") != 0: + raise ControlError(f"{argv[0]} exited with {response.get('exitCode')}: " + f"{(response.get('stderr') or {}).get('text', '')[-400:]}", "GUEST_EXIT") + return add_serial(response, serial) + + if command == "cdp": + if args.cdp_op == "targets": + request = {"op": "targets"} + else: + request = {"op": "eval", "expression": args.expression, "awaitPromise": not args.no_await, + "timeout": args.timeout} + if args.target: + request["target"] = args.target + timeout = getattr(args, "timeout", 15) + return add_serial(checked(provider_call(adb, serial, "cdp", request=request, timeout=timeout + 40), + "CDP_FAILED"), serial) + + if command == "input": + return add_serial(checked(provider_call(adb, serial, "input", request=input_request(args), timeout=60), + "INPUT_FAILED"), serial) + + if command == "ui": + if args.ui_op == "dump": + request = {"op": "dump", "all": args.all} + else: + request = {"op": args.ui_op, "index": args.index} + if args.match: + request["match"] = args.match + else: + request["tag"] = args.tag + if args.ui_op == "set-text": + request["text"] = args.text + return add_serial(checked(provider_call(adb, serial, "ui", request=request), "UI_FAILED"), serial) + + if command == "env": + if args.env_op == "set": + request = {"op": "set", "lines": args.lines, "persistent": args.persistent} + elif args.env_op == "clear": + request = {"op": "clear", "scope": args.scope} + else: + request = {"op": "list"} + return add_serial(checked(provider_call(adb, serial, "env", request=request), "ENV_FAILED"), serial) + + if command == "override": + access = require_commands(adb, serial) + if not re.fullmatch(r"[A-Za-z0-9._-]{1,64}", args.name) or args.name in {".", ".."}: + raise ControlError("Override names must be simple filenames", "INVALID_NAME") + source = Path(args.path).expanduser() + if not source.is_file(): + raise ControlError(f"No such file: {source}", "FILE_IO") + inbox = access["inbox"] + run_adb(adb, serial, "shell", "mkdir", "-p", inbox) + pushed = run_adb(adb, serial, "push", str(source), f"{inbox}/{args.name}", timeout=300) + if pushed.returncode != 0: + raise ControlError(pushed.stderr.decode(errors="replace").strip() or "adb push failed", "PUSH_FAILED") + return add_serial(checked(provider_call(adb, serial, "override", request={"name": args.name}), + "OVERRIDE_FAILED"), serial) + + if command == "prefs": + if args.prefs_op == "set": + request = {"op": "set", "file": args.file, "key": args.key, "type": args.type, "value": args.value} + else: + request = {"op": "get", "file": args.file} + return add_serial(checked(provider_call(adb, serial, "prefs", request=request), "PREFS_FAILED"), serial) + + if command == "access": + return add_serial(checked(provider_call(adb, serial, "access"), "ACCESS_FAILED"), serial) + + if command == "logs": state = get_state(adb, serial) session = state.get("session", {}) if not session.get("running") and session.get("artifactsAvailable") and not session.get("artifactsComplete"): @@ -258,20 +501,24 @@ def execute(args: argparse.Namespace, adb: str, serial: str) -> dict: raise ControlError(detail or "adb pull failed", "LOG_PULL_FAILED") return add_serial({"ok": True, "command": "logs", "sessionId": session["id"], "path": str(destination)}, serial) - if args.command == "screenshot": - destination = Path(args.path).expanduser().resolve() - result = run_adb(adb, serial, "exec-out", "screencap", "-p", timeout=30) - if result.returncode != 0: - detail = result.stderr.decode(errors="replace").strip() - raise ControlError(detail or "screencap failed", "SCREENSHOT_FAILED") - try: - destination.parent.mkdir(parents=True, exist_ok=True) - destination.write_bytes(result.stdout) - except OSError as exc: - raise ControlError(str(exc), "FILE_IO") from exc - return add_serial({"ok": True, "command": "screenshot", "path": str(destination)}, serial) + if command == "screenshot": + return add_serial(screenshot(adb, serial, args.path, args.display), serial) - raise ControlError(f"Unknown command: {args.command}", "UNKNOWN_COMMAND") + if command == "record": + return add_serial(record(adb, serial, args.path, args.seconds, args.display), serial) + + if command == "wake": + # A sleeping device stops the session and hides the app's windows from ui dump. + run_adb(adb, serial, "shell", "input", "keyevent", "KEYCODE_WAKEUP") + run_adb(adb, serial, "shell", "wm", "dismiss-keyguard") + power = run_adb(adb, serial, "shell", "dumpsys", "power").stdout.decode(errors="replace") + awake = re.search(r"mWakefulness=(\w+)", power) + return add_serial({"ok": True, "command": "wake", "wakefulness": awake.group(1) if awake else None}, serial) + + if command == "displays": + return add_serial({"ok": True, "command": "displays", "displays": displays(adb, serial)}, serial) + + raise ControlError(f"Unknown command: {command}", "UNKNOWN_COMMAND") def build_parser() -> argparse.ArgumentParser: @@ -288,49 +535,172 @@ def build_parser() -> argparse.ArgumentParser: start.add_argument("--ui", choices=["bigpicture", "desktop"], default="bigpicture") start.add_argument("--url", help="steam:// URL to pass to the client") start.add_argument("--wait", action="store_true", help="wait for READY after starting") + start.add_argument("--reuse", action="store_true", help="keep a running session of this mode instead of failing") start.add_argument("--timeout", type=float, default=90) run = commands.add_parser("run", help="run a guest program under Gamescope") run.add_argument("program") run.add_argument("arguments", nargs=argparse.REMAINDER) - wait = commands.add_parser("wait", help="wait for a session phase") - wait.add_argument("phase", choices=["ready", "idle", "failed"]) + wait = commands.add_parser("wait", help="wait for a session phase, or for a game to have focus") + wait.add_argument("phase", choices=["ready", "idle", "failed", "focused", "game"]) + wait.add_argument("app_id", nargs="?", type=int, help="with focused: the Steam app id") wait.add_argument("--timeout", type=float, default=90) stop = commands.add_parser("stop", help="stop the session and wait for IDLE") stop.add_argument("--timeout", type=float, default=90) + # Collecting the client's logs and redacting them took about two minutes after a Skyrim session. + stop.add_argument("--artifact-timeout", type=float, default=300) commands.add_parser("resume", help="resume a suspended session") + launch = commands.add_parser("launch", help="launch a Steam game in the running Steam session") + launch.add_argument("app_id", type=int) + launch.add_argument("--wait", action="store_true", help="wait until the game has focus") + launch.add_argument("--timeout", type=float, default=180) + + quit_ = commands.add_parser("quit", help="quit a running game (through the client, then signals)") + quit_.add_argument("app_id", type=int) + quit_.add_argument("--timeout", type=float, default=15) + + commands.add_parser("focus", help="gamescope's focus and every Xwayland server's windows, fresh") + + guest = commands.add_parser("guest", help="run a command inside the session (debugging tools)") + guest.add_argument("--timeout", type=float, default=30) + guest.add_argument("--env", action="append", metavar="KEY=VALUE") + guest.add_argument("--cwd") + guest.add_argument("--stdin") + guest.add_argument("--check", action="store_true", help="fail unless the command exits 0") + guest.add_argument("argv", nargs=argparse.REMAINDER) + + cdp = commands.add_parser("cdp", help="the Steam client's DevTools (debugging tools)") + cdp_ops = cdp.add_subparsers(dest="cdp_op", required=True) + cdp_ops.add_parser("targets", help="list DevTools targets") + evaluate = cdp_ops.add_parser("eval", help="evaluate JavaScript (default target SharedJSContext)") + evaluate.add_argument("expression") + evaluate.add_argument("--target", help="title or URL substring of the target") + evaluate.add_argument("--no-await", action="store_true", help="do not await a returned promise") + evaluate.add_argument("--timeout", type=float, default=15) + + inp = commands.add_parser("input", help="keys, text, touch and pad input into the session") + kinds = inp.add_subparsers(dest="input_type", required=True) + key = kinds.add_parser("key", help="a key by name (ENTER, ESC, A, F1...) or evdev code") + key.add_argument("key") + key.add_argument("--action", choices=["tap", "down", "up"], default="tap") + key.add_argument("--mod", action="append", help="modifier held around a tap (CTRL, SHIFT, ALT, META)") + key.add_argument("--hold", type=int, default=40, help="ms between down and up") + text = kinds.add_parser("text", help="type text (US layout keys; --commit for text-input)") + text.add_argument("text") + text.add_argument("--commit", action="store_true") + tap = kinds.add_parser("tap", help="touch at a point of the session's output") + tap.add_argument("x", type=float) + tap.add_argument("y", type=float) + tap.add_argument("--space", choices=["output", "fraction"], default="output") + tap.add_argument("--hold", type=int, default=60) + swipe = kinds.add_parser("swipe", help="drag a touch from one point to another") + for name in ("x", "y", "x2", "y2"): + swipe.add_argument(name, type=float) + swipe.add_argument("--space", choices=["output", "fraction"], default="output") + swipe.add_argument("--duration", type=int, default=300) + pad = kinds.add_parser("pad", help="a virtual pad button (a, b, x, y, lb, rb, start, select, guide, qam, up...)") + pad.add_argument("button") + pad.add_argument("--action", choices=["tap", "down", "up"], default="tap") + pad.add_argument("--hold", type=int, default=120) + stick = kinds.add_parser("stick", help="hold a stick at x, y (-1..1)") + stick.add_argument("stick", choices=["left", "right"]) + stick.add_argument("x", type=float) + stick.add_argument("y", type=float) + stick.add_argument("--hold", type=int, default=300) + trigger = kinds.add_parser("trigger", help="hold a trigger (0..1)") + trigger.add_argument("trigger", choices=["left", "right"]) + trigger.add_argument("value", type=float, nargs="?", default=1.0) + trigger.add_argument("--hold", type=int, default=200) + + ui = commands.add_parser("ui", help="the app's own UI: dump nodes, click or type by test tag") + ui_ops = ui.add_subparsers(dest="ui_op", required=True) + dump = ui_ops.add_parser("dump", help="tagged, labelled and clickable nodes of every app window") + dump.add_argument("--all", action="store_true", help="every node") + for name in ("click", "set-text"): + op = ui_ops.add_parser(name) + op.add_argument("tag", nargs="?", help="test tag, e.g. rail-steam") + op.add_argument("--match", help="instead of a tag: text or description containing this") + op.add_argument("--index", type=int, default=0, help="which match, in tree order") + if name == "set-text": + op.add_argument("--text", required=True) + + env = commands.add_parser("env", help="session environment lines (debugging tools)") + env_ops = env.add_subparsers(dest="env_op", required=True) + env_ops.add_parser("list") + env_set = env_ops.add_parser("set", help="KEY=VALUE lines for the next session") + env_set.add_argument("lines", nargs="+") + env_set.add_argument("--persistent", action="store_true", help="every session until cleared") + env_clear = env_ops.add_parser("clear") + env_clear.add_argument("scope", nargs="?", choices=["next", "persistent", "all"], default="next") + + override = commands.add_parser("override", help="put a binary first on the next session's PATH (debugging tools)") + override.add_argument("name", help="the program name, e.g. gamescope") + override.add_argument("path", help="the local file to push") + + prefs = commands.add_parser("prefs", help="the app's preferences (debugging tools)") + prefs_ops = prefs.add_subparsers(dest="prefs_op", required=True) + prefs_get = prefs_ops.add_parser("get") + prefs_get.add_argument("file", help="preferences file, e.g. session") + prefs_set = prefs_ops.add_parser("set") + prefs_set.add_argument("file") + prefs_set.add_argument("key") + prefs_set.add_argument("value", nargs="?") + prefs_set.add_argument("--type", choices=["bool", "int", "long", "float", "string", "remove"], default="string") + + commands.add_parser("access", help="whether debugging tools are enabled on the device") + logs = commands.add_parser("logs", help="pull the latest session artifact directory") logs.add_argument("which", choices=["latest"]) logs.add_argument("destination", nargs="?") logs.add_argument("--timeout", type=float, default=90) - screenshot = commands.add_parser("screenshot", help="save a device screenshot") - screenshot.add_argument("path") + shot = commands.add_parser("screenshot", help="save a device screenshot") + shot.add_argument("path") + shot.add_argument("--display", type=int, help="logical display id (see displays); default the default display") + + rec = commands.add_parser("record", help="record the screen to an mp4") + rec.add_argument("path") + rec.add_argument("--seconds", type=float, default=10) + rec.add_argument("--display", type=int) + + commands.add_parser("displays", help="the device's displays and their capture ids") + commands.add_parser("wake", help="wake the device and dismiss the keyguard") return parser +EXIT_ADB = {"ADB_NOT_FOUND", "ADB_FAILED", "INVALID_PROVIDER_RESPONSE"} +EXIT_SESSION = { + "SESSION_ACTIVE", "NO_ACTIVE_SESSION", "SESSION_NOT_SUSPENDED", "SESSION_FAILED", "GUEST_EXIT", + "GUEST_START_FAILED", "RUNTIME_INSTALL_FAILED", "DESKTOP_INSTALL_FAILED", "ACTIVITY_START_FAILED", + "NO_STEAM_SESSION", "SESSION_NOT_READY", "AGENT_UNAVAILABLE", "LAUNCH_REJECTED", "NO_PAD", +} +EXIT_TIMEOUT = {"TIMEOUT", "ARTIFACT_TIMEOUT"} +EXIT_FILE = {"NO_SESSION_LOGS", "LOG_PULL_FAILED", "SCREENSHOT_FAILED", "FILE_IO", "RECORD_FAILED", "PUSH_FAILED"} +EXIT_DENIED = {"AGENT_COMMANDS_DISABLED", "PROTECTED_PREFS", "PROTECTED_CONTROL"} + + def exit_code(exc: Exception) -> int: if isinstance(exc, DeviceResolutionError): return 3 code = getattr(exc, "code", "") - if code in {"ADB_NOT_FOUND", "ADB_FAILED", "INVALID_PROVIDER_RESPONSE"}: + if code in EXIT_ADB: return 3 - if code in {"SESSION_ACTIVE", "NO_ACTIVE_SESSION", "SESSION_NOT_SUSPENDED", "SESSION_FAILED", - "GUEST_EXIT", "GUEST_START_FAILED", "RUNTIME_INSTALL_FAILED", "DESKTOP_INSTALL_FAILED", - "ACTIVITY_START_FAILED"}: + if code in EXIT_SESSION: return 4 - if code in {"TIMEOUT", "ARTIFACT_TIMEOUT"}: + if code in EXIT_TIMEOUT: return 5 - if code in {"NO_SESSION_LOGS", "LOG_PULL_FAILED", "SCREENSHOT_FAILED", "FILE_IO"}: + if code in EXIT_FILE: return 6 + if code in EXIT_DENIED: + return 7 return 2 -def main() -> int: - args = build_parser().parse_args() +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) serial = None try: adb = adb_path(args.adb) @@ -340,11 +710,15 @@ def main() -> int: return 0 except (ControlError, DeviceResolutionError) as exc: error = {"code": getattr(exc, "code", "DEVICE_RESOLUTION_FAILED"), "message": str(exc)} - response = {"ok": False, "error": error} - if serial: - response["deviceSerial"] = serial - print(json.dumps(response, indent=2, sort_keys=True)) - return exit_code(exc) + code = exit_code(exc) + except Exception as exc: # the contract is JSON on stdout, even for a bug in this tool + error = {"code": "INTERNAL_ERROR", "message": f"{type(exc).__name__}: {exc}"} + code = 2 + response = {"ok": False, "error": error} + if serial: + response["deviceSerial"] = serial + print(json.dumps(response, indent=2, sort_keys=True)) + return code if __name__ == "__main__": diff --git a/tools/linuxfs/overlay/usr/local/bin/droiddeck-agent b/tools/linuxfs/overlay/usr/local/bin/droiddeck-agent new file mode 100755 index 0000000000..972c1502b8 --- /dev/null +++ b/tools/linuxfs/overlay/usr/local/bin/droiddeck-agent @@ -0,0 +1,687 @@ +#!/usr/bin/python3 +"""The guest side of the agent bridge (docs/agent-control.md). + +Started by droiddeck-session inside the session, so whatever it runs has the session's own +environment: DISPLAY, the games' Xwayland, XDG_RUNTIME_DIR, and the preloads every guest process +gets - which is what lets it reach the Steam client's DevTools port, open to guest processes only. + +The app talks to it through files under $BL_LAUNCH_DIR/agent (the session root, the same path on +both sides): + + req/.json a request the app wrote (tmp + rename) + resp/.json the answer, written the same way + hello.json this daemon is up: pid, version, what it can do + focus.json gamescope's focus and every server's top-level windows, rewritten on change + cdp-port the client's DevTools port, written by droiddeck-session + +Requests: ping, exec, focus, cdp, quit. Each answer is {"ok": true, ...} or +{"ok": false, "error": {"code", "message"}}. +""" + +import base64 +import json +import math +import os +import selectors +import signal +import socket +import struct +import subprocess +import sys +import threading +import time +import urllib.request +import urllib.parse +from pathlib import Path + +VERSION = 1 +OUTPUT_CAP = 256 * 1024 +REQUEST_CAP = 256 * 1024 +RESPONSE_CAP = 1024 * 1024 +FOCUS_PROPS = ( + "GAMESCOPE_FOCUSED_APP", "GAMESCOPE_FOCUSED_WINDOW", "GAMESCOPE_FOCUSABLE_APPS", + "GAMESCOPE_FOCUSABLE_WINDOWS", "GAMESCOPECTRL_BASELAYER_APPID", +) +WINDOW_PROPS = ( + "STEAM_GAME", "WM_STATE", "_NET_WM_PID", "WM_CLASS", "_NET_WM_WINDOW_OPACITY", "STEAM_OVERLAY", + "GAMESCOPE_EXTERNAL_OVERLAY", "STEAM_INPUT_FOCUS", "_NET_WM_STATE", +) +MAP_STATE = ("unmapped", "unviewable", "viewable") +WM_STATES = {0: "withdrawn", 1: "normal", 3: "iconic"} + + +def log(message): + print("== agent: " + message, flush=True) + + +def write_json(path, value): + tmp = path.with_name(path.name + ".tmp") + with os.fdopen(os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC | os.O_NOFOLLOW, 0o600), "w") as stream: + os.fchmod(stream.fileno(), 0o600) + json.dump(value, stream, separators=(",", ":")) + os.replace(tmp, path) + + +class AgentError(Exception): + def __init__(self, code, message): + super().__init__(message) + self.code = code + + +# --- X11: just enough of the protocol for root properties, the window tree and events --------- + +class X: + """One connection to an Xwayland server. The rootfs has xprop but no python X library.""" + + def __init__(self, display): + num = display.lstrip(":").split(".")[0] + last = None + for address in ("\0/tmp/.X11-unix/X" + num, "/tmp/.X11-unix/X" + num): + try: + self.s = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) + self.s.settimeout(3) + self.s.connect(address) + break + except OSError as e: + last = e + self.s.close() + else: + raise last + self.s.sendall(struct.pack(" 1: + return head + + def atom(self, name): + if name not in self._atoms: + n = name.encode() + pad = (4 - len(n) % 4) % 4 + r = self.request(struct.pack(" 16 * 1024: + raise AgentError("RESPONSE_TOO_LARGE", "The DevTools handshake exceeds 16 KiB") + status = head.split(b"\r\n", 1)[0] + if b" 101 " not in status: + raise OSError("DevTools refused the WebSocket: " + status.decode(errors="replace")) + self.buffer = head.split(b"\r\n\r\n", 1)[1] + + def _read(self, n): + while len(self.buffer) < n: + chunk = self.s.recv(65536) + if not chunk: + raise OSError("DevTools closed the connection") + self.buffer += chunk + data, self.buffer = self.buffer[:n], self.buffer[n:] + return data + + def send(self, text): + payload = text.encode() + header = bytearray([0x81]) + n = len(payload) + if n < 126: + header.append(0x80 | n) + elif n < 65536: + header.append(0x80 | 126) + header += struct.pack(">H", n) + else: + header.append(0x80 | 127) + header += struct.pack(">Q", n) + mask = os.urandom(4) + header += mask + self.s.sendall(bytes(header) + bytes(b ^ mask[i % 4] for i, b in enumerate(payload))) + + def recv(self): + message = b"" + while True: + b0, b1 = self._read(2) + n = b1 & 0x7F + if n == 126: + n = struct.unpack(">H", self._read(2))[0] + elif n == 127: + n = struct.unpack(">Q", self._read(8))[0] + if n > RESPONSE_CAP or len(message) + n > RESPONSE_CAP: + raise AgentError("RESPONSE_TOO_LARGE", "The DevTools response exceeds 1 MiB") + mask = self._read(4) if b1 & 0x80 else None + data = self._read(n) + if mask: + data = bytes(b ^ mask[i % 4] for i, b in enumerate(data)) + op = b0 & 0x0F + if op == 8: + raise OSError("DevTools closed the WebSocket") + if op == 9: # ping + continue + if op in (0, 1, 2): + message += data + if b0 & 0x80: + return message.decode(errors="replace") + + def close(self): + try: + self.s.close() + except OSError: + pass + + +def cdp_port(agent_dir): + try: + port = (agent_dir / "cdp-port").read_text().strip() + except OSError: + port = os.environ.get("BL_CDP_PORT", "") + if not port.isdigit(): + raise AgentError("NO_DEVTOOLS", "The Steam client's DevTools port is not known (no Steam client in this session yet)") + return int(port) + + +def cdp_targets(agent_dir, timeout=5): + url = "http://127.0.0.1:%d/json" % cdp_port(agent_dir) + try: + with urllib.request.urlopen(url, timeout=timeout) as r: + data = r.read(RESPONSE_CAP + 1) + if len(data) > RESPONSE_CAP: + raise AgentError("RESPONSE_TOO_LARGE", "The DevTools response exceeds 1 MiB") + return json.loads(data.decode()) + except OSError as e: + raise AgentError("DEVTOOLS_UNREACHABLE", "Could not reach the client's DevTools at %s: %s" % (url, e)) + + +def cdp_eval(agent_dir, expression, target=None, await_promise=True, timeout=15): + targets = [t for t in cdp_targets(agent_dir) if t.get("webSocketDebuggerUrl")] + want = target or "SharedJSContext" + match = [t for t in targets if want in (t.get("title") or "") or want in (t.get("url") or "")] + if not match: + names = ", ".join(sorted({t.get("title") or t.get("url") or "?" for t in targets})) + raise AgentError("NO_TARGET", "No DevTools target matches '%s' (have: %s)" % (want, names)) + ws = WebSocket(match[0]["webSocketDebuggerUrl"], timeout) + try: + ws.send(json.dumps({"id": 1, "method": "Runtime.evaluate", "params": { + "expression": expression, "returnByValue": True, "awaitPromise": await_promise, + "userGesture": True, + }})) + deadline = time.monotonic() + timeout + while time.monotonic() < deadline: + message = json.loads(ws.recv()) + if message.get("id") != 1: + continue + if "error" in message: + raise AgentError("CDP_ERROR", json.dumps(message["error"])) + result = message.get("result", {}) + if result.get("exceptionDetails"): + details = result["exceptionDetails"] + text = (details.get("exception") or {}).get("description") or details.get("text") or "exception" + raise AgentError("JS_EXCEPTION", text) + value = result.get("result", {}) + return {"target": match[0].get("title"), "type": value.get("type"), + "value": value.get("value"), "description": value.get("description")} + raise AgentError("TIMEOUT", "No answer from DevTools in %ss" % timeout) + finally: + ws.close() + + +# --- Game processes ------------------------------------------------------------------------------ + +def game_pids(app_id): + """Our processes started for this Steam app (Steam sets SteamAppId / SteamGameId in their + environment, and Proton's wine processes inherit it).""" + wanted = [("SteamAppId=%s" % app_id).encode(), ("SteamGameId=%s" % app_id).encode()] + me = os.getpid() + pids = [] + for entry in os.listdir("/proc"): + if not entry.isdigit() or int(entry) == me: + continue + try: + with open("/proc/%s/environ" % entry, "rb") as f: + env = f.read().split(b"\0") + except OSError: + continue + if any(w in env for w in wanted): + pids.append(int(entry)) + return pids + + +def quit_game(agent_dir, app_id, timeout): + if not str(app_id).isdigit(): + raise AgentError("INVALID_APP_ID", "appId must be a decimal Steam app id") + steps = [] + if game_pids(app_id): + try: + cdp_eval(agent_dir, "SteamClient.Apps.TerminateApp(%s, false)" % json.dumps(str(app_id)), timeout=5) + steps.append("client") + except AgentError as e: + steps.append("client unavailable: %s" % e) + deadline = time.monotonic() + timeout + while game_pids(app_id) and time.monotonic() < deadline: + time.sleep(0.5) + left = game_pids(app_id) + if left: + steps.append("SIGTERM %s" % left) + for pid in left: + try: + os.kill(pid, signal.SIGTERM) + except OSError: + pass + end = time.monotonic() + 5 + while game_pids(app_id) and time.monotonic() < end: + time.sleep(0.5) + left = game_pids(app_id) + if left: + steps.append("SIGKILL %s" % left) + for pid in left: + try: + os.kill(pid, signal.SIGKILL) + except OSError: + pass + time.sleep(1) + return {"appId": int(app_id), "steps": steps, "remaining": game_pids(app_id)} + + +# --- Requests ------------------------------------------------------------------------------------ + +def run_exec(req): + argv = req.get("argv") + if not isinstance(argv, list) or not argv or not all(isinstance(a, str) and "\0" not in a for a in argv): + raise AgentError("INVALID_REQUEST", "exec needs argv, a non-empty list of strings") + timeout = request_timeout(req, 30) + env = dict(os.environ) + extra_env = req.get("env") if req.get("env") is not None else {} + if not isinstance(extra_env, dict) or any("\0" in str(k) or "=" in str(k) or "\0" in str(v) for k, v in extra_env.items()): + raise AgentError("INVALID_REQUEST", "env must be an object with valid environment entries") + env.update({str(k): str(v) for k, v in extra_env.items()}) + stdin = req.get("stdin") + if stdin is not None and not isinstance(stdin, str): + raise AgentError("INVALID_REQUEST", "stdin must be a string") + started = time.monotonic() + try: + proc = subprocess.Popen( + argv, cwd=req.get("cwd") or None, env=env, start_new_session=True, + stdin=subprocess.PIPE if stdin is not None else subprocess.DEVNULL, + stdout=subprocess.PIPE, stderr=subprocess.PIPE, + ) + except OSError as e: + raise AgentError("EXEC_FAILED", "%s: %s" % (argv[0], e)) + captured = {"stdout": bytearray(), "stderr": bytearray()} + truncated = {"stdout": False, "stderr": False} + pending = memoryview(stdin.encode()) if stdin is not None else memoryview(b"") + deadline = started + timeout + timed_out = False + try: + with selectors.DefaultSelector() as selector: + for stream, name in ((proc.stdout, "stdout"), (proc.stderr, "stderr")): + os.set_blocking(stream.fileno(), False) + selector.register(stream, selectors.EVENT_READ, name) + if proc.stdin is not None: + os.set_blocking(proc.stdin.fileno(), False) + if pending: + selector.register(proc.stdin, selectors.EVENT_WRITE, "stdin") + else: + proc.stdin.close() + while selector.get_map() or proc.poll() is None: + remaining = deadline - time.monotonic() + if remaining <= 0: + timed_out = True + break + for key, _ in selector.select(min(0.1, remaining)): + stream, name = key.fileobj, key.data + if name == "stdin": + try: + pending = pending[os.write(stream.fileno(), pending[:65536]):] + except BrokenPipeError: + pending = pending[len(pending):] + if not pending: + selector.unregister(stream) + stream.close() + else: + data = os.read(stream.fileno(), 65536) + if not data: + selector.unregister(stream) + stream.close() + continue + available = OUTPUT_CAP - len(captured[name]) + captured[name].extend(data[:available]) + truncated[name] |= len(data) > available + if timed_out: + try: + os.killpg(proc.pid, signal.SIGKILL) + except ProcessLookupError: + pass + proc.wait(timeout=5) + finally: + if proc.poll() is None: + try: + os.killpg(proc.pid, signal.SIGKILL) + except ProcessLookupError: + pass + proc.wait(timeout=5) + for stream in (proc.stdin, proc.stdout, proc.stderr): + if stream is not None: + stream.close() + + def text(name): + return {"text": captured[name].decode(errors="replace"), "truncated": truncated[name]} + + return {"exitCode": proc.returncode, "timedOut": timed_out, + "seconds": round(time.monotonic() - started, 3), "stdout": text("stdout"), "stderr": text("stderr")} + + +def request_timeout(req, default): + try: + timeout = float(req.get("timeout", default)) + except (TypeError, ValueError): + raise AgentError("INVALID_REQUEST", "timeout must be a positive number no greater than 600 seconds") + if not math.isfinite(timeout) or not 0 < timeout <= 600: + raise AgentError("INVALID_REQUEST", "timeout must be a positive number no greater than 600 seconds") + return timeout + + +def handle(agent_dir, req): + kind = req.get("kind") + if kind == "ping": + return {"pid": os.getpid(), "version": VERSION, "displays": displays()} + if kind == "exec": + return run_exec(req) + if kind == "focus": + return focus_snapshot() + if kind == "cdp": + if req.get("op") == "targets": + return {"targets": [{k: t.get(k) for k in ("title", "url", "type")} for t in cdp_targets(agent_dir)]} + expression = req.get("expression") + if not isinstance(expression, str) or not expression: + raise AgentError("INVALID_REQUEST", "cdp eval needs an expression") + return cdp_eval(agent_dir, expression, req.get("target"), bool(req.get("awaitPromise", True)), + request_timeout(req, 15)) + if kind == "quit": + return quit_game(agent_dir, req.get("appId"), request_timeout(req, 15)) + raise AgentError("UNKNOWN_REQUEST", "Unknown agent request '%s'" % kind) + + +def answer(agent_dir, path): + rid = path.stem + try: + with path.open("rb") as stream: + data = stream.read(REQUEST_CAP + 1) + if len(data) > REQUEST_CAP: + raise ValueError("The request exceeds 256 KiB") + req = json.loads(data) + if not isinstance(req, dict): + raise ValueError("The request must be a JSON object") + except (OSError, ValueError) as e: + req = None + result = {"ok": False, "error": {"code": "INVALID_REQUEST", "message": str(e)}} + finally: + try: + path.unlink() + except OSError: + pass + if req is not None: + try: + result = dict(handle(agent_dir, req), ok=True) + except AgentError as e: + result = {"ok": False, "error": {"code": e.code, "message": str(e)}} + except Exception as e: # an answer of some kind always goes back + result = {"ok": False, "error": {"code": "AGENT_FAILED", "message": "%s: %s" % (type(e).__name__, e)}} + write_json(agent_dir / "resp" / (rid + ".json"), result) + + +def serve(agent_dir, focus=True, poll=0.1): + (agent_dir / "req").mkdir(parents=True, exist_ok=True) + (agent_dir / "resp").mkdir(parents=True, exist_ok=True) + can_focus = focus and bool(os.environ.get("DISPLAY")) + if can_focus: + FocusWatcher(agent_dir / "focus.json").start() + write_json(agent_dir / "hello.json", {"pid": os.getpid(), "version": VERSION, "started": int(time.time() * 1000), + "displays": displays(), "focus": can_focus}) + log("serving %s (focus %s)" % (agent_dir, "on" if can_focus else "off")) + taken = set() + while True: + for path in sorted((agent_dir / "req").glob("*.json")): + if path.name in taken: + continue + taken.add(path.name) + threading.Thread(target=lambda p=path: (answer(agent_dir, p), taken.discard(p.name)), + daemon=True, name="req").start() + time.sleep(poll) + + +def main(argv): + base = os.environ.get("BL_LAUNCH_DIR") + if not base: + print("BL_LAUNCH_DIR is not set", file=sys.stderr) + return 2 + serve(Path(base) / "agent", focus="--no-focus" not in argv) + return 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/tools/linuxfs/overlay/usr/local/bin/droiddeck-session b/tools/linuxfs/overlay/usr/local/bin/droiddeck-session index 6654ddb0f0..77205c03ce 100755 --- a/tools/linuxfs/overlay/usr/local/bin/droiddeck-session +++ b/tools/linuxfs/overlay/usr/local/bin/droiddeck-session @@ -97,6 +97,14 @@ export GAMESCOPE_FORCE_VULKAN_REALTIME=${BL_GAMESCOPE_REALTIME:-0} # A sleep that starts no process. Under proot every exec is a traced execve plus the loader's # opens and maps, and the watchers below poll for the whole session: `sleep 1` in a loop was 60 # execs a minute each. read -t on a pipe nothing ever writes to waits in bash itself. +# The agent bridge's guest side (docs/agent-control.md): runs what the app's agent provider asks +# for inside this session and publishes gamescope's focus. Its files live under the session root +# ($BL_LAUNCH_DIR/agent), which the app empties before each session. +start_agent() { + [ -n "${BL_LAUNCH_DIR:-}" ] && [ -x /usr/local/bin/droiddeck-agent ] || return 0 + mkdir -p "$BL_LAUNCH_DIR/agent" + /usr/local/bin/droiddeck-agent "$@" 2>&1 & +} nap() { [ -n "${bl_nap_fd:-}" ] || exec {bl_nap_fd}<> <(:) read -r -t "$1" -u "$bl_nap_fd" _ 2>/dev/null || : @@ -166,6 +174,7 @@ if [ -z "${BL_INSIDE:-}" ]; then # into the app's: no gamescope in between. if [ "$mode" = lxqt ]; then step "starting the desktop" + start_agent --no-focus [ -x /usr/local/bin/droiddeck-desktop ] || { echo "== the desktop package is not installed"; exit 66; } cores=$(program_cores) if [ -n "$cores" ]; then @@ -284,6 +293,8 @@ if [ -n "${BL_ANDROID_CLIPBOARD:-}" ] && [ -x /usr/local/bin/droiddeck-clipboard /usr/local/bin/droiddeck-clipboard "$BL_ANDROID_CLIPBOARD" & fi +start_agent + case $mode in desktop) exec pcmanfm @@ -710,6 +721,8 @@ BUSCONF export BL_CDP_GUARD=$BL_CDP_PORT echo "== steam: devtools port $BL_CDP_PORT, guest processes only" fi + # The agent bridge drives the client through it (droiddeck-agent's cdp requests). + [ -n "${BL_LAUNCH_DIR:-}" ] && mkdir -p "$BL_LAUNCH_DIR/agent" && echo "$BL_CDP_PORT" > "$BL_LAUNCH_DIR/agent/cdp-port" droiddeck-steam-compat "$steam_root" 2>&1 & # The client exits 42 when it has updated itself and wants a fresh start (steam.sh does this). # BL_STEAM_UI=desktop = the client's desktop UI (a window, the library as a list), which the diff --git a/tools/linuxfs/preload/net.c b/tools/linuxfs/preload/net.c index 44de4809b1..c06c8dd796 100644 --- a/tools/linuxfs/preload/net.c +++ b/tools/linuxfs/preload/net.c @@ -41,6 +41,19 @@ static const char *net_dir(void) { return dir; } +static int loopback_family(const struct sockaddr *address, socklen_t length) { + if (address && address->sa_family == AF_INET && length >= sizeof(struct sockaddr_in)) { + return ((const struct sockaddr_in *)address)->sin_addr.s_addr == htonl(INADDR_LOOPBACK) ? AF_INET : 0; + } + if (address && address->sa_family == AF_INET6 && length >= sizeof(struct sockaddr_in6)) { + const struct in6_addr *ip = &((const struct sockaddr_in6 *)address)->sin6_addr; + if (IN6_IS_ADDR_LOOPBACK(ip)) return AF_INET6; + if (IN6_IS_ADDR_V4MAPPED(ip) && ip->s6_addr[12] == 127 && ip->s6_addr[13] == 0 && + ip->s6_addr[14] == 0 && ip->s6_addr[15] == 1) return AF_INET; + } + return 0; +} + /* Record that this process owns a loopback socket on its local port; peer is the far end's port, * 0 for a listening socket. */ static void record_port(int fd, unsigned peer) { @@ -49,12 +62,11 @@ static void record_port(int fd, unsigned peer) { if (getsockname(fd, (struct sockaddr *)&ss, &len) != 0) { return; } + int family = loopback_family((struct sockaddr *)&ss, len); + if (!family) return; unsigned port; if (ss.ss_family == AF_INET) { struct sockaddr_in *in = (struct sockaddr_in *)&ss; - if (in->sin_addr.s_addr != htonl(INADDR_LOOPBACK)) { - return; - } port = ntohs(in->sin_port); } else if (ss.ss_family == AF_INET6) { port = ntohs(((struct sockaddr_in6 *)&ss)->sin6_port); @@ -64,14 +76,21 @@ static void record_port(int fd, unsigned peer) { if (port == 0) { return; } + struct stat socket_stat; + if (fstat(fd, &socket_stat) != 0) return; char path[300]; snprintf(path, sizeof(path), "%s/p%u", net_dir(), port); - char line[64]; - int n = snprintf(line, sizeof(line), "%d %d %d %u\n", (int)getpid(), (int)getppid(), (int)getuid(), peer); - int out = open(path, O_WRONLY | O_CREAT | O_TRUNC, 0666); + char staged[360]; + snprintf(staged, sizeof(staged), "%s.tmp.%d.%d", path, (int)getpid(), fd); + char line[128]; + int n = snprintf(line, sizeof(line), "%d %d %d %u %d %llu %d\n", (int)getpid(), (int)getppid(), + (int)getuid(), peer, fd, (unsigned long long)socket_stat.st_ino, family); + int out = open(staged, O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW, 0600); if (out >= 0) { - if (write(out, line, n) != n) { /* best effort */ } + int complete = write(out, line, n) == n; close(out); + if (complete) rename(staged, path); + unlink(staged); } } @@ -98,6 +117,7 @@ typedef int (*bind_fn)(int, const struct sockaddr *, socklen_t); typedef int (*listen_fn)(int, int); typedef int (*connect_fn)(int, const struct sockaddr *, socklen_t); typedef int (*accept4_fn)(int, struct sockaddr *, socklen_t *, int); +static unsigned guarded_port(void); /* udevmon.c: a stand-in for the netlink socket the sandbox refuses, bound here without the kernel. */ __attribute__((visibility("hidden"))) int bl_udevmon_stand_in(int fd); @@ -112,6 +132,18 @@ int bind(int fd, const struct sockaddr *addr, socklen_t len) { } return 0; } + struct sockaddr_storage local; + unsigned guarded = guarded_port(); + if (guarded && addr_port(addr, len) == guarded && len <= sizeof(local)) { + memcpy(&local, addr, len); + if (addr->sa_family == AF_INET) { + ((struct sockaddr_in *)&local)->sin_addr.s_addr = htonl(INADDR_LOOPBACK); + addr = (struct sockaddr *)&local; + } else if (addr->sa_family == AF_INET6) { + ((struct sockaddr_in6 *)&local)->sin6_addr = in6addr_loopback; + addr = (struct sockaddr *)&local; + } + } int ret = real(fd, addr, len); if (ret == 0) record_port(fd, 0); return ret; @@ -135,22 +167,20 @@ static unsigned local_port(int fd) { } static void bind_before_loopback_connect(int fd, const struct sockaddr *addr, socklen_t len) { - if (!addr || addr->sa_family != AF_INET || len < sizeof(struct sockaddr_in) || - ((const struct sockaddr_in *)addr)->sin_addr.s_addr != htonl(INADDR_LOOPBACK)) { - return; - } + if (!loopback_family(addr, len)) return; struct sockaddr_storage ss; socklen_t slen = sizeof(ss); - if (getsockname(fd, (struct sockaddr *)&ss, &slen) != 0 || ss.ss_family != AF_INET || - ((struct sockaddr_in *)&ss)->sin_port != 0) { + if (getsockname(fd, (struct sockaddr *)&ss, &slen) != 0 || ss.ss_family != addr->sa_family || + addr_port((struct sockaddr *)&ss, slen) != 0) { return; } - struct sockaddr_in local; - memset(&local, 0, sizeof(local)); - local.sin_family = AF_INET; - local.sin_addr.s_addr = htonl(INADDR_LOOPBACK); + struct sockaddr_storage local; + if (len > sizeof(local)) return; + memcpy(&local, addr, len); + if (addr->sa_family == AF_INET) ((struct sockaddr_in *)&local)->sin_port = 0; + else ((struct sockaddr_in6 *)&local)->sin6_port = 0; int saved = errno; - bind(fd, (struct sockaddr *)&local, sizeof(local)); + bind(fd, (struct sockaddr *)&local, len); errno = saved; } @@ -165,6 +195,11 @@ static unsigned guarded_port(void) { } static int guest_peer(int fd) { + struct sockaddr_storage address; + socklen_t length = sizeof(address); + if (getpeername(fd, (struct sockaddr *)&address, &length) != 0) return 0; + int family = loopback_family((struct sockaddr *)&address, length); + if (!family) return 0; unsigned peer = peer_port(fd); if (peer == 0) { return 0; @@ -179,26 +214,34 @@ static int guest_peer(int fd) { if (in < 0) { return 0; } - char buf[64]; + char buf[128]; int n = read(in, buf, sizeof(buf) - 1); close(in); if (n <= 0) { return 0; } buf[n] = '\0'; - int pid = atoi(buf); - return pid > 0 && (kill(pid, 0) == 0 || errno != ESRCH); + int pid, parent, uid, descriptor, recorded_family; + unsigned destination; + unsigned long long inode; + if (sscanf(buf, "%d %d %d %u %d %llu %d", &pid, &parent, &uid, &destination, &descriptor, + &inode, &recorded_family) != 7 || pid <= 0 || descriptor < 0 || destination != guarded_port() || + recorded_family != family) return 0; + snprintf(path, sizeof(path), "/proc/%d/fd/%d", pid, descriptor); + return stat(path, &st) == 0 && S_ISSOCK(st.st_mode) && (unsigned long long)st.st_ino == inode; } int connect(int fd, const struct sockaddr *addr, socklen_t len) { static connect_fn real; if (!real) real = (connect_fn)dlsym(RTLD_NEXT, "connect"); bind_before_loopback_connect(fd, addr, len); + unsigned peer = loopback_family(addr, len) ? addr_port(addr, len) : 0; + if (peer) record_port(fd, peer); int ret = real(fd, addr, len); if (ret == 0 || errno == EINPROGRESS) { /* The caller goes on to test for EINPROGRESS, which the bookkeeping must not disturb. */ int saved = errno; - record_port(fd, addr_port(addr, len)); + record_port(fd, peer); errno = saved; } return ret; diff --git a/tools/scenarios/skyrim-launcher-focus.json b/tools/scenarios/skyrim-launcher-focus.json new file mode 100644 index 0000000000..7be429d0b6 --- /dev/null +++ b/tools/scenarios/skyrim-launcher-focus.json @@ -0,0 +1,83 @@ +{ + "name": "skyrim-launcher-focus", + "vars": { + "appId": 489830 + }, + "repeat": 6, + "setup": [ + [ + "wake" + ] + ], + "before": [ + [ + "start", + "steam", + "--wait", + "--reuse", + "--timeout", + "240" + ] + ], + "steps": [ + [ + "launch", + "${appId}", + "--wait", + "--timeout", + "240" + ], + { + "sleep": 8 + }, + [ + "input", + "tap", + "0.927", + "0.111", + "--space", + "fraction" + ], + { + "sleep": 30 + }, + [ + "wait", + "focused", + "${appId}", + "--timeout", + "60" + ], + { + "screenshot": "in-game" + }, + [ + "quit", + "${appId}", + "--timeout", + "20" + ], + { + "assert": "remaining", + "equals": [] + }, + { + "sleep": 5 + } + ], + "after": [ + [ + "quit", + "${appId}", + "--timeout", + "20" + ] + ], + "teardown": [ + [ + "stop", + "--timeout", + "120" + ] + ] +} diff --git a/tools/scenarios/steam-game-focus.json b/tools/scenarios/steam-game-focus.json new file mode 100644 index 0000000000..b3fb85a94f --- /dev/null +++ b/tools/scenarios/steam-game-focus.json @@ -0,0 +1,70 @@ +{ + "name": "steam-game-focus", + "vars": { + "appId": 489830 + }, + "repeat": 6, + "setup": [ + [ + "wake" + ] + ], + "before": [ + [ + "start", + "steam", + "--wait", + "--reuse", + "--timeout", + "240" + ] + ], + "steps": [ + [ + "launch", + "${appId}", + "--wait", + "--timeout", + "240" + ], + { + "assert": "focus.focusedApp", + "equals": "${appId}" + }, + { + "assert": "focus.focusableApps", + "contains": "${appId}" + }, + { + "screenshot": "focused" + }, + [ + "quit", + "${appId}", + "--timeout", + "20" + ], + { + "assert": "remaining", + "equals": [] + }, + { + "sleep": 5 + } + ], + "after": [ + [ + "quit", + "${appId}", + "--timeout", + "20" + ] + ], + "teardown": [ + [ + "stop", + "--timeout", + "120" + ] + ] +} diff --git a/tools/tests/test_cdp_guard.py b/tools/tests/test_cdp_guard.py new file mode 100644 index 0000000000..98e586f121 --- /dev/null +++ b/tools/tests/test_cdp_guard.py @@ -0,0 +1,118 @@ +import os +from pathlib import Path +import shutil +import socket +import subprocess +import sys +import tempfile +import unittest + +SOURCE = Path(__file__).resolve().parents[1] / "linuxfs/preload/net.c" + + +@unittest.skipUnless(sys.platform.startswith("linux") and shutil.which("cc"), "needs Linux and a C compiler") +class CdpGuardTest(unittest.TestCase): + @classmethod + def setUpClass(cls): + cls.build = tempfile.TemporaryDirectory() + cls.library = Path(cls.build.name) / "net.so" + subprocess.run(["cc", "-shared", "-fPIC", "-O2", str(SOURCE), "-x", "c", "-", "-ldl", "-o", str(cls.library)], + input=b"int bl_udevmon_stand_in(int fd) { return 0; }", check=True, capture_output=True) + + @classmethod + def tearDownClass(cls): + cls.build.cleanup() + + def setUp(self): + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.registry = Path(self.temp.name) / "net" + self.registry.mkdir() + + def port(self, ipv6=False): + with socket.socket(socket.AF_INET6 if ipv6 else socket.AF_INET) as s: + s.bind(("::1" if ipv6 else "127.0.0.1", 0)) + return s.getsockname()[1] + + def env(self, port): + return dict(os.environ, LD_PRELOAD=str(self.library), BL_CDP_GUARD=str(port), BL_SYSV_DIR=self.temp.name) + + def test_guarded_ipv4_bind_is_loopback_only(self): + port = self.port() + program = "import socket; s=socket.socket(); s.bind(('0.0.0.0', %d)); print(s.getsockname()[0])" % port + result = subprocess.run([sys.executable, "-c", program], env=self.env(port), check=True, capture_output=True, text=True) + self.assertEqual("127.0.0.1", result.stdout.strip()) + + def test_guarded_ipv6_bind_is_loopback_only(self): + if not socket.has_ipv6: + self.skipTest("needs IPv6") + port = self.port(True) + program = "import socket; s=socket.socket(socket.AF_INET6); s.bind(('::', %d)); print(s.getsockname()[0])" % port + result = subprocess.run([sys.executable, "-c", program], env=self.env(port), check=True, capture_output=True, text=True) + self.assertEqual("::1", result.stdout.strip()) + + def test_other_listeners_are_unchanged(self): + port = self.port() + program = "import socket; s=socket.socket(); s.bind(('0.0.0.0', %d)); print(s.getsockname()[0])" % port + result = subprocess.run([sys.executable, "-c", program], env=self.env(0), check=True, capture_output=True, text=True) + self.assertEqual("0.0.0.0", result.stdout.strip()) + + def connect(self, address, registered, stale=False, wrong_destination=False): + port = self.port() + program = "import socket; s=socket.socket(); s.bind(('0.0.0.0', %d)); s.listen(); print('ready', flush=True); c,_=s.accept(); c.sendall(b'accepted')" % port + server = subprocess.Popen([sys.executable, "-u", "-c", program], env=self.env(port), stdout=subprocess.PIPE, stderr=subprocess.PIPE) + try: + self.assertEqual(b"ready\n", server.stdout.readline()) + with socket.socket() as client: + client.settimeout(3) + client.bind((address, 0)) + if registered: + peer = client.getsockname()[1] + inode = os.fstat(client.fileno()).st_ino + (1 if stale else 0) + destination = port + (1 if wrong_destination else 0) + (self.registry / ("p%d" % peer)).write_text("%d 1 %d %d %d %d %d\n" % + (os.getpid(), os.getuid(), destination, client.fileno(), inode, socket.AF_INET)) + client.connect(("127.0.0.1", port)) + try: + return client.recv(8) + except ConnectionResetError: + return b"" + finally: + server.kill() + server.wait() + server.stdout.close() + server.stderr.close() + + def test_registered_guest_loopback_peer_is_accepted(self): + self.assertEqual(b"accepted", self.connect("127.0.0.1", True)) + + def test_unregistered_local_peer_is_refused(self): + self.assertEqual(b"", self.connect("127.0.0.1", False)) + + def test_matching_port_record_cannot_authorize_another_address(self): + self.assertEqual(b"", self.connect("127.0.0.2", True)) + + def test_stale_socket_record_does_not_authorize_a_reused_port(self): + self.assertEqual(b"", self.connect("127.0.0.1", True, stale=True)) + + def test_record_for_another_destination_does_not_authorize_cdp(self): + self.assertEqual(b"", self.connect("127.0.0.1", True, wrong_destination=True)) + + def test_preloaded_guest_connect_still_works(self): + port = self.port() + program = "import socket; s=socket.socket(); s.bind(('0.0.0.0', %d)); s.listen(); print('ready', flush=True); c,_=s.accept(); c.sendall(b'accepted')" % port + server = subprocess.Popen([sys.executable, "-u", "-c", program], env=self.env(port), stdout=subprocess.PIPE, stderr=subprocess.PIPE) + try: + self.assertEqual(b"ready\n", server.stdout.readline()) + client = "import socket; s=socket.create_connection(('127.0.0.1', %d), timeout=3); print(s.recv(8).decode())" % port + result = subprocess.run([sys.executable, "-c", client], env=self.env(port), check=True, capture_output=True, text=True, timeout=5) + self.assertEqual("accepted", result.stdout.strip()) + finally: + server.kill() + server.wait() + server.stdout.close() + server.stderr.close() + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/tests/test_droiddeck_agent.py b/tools/tests/test_droiddeck_agent.py new file mode 100644 index 0000000000..e0dce56a7d --- /dev/null +++ b/tools/tests/test_droiddeck_agent.py @@ -0,0 +1,250 @@ +"""The guest agent: its request files, exec, errors and the DevTools client, without a session.""" +import base64 +import hashlib +import importlib.machinery +import importlib.util +import json +import os +from pathlib import Path +import socket +import struct +import sys +import tempfile +import threading +import time +import unittest +from unittest.mock import patch +import tracemalloc + +SCRIPT = Path(__file__).resolve().parents[1] / "linuxfs/overlay/usr/local/bin/droiddeck-agent" +loader = importlib.machinery.SourceFileLoader("droiddeck_agent", str(SCRIPT)) +spec = importlib.util.spec_from_loader(loader.name, loader) +agent = importlib.util.module_from_spec(spec) +loader.exec_module(agent) + + +class FakeDevTools(threading.Thread): + """GET /json lists one target; its WebSocket answers Runtime.evaluate the way Chromium does.""" + + def __init__(self, answer): + super().__init__(daemon=True) + self.answer = answer + self.server = socket.socket() + self.server.bind(("127.0.0.1", 0)) + self.server.listen(4) + self.port = self.server.getsockname()[1] + self.seen = [] + + def run(self): + while True: + try: + conn, _ = self.server.accept() + except OSError: + return + threading.Thread(target=self.serve, args=(conn,), daemon=True).start() + + def serve(self, conn): + head = b"" + while b"\r\n\r\n" not in head: + head += conn.recv(4096) + request = head.decode() + if request.startswith("GET /json"): + body = json.dumps([{"title": "SharedJSContext", "url": "https://steamloopback.host/", "type": "page", + "webSocketDebuggerUrl": "ws://127.0.0.1:%d/devtools/page/1" % self.port}]).encode() + conn.sendall(b"HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nContent-Length: %d\r\n\r\n" % len(body) + body) + conn.close() + return + key = [l.split(":", 1)[1].strip() for l in request.split("\r\n") if l.lower().startswith("sec-websocket-key")][0] + accept = base64.b64encode(hashlib.sha1((key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").encode()).digest()).decode() + conn.sendall(("HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n" + "Sec-WebSocket-Accept: %s\r\n\r\n" % accept).encode()) + b0, b1 = conn.recv(2) + n = b1 & 0x7F + if n == 126: + n = struct.unpack(">H", conn.recv(2))[0] + mask = conn.recv(4) + data = b"" + while len(data) < n: + data += conn.recv(n - len(data)) + message = json.loads(bytes(b ^ mask[i % 4] for i, b in enumerate(data))) + self.seen.append(message) + for reply in ({"method": "Runtime.consoleAPICalled", "params": {}}, dict(self.answer, id=message["id"])): + payload = json.dumps(reply).encode() + header = bytes([0x81, 126]) + struct.pack(">H", len(payload)) if len(payload) > 125 else bytes([0x81, len(payload)]) + conn.sendall(header + payload) + time.sleep(0.2) + conn.close() + + +class AgentTest(unittest.TestCase): + def setUp(self): + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.dir = Path(self.temp.name) + (self.dir / "resp").mkdir() + + def ask(self, request): + path = self.dir / "req.json" + path.write_text(json.dumps(request)) + agent.answer(self.dir, path) + self.assertFalse(path.exists(), "the request file is consumed") + return json.loads((self.dir / "resp" / "req.json").read_text()) + + def test_exec_output_and_status(self): + answer = self.ask({"kind": "exec", "argv": ["sh", "-c", "echo out; echo err >&2; exit 3"], "env": {"X": "1"}}) + self.assertTrue(answer["ok"]) + self.assertEqual(3, answer["exitCode"]) + self.assertEqual("out\n", answer["stdout"]["text"]) + self.assertEqual("err\n", answer["stderr"]["text"]) + self.assertFalse(answer["timedOut"]) + + def test_exec_environment_stdin_and_cap(self): + answer = self.ask({"kind": "exec", "argv": ["sh", "-c", "printf %s \"$X\"; cat"], "env": {"X": "a"}, "stdin": "b"}) + self.assertEqual("ab", answer["stdout"]["text"]) + big = self.ask({"kind": "exec", "argv": ["sh", "-c", "head -c 300000 /dev/zero"]}) + self.assertTrue(big["stdout"]["truncated"]) + self.assertEqual(agent.OUTPUT_CAP, len(big["stdout"]["text"])) + + def test_exec_timeout_kills_the_process_group(self): + started = time.monotonic() + answer = self.ask({"kind": "exec", "argv": ["sh", "-c", "sleep 30 & sleep 30"], "timeout": 0.5}) + self.assertTrue(answer["timedOut"]) + self.assertLess(time.monotonic() - started, 10) + + def test_exec_memory_is_bounded_while_draining_large_output(self): + tracemalloc.start() + try: + answer = agent.run_exec({"argv": [sys.executable, "-c", "import os; [os.write(1, b'x' * 65536) for _ in range(1024)]"]}) + _, peak = tracemalloc.get_traced_memory() + finally: + tracemalloc.stop() + self.assertEqual(0, answer["exitCode"]) + self.assertEqual(agent.OUTPUT_CAP, len(answer["stdout"]["text"])) + self.assertTrue(answer["stdout"]["truncated"]) + self.assertLess(peak, 6 * 1024 * 1024) + + def test_exec_drains_both_streams_while_writing_stdin(self): + program = "import os, sys; os.write(1, b'x' * 300000); print(len(sys.stdin.read()), file=sys.stderr)" + answer = self.ask({"kind": "exec", "argv": [sys.executable, "-c", program], "stdin": "y" * 100000}) + self.assertFalse(answer["timedOut"]) + self.assertTrue(answer["stdout"]["truncated"]) + self.assertEqual("100000\n", answer["stderr"]["text"]) + + def test_flooding_both_streams_still_times_out(self): + program = "import os\nwhile True:\n os.write(1, b'o' * 65536)\n os.write(2, b'e' * 65536)" + answer = self.ask({"kind": "exec", "argv": [sys.executable, "-c", program], "timeout": 0.5}) + self.assertTrue(answer["timedOut"]) + for name in ("stdout", "stderr"): + self.assertEqual(agent.OUTPUT_CAP, len(answer[name]["text"])) + self.assertTrue(answer[name]["truncated"]) + + def test_timeout_applies_when_parent_exits_with_inherited_pipes(self): + started = time.monotonic() + answer = self.ask({"kind": "exec", "argv": ["sh", "-c", "sleep 30 & exit 0"], "timeout": 0.5}) + self.assertTrue(answer["timedOut"]) + self.assertLess(time.monotonic() - started, 5) + + def test_invalid_timeout_and_input_are_refused_before_exec(self): + for value in (0, -1, 601, "NaN", "Infinity", "invalid"): + answer = self.ask({"kind": "exec", "argv": ["true"], "timeout": value}) + self.assertEqual("INVALID_REQUEST", answer["error"]["code"]) + for fields in ({"stdin": 1}, {"env": []}, {"env": {"BAD=KEY": "value"}}, {"argv": ["true\0"]}): + answer = self.ask({"kind": "exec", "argv": ["true"], **fields}) + self.assertEqual("INVALID_REQUEST", answer["error"]["code"]) + + def test_errors_are_answers(self): + self.assertEqual("INVALID_REQUEST", self.ask({"kind": "exec", "argv": []})["error"]["code"]) + self.assertEqual("EXEC_FAILED", self.ask({"kind": "exec", "argv": ["/no/such/program"]})["error"]["code"]) + self.assertEqual("UNKNOWN_REQUEST", self.ask({"kind": "nope"})["error"]["code"]) + self.assertEqual("INVALID_APP_ID", self.ask({"kind": "quit", "appId": "x"})["error"]["code"]) + (self.dir / "req.json").write_text("{not json") + agent.answer(self.dir, self.dir / "req.json") + self.assertEqual("INVALID_REQUEST", json.loads((self.dir / "resp" / "req.json").read_text())["error"]["code"]) + + def test_request_shape_and_size_are_bounded(self): + self.assertEqual("INVALID_REQUEST", self.ask([])["error"]["code"]) + self.assertEqual("INVALID_REQUEST", self.ask({"kind": "ping", "unused": "x" * agent.REQUEST_CAP})["error"]["code"]) + + def test_replies_are_owner_only_even_when_replacing_a_public_file(self): + path = self.dir / "private.json" + path.write_text("old") + path.chmod(0o644) + agent.write_json(path, {"ok": True}) + self.assertEqual(0o600, path.stat().st_mode & 0o777) + + def test_oversized_websocket_frames_are_refused_before_reading_payload(self): + ws = agent.WebSocket.__new__(agent.WebSocket) + ws.buffer = bytes([0x81, 127]) + struct.pack(">Q", agent.RESPONSE_CAP + 1) + with self.assertRaises(agent.AgentError) as caught: + ws.recv() + self.assertEqual("RESPONSE_TOO_LARGE", caught.exception.code) + + def test_devtools_targets_cannot_connect_to_remote_hosts(self): + for url in ("ws://example.com/devtools", "ws://127.0.0.1@example.com/devtools", "wss://127.0.0.1/devtools"): + with patch.object(agent.socket, "create_connection") as connect: + with self.assertRaises(agent.AgentError) as caught: + agent.WebSocket(url, 1) + self.assertEqual("INVALID_TARGET", caught.exception.code) + connect.assert_not_called() + + def test_cdp_without_a_port(self): + os.environ.pop("BL_CDP_PORT", None) + self.assertEqual("NO_DEVTOOLS", self.ask({"kind": "cdp", "expression": "1"})["error"]["code"]) + + def test_cdp_eval(self): + server = FakeDevTools({"result": {"result": {"type": "number", "value": 42}}}) + server.start() + self.addCleanup(server.server.close) + (self.dir / "cdp-port").write_text("%d\n" % server.port) + answer = self.ask({"kind": "cdp", "expression": "6 * 7"}) + self.assertTrue(answer["ok"], answer) + self.assertEqual(42, answer["value"]) + self.assertEqual("SharedJSContext", answer["target"]) + self.assertEqual("Runtime.evaluate", server.seen[0]["method"]) + self.assertEqual("6 * 7", server.seen[0]["params"]["expression"]) + targets = self.ask({"kind": "cdp", "op": "targets"}) + self.assertEqual("SharedJSContext", targets["targets"][0]["title"]) + missing = self.ask({"kind": "cdp", "expression": "1", "target": "Nope"}) + self.assertEqual("NO_TARGET", missing["error"]["code"]) + + def test_cdp_exception(self): + server = FakeDevTools({"result": {"result": {"type": "object"}, "exceptionDetails": { + "text": "Uncaught", "exception": {"description": "ReferenceError: SteamClient is not defined"}}}}) + server.start() + self.addCleanup(server.server.close) + (self.dir / "cdp-port").write_text(str(server.port)) + answer = self.ask({"kind": "cdp", "expression": "SteamClient"}) + self.assertEqual("JS_EXCEPTION", answer["error"]["code"]) + self.assertIn("ReferenceError", answer["error"]["message"]) + + def test_serve_answers_request_files(self): + os.environ.pop("DISPLAY", None) + thread = threading.Thread(target=agent.serve, args=(self.dir, False, 0.02), daemon=True) + thread.start() + for _ in range(100): + if (self.dir / "hello.json").exists(): + break + time.sleep(0.02) + hello = json.loads((self.dir / "hello.json").read_text()) + self.assertEqual(os.getpid(), hello["pid"]) + self.assertFalse(hello["focus"]) + (self.dir / "req" / "a.json.tmp").write_text(json.dumps({"kind": "ping"})) + os.replace(self.dir / "req" / "a.json.tmp", self.dir / "req" / "a.json") + for _ in range(200): + if (self.dir / "resp" / "a.json").exists(): + break + time.sleep(0.02) + self.assertEqual(agent.VERSION, json.loads((self.dir / "resp" / "a.json").read_text())["version"]) + + def test_game_pids_reads_the_steam_environment(self): + import subprocess + if not Path("/proc").is_dir(): + self.skipTest("needs /proc") + child = subprocess.Popen(["sleep", "30"], env=dict(os.environ, SteamAppId="424242")) + self.addCleanup(lambda: (child.kill(), child.wait())) + time.sleep(0.2) + self.assertIn(child.pid, agent.game_pids(424242)) + + +if __name__ == "__main__": + unittest.main() diff --git a/tools/tests/test_droiddeckctl.py b/tools/tests/test_droiddeckctl.py new file mode 100644 index 0000000000..22330ded0a --- /dev/null +++ b/tools/tests/test_droiddeckctl.py @@ -0,0 +1,353 @@ +"""droiddeckctl and droiddeck-scenario against a fake adb: the JSON contract and exit codes.""" +import base64 +import contextlib +import importlib.machinery +import importlib.util +import io +import json +import os +from pathlib import Path +import stat +import sys +import tempfile +import textwrap +import unittest + +TOOLS = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(TOOLS)) + + +def load(name): + loader = importlib.machinery.SourceFileLoader(name.replace("-", "_"), str(TOOLS / name)) + spec = importlib.util.spec_from_loader(loader.name, loader) + module = importlib.util.module_from_spec(spec) + loader.exec_module(module) + return module + + +ctl = load("droiddeckctl") +scenario = load("droiddeck-scenario") + +# A stand-in for adb: answers the provider's content calls from a JSON config (a list answers +# successive calls), records every invocation, and fakes the few shell commands droiddeckctl uses. +FAKE_ADB = textwrap.dedent('''\ + #!/usr/bin/env python3 + import base64, json, os, sys + config_path = os.environ["FAKE_ADB_CONFIG"] + config = json.load(open(config_path)) + args = sys.argv[1:] + if args[:1] == ["-s"]: + args = args[2:] + entry = {"args": args} + if args[:1] == ["get-state"]: + print("device"); sys.exit(0) + if args[:3] == ["shell", "content", "call"]: + method = args[args.index("--method") + 1] + request = None + if "--extra" in args: + request = json.loads(base64.b64decode(args[args.index("--extra") + 1].split(":", 2)[2])) + entry.update(method=method, request=request) + answers = config["provider"].get(method, {"ok": False, "error": {"code": "UNKNOWN_COMMAND", "message": method}}) + if isinstance(answers, list): + count = config.setdefault("counts", {}).get(method, 0) + config["counts"][method] = count + 1 + answers = answers[min(count, len(answers) - 1)] + json.dump(config, open(config_path, "w")) + print("Result: Bundle[{json=" + json.dumps(answers) + "}]") + elif args[:3] == ["shell", "dumpsys", "display"]: + print(config.get("dumpsys_display", "")) + elif args[:3] == ["shell", "dumpsys", "power"]: + print(" mWakefulness=Awake") + elif args[:2] == ["exec-out", "screencap"]: + sys.stdout.buffer.write(b"\\x89PNG fake") + with open(config["log"], "a") as log: + log.write(json.dumps(entry) + "\\n") +''') + +DUMPSYS_DISPLAY = textwrap.dedent('''\ + Display Devices: size=2 + DisplayDeviceInfo{"Built-in Screen": uniqueId="local:111", 1080 x 1920} + DisplayDeviceInfo{"Screen-2": uniqueId="local:222", 1080 x 1240} + Logical Displays: size=2 + Display 0: + mDisplayId=0 + mPrimaryDisplayDevice=Built-in Screen + mBaseDisplayInfo=DisplayInfo{"Built-in Screen", displayId 0", real 1080 x 1920, x} + Display 4: + mDisplayId=4 + mPrimaryDisplayDevice=Screen-2 + mBaseDisplayInfo=DisplayInfo{"Screen-2", displayId 4", real 1080 x 1240, x} +''') + + +def state(phase="READY", focused=None, focusable=()): + focus = None if focused is None else {"focusedApp": focused, "focusableApps": list(focusable), + "baselayerAppIds": [], "seq": 1, "t": 0} + return {"ok": True, "schema": 2, "session": {"id": "s1", "phase": phase, "running": phase == "READY", + "focus": focus, "failure": None}} + + +class FakeAdbTest(unittest.TestCase): + def setUp(self): + self.temp = tempfile.TemporaryDirectory() + self.addCleanup(self.temp.cleanup) + self.dir = Path(self.temp.name) + self.adb = self.dir / "adb" + self.adb.write_text(FAKE_ADB) + self.adb.chmod(self.adb.stat().st_mode | stat.S_IEXEC) + self.config = self.dir / "config.json" + self.log = self.dir / "log.jsonl" + self.configure({}) + os.environ["FAKE_ADB_CONFIG"] = str(self.config) + self.addCleanup(os.environ.pop, "FAKE_ADB_CONFIG", None) + + def configure(self, provider, **extra): + self.config.write_text(json.dumps(dict({"provider": provider, "log": str(self.log)}, **extra))) + + def run_ctl(self, *argv): + out = io.StringIO() + with contextlib.redirect_stdout(out), contextlib.redirect_stderr(io.StringIO()): + code = ctl.main(["--adb", str(self.adb), "--serial", "fake-1", *argv]) + return code, json.loads(out.getvalue()) + + def calls(self, method=None): + if not self.log.exists(): + return [] + entries = [json.loads(line) for line in self.log.read_text().splitlines()] + return [e for e in entries if method is None or e.get("method") == method] + + +class DroiddeckctlTest(FakeAdbTest): + def test_oversized_requests_are_refused_before_adb(self): + with self.assertRaises(ctl.ControlError) as caught: + ctl.provider_call(str(self.adb), "fake-1", "guest", request={"stdin": "x" * ctl.REQUEST_CAP}) + self.assertEqual("INVALID_REQUEST", caught.exception.code) + self.assertFalse(self.calls()) + + def test_state_passes_through_with_the_serial(self): + self.configure({"state": state()}) + code, out = self.run_ctl("state") + self.assertEqual(0, code) + self.assertEqual("READY", out["session"]["phase"]) + self.assertEqual("fake-1", out["deviceSerial"]) + + def test_launch_sends_the_app_id_and_waits_for_focus(self): + self.configure({ + "launch": {"ok": True, "command": "launch", "appId": "489830"}, + "state": [state(focused=769, focusable=[769]), state(focused=489830, focusable=[769])], + }) + # Focus alone is not enough: the game must also be in the list Steam orders from. + code, out = self.run_ctl("launch", "489830", "--wait", "--timeout", "1") + self.assertEqual(5, code) + self.assertEqual("TIMEOUT", out["error"]["code"]) + self.assertIn("focused app 489830", out["error"]["message"]) + self.assertEqual({"appId": "489830"}, self.calls("launch")[0]["request"]) + + self.configure({ + "launch": {"ok": True, "command": "launch", "appId": "489830"}, + "state": [state(focused=769, focusable=[769]), state(focused=489830, focusable=[489830, 769])], + }) + code, out = self.run_ctl("launch", "489830", "--wait", "--timeout", "5") + self.assertEqual(0, code) + self.assertEqual(489830, out["focus"]["focusedApp"]) + + def test_start_reuse_keeps_a_running_session(self): + running = state(focused=769) + running["session"]["mode"] = "steam" + self.configure({"state": running}) + code, out = self.run_ctl("start", "steam", "--reuse", "--wait") + self.assertEqual(0, code) + self.assertTrue(out["reused"]) + self.assertFalse([c for c in self.calls() if c["args"][:2] == ["shell", "am"]]) + + def test_start_without_reuse_refuses_a_running_session(self): + running = state() + running["session"]["mode"] = "steam" + self.configure({"state": running}) + code, out = self.run_ctl("start", "steam") + self.assertEqual(4, code) + self.assertEqual("SESSION_ACTIVE", out["error"]["code"]) + + def test_wait_game_ignores_the_client(self): + self.configure({"state": [state(focused=769), state(focused=752590, focusable=[752590])]}) + code, out = self.run_ctl("wait", "game", "--timeout", "5") + self.assertEqual(0, code) + self.assertEqual(752590, out["session"]["focus"]["focusedApp"]) + + def test_a_failed_session_ends_a_wait(self): + failed = state(phase="FAILED") + failed["session"]["failure"] = {"code": "GUEST_EXIT", "message": "boom"} + self.configure({"state": failed}) + code, out = self.run_ctl("wait", "focused", "1", "--timeout", "5") + self.assertEqual(4, code) + self.assertEqual("GUEST_EXIT", out["error"]["code"]) + + def test_disabled_agent_commands_exit_7(self): + self.configure({"guest": {"ok": False, "error": {"code": "AGENT_COMMANDS_DISABLED", "message": "off"}}}) + code, out = self.run_ctl("guest", "--", "true") + self.assertEqual(7, code) + self.assertEqual("AGENT_COMMANDS_DISABLED", out["error"]["code"]) + + def test_run_checks_access_before_launching_an_activity(self): + self.configure({"access": {"ok": True, "commands": False}}) + code, out = self.run_ctl("run", "/usr/bin/sh", "--", "-c", "true") + self.assertEqual(7, code) + self.assertEqual("AGENT_COMMANDS_DISABLED", out["error"]["code"]) + self.assertIn("Debugging tools", out["error"]["message"]) + self.assertEqual(["access"], [c.get("method") for c in self.calls()]) + + def test_override_checks_names_before_pushing_any_file(self): + self.configure({"access": {"ok": True, "commands": True, "inbox": "/tmp/inbox"}}) + source = self.dir / "binary" + source.write_bytes(b"test") + code, out = self.run_ctl("override", "../outside", str(source)) + self.assertEqual(2, code) + self.assertEqual("INVALID_NAME", out["error"]["code"]) + self.assertEqual(["access"], [c.get("method") for c in self.calls()]) + + def test_guest_request_and_check(self): + self.configure({"guest": {"ok": True, "exitCode": 3, "stdout": {"text": ""}, "stderr": {"text": "nope"}}}) + code, out = self.run_ctl("guest", "--timeout", "7", "--env", "A=1", "--check", "--", "xprop", "-root") + self.assertEqual(4, code) + self.assertEqual("GUEST_EXIT", out["error"]["code"]) + self.assertEqual({"argv": ["xprop", "-root"], "timeout": 7.0, "env": {"A": "1"}}, + self.calls("guest")[0]["request"]) + + def test_screenshot_resolves_the_logical_display(self): + self.configure({}, dumpsys_display=DUMPSYS_DISPLAY) + target = self.dir / "shot.png" + code, out = self.run_ctl("screenshot", str(target), "--display", "4") + self.assertEqual(0, code) + self.assertTrue(target.read_bytes().startswith(b"\x89PNG")) + shot = [c for c in self.calls() if c["args"][:2] == ["exec-out", "screencap"]][0] + self.assertEqual(["exec-out", "screencap", "-p", "-d", "222"], shot["args"]) + + def test_displays(self): + self.configure({}, dumpsys_display=DUMPSYS_DISPLAY) + code, out = self.run_ctl("displays") + self.assertEqual(0, code) + self.assertEqual([0, 4], [d["display"] for d in out["displays"]]) + self.assertEqual("222", out["displays"][1]["physicalId"]) + self.assertEqual([1080, 1240], out["displays"][1]["size"]) + + def test_unknown_display_is_an_error(self): + self.configure({}, dumpsys_display=DUMPSYS_DISPLAY) + code, out = self.run_ctl("screenshot", str(self.dir / "x.png"), "--display", "9") + self.assertEqual(2, code) + self.assertEqual("NO_SUCH_DISPLAY", out["error"]["code"]) + + def test_input_requests(self): + self.configure({"input": {"ok": True, "command": "input"}}) + self.run_ctl("input", "tap", "0.5", "0.25", "--space", "fraction") + self.run_ctl("input", "key", "enter", "--mod", "CTRL") + self.run_ctl("input", "pad", "a", "--hold", "50") + requests = [c["request"] for c in self.calls("input")] + self.assertEqual({"type": "tap", "x": 0.5, "y": 0.25, "space": "fraction", "holdMs": 60}, requests[0]) + self.assertEqual({"type": "key", "key": "enter", "action": "tap", "modifiers": ["CTRL"], "holdMs": 40}, requests[1]) + self.assertEqual({"type": "pad", "button": "a", "action": "tap", "holdMs": 50}, requests[2]) + + def test_ui_click_by_tag_or_match(self): + self.configure({"ui": {"ok": True, "command": "ui"}}) + self.run_ctl("ui", "click", "rail-steam") + self.run_ctl("ui", "click", "--match", "Play", "--index", "1") + requests = [c["request"] for c in self.calls("ui")] + self.assertEqual({"op": "click", "index": 0, "tag": "rail-steam"}, requests[0]) + self.assertEqual({"op": "click", "index": 1, "match": "Play"}, requests[1]) + + def test_cdp_targets_and_eval_requests(self): + self.configure({"cdp": {"ok": True, "targets": []}}) + self.assertEqual(0, self.run_ctl("cdp", "targets")[0]) + self.assertEqual(0, self.run_ctl("cdp", "eval", "1+1", "--target", "Big Picture")[0]) + requests = [c["request"] for c in self.calls("cdp")] + self.assertEqual({"op": "targets"}, requests[0]) + self.assertEqual({"op": "eval", "expression": "1+1", "awaitPromise": True, "timeout": 15.0, + "target": "Big Picture"}, requests[1]) + + def test_a_bug_still_answers_json(self): + self.configure({"state": {"ok": True, "session": "not an object"}}) + code, out = self.run_ctl("wait", "game", "--timeout", "1") + self.assertEqual(2, code) + self.assertEqual("INTERNAL_ERROR", out["error"]["code"]) + + def test_wake(self): + code, out = self.run_ctl("wake") + self.assertEqual(0, code) + self.assertEqual("Awake", out["wakefulness"]) + self.assertIn(["shell", "input", "keyevent", "KEYCODE_WAKEUP"], [c["args"] for c in self.calls()]) + + def test_override_pushes_to_the_inbox_first(self): + self.configure({ + "access": {"ok": True, "commands": True, "inbox": "/sdcard/Android/data/x/files/agent-inbox"}, + "override": {"ok": True, "installed": "/opt/droiddeck-agent/bin/gamescope"}, + }) + binary = self.dir / "gamescope" + binary.write_bytes(b"\x7fELF") + code, out = self.run_ctl("override", "gamescope", str(binary)) + self.assertEqual(0, code) + push = [c for c in self.calls() if c["args"][:1] == ["push"]][0] + self.assertEqual("/sdcard/Android/data/x/files/agent-inbox/gamescope", push["args"][2]) + self.assertEqual({"name": "gamescope"}, self.calls("override")[0]["request"]) + + def test_override_refused_before_pushing_when_commands_are_off(self): + self.configure({"access": {"ok": True, "commands": False, "inbox": "/x"}}) + binary = self.dir / "gamescope" + binary.write_bytes(b"x") + code, out = self.run_ctl("override", "gamescope", str(binary)) + self.assertEqual(7, code) + self.assertFalse([c for c in self.calls() if c["args"][:1] == ["push"]]) + + +class ScenarioTest(FakeAdbTest): + def write(self, body): + path = self.dir / "scenario.json" + path.write_text(json.dumps(body)) + return path + + def run_scenario(self, path, *extra): + out = io.StringIO() + with contextlib.redirect_stdout(out), contextlib.redirect_stderr(io.StringIO()): + code = scenario.main([str(path), "--adb", str(self.adb), "--serial", "fake-1", + "--out", str(self.dir / "runs"), *extra]) + return code, json.loads(out.getvalue()) + + def test_variables_asserts_and_repeats(self): + self.configure({"state": state(focused=489830, focusable=[489830])}) + path = self.write({ + "name": "t", "vars": {"appId": 1}, "repeat": 2, + "steps": [["state"], {"assert": "session.focus.focusedApp", "equals": "${appId}"}], + }) + code, report = self.run_scenario(path, "--var", "appId=489830") + self.assertEqual(0, code) + self.assertEqual(2, report["passed"]) + output = Path(report["out"]) + self.assertEqual(0o700, output.stat().st_mode & 0o777) + for artifact in output.rglob("*.json"): + self.assertEqual(0o600, artifact.stat().st_mode & 0o777, str(artifact)) + for run in report["runs"]: + self.assertEqual(0o700, Path(run["folder"]).stat().st_mode & 0o777) + + def test_a_failed_assert_fails_the_run_and_collects_evidence(self): + self.configure({"state": state(focused=769, focusable=[769]), "focus": {"ok": True, "focusedApp": 769}}, + dumpsys_display=DUMPSYS_DISPLAY) + path = self.write({"name": "t", "repeat": 3, + "steps": [["state"], {"assert": "session.focus.focusedApp", "equals": 489830}]}) + code, report = self.run_scenario(path) + self.assertEqual(1, code) + self.assertEqual(1, len(report["runs"])) # stops at the first failure without --keep-going + self.assertIn("is 769", report["runs"][0]["error"]) + evidence = json.loads((Path(report["runs"][0]["folder"]) / "evidence.json").read_text()) + self.assertEqual(769, evidence["focus"]["focusedApp"]) + + def test_after_steps_run_after_a_failure(self): + self.configure({"state": state(focused=769), "quit": {"ok": True, "remaining": []}}) + path = self.write({"name": "t", "repeat": 2, "vars": {"appId": 7}, + "steps": [["state"], {"assert": "session.focus.focusedApp", "equals": 7}], + "after": [["quit", "${appId}"]]}) + code, report = self.run_scenario(path, "--keep-going") + self.assertEqual(1, code) + self.assertEqual(2, len(report["runs"])) + self.assertEqual([{"appId": 7, "timeout": 15.0}] * 2, [c["request"] for c in self.calls("quit")]) + + +if __name__ == "__main__": + unittest.main()