feat(agent): launch and quit store games, list the library, and run Xbox and cloud save commands from droiddeckctl (#2860)

This commit is contained in:
Kurt Himebauch authored and GitHub committed 2026-11-19 11:04:34 -05:00
1 parent 786166ba1a
commit 1456c0529d
6 files changed
+255 -8

No files matched your search

+80 -5
View File
@@ -153,6 +153,31 @@ def checked(response: dict, default_code: str) -> dict:
return response
def find_game(adb: str, serial: str, wanted: str) -> dict:
games = checked(provider_call(adb, serial, "library", request={}), "LIBRARY_FAILED").get("games") or []
exact = [g for g in games if g.get("id") == wanted]
if exact:
return exact[0]
named = [g for g in games if wanted.casefold() in str(g.get("name", "")).casefold()]
if len(named) == 1:
return named[0]
if not named:
raise ControlError(f"No library game matches {wanted!r}; list them with library", "GAME_NOT_FOUND")
names = ", ".join(f"{g.get('name')} ({g.get('id')})" for g in named[:10])
raise ControlError(f"{wanted!r} matches {len(named)} games: {names}", "GAME_AMBIGUOUS")
def open_game_link(adb: str, serial: str, game_id: str) -> None:
if not game_id.isdigit():
raise ControlError(f"Library id {game_id!r} is not a number", "INVALID_GAME_ID")
result = run_adb(adb, serial, "shell", "am", "start", "-W", "-a", "android.intent.action.VIEW",
"-d", f"droiddeck://game/{game_id}", "-n", f"{PACKAGE}/com.droiddeck.launcher.FrontEndActivity",
timeout=60)
output = (result.stdout + result.stderr).decode(errors="replace")
if result.returncode != 0 or "error" in output.lower():
raise ControlError(output.strip() or "The game link did not open", "ACTIVITY_START_FAILED")
def start_agent_activity(adb: str, serial: str, request: dict) -> None:
encoded = encode_request(request)
result = run_adb(
@@ -949,6 +974,17 @@ def execute(args: argparse.Namespace, adb: str, serial: str) -> dict:
return add_serial(checked(provider_call(adb, serial, "resume"), "RESUME_FAILED"), serial)
if command == "launch":
if (args.app_id is None) == (args.game is None):
raise ControlError("launch takes a Steam app id or --game, not both", "INVALID_ARGUMENTS")
if args.game is not None:
game = find_game(adb, serial, args.game)
open_game_link(adb, serial, game["id"])
response = {"ok": True, "command": "launch", "game": game}
if args.wait:
state = wait_until(adb, serial, f"{game['name']} to have focus",
lambda s: focused(s, None), args.timeout, 0.5)
response["focus"] = state["session"].get("focus")
return add_serial(response, serial)
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",
@@ -957,10 +993,33 @@ def execute(args: argparse.Namespace, adb: str, serial: str) -> dict:
return add_serial(response, serial)
if command == "quit":
response = provider_call(adb, serial, "quit", request={"appId": args.app_id, "timeout": args.timeout},
app_id = args.app_id
if app_id is None:
current = (get_state(adb, serial)["session"].get("focus") or {}).get("focusedApp")
if current in (None, 0, STEAM_CLIENT_APP):
raise ControlError("No game has focus; name the app id to quit", "NO_FOCUSED_GAME")
app_id = current
response = provider_call(adb, serial, "quit", request={"appId": app_id, "timeout": args.timeout},
timeout=args.timeout + 40)
return add_serial(checked(response, "QUIT_FAILED"), serial)
if command == "library":
request = {"query": args.query or "", "source": args.source or ""}
return add_serial(checked(provider_call(adb, serial, "library", request=request), "LIBRARY_FAILED"), serial)
if command == "xodus":
argv = args.argv[1:] if args.argv[:1] == ["--"] else args.argv
if not argv:
raise ControlError("xodus needs its arguments after --", "INVALID_ARGUMENTS")
response = provider_call(adb, serial, "xodus", request={"args": argv, "timeout": args.timeout},
timeout=args.timeout + 30)
return add_serial(checked(response, "XODUS_FAILED"), serial)
if command == "cloud":
request = {"direction": args.direction, "store": args.store, "id": args.game_id, "force": args.force}
response = provider_call(adb, serial, "cloud", request=request, timeout=args.timeout)
return add_serial(checked(response, "CLOUD_FAILED"), serial)
if command == "focus":
return add_serial(checked(provider_call(adb, serial, "focus", timeout=40), "FOCUS_FAILED"), serial)
@@ -1224,15 +1283,31 @@ def build_parser() -> argparse.ArgumentParser:
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 = commands.add_parser("launch", help="launch a Steam game in the running Steam session, or any library game with --game")
launch.add_argument("app_id", type=int, nargs="?")
launch.add_argument("--game", help="a library game id or a unique part of its name (store and added games too)")
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_ = commands.add_parser("quit", help="quit a running game (through the client, then signals); the focused one by default")
quit_.add_argument("app_id", type=int, nargs="?")
quit_.add_argument("--timeout", type=float, default=15)
library = commands.add_parser("library", help="the library games the front end lists, with the ids launch --game takes")
library.add_argument("--query", help="only games whose name contains this")
library.add_argument("--source", help="only games from this source, e.g. steam, xbox, ea, ubisoft, gog, epic")
xodus = commands.add_parser("xodus", help="run the Xbox backend with the app's credentials (debugging tools)")
xodus.add_argument("--timeout", type=float, default=120)
xodus.add_argument("argv", nargs=argparse.REMAINDER)
cloud = commands.add_parser("cloud", help="sync a store game's cloud saves now (debugging tools)")
cloud.add_argument("direction", choices=["down", "up"])
cloud.add_argument("store", help="gog, epic, ea or ubisoft")
cloud.add_argument("game_id", help="the store's id for the game, as its install record names it")
cloud.add_argument("--force", action="store_true", help="take this side even over conflicts")
cloud.add_argument("--timeout", type=float, default=300)
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)")
+54
View File
@@ -274,6 +274,60 @@ class DroiddeckctlTest(FakeAdbTest):
self.assertEqual(0, code)
self.assertEqual(489830, out["focus"]["focusedApp"])
LIBRARY = {"ok": True, "command": "library", "games": [
{"id": "9227380185612091392", "name": "TimeSplitters Future Perfect", "source": "xbox", "storeId": "9N51S9QZMSB6", "folder": "/g/ts"},
{"id": "12302733539203571712", "name": "Dead Space (2008)", "source": "ea", "storeId": "DR:105641400", "folder": "/g/ds"},
{"id": "12302733539203571999", "name": "Dead Space 2", "source": "ea", "storeId": "DR:1", "folder": "/g/ds2"},
]}
def test_launch_by_name_opens_the_game_link_and_waits_for_a_game(self):
self.configure({"library": self.LIBRARY, "state": [state(focused=769, focusable=[769]), state(focused=7, focusable=[7, 769])]})
code, out = self.run_ctl("launch", "--game", "timesplitters", "--wait", "--timeout", "5")
self.assertEqual(0, code)
self.assertEqual("TimeSplitters Future Perfect", out["game"]["name"])
self.assertEqual(7, out["focus"]["focusedApp"])
started = [e["args"] for e in self.calls() if e["args"][:3] == ["shell", "am", "start"]]
self.assertIn("droiddeck://game/9227380185612091392", started[0])
self.assertIn("com.droiddeck.launcher/com.droiddeck.launcher.FrontEndActivity", started[0])
self.assertFalse(self.calls("launch"))
def test_launch_by_name_refuses_an_ambiguous_or_missing_game(self):
self.configure({"library": self.LIBRARY})
code, out = self.run_ctl("launch", "--game", "dead space")
self.assertNotEqual(0, code)
self.assertEqual("GAME_AMBIGUOUS", out["error"]["code"])
self.assertIn("Dead Space 2 (12302733539203571999)", out["error"]["message"])
code, out = self.run_ctl("launch", "--game", "12302733539203571712")
self.assertEqual(0, code)
self.assertEqual("ea", out["game"]["source"])
code, out = self.run_ctl("launch", "--game", "halo")
self.assertEqual("GAME_NOT_FOUND", out["error"]["code"])
code, out = self.run_ctl("launch")
self.assertEqual("INVALID_ARGUMENTS", out["error"]["code"])
self.assertFalse([e for e in self.calls() if e["args"][:3] == ["shell", "am", "start"] and "droiddeck://game/12302733539203571999" in e["args"]])
def test_quit_without_an_app_quits_the_focused_game(self):
self.configure({"state": state(focused=4040, focusable=[4040, 769]), "quit": {"ok": True, "command": "quit"}})
code, _ = self.run_ctl("quit")
self.assertEqual(0, code)
self.assertEqual(4040, self.calls("quit")[0]["request"]["appId"])
self.configure({"state": state(focused=769, focusable=[769])})
code, out = self.run_ctl("quit")
self.assertEqual("NO_FOCUSED_GAME", out["error"]["code"])
self.assertEqual(1, len(self.calls("quit")))
def test_library_xodus_and_cloud_pass_their_requests(self):
self.configure({"library": self.LIBRARY, "xodus": {"ok": True, "command": "xodus", "exit": 0, "stdout": "{}", "stderr": ""},
"cloud": {"ok": True, "command": "cloud", "result": "ok", "files": 2, "reason": "downloaded"}})
self.assertEqual(0, self.run_ctl("library", "--source", "ea", "--query", "dead")[0])
self.assertEqual({"query": "dead", "source": "ea"}, self.calls("library")[0]["request"])
self.assertEqual(0, self.run_ctl("xodus", "--timeout", "30", "--", "license", "abc", "--market", "US")[0])
self.assertEqual({"args": ["license", "abc", "--market", "US"], "timeout": 30.0}, self.calls("xodus")[0]["request"])
code, out = self.run_ctl("cloud", "down", "ubisoft", "92c79ab6", "--force")
self.assertEqual(0, code)
self.assertEqual("downloaded", out["reason"])
self.assertEqual({"direction": "down", "store": "ubisoft", "id": "92c79ab6", "force": True}, self.calls("cloud")[0]["request"])
def test_start_reuse_keeps_a_running_session(self):
running = state(focused=769)
running["session"]["mode"] = "steam"